DIT-13464: Capture the raw literal (snapshot_text) in source-code extractors

[laurakoye]

Overview

Adds snapshot_text to scan candidates: the raw source span a value came from, quotes and escapes intact.

value_raw is decoded — "Line one\nLine two" arrives holding a real newline — so it can't be searched for in the file, and writing it back would mangle the syntax around it. snapshot_text is a verbatim slice, so source.includes(snapshot_text) always holds.

• snapshotText?: string on ExtractedHit, emitted as snapshot_text: string | null on the candidate.
• Populated in javascript, html-markup (three push sites), vue (inherits), kotlin, swift, fallback.
• Every source-code hit carries a span. The field stays optional here only because the resource-file extractors haven't been filled in yet; DIT-13480: Capture the raw literal (snapshot_text) in resource-file extractors #4 fills them and flips the type to required, at which point the compiler enforces it.
• The markup-attribute push site drops a valueNode?.text() that could never yield undefined — both branches of the loop above set the node and the text together. Stating that as one guard is what lets DIT-13480: Capture the raw literal (snapshot_text) in resource-file extractors #4's type flip compile.

Nothing server-side is needed to merge — zod strips unknown keys, so the field is ignored on arrival for now.

Context

DIT-13464, part of DIT-13405.

Re-lands #3, which merged to the wrong base. #3's base was still laura/dit-13463-stable-occurrence-index, and #2 merged that branch to main 85 seconds earlier — so #3 merged into a spent branch and none of it reached main. This is 8478306 and cd24c3a cherry-picked straight onto main, unchanged. Cherry-picked rather than merging the old branch, which would have dragged version back to 0.2.0 and engines.node back to >=22, reverting #5.

A code link identifies a string by (file, value, occurrence index) and stores snapshot_text as the code's own rendering of it. Schema design.

Screenshots

None — extraction output only.

Test Plan

1. The suite

yarn jest        # 23 suites, 160 tests — 16 new in src/lang/extractors/snapshot-text.test.ts
yarn typecheck   # clean

A describe.each table asserts, per extractor, that snapshotText is a string on every hit and that source.includes(hit.snapshotText) holds. Four further cases pin what the snapshot keeps and the value drops: escapes, quote style, a template literal's ${...}, and inline markup in a JSX text run.

2. Coverage on a real app

The suite runs on hand-written snippets. This checks a real codebase, and that the nulls land only where they should.

yarn build

mkdir -p /tmp/demo
git -C ../v0-demo archive HEAD | tar -x -C /tmp/demo

cat > snap.mjs <<'EOF'
import { runExtract } from "./dist/index.js";
const { candidates } = await runExtract({ inputPath: process.argv[2] });
const nulls = candidates.filter((c) => c.snapshot_text === null);
console.log(`${candidates.length - nulls.length}/${candidates.length} carry a snapshot`);
console.log("null kinds:", [...new Set(nulls.map((c) => c.detection_kind))]);
EOF

node snap.mjs /tmp/demo
rm snap.mjs

snap.mjs goes in the repo root — ./dist/index.js resolves relative to the script, not the working directory.

3. What to look for

140/200 carry a snapshot
null kinds: [ 'resource_value' ]

Every null is a resource_value. Expected: this PR only touches the source-code extractors, so resource files stay null until DIT-13480. Any other kind appearing in that list means an extractor emitted a value it can't point at in the source.

Note: yarn linking this into the CLI and running yarn scan does not exercise this code until cli#151 merges — the CLI still uses its own copy.