spexcode 0.6.1 → 0.6.5

package/node_modules/@spexcode/spec-core/dist/anchors.js

@@ -0,0 +1,730 @@
+import { join } from 'node:path';
+import { createRequire } from 'node:module';
+import { gitRequiredA, gitObjectFormat, isGitObjectId, batchRevisionOids, batchBlobTexts, combinedDiffOwnedChanges, driftPathWindow, readImmutableHunkFacts, persistImmutableHunkFacts, withEventLedgerBuild } from './git.js';
+const RS = '\x1e';
+export function parseCodeEntry(raw) {
+    const i = raw.indexOf('#');
+    if (i < 0)
+        return { path: raw.trim(), anchor: null };
+    return { path: raw.slice(0, i).trim(), anchor: raw.slice(i + 1).trim() || null };
+}
+export function relationClaimsPath(claim, file) {
+    if (claim === file)
+        return true;
+    if (file.startsWith(claim.replace(/\/+$/, '') + '/'))
+        return true;
+    if (!claim.includes('*'))
+        return false;
+    const pattern = claim.replace(/[.+?^${}()|[\]\\]/g, '\\$&').replace(/\*/g, '.*');
+    return new RegExp(`^${pattern}$`).test(file);
+}
+export function parseRelation(raws, relation) {
+    const order = [];
+    const byPath = new Map();
+    const problems = [];
+    for (const raw of raws) {
+        const { path, anchor } = parseCodeEntry(raw);
+        let e = byPath.get(path);
+        if (!e) {
+            e = { bare: false, selectors: [] };
+            byPath.set(path, e);
+            order.push(path);
+        }
+        if (anchor === null) {
+            if (e.bare)
+                problems.push(`${relation}: lists '${path}' twice — drop the duplicate entry`);
+            e.bare = true;
+        }
+        else if (e.selectors.includes(anchor)) {
+            problems.push(`${relation}: lists selector '${path}#${anchor}' twice — drop the duplicate`);
+        }
+        else
+            e.selectors.push(anchor);
+    }
+    for (const path of order) {
+        const e = byPath.get(path);
+        if (e.bare && e.selectors.length)
+            problems.push(`${relation}: mixes bare '${path}' with '${path}#…' selectors — one base path is either whole-file or selector-scoped, never both; drop one form`);
+        if (e.selectors.length && path.includes('*'))
+            problems.push(`${relation}: '${path}#${e.selectors[0]}' puts a selector on a glob — a selector scopes ONE real file`);
+    }
+    return { entries: order.map((p) => ({ path: p, selectors: byPath.get(p).selectors })), problems };
+}
+// ---- extractor: ts-ast (the designated extractor for the JS family) ----
+// Parse-only via the HOST project's own typescript, so the parse matches what the project itself compiles
+// with. If it cannot resolve, ready() returns a loud unverified verdict and lint skips these anchors
+// without crashing (no bundled compiler, regex fallback, or fake pass for JS).
+const JS_EXTS = new Set(['ts', 'tsx', 'js', 'jsx', 'mjs', 'cjs', 'mts', 'cts']);
+const TS_AST_MEMO_SCHEMA = 'ts-ast-memo-v1';
+export function tsAstExtractor(root) {
+    let ts; // undefined = unprobed; null = unresolvable
+    let tsModulePath = '';
+    let readiness;
+    const probe = () => {
+        if (ts !== undefined)
+            return;
+        try {
+            const require = createRequire(join(root, 'package.json'));
+            tsModulePath = require.resolve('typescript');
+            ts = require('typescript');
+        }
+        catch {
+            ts = null;
+        }
+    };
+    return {
+        id: 'ts-ast',
+        claims: (ext) => JS_EXTS.has(ext),
+        ready() {
+            if (readiness !== undefined)
+                return readiness;
+            probe();
+            if (!ts)
+                return (readiness = `typescript is not resolvable from the governed repository (${root}) — JS-family anchors were skipped and remain unverified; run 'npm i -D typescript@5', or remove the #anchor`);
+            // resolvability is not usability: typescript@7 (the Go rewrite) may resolve yet not expose the JS
+            // compiler API this extractor drives. Probe the ACTUAL surface with a tiny parse. Once a candidate
+            // resolves, incompatibility is loud rather than silently changing parser versions.
+            try {
+                const sf = ts.createSourceFile('probe.ts', 'const x = 1', ts.ScriptTarget.Latest, false, ts.ScriptKind.TS);
+                if (!sf?.statements?.length || sf.parseDiagnostics?.length)
+                    throw new Error('probe parse failed');
+                readiness = true;
+            }
+            catch {
+                readiness = `host typescript (v${ts?.version ?? 'unknown'}) resolves but its createSourceFile API is unusable (a TS7/Go build?) — pin 'npm i -D typescript@5', or remove the #anchor`;
+            }
+            return readiness;
+        },
+        extract(content, filename) {
+            probe();
+            if (!ts)
+                throw new Error('ts-ast extractor is not ready (typescript unresolvable)');
+            const kind = /\.(tsx)$/.test(filename) ? ts.ScriptKind.TSX
+                : /\.(jsx)$/.test(filename) ? ts.ScriptKind.JSX
+                    : /\.(ts|mts|cts)$/.test(filename) ? ts.ScriptKind.TS
+                        : ts.ScriptKind.JS;
+            const sf = ts.createSourceFile(filename, content, ts.ScriptTarget.Latest, false, kind);
+            // parse-only gate: a file that does not parse yields GARBAGE units (a shell script's `x=$(...)`
+            // parses as a const) — throw so the caller renders an honest "cannot parse" verdict instead.
+            if (sf.parseDiagnostics?.length)
+                throw new Error(`${filename} does not parse as ${ts.ScriptKind[kind]} (${sf.parseDiagnostics.length} syntax error(s))`);
+            const line = (pos) => sf.getLineAndCharacterOfPosition(pos).line + 1;
+            const units = [];
+            const push = (name, ukind, node, typeOnly = false) => units.push({ name, kind: ukind, start: line(node.getStart(sf)), end: line(node.end), ...(typeOnly ? { typeOnly } : {}) });
+            for (const st of sf.statements) {
+                if (ts.isFunctionDeclaration(st))
+                    push(st.name ? st.name.text : '(default)', 'function', st);
+                else if (ts.isClassDeclaration(st)) {
+                    const cname = st.name ? st.name.text : '(default)';
+                    push(cname, 'class', st);
+                    for (const m of st.members) {
+                        if ((ts.isMethodDeclaration(m) || ts.isConstructorDeclaration(m) || ts.isGetAccessorDeclaration(m) || ts.isSetAccessorDeclaration(m)) && m.body) {
+                            const mname = ts.isConstructorDeclaration(m) ? 'constructor' : (m.name && ts.isIdentifier(m.name) ? m.name.text : '(computed)');
+                            push(`${cname}.${mname}`, 'method', m);
+                        }
+                    }
+                }
+                else if (ts.isVariableStatement(st)) {
+                    for (const d of st.declarationList.declarations) {
+                        if (!ts.isIdentifier(d.name))
+                            continue; // destructuring — not anchorable by one name
+                        const fn = d.initializer && (ts.isArrowFunction(d.initializer) || ts.isFunctionExpression(d.initializer));
+                        // range = the whole statement (multi-declarator lines co-move; each name shares the range)
+                        units.push({ name: d.name.text, kind: fn ? 'const-fn' : 'const-data', start: line(st.getStart(sf)), end: line(st.end) });
+                    }
+                }
+                else if (ts.isEnumDeclaration(st))
+                    push(st.name.text, 'enum', st);
+                else if (ts.isInterfaceDeclaration(st))
+                    push(st.name.text, 'interface', st, true);
+                else if (ts.isTypeAliasDeclaration(st))
+                    push(st.name.text, 'type', st, true);
+            }
+            return units;
+        },
+        memoKey(filename) {
+            probe();
+            const host = ts ? `${tsModulePath}\0${ts.version ?? 'unknown'}` : `unresolved\0${root}`;
+            return `${TS_AST_MEMO_SCHEMA}\0${host}\0target:Latest\0parents:false\0${filename}`;
+        },
+    };
+}
+const balance = (s) => { let n = 0; for (const ch of s) {
+    if ('([{'.includes(ch))
+        n++;
+    else if (')]}'.includes(ch))
+        n--;
+} return n; };
+// split a declarator-list head on top-level commas: `COLS = 220, ROWS = 50` -> [COLS, ROWS]
+function declNames(head) {
+    let d = 0, seg = '';
+    const segs = [];
+    for (const ch of head) {
+        if ('([{<'.includes(ch))
+            d++;
+        else if (')]}>'.includes(ch))
+            d--;
+        if (ch === ',' && d === 0) {
+            segs.push(seg);
+            seg = '';
+        }
+        else
+            seg += ch;
+    }
+    segs.push(seg);
+    return segs.map((s) => s.match(/^\s*([A-Za-z_$][\w$]*)\s*(?::|=|$)/)?.[1]).filter((x) => !!x);
+}
+const indentation = (line) => {
+    let n = 0;
+    for (const ch of line) {
+        if (ch === ' ')
+            n++;
+        else if (ch === '\t')
+            n += 8 - (n % 8);
+        else
+            break;
+    }
+    return n;
+};
+function extractIndentScoped(content, spec) {
+    const lines = content.split('\n');
+    const units = [];
+    const scopes = [];
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        if (!line.trim() || /^\s*#/.test(line))
+            continue;
+        const indent = indentation(line);
+        while (scopes.length && scopes[scopes.length - 1].indent >= indent)
+            scopes.pop();
+        for (const d of spec.decls) {
+            const m = line.match(d.re);
+            if (!m)
+                continue;
+            const local = m[1];
+            const name = [...scopes.map((s) => s.name), local].join('.');
+            const parent = scopes[scopes.length - 1];
+            const kind = d.memberOf && parent?.kind === d.memberOf.parentKind ? d.memberOf.kind : d.kind;
+            let start = i + 1;
+            if (spec.indentScopes?.decorator) {
+                for (let j = i - 1; j >= 0; j--) {
+                    if (indentation(lines[j]) !== indent || !spec.indentScopes.decorator.test(lines[j]))
+                        break;
+                    start = j + 1;
+                }
+            }
+            units.push({ name, kind, start, end: i + 1, declaration: i, indent, ...(d.typeOnly ? { typeOnly: true } : {}) });
+            if (d.scopeOpener)
+                scopes.push({ indent, name: local, kind: d.kind });
+            break;
+        }
+    }
+    for (const unit of units) {
+        let boundary = null;
+        for (let i = unit.declaration + 1; i < lines.length; i++) {
+            const line = lines[i];
+            if (!line.trim())
+                continue;
+            const indent = indentation(line);
+            if (/^\s*#/.test(line)) {
+                if (indent <= unit.indent && boundary === null)
+                    boundary = i;
+                continue;
+            }
+            if (indent <= unit.indent) {
+                boundary ??= i;
+                break;
+            }
+            boundary = null;
+        }
+        unit.end = Math.max(unit.start, (boundary ?? lines.length));
+    }
+    return units.map(({ declaration: _declaration, indent: _indent, ...unit }) => unit);
+}
+export function heuristicExtractor(spec) {
+    return {
+        id: spec.id,
+        claims: (ext) => spec.extensions.includes(ext),
+        ready: () => true,
+        extract(content) {
+            if (spec.indentScopes)
+                return extractIndentScoped(content, spec);
+            const lines = content.split('\n');
+            const units = [];
+            let cls = null, depth = 0;
+            for (let i = 0; i < lines.length; i++) {
+                const l = lines[i];
+                if (cls) {
+                    const m = spec.member && l.match(spec.member.re);
+                    if (m && !spec.member.blacklist?.test(m[1]))
+                        units.push({ name: `${cls}.${m[1]}`, kind: 'method', start: i + 1, end: i + 1 });
+                    depth += balance(l);
+                    if (depth <= 0)
+                        cls = null;
+                    continue;
+                }
+                for (const d of spec.decls) {
+                    const m = l.match(d.re);
+                    if (!m)
+                        continue;
+                    for (const name of d.declList ? declNames(m[1]) : [m[1]])
+                        units.push({ name, kind: d.kind, start: i + 1, end: i + 1, ...(d.typeOnly ? { typeOnly: true } : {}) });
+                    if (d.classOpener) {
+                        cls = m[1];
+                        depth = balance(l);
+                    }
+                    break;
+                }
+            }
+            // R5b ranges: a unit ends before the next column-0 boundary line; a method is also capped by the
+            // next unit's start (methods sit inside their class's indentation, below boundary's radar).
+            const bset = [];
+            for (let i = 0; i < lines.length; i++)
+                if (spec.boundary.test(lines[i]))
+                    bset.push(i + 1);
+            const starts = units.map((u) => u.start).sort((a, b) => a - b);
+            for (const u of units) {
+                const nb = bset.find((b) => b > u.start);
+                let end = nb ?? lines.length + 1;
+                if (u.kind === 'method') {
+                    const ns = starts.find((x) => x > u.start);
+                    if (ns && ns < end)
+                        end = ns;
+                }
+                u.end = Math.max(u.start, end - 1);
+            }
+            return units;
+        },
+        memoKey(filename) {
+            const regex = (r) => r ? `${r.source}/${r.flags}` : null;
+            return JSON.stringify({
+                schema: 'heuristic-memo-v1', filename, id: spec.id, extensions: spec.extensions,
+                decls: spec.decls.map((d) => ({
+                    re: regex(d.re), kind: d.kind, typeOnly: !!d.typeOnly, classOpener: !!d.classOpener,
+                    declList: !!d.declList, scopeOpener: !!d.scopeOpener, memberOf: d.memberOf ?? null,
+                })),
+                member: spec.member ? { re: regex(spec.member.re), blacklist: regex(spec.member.blacklist) } : null,
+                indentScopes: spec.indentScopes ? { decorator: regex(spec.indentScopes.decorator) } : null,
+                boundary: regex(spec.boundary),
+            });
+        },
+    };
+}
+// The validated JS-family reference row (R5b: name precision 99.7% / recall 100% / range 98.9% on the
+// 41-file oracle) — NOT registered for JS (ts-ast is designated); kept as the engine's reference shape
+// and the benchmark's scoring subject.
+export const JS_LANG_R5B = {
+    id: 'heuristic-js',
+    extensions: [...JS_EXTS],
+    decls: [
+        { re: /^(?:export\s+)?(?:default\s+)?(?:async\s+)?function\*?\s+([A-Za-z_$][\w$]*)/, kind: 'function' },
+        { re: /^(?:export\s+)?(?:abstract\s+)?class\s+([A-Za-z_$][\w$]*)/, kind: 'class', classOpener: true },
+        { re: /^(?:export\s+)?(?:declare\s+)?enum\s+([A-Za-z_$][\w$]*)/, kind: 'enum' },
+        { re: /^(?:export\s+)?(?:declare\s+)?interface\s+([A-Za-z_$][\w$]*)/, kind: 'interface', typeOnly: true },
+        { re: /^(?:export\s+)?(?:declare\s+)?type\s+([A-Za-z_$][\w$]*)/, kind: 'type', typeOnly: true },
+        { re: /^(?:export\s+)?(?:const|let|var)\s+(.+)$/, kind: 'const', declList: true },
+    ],
+    member: {
+        re: /^\s+(?:(?:public|private|protected|static|readonly|async|get|set)\s+)*([A-Za-z_$][\w$]*)\s*(?:<[^>]*>)?\(/,
+        blacklist: /^(if|for|while|switch|return|catch|new|await|typeof|throw|else|do)$/,
+    },
+    boundary: /^(?:[A-Za-z_$]|\/\/|\/\*)/,
+};
+// Python is a LangSpec DATA row over the same generic engine: declaration names come from patterns;
+// significant indentation supplies lexical qualification and ranges. It is intentionally structural,
+// not a Python runtime or full grammar (the user-facing boundary is documented by [[code-anchor]]).
+const PY_ID = String.raw `[\p{ID_Start}_][\p{ID_Continue}_]*`;
+export const PYTHON_LANG = {
+    id: 'heuristic-python',
+    extensions: ['py', 'pyi'],
+    decls: [
+        {
+            re: new RegExp(`^\\s*(?:async\\s+)?def\\s+(${PY_ID})\\s*\\(`, 'u'),
+            kind: 'function',
+            scopeOpener: true,
+            memberOf: { parentKind: 'class', kind: 'method' },
+        },
+        { re: new RegExp(`^\\s*class\\s+(${PY_ID})(?:\\s*\\(|\\s*:)`, 'u'), kind: 'class', scopeOpener: true },
+    ],
+    indentScopes: { decorator: /^\s*@/ },
+    boundary: /^\S/,
+};
+// ---- registry: extension -> its ONE designated extractor ----
+// The registry's shape is the Extractor INTERFACE, not any engine: a future language row may be a
+// heuristicExtractor(LangSpec) or a web-tree-sitter extractor carrying its own wasm-grammar/query
+// config — whatever the implementation needs rides inside its own factory, never in the registry.
+export function extractors(root) {
+    return [tsAstExtractor(root), ...[PYTHON_LANG].map(heuristicExtractor)];
+}
+// first claiming extractor IS the designation (the registry order defines it); null = no anchor support
+// for this language yet (lint ERRORS — the remedy is a LangSpec data row, or dropping the anchor).
+export function extractorFor(regs, ext) {
+    return regs.find((x) => x.claims(ext)) ?? null;
+}
+export const extOf = (path) => {
+    const base = path.slice(path.lastIndexOf('/') + 1);
+    const dot = base.lastIndexOf('.');
+    return dot > 0 ? base.slice(dot + 1) : '';
+};
+export function resolveSelectors(units, selectors) {
+    return selectors.map((selector) => {
+        const r = resolveAnchor(units, selector);
+        if ('dead' in r)
+            return { selector, dead: true };
+        if ('ambiguous' in r)
+            return { selector, ambiguous: r.ambiguous };
+        return { selector, ok: r.ok };
+    });
+}
+export function resolveAnchor(units, symbol) {
+    const hits = units.filter((u) => u.name === symbol);
+    if (!hits.length)
+        return { dead: true };
+    if (hits.length > 1)
+        return { ambiguous: hits.length };
+    return { ok: hits[0] };
+}
+// The one selector/range intersection used by historical commits and a pinned worktree overlay.
+export function selectorsHitRanges(units, symbols, ranges) {
+    return symbols.filter((symbol) => {
+        const matching = units.filter((unit) => unit.name === symbol);
+        return matching.length > 0 && ranges.some(([start, end]) => matching.some((unit) => start <= unit.end && unit.start <= end));
+    });
+}
+// Ordinary zero-context ranges. The side chooses the immutable image whose units the caller resolved.
+export function diffHunkRanges(patch, side = 'new') {
+    const ranges = [];
+    for (const match of patch.matchAll(/^@@ -(\d+)(?:,(\d+))? \+(\d+)(?:,(\d+))? @@/gm)) {
+        const offset = side === 'old' ? 1 : 3;
+        const start = +match[offset];
+        const count = match[offset + 1] === undefined ? 1 : +match[offset + 1];
+        if (count > 0)
+            ranges.push([start, start + count - 1]);
+    }
+    return ranges;
+}
+const fileRevisionUnitMemo = new Map();
+const MEMO_MAX = 4096;
+const fileRevisionMemoKey = (objectFormat, oid, x, path) => `${objectFormat}\0${oid}\0${x.memoKey(path)}`;
+async function unitsAtFileRevision(commit, path, x, objectFormat, oid, text) {
+    if (!oid)
+        return { absent: true };
+    const key = fileRevisionMemoKey(objectFormat, oid, x, path);
+    const hit = fileRevisionUnitMemo.get(key);
+    if (hit)
+        return hit;
+    if (text === undefined)
+        throw new Error(`git cat-file --batch omitted object ${oid} for ${commit}:${path}`);
+    let result;
+    try {
+        result = { units: x.extract(text, path) };
+    }
+    catch (e) {
+        result = { unparseable: e?.message ?? String(e) };
+    }
+    if (fileRevisionUnitMemo.size >= MEMO_MAX)
+        fileRevisionUnitMemo.clear();
+    fileRevisionUnitMemo.set(key, result);
+    return result;
+}
+// @@@ RANGE_SEMANTICS - hunk ranges must not depend on ambient Git state, because a range that moves with
+// config or attributes is neither a sound anchor verdict nor a reusable fact. Outside the commit, three
+// classes decide them: presentation (`.gitattributes` `-diff` prints `Binary files … differ` with no `@@` at
+// all — measured: one hunk bare, ZERO under `src/x.py -diff`, so an attribute edit silently disabled an
+// anchored contract's drift; a textconv or external driver replaces the text compared), the ALGORITHM and
+// its heuristics (`diff.algorithm`, `diff.indentHeuristic` — both repo config), and hunk COALESCING
+// (`diff.interHunkContext`). All are pinned here, on the two readers this node owns.
+//
+// The algorithm's VALUE is a product choice, not a formality, because the algorithms genuinely disagree:
+// on `c a c a` -> `c c a a a`, myers authors new lines 4-5 and deletes old line 2, while histogram authors
+// new lines 2-3 and deletes old line 3 — so a unit on line 3 is a HIT under histogram and a MISS under
+// myers, on one commit. histogram is pinned because it aligns the change with the unit that actually moved,
+// which for a BLOCKING gate is the conservative direction; myers (Git's default) would silently miss that
+// drift. So this pin is not merely determinism: it settles which reading a verdict means.
+// `--no-color` is not cosmetic here: under an ambient `color.ui=always` Git prefixes every `@@` with an
+// ANSI escape, so a `/^@@/` parse finds NO hunks and every anchored path reads as "nothing changed" — a
+// silent zero-drift verdict for the whole corpus, and one that would then be memoized. `-M -l0` pins rename
+// detection with no candidate limit, matching the identity stream this engine's events come from, so a large
+// rename set cannot quietly change which pairs are compared.
+const RANGE_SEMANTICS = [
+    '--text', '--no-textconv', '--no-ext-diff', '--no-color',
+    '--diff-algorithm=histogram', '--no-indent-heuristic', '--inter-hunk-context=0',
+    '-M', '-l0',
+];
+const hunkMemo = new Map();
+// @@@ the reusable fact is a diff of ORDERED IMAGES, not of a commit id - a commit id is not immutable
+// interpretation: `refs/replace` can swap the object, and a graft or an unshallow can change its parents, so
+// one (commit,path) can name two different diffs inside one process. The inputs that actually decide the
+// hunks are the result image and each parent image, in order, each identified by its resolved blob oid and
+// historical path. Keying on those makes the key move exactly when an input does, and the oids are already
+// resolved by this read's one `cat-file --batch-check`, so completeness costs no extra child and no new state.
+const ABSENT_IMAGE = '-';
+const HUNK_FACT_SCHEMA = 'anchor-range-histogram-v1';
+const hunkMemoKey = (images) => `${HUNK_FACT_SCHEMA}\0${images.join('\0')}`;
+function rememberHunks(key, ranges) {
+    if (hunkMemo.size >= MEMO_MAX)
+        hunkMemo.clear();
+    hunkMemo.set(key, ranges);
+    return ranges;
+}
+async function hunksAt(root, event, key) {
+    const paths = [...new Set([event.historicalPath, ...event.parents.map((parent) => parent.historicalPath)])];
+    const hit = hunkMemo.get(key);
+    if (hit)
+        return hit;
+    const merge = event.parents.length > 1;
+    const out = await gitRequiredA(['-C', root, '-c', 'core.quotePath=false', 'show', '--cc', '--combined-all-paths', '--unified=0', ...RANGE_SEMANTICS, '--format=', event.commit,
+        ...(merge ? [] : ['--', ...paths])], `cannot derive anchor hunks for ${event.commit}:${event.historicalPath}`);
+    let ranges = { after: [], before: [[]] };
+    if (/^@@@/m.test(out)) {
+        const owned = combinedDiffOwnedChanges(out).get(event.historicalPath);
+        if (!owned)
+            throw new Error(`combined diff for ${event.commit} did not expose owned ranges for '${event.historicalPath}'`);
+        ranges = owned;
+    }
+    else {
+        for (const m of out.matchAll(/^@@ -(\d+)(?:,(\d+))? \+(\d+)(?:,(\d+))? @@/gm)) {
+            const oldStart = +m[1], oldCount = m[2] === undefined ? 1 : +m[2];
+            const newStart = +m[3], newCount = m[4] === undefined ? 1 : +m[4];
+            if (oldCount > 0)
+                ranges.before[0].push([oldStart, oldStart + oldCount - 1]);
+            if (newCount > 0)
+                ranges.after.push([newStart, newStart + newCount - 1]);
+        }
+    }
+    return rememberHunks(key, ranges);
+}
+// Ordinary commits whose two images keep one path share a single query. Renames and merges retain distinct
+// image paths, so they stay on hunksAt's exact event-shaped query. Commits ride argv here, so a build-wide
+// batch is split to stay clear of the kernel's exec argument limit; the records are order-independent.
+//
+// @@@ the demand set is the MISSES - a hunk is reusable by the identity of the IMAGES it diffed, never by the
+// commit id (see hunkMemoKey): under that identity, plus this seam's pinned interpretation, the fact cannot be
+// reinterpreted inside one process, so the batch may ask git only for what it has not read. Asking for the
+// whole window again is what made a repeated read cost the CORPUS instead of the movement: a re-lint after one
+// trunk commit or one dirty edit re-forked one `log --patch` per anchored path (22 here) to re-derive
+// byte-identical answers.
+const HUNK_COMMIT_CHUNK = 400;
+async function hunksAtMany(root, path, entries) {
+    const result = new Map();
+    const ordinary = [];
+    for (const [commit, key] of entries) {
+        const hit = hunkMemo.get(key);
+        if (hit)
+            result.set(commit, hit);
+        else
+            ordinary.push(commit);
+    }
+    if (!ordinary.length)
+        return result;
+    for (let cursor = 0; cursor < ordinary.length; cursor += HUNK_COMMIT_CHUNK)
+        await hunkRecordsInto(root, ordinary.slice(cursor, cursor + HUNK_COMMIT_CHUNK), path, entries, result);
+    return result;
+}
+async function hunkRecordsInto(root, ordinary, path, keys, result) {
+    const out = await gitRequiredA(['-C', root, '-c', 'core.quotePath=false', 'log', '--no-walk', '--no-merges', '--patch', '--unified=0', ...RANGE_SEMANTICS,
+        `--format=${RS}%H`, ...ordinary, '--', path], `cannot derive anchor hunks for ${path}`);
+    for (const rec of out.split(RS)) {
+        const normalized = rec.replace(/^\n/, '');
+        if (!normalized)
+            continue;
+        const newline = normalized.indexOf('\n');
+        const hash = (newline < 0 ? normalized : normalized.slice(0, newline)).trim();
+        if (!isGitObjectId(root, hash))
+            throw new Error(`anchor hunk query returned malformed object id '${hash || 'empty'}'`);
+        const patch = newline < 0 ? '' : normalized.slice(newline + 1);
+        const ranges = { after: [], before: [[]] };
+        for (const m of patch.matchAll(/^@@ -(\d+)(?:,(\d+))? \+(\d+)(?:,(\d+))? @@/gm)) {
+            const oldStart = +m[1], oldCount = m[2] === undefined ? 1 : +m[2];
+            const newStart = +m[3], newCount = m[4] === undefined ? 1 : +m[4];
+            if (oldCount > 0)
+                ranges.before[0].push([oldStart, oldStart + oldCount - 1]);
+            if (newCount > 0)
+                ranges.after.push([newStart, newStart + newCount - 1]);
+        }
+        const key = keys.get(hash);
+        result.set(hash, key === undefined ? ranges : rememberHunks(key, ranges));
+    }
+}
+// the drift window of an anchored file: every commit to `path` not reachable from the spec's version
+// and not covered by a valid Spec-OK ack — the SAME set driftFor counts, exposed as commits so the
+// anchor engine can probe each one. Ordinary file commits and merge-authored dense-combined paths are
+// indexed separately so clean merge transport is never charged twice.
+export function windowEvents(idx, sinceHash, path, nodeId) {
+    if (!sinceHash)
+        return [];
+    return driftPathWindow(idx, sinceHash, path, nodeId) ?? [];
+}
+const anchorRevisionKey = ({ commit, path }) => `${commit}\0${path}`;
+// One lint can judge several selectors with overlapping windows. Their Git images and ordinary hunks are
+// reusable under the identity of those images, so the batch owns them once and each query keeps its own
+// selector verdict.
+async function runAnchorQueries(root, queries, regs, stopAtFirstHit) {
+    if (!queries.length)
+        return [];
+    return withEventLedgerBuild(root, () => runAnchorQueriesInLedger(root, queries, regs, stopAtFirstHit));
+}
+async function runAnchorQueriesInLedger(root, queries, regs, stopAtFirstHit) {
+    const objectFormat = gitObjectFormat(root);
+    const revisions = new Map();
+    const ordinaryEvents = [];
+    for (const { win } of queries)
+        for (const event of win) {
+            const refs = [{ commit: event.commit, path: event.historicalPath }, ...event.parents.map(({ commit, historicalPath }) => ({ commit, path: historicalPath }))];
+            for (const ref of refs)
+                revisions.set(anchorRevisionKey(ref), ref);
+            if (event.parents.length > 1 || event.parents.some((parent) => parent.historicalPath !== event.historicalPath))
+                continue;
+            ordinaryEvents.push({ path: event.historicalPath, commit: event.commit, event });
+        }
+    const refs = [...revisions.values()];
+    const oids = await batchRevisionOids(root, refs.map(({ commit, path }) => `${commit}:${path}`));
+    // Every image this read will diff is now resolved, so the reusable hunk fact can be named by the identity
+    // that actually decides it: the result image and each parent image, in order, oid + historical path.
+    const oidByRef = new Map();
+    for (let index = 0; index < refs.length; index++)
+        oidByRef.set(anchorRevisionKey(refs[index]), oids[index]);
+    const imageOf = (commit, path) => `${oidByRef.get(anchorRevisionKey({ commit, path })) ?? ABSENT_IMAGE}:${path}`;
+    const imageIdentity = (event) => hunkMemoKey([
+        imageOf(event.commit, event.historicalPath),
+        ...event.parents.map(({ commit, historicalPath }) => imageOf(commit, historicalPath)),
+    ]);
+    const hunkKeys = new Set();
+    const ordinaryByPath = new Map();
+    for (const { path, commit, event } of ordinaryEvents) {
+        const entries = ordinaryByPath.get(path) ?? new Map();
+        const key = imageIdentity(event);
+        hunkKeys.add(key);
+        entries.set(commit, key);
+        ordinaryByPath.set(path, entries);
+    }
+    for (const { win } of queries)
+        for (const event of win)
+            hunkKeys.add(imageIdentity(event));
+    const durableHunks = readImmutableHunkFacts(root, hunkKeys);
+    for (const [key, ranges] of durableHunks)
+        rememberHunks(key, ranges);
+    const newHunks = new Map();
+    const ordinaryHunks = new Map();
+    for (const [path, entries] of ordinaryByPath) {
+        const rangesByCommit = await hunksAtMany(root, path, entries);
+        ordinaryHunks.set(path, rangesByCommit);
+        for (const [commit, key] of entries) {
+            const ranges = rangesByCommit.get(commit);
+            if (ranges && !durableHunks.has(key))
+                newHunks.set(key, ranges);
+        }
+    }
+    // The image's own memo answers before any bytes move, so the read asks git only for the revisions this
+    // process has not parsed yet — the retention half of the same rule the hunk demand set follows.
+    const units = new Map();
+    const primeUnits = async (keys) => {
+        const pending = [];
+        const wanted = new Set();
+        for (const key of keys) {
+            if (units.has(key))
+                continue;
+            const ref = revisions.get(key), oid = oidByRef.get(key) ?? null;
+            const x = extractorFor(regs, extOf(ref.path));
+            const ready = x?.ready();
+            if (!x || ready !== true) {
+                units.set(key, { unparseable: !x ? `no designated extractor for ${ref.path}` : String(ready) });
+                continue;
+            }
+            if (!oid) {
+                units.set(key, { absent: true });
+                continue;
+            }
+            const hit = fileRevisionUnitMemo.get(fileRevisionMemoKey(objectFormat, oid, x, ref.path));
+            if (hit) {
+                units.set(key, hit);
+                continue;
+            }
+            pending.push({ key, ref, oid, x });
+            wanted.add(oid);
+        }
+        if (!pending.length)
+            return;
+        const blobs = await batchBlobTexts(root, [...wanted]);
+        for (const { key, ref, oid, x } of pending)
+            units.set(key, await unitsAtFileRevision(ref.commit, ref.path, x, objectFormat, oid, blobs.get(oid)));
+    };
+    const intersects = (ranges, candidates) => ranges.some(([start, end]) => candidates.some((unit) => start <= unit.end && unit.start <= end));
+    // @@@ the scan advances in DOUBLING corpus-wide rounds - an existence read may stop at its window's first
+    // hit, but which event that is cannot be known before the images are parsed, so the demand set has to be
+    // discovered rather than declared. Each round still asks the WHOLE unsettled corpus at once (never one
+    // reading at a time, which is what would re-fork the batch per unit), and doubling bounds the rounds by hit
+    // DEPTH, not by how many readings are asked. An enumeration read takes its whole remaining window in one
+    // slice, so it keeps the single-round shape it has always had.
+    const runs = queries.map(() => ({ hits: new Map(), cursor: 0, settled: false }));
+    for (let chunk = 1;; chunk *= 2) {
+        const slices = [];
+        for (let index = 0; index < queries.length; index++) {
+            const run = runs[index], { win, symbols } = queries[index];
+            if (run.settled || run.cursor >= win.length)
+                continue;
+            slices.push({ run, symbols, events: win.slice(run.cursor, run.cursor + (stopAtFirstHit ? chunk : win.length - run.cursor)) });
+        }
+        if (!slices.length)
+            break;
+        const keys = new Set();
+        for (const { events } of slices)
+            for (const event of events) {
+                keys.add(anchorRevisionKey({ commit: event.commit, path: event.historicalPath }));
+                for (const parent of event.parents)
+                    keys.add(anchorRevisionKey({ commit: parent.commit, path: parent.historicalPath }));
+            }
+        await primeUnits(keys);
+        for (const { run, symbols, events } of slices) {
+            for (const event of events) {
+                run.cursor++;
+                const after = units.get(anchorRevisionKey({ commit: event.commit, path: event.historicalPath }));
+                const before = event.parents.map(({ commit, historicalPath }) => units.get(anchorRevisionKey({ commit, path: historicalPath })));
+                const key = imageIdentity(event);
+                const ranges = ordinaryHunks.get(event.historicalPath)?.get(event.commit)
+                    ?? await hunksAt(root, event, key);
+                if (!durableHunks.has(key))
+                    newHunks.set(key, ranges);
+                if (event.parents.length && ranges.before.length !== before.length)
+                    throw new Error(`anchor diff for ${event.commit}:${event.historicalPath} has ${ranges.before.length} parent ranges for ${before.length} parents`);
+                const hit = run.hits.get(event.commit) ?? { selectors: new Set() };
+                const broken = [after, ...before].find((image) => 'unparseable' in image);
+                if (broken && 'unparseable' in broken) {
+                    for (const symbol of symbols)
+                        hit.selectors.add(symbol);
+                    hit.unparseable = broken.unparseable;
+                }
+                else {
+                    for (const symbol of symbols) {
+                        const afterUnits = 'units' in after ? after.units.filter((unit) => unit.name === symbol) : [];
+                        const authoredAfter = intersects(ranges.after, afterUnits);
+                        const authoredBefore = before.length > 0 && before.every((image, parent) => 'units' in image && intersects(ranges.before[parent], image.units.filter((unit) => unit.name === symbol)));
+                        if (authoredAfter || authoredBefore)
+                            hit.selectors.add(symbol);
+                    }
+                }
+                if (hit.selectors.size)
+                    run.hits.set(event.commit, hit);
+                if (stopAtFirstHit && run.hits.size) {
+                    run.settled = true;
+                    break;
+                }
+            }
+        }
+    }
+    await persistImmutableHunkFacts(root, newHunks);
+    return runs.map((run) => [...run.hits].map(([commit, hit]) => ({ commit, selectors: [...hit.selectors], ...(hit.unparseable ? { unparseable: hit.unparseable } : {}) })));
+}
+// The two consumers ask DIFFERENT questions of this engine, so they enter through different doors rather
+// than through one call with a mode flag. Enumeration must scan every window event because its answer IS the
+// per-commit, per-selector list; existence is discharged by the first hit, and scanning past it computes rows
+// nobody reads.
+export async function anchorHitQueries(root, queries, regs) {
+    return runAnchorQueries(root, queries, regs, false);
+}
+export async function anchorHitExists(root, queries, regs) {
+    return (await runAnchorQueries(root, queries, regs, true)).map((hits) => hits.length > 0);
+}
+export async function anchorHitCommits(root, win, symbols, regs) {
+    return (await anchorHitQueries(root, [{ win, symbols }], regs))[0];
+}