DIT-13463: Stable occurrence index on scan candidates

[laurakoye]

Overview

Adds occurrence_index to scan candidates: which repeat this string is within its file, counting from 0 in source order.

If a file has three "Save" strings, only the line number tells them apart today — and line numbers move whenever someone adds an import. The index doesn't, so a code link can still say which occurrence it points at after the file shifts.

• New assignOccurrenceIndexes(hits) in src/extract.ts, used by extractFromResolvedFile and exported so it can be unit tested.
• It sorts by (line, column) first, which is the point of the PR. The JS extractor emits hits grouped by node kind (src/lang/extractors/javascript.ts:38), not source order, so counting them as they arrive gives an index that changes between runs of an unmodified file. Sorting happens on indices internally, so emitted candidate order is unchanged.
• occurrence_index added to DittoScanCandidateSchema.

Nothing server-side is needed to merge — zod strips unknown keys, so the field is ignored on arrival for now. A ditto-app follow-up adds it to PtdCandidateSchema, where the code link write will read it.

Context

DIT-13463, part of DIT-13405.

A code link identifies a hardcoded string by (file, value, occurrence index) — never by line number, which is display-only. This is the last of those three fields. Schema design.

Screenshots

None — extraction output only.

Test Plan

Example e2e test: In v0-demo

yarn build

Make two identical copies of a real app.

mkdir -p /tmp/demo-a
git -C ../v0-demo archive HEAD | tar -x -C /tmp/demo-a
cp -R /tmp/demo-a /tmp/demo-b

git archive HEAD streams a tarball of the committed tree straight into tar -x

Edit one copy, in the two ways that matter.

In /tmp/demo-b/src/features/payments/SendMoney.tsx:

1. Define a const at the top of the file (to shift line numbers)
2. Add one more t("send.title") below the two already there. This checks that a new repeat takes the next index rather than disturbing the existing ones.

Extract both and compare.

The script goes in the repo root: ./dist/index.js resolves relative to the script's own location, not the working directory.

cat > occ.mjs <<'EOF'
import { runExtract } from "./dist/index.js";
const { candidates } = await runExtract({ inputPath: process.argv[2] });
for (const c of candidates) {
  if (!/SendMoney/.test(c.location.file)) continue;
  if (!/send\./.test(c.value_raw)) continue;
  console.log(`${String(c.location.line).padStart(3)}  #${c.occurrence_index}  ${c.value_raw}`);
}
EOF

node occ.mjs /tmp/demo-a   # before
node occ.mjs /tmp/demo-b   # after
rm occ.mjs

The filter matches on value_raw, not i18n_key. These are t("send.title") call arguments in a .tsx file, so they're extracted as hardcoded literals and arrive with i18n_key: null — filtering on the key prints nothing at all.

3. What to look for

before                              after
 14  #0  "send.title"                18  #0  "send.title"
 17  #0  "send.confirmBody"          21  #0  "send.confirmBody"
 19  #0  "send.recipientLabel"       23  #0  "send.recipientLabel"
 23  #0  "send.confirmButton"        27  #0  "send.confirmButton"
 32  #1  "send.title"                36  #1  "send.title"
 40  #1  "send.recipientLabel"       44  #1  "send.recipientLabel"
 48  #0  "send.amountLabel"          52  #0  "send.amountLabel"
 49  #0  "send.dailyLimit"           53  #0  "send.dailyLimit"
 60  #0  "send.reviewButton"         64  #0  "send.reviewButton"
                                     67  #2  "send.title"   ← the added one

Every line moved by 4. Every index stayed. That's the whole result: line numbers churn on an unrelated edit, occurrence_index doesn't, so a code link keyed on it still points at the same string. Assigned in extraction order instead, these would have shuffled. The new occurrence is #2 because it comes after the others in the file.

Known limit: add that third t("send.title") above the existing two instead and it becomes #0, renumbering the rest to #1 and #2. Keyed strings survive that via i18nKey; hardcoded ones fall through to the value-in-file rung during reconciliation. The index only has to be stable against edits elsewhere in the file, not against inserting a new copy of itself.

Note: linking this package into the CLI (yarn link @dittowords/text-extract) and running yarn scan does not exercise this code until cli#151 merges — the CLI still uses its own copy of the extractor until then.

[jholiga]

1 small thing, otherwise LGTM! Just a note that we'll also want to bump the version in package.json before publishing the changes from your 3 PRs to npm

[jholiga]

I think this comment should be above extractFromResolvedFile

[laurakoye]

1 small thing, otherwise LGTM! Just a note that we'll also want to bump the version in package.json before publishing the changes from your 3 PRs to npm

I'll do that last after all three go in