CMG-1101: fix delta reference resolution and locale-migrated tracking

[chetan-contentstack]

🔗 Jira Tickets

Parent story: CMG-789 — Delta Migration | v1.0.0 | Update Feature Implementation

• CMG-1101 — Contentful delta: reference lost & new locale not populated on iteration 2+

---

📋 PR Type

• ✨ Feature
• 🐛 Bug Fix
• 🔥 Hotfix
• ♻️ Refactor
• 🧹 Chore / Dependency Update
• 📝 Documentation

---

📝 Description

What changed?

• CMG-1101 — References resolve on the delta/update path. The master-locale bulk import resolves references via the CLI's uid-mapper; the update path skipped it and wrote source-cms ids straight to the destination. Threads the flat + per-locale entry uid-mapper into the update config as __entryMapping__ and remaps Link(Entry) uids in entry-update-script.cjs.
• CMG-1101 — Only actually-processed locales get marked "migrated". Was recording all configured locales after every run, so a newly-added locale got flagged done before it ran and was skipped on later restarts. Iteration 1 keeps the old behaviour (single bulk); iteration 2+ records master + locales present in updated-entries.json.
• Typo in contentful.service.ts:439: Array?.isArray(entryId?.id) → Array.isArray(entryId?.[id]).
• Unit coverage added for the new helpers.

Why?

Reproduced with the bundled contentful-export.json / -v2.json / -v3.json: on iteration 2 the destination reference field went empty and the newly-added locale had zero entries.

---

🧩 Affected Areas

• api — Node.js backend
• ui
• upload-api
• docker / docker-compose
• CI / GitHub Actions workflows
• Environment variables / config

---

🧪 How to Test

Use the three bundled fixtures.

1. Iter 1 — migrate contentful-export.json (1 locale, 2 refs). Confirm both refs resolve in destination.
2. Iter 2 — restart with contentful-export-v2.json (adds en-IN, updates one entry's title). On Map Entry, select the changed entry. After migration, confirm refs still resolve in en-US and en-IN is populated.
3. Iter 3 — restart with contentful-export-v3.json (adds en-GB, adds relatedArticles ref). Confirm both author and relatedArticles resolve in all three locales.
4. cd api && npm test passes.

---

📸 Screenshots / Recordings

Before	After
Iter 2: author ref empty in destination after re-mapping	Ref resolves to destination uid
Iter 2: en-IN locale has 0 entries	en-IN populated for every entry
Iter 3: relatedArticles empty across locales	Both refs resolve in all 3 locales

---

🔗 Related PRs / Dependencies

• Parent story: CMG-789

---

✅ Author Checklist

• Branch follows naming convention: bugfix/cmg-1101-delta-ref-locale
• Jira ticket linked
• Self-reviewed the diff
• .env / example.env updated — N/A
• No secrets committed
• Existing tests pass (npm test in api/)
• New tests written for the added helpers
• README.md / docs updated — N/A
• Talisman pre-push scan passes

---

👀 Reviewer Notes

• Reference resolution precedence: per-locale new → per-locale old → flat new → flat old → identity. Identity fallback preserves current behaviour for non-Contentful sources.
• Iteration-1 locale tracking is intentionally unchanged — that path is a single bulk import, so the full configured set is what actually ran.
• No changes outside api/src/ and api/tests/.

[chetan-contentstack]

Superseded by fresh branch off dev — see new PR.