@feng0531/dsh-code-review 0.83.0 → 0.84.0

package/src/git.mjs

@@ -2,57 +2,188 @@ import { isSecretPath } from './secret-path.mjs';
 import { realpath } from 'node:fs/promises';
 import { run, checked } from './process.mjs';
 import { hash, decode, readLocal, relativePath } from './content.mjs';
+import { changeScope } from './git-change-scope.mjs';
 
 const flags = ['--no-optional-locks', '-c', 'core.fsmonitor=false', '-c', 'core.untrackedCache=false'];
+const STATUS_ARGS = ['status', '--porcelain=v1', '-z', '--untracked-files=all', '--ignore-submodules=none'];
 const git = (cwd, args, options) => checked('git', [...flags, ...args], { ...options, cwd });
 const text = bytes => new TextDecoder('utf-8', { fatal: true }).decode(bytes);
 
-export async function captureGit(cwd, options = {}) {
-  const { signal, selectedPaths, maxFiles = 200, maxFileBytes = 256 * 1024 } = options;
-  if (selectedPaths) for (const name of selectedPaths) relativePath(name);
-  const root = await realpath(text(await git(cwd, ['rev-parse', '--show-toplevel'], options)).trim());
-  const statusArgs = ['status', '--porcelain=v1', '-z', '--untracked-files=all', '--ignore-submodules=none'];
-  const before = await git(root, statusArgs, options);
+async function resolveRoot(cwd, options) {
+  const top = text(await git(cwd, ['rev-parse', '--show-toplevel'], options)).trim();
+  return realpath(top);
+}
+
+/** HEAD commit sha, or null only for a genuinely unborn branch. */
+async function resolveHead(root, options) {
   const headResult = await run('git', [...flags, 'rev-parse', '--verify', 'HEAD'], { ...options, cwd: root });
-  // Only a genuinely unborn branch may use an empty baseline.
-  let head = headResult.code === 0 ? text(headResult.stdout).trim() : null;
-  if (!head) {
-    const branch = text(await git(root, ['symbolic-ref', 'HEAD'], options)).trim();
-    const ref = await run('git', [...flags, 'show-ref', '--verify', '--quiet', branch], { ...options, cwd: root });
-    if (ref.code !== 1) throw new Error('Cannot resolve Git HEAD');
-  }
-  const base = new Map();
-  // Resolve only reviewable changed baselines below; never enumerate the HEAD tree.
-  const records = text(before).split('\0');
+  const head = headResult.code === 0 ? text(headResult.stdout).trim() : null;
+  if (head) return head;
+  const branch = text(await git(root, ['symbolic-ref', 'HEAD'], options)).trim();
+  const ref = await run('git', [...flags, 'show-ref', '--verify', '--quiet', branch], { ...options, cwd: root });
+  if (ref.code !== 1) throw new Error('Cannot resolve Git HEAD');
+  return null;
+}
+
+function parseChanges(bytes) {
+  const records = text(bytes).split('\0');
   const changes = [];
   for (let i = 0; i < records.length; i++) {
     if (!records[i]) continue;
-    const rawStatus = records[i].slice(0, 2), name = records[i].slice(3);
+    const rawStatus = records[i].slice(0, 2);
+    const name = records[i].slice(3);
     let oldPath;
     if (/[RC]/.test(rawStatus)) oldPath = records[++i];
     changes.push({ path: name, ...(oldPath ? { oldPath } : {}), rawStatus });
   }
-  if (changes.length > maxFiles) throw new Error('Change count limit exceeded; narrow repository scope');
-  const known = new Set(changes.map(c => c.path));
-  if (selectedPaths?.some(p => !known.has(p))) throw new Error('Selected path is not a current change');
-  if (head) {
-    const requested = [...new Set(changes.filter(c => !isSecretPath(c.path) && !isSecretPath(c.oldPath) && (!selectedPaths || selectedPaths.includes(c.path)) && (c.rawStatus !== '??' || selectedPaths?.includes(c.path))).map(c => relativePath(c.oldPath ?? c.path)))];
-    for (const name of requested) {
-      signal?.throwIfAborted();
-      const records = text(await git(root, ['--literal-pathspecs','ls-tree','-z','--full-tree',head,'--',name], options)).split('\0').filter(Boolean);
-      for (const record of records) {
-        const m = /^(\d{6}) (blob|tree|commit) ([a-f0-9]{40}|[a-f0-9]{64})\t([\s\S]+)$/.exec(record);
-        if (!m || m[4] !== name || base.has(name)) throw new Error('Invalid changed baseline lookup');
-        base.set(name,{mode:m[1],type:m[2],oid:m[3]});
-      }
+  return changes;
+}
+
+/** Keep only the entries the requested comparison actually observes. */
+function changesInScope(changes, scope) {
+  if (scope === 'worktree') return changes;
+  if (scope === 'staged') return changes.filter(change => change.rawStatus[0] !== ' ' && change.rawStatus[0] !== '?');
+  return changes.filter(change => change.rawStatus[1] !== ' ' || change.rawStatus === '??');
+}
+
+/** Report only the status column this scope observes so identity follows the compared sides. */
+function scopeStatus(rawStatus, scope) {
+  if (scope === 'worktree') return rawStatus;
+  if (scope === 'staged') return rawStatus[0] + ' ';
+  return rawStatus === '??' ? '??' : ' ' + rawStatus[1];
+}
+
+/**
+ * Serialize one change for the snapshot. An unstaged entry compares index to worktree, so a
+ * staged rename's old path is not a side of that comparison and must not reach the model.
+ */
+function scopeEntry(change, scope) {
+  const oldPath = scope === 'unstaged' ? undefined : change.oldPath;
+  return { path: change.path, ...(oldPath ? { oldPath } : {}), rawStatus: scopeStatus(change.rawStatus, scope) };
+}
+
+/** Resolve only reviewable changed baselines; never enumerate the whole HEAD tree. */
+async function resolveBaselines(root, head, changes, selectedPaths, options, signal) {
+  const base = new Map();
+  const requested = [...new Set(changes
+    .filter(change =>
+      !isSecretPath(change.path) &&
+      !isSecretPath(change.oldPath) &&
+      (!selectedPaths || selectedPaths.includes(change.path)) &&
+      (change.rawStatus !== '??' || selectedPaths?.includes(change.path)))
+    .map(change => relativePath(change.oldPath ?? change.path)))];
+  for (const name of requested) {
+    signal?.throwIfAborted();
+    const records = text(await git(root, ['--literal-pathspecs', 'ls-tree', '-z', '--full-tree', head, '--', name], options)).split('\0').filter(Boolean);
+    for (const record of records) {
+      const m = /^(\d{6}) (blob|tree|commit) ([a-f0-9]{40}|[a-f0-9]{64})\t([\s\S]+)$/.exec(record);
+      if (!m || m[4] !== name || base.has(name)) throw new Error('Invalid changed baseline lookup');
+      base.set(name, { mode: m[1], type: m[2], oid: m[3] });
+    }
+  }
+  return base;
+}
+
+/**
+ * Resolve index entries for the selected paths only. Stage entries above zero mean an
+ * unresolved conflict; callers block those files instead of reading a partial side.
+ */
+async function resolveIndexEntries(root, names, options) {
+  const entries = new Map();
+  for (let i = 0; i < names.length; i += 64) {
+    const chunk = names.slice(i, i + 64);
+    const records = text(await git(root, ['--literal-pathspecs', 'ls-files', '--stage', '-z', '--', ...chunk], options)).split('\0');
+    for (const record of records) {
+      if (!record) continue;
+      const m = /^(\d{6}) ([a-f0-9]{40}|[a-f0-9]{64}) ([0-3])\t([\s\S]+)$/.exec(record);
+      if (!m || !chunk.includes(m[4])) throw new Error('Invalid index entry lookup');
+      if (entries.has(m[4])) entries.set(m[4], { conflict: true });
+      else entries.set(m[4], { mode: m[1], oid: m[2], stage: m[3] });
     }
   }
+  return entries;
+}
+
+/** Stable identity of the index entries a capture depends on; mode and content changes are caught even when status text is unchanged. */
+function indexIdentity(entries, names) {
+  return names.map(name => {
+    const entry = entries.get(name);
+    return name + '\0' + (entry ? (entry.conflict ? 'conflict' : entry.mode + ':' + entry.oid) : '');
+  }).join('\n');
+}
+
+function assertReviewableIndexEntry(entry) {
+  if (!entry) throw new Error('Missing index baseline');
+  if (entry.conflict || entry.stage !== '0') throw new Error('Unresolved conflict');
+  if (entry.mode === '120000' || entry.mode === '160000') throw new Error('Submodule or symbolic link baseline');
+}
+
+async function readIndexBlob(root, entry, options, maxFileBytes) {
+  let bytes;
+  try {
+    bytes = await git(root, ['cat-file', 'blob', entry.oid], { ...options, maxBytes: maxFileBytes });
+  } catch (error) {
+    if (/output limit exceeded/i.test(error.message)) throw new Error('File size limit exceeded');
+    throw error;
+  }
+  return decode(bytes);
+}
+
+/** A staged deletion has no index entry; every other staged path reads its index blob. */
+async function readStagedRight(root, entry, options, maxFileBytes) {
+  if (!entry) return { right: decode(Buffer.alloc(0)), rightExists: false };
+  assertReviewableIndexEntry(entry);
+  return { right: await readIndexBlob(root, entry, options, maxFileBytes), rightExists: true };
+}
+
+/** Unstaged left side is the index entry; untracked files have no index baseline. */
+async function readUnstagedLeft(root, change, entries, options, maxFileBytes) {
+  if (change.rawStatus === '??') return decode(Buffer.alloc(0));
+  const entry = entries.get(change.path);
+  assertReviewableIndexEntry(entry);
+  return readIndexBlob(root, entry, options, maxFileBytes);
+}
+
+/** Worktree and staged captures read the same HEAD baseline; unstaged uses the index instead. */
+async function readHeadLeft(root, change, baselines, options, maxFileBytes) {
+  const previous = baselines.get(change.oldPath ?? change.path);
+  if (previous && (previous.type !== 'blob' || previous.mode === '120000')) throw new Error('Submodule or symbolic link baseline');
+  return previous ? decode(await git(root, ['cat-file', 'blob', previous.oid], { ...options, maxBytes: maxFileBytes })) : decode(Buffer.alloc(0));
+}
+
+async function readWorktreeRight(root, change, options) {
+  try {
+    return { right: await readLocal(root, change.path, options), rightExists: true };
+  } catch (error) {
+    if (error.code === 'ENOENT' && change.rawStatus.includes('D')) return { right: decode(Buffer.alloc(0)), rightExists: false };
+    throw error;
+  }
+}
+
+export async function captureGit(cwd, options = {}) {
+  const { signal, selectedPaths, maxFiles = 200, maxFileBytes = 256 * 1024 } = options;
+  const scope = changeScope(options.changeScope);
+  if (selectedPaths) for (const name of selectedPaths) relativePath(name);
+  const root = await resolveRoot(cwd, options);
+  const before = await git(root, STATUS_ARGS, options);
+  const head = await resolveHead(root, options);
+  const changes = changesInScope(parseChanges(before), scope);
+  const counted = changes.filter(change => change.rawStatus !== '??' || selectedPaths?.includes(change.path));
+  if (counted.length > maxFiles) throw new Error('Change count limit exceeded; narrow repository scope');
+  const known = new Set(changes.map(c => c.path));
+  if (selectedPaths?.some(p => !known.has(p))) throw new Error('Selected path is not a current change in the selected scope');
+  const projectedBefore = scope === 'worktree' ? null : JSON.stringify(changes.map(change => scopeEntry(change, scope)));
+  const baselines = scope !== 'unstaged' && head ? await resolveBaselines(root, head, changes, selectedPaths, options, signal) : new Map();
+  const indexNames = scope === 'worktree' ? [] : [...new Set(changes.filter(change => change.rawStatus !== '??').map(change => change.path))];
+  const indexEntries = scope === 'worktree' ? new Map() : await resolveIndexEntries(root, indexNames, options);
+  const indexBefore = indexIdentity(indexEntries, indexNames);
+
   const files = [];
   for (const change of changes) {
     signal?.throwIfAborted();
-    const item = { ...change, id: hash(change.path), eligibility: 'reviewable', properties: [] };
+    const item = { ...scopeEntry(change, scope), id: hash(change.path), eligibility: 'reviewable', properties: [] };
     files.push(item);
-    if (isSecretPath(change.path) || isSecretPath(change.oldPath)) { item.eligibility='excluded'; item.reason='Credential path excluded'; continue; }
+    if (isSecretPath(change.path) || isSecretPath(change.oldPath)) { item.eligibility = 'excluded'; item.reason = 'Credential path excluded'; continue; }
     if ((selectedPaths && !selectedPaths.includes(change.path)) || (change.rawStatus === '??' && !selectedPaths?.includes(change.path))) {
       item.eligibility = 'excluded'; item.reason = 'Not explicitly selected'; continue;
     }
@@ -60,34 +191,45 @@ export async function captureGit(cwd, options = {}) {
       relativePath(change.path);
       if (change.oldPath) relativePath(change.oldPath);
       if (/U/.test(change.rawStatus) || ['AA', 'DD'].includes(change.rawStatus)) throw new Error('Unresolved conflict');
-      const previous = base.get(change.oldPath ?? change.path);
-      if (previous && (previous.type !== 'blob' || previous.mode === '120000')) throw new Error('Submodule or symbolic link baseline');
-      const left = previous ? await git(root, ['cat-file', 'blob', previous.oid], { ...options, maxBytes: maxFileBytes }) : Buffer.alloc(0);
-      item.left = decode(left);
-      try { item.right = await readLocal(root, change.path, options); item.rightExists = true; }
-      catch (error) {
-        if (error.code === 'ENOENT' && change.rawStatus.includes('D')) { item.right = decode(Buffer.alloc(0)); item.rightExists = false; }
-        else throw error;
+      const baselineExists = scope === 'unstaged' ? change.rawStatus !== '??' : baselines.has(change.oldPath ?? change.path);
+      item.left = scope === 'unstaged' ? await readUnstagedLeft(root, change, indexEntries, options, maxFileBytes) : await readHeadLeft(root, change, baselines, options, maxFileBytes);
+      const right = scope === 'staged'
+        ? await readStagedRight(root, change.rawStatus[0] === 'D' ? undefined : indexEntries.get(change.path), options, maxFileBytes)
+        : await readWorktreeRight(root, change, options);
+      item.right = right.right;
+      item.rightExists = right.rightExists;
+      if (baselineExists && item.rightExists && item.left.hash === item.right.hash && !item.oldPath) {
+        item.eligibility = 'excluded'; item.reason = 'No net content change (mode-only changes not analyzed)';
       }
-      if (previous && item.rightExists && item.left.hash === item.right.hash && !change.oldPath) { item.eligibility = 'excluded'; item.reason = 'No net content change (mode-only changes not analyzed)'; }
     } catch (error) {
       signal?.throwIfAborted();
       item.eligibility = 'blocked'; item.reason = error.message;
       delete item.left; delete item.right;
     }
   }
-  if (!(await git(root, statusArgs, options)).equals(before)) throw new Error('Repository changed during capture');
+
+  const after = await git(root, STATUS_ARGS, options);
+  const scopeUnchanged = scope === 'worktree'
+    ? after.equals(before)
+    : JSON.stringify(changesInScope(parseChanges(after), scope).map(change => scopeEntry(change, scope))) === projectedBefore;
+  if (!scopeUnchanged) throw new Error('Repository changed during capture');
   const finalHead = await run('git', [...flags, 'rev-parse', '--verify', 'HEAD'], { ...options, cwd: root });
   if ((finalHead.code === 0 ? text(finalHead.stdout).trim() : null) !== head) throw new Error('HEAD changed during capture');
-  for (const file of files.filter(f => f.right)) {
-    if (file.rightExists) {
-      if ((await readLocal(root, file.path, options)).hash !== file.right.hash) throw new Error('Content changed during capture');
-    } else {
-      try { await readLocal(root, file.path, options); }
-      catch (error) { if (error.code === 'ENOENT') continue; throw error; }
-      throw new Error('Deleted path reappeared during capture');
+  if (scope !== 'worktree') {
+    const entriesAfter = await resolveIndexEntries(root, indexNames, options);
+    if (indexIdentity(entriesAfter, indexNames) !== indexBefore) throw new Error('Index changed during capture');
+  }
+  if (scope !== 'staged') {
+    for (const file of files.filter(f => f.right)) {
+      if (file.rightExists) {
+        if ((await readLocal(root, file.path, options)).hash !== file.right.hash) throw new Error('Content changed during capture');
+      } else {
+        try { await readLocal(root, file.path, options); }
+        catch (error) { if (error.code === 'ENOENT') continue; throw error; }
+        throw new Error('Deleted path reappeared during capture');
+      }
     }
   }
-  const snapshot = { schemaVersion: 1, vcs: 'git', root, baseline: head, files };
+  const snapshot = { schemaVersion: 1, vcs: 'git', root, baseline: head, ...(scope === 'worktree' ? {} : { changeScope: scope }), files };
   return { ...snapshot, id: hash(JSON.stringify(snapshot)) };
 }

package/src/import-bindings.mjs

@@ -1,81 +1,90 @@
 // Conservative direct exported-function hints, never execution/reachability proof.
+function identifierPattern(name, suffix, flags = '') {
+  return new RegExp('(^|[^A-Za-z0-9_$])' + name.replaceAll('$', '\\$') + suffix, flags);
+}
+
 export function directImportBindings(lines, importLine, calls, targetText) {
- if (typeof targetText !== 'string' || Buffer.byteLength(targetText) > 256 * 1024 || /[\x60]|\/\*/.test(targetText)) return [];
- const match = /^\s*import\s+\{([^}]+)\}\s+from\s+(['"])[^'"]+\2\s*;?\s*(?:\/\/.*)?$/.exec(lines[importLine - 1]);
- if (!match) return [];
- const bindings = match[1].split(',').map(part => /^\s*([A-Za-z_$][A-Za-z0-9_$]*)(?:\s+as\s+([A-Za-z_$][A-Za-z0-9_$]*))?\s*$/.exec(part));
- if (bindings.some(b => !b)) return [];
- const targets = targetText.split(String.fromCharCode(10)), result = [];
- for (const binding of bindings) {
-  const imported = binding[1], local = binding[2] ?? imported;
-  const token = new RegExp('(^|[^A-Za-z0-9_$])' + local.replaceAll('$', '\\$') + '([^A-Za-z0-9_$]|$)');
-  const positions = calls.filter(c => c.local === local);
-  if (!positions.length) continue;
-  // Arguments may mutate/escape the alias on the SAME indexed call line.
-  // Keep a hint only when the sole local token is the call callee.
-  const occurrences = new RegExp('(^|[^A-Za-z0-9_$])' + local.replaceAll('$', '\\$') + '(?=[^A-Za-z0-9_$]|$)', 'g');
-  if (positions.some(call => [...lines[call.line - 1].matchAll(occurrences)].length !== 1)) continue;
-  // Every other occurrence may be declaration, parameter, mutation or escape.
-  if (lines.some((line, i) => i + 1 !== importLine && !positions.some(c => c.line === i + 1) && token.test(line))) continue;
-  const declarations = uniqueApprovedDeclarations(targets, imported);
-  if (declarations.length !== 1) continue;
-  const exportedToken = new RegExp('(^|[^A-Za-z0-9_$])' + imported.replaceAll('$', String.fromCharCode(92) + '$') + '([^A-Za-z0-9_$]|$)');
-  if (targets.some((line, i) => i + 1 !== declarations[0].number && exportedToken.test(line))) continue;
-  result.push(...positions.map(call => ({ imported, local, importLine, callLine: call.line, declarationLine: declarations[0].number, declarationKind: declarations[0].kind, confidence: 'conservative-syntax-only' })));
- }
- return result.slice(0, 20);
+  if (typeof targetText !== 'string' || Buffer.byteLength(targetText) > 256 * 1024 || /[\x60]|\/\*/.test(targetText)) return [];
+  const match = /^\s*import\s+\{([^}]+)\}\s+from\s+(['"])[^'"]+\2\s*;?\s*(?:\/\/.*)?$/.exec(lines[importLine - 1]);
+  if (!match) return [];
+  const bindings = match[1].split(',').map(part => /^\s*([A-Za-z_$][A-Za-z0-9_$]*)(?:\s+as\s+([A-Za-z_$][A-Za-z0-9_$]*))?\s*$/.exec(part));
+  if (bindings.some(b => !b)) return [];
+  const targets = targetText.split(String.fromCharCode(10));
+  const result = [];
+  for (const binding of bindings) {
+    const imported = binding[1], local = binding[2] ?? imported;
+    const token = identifierPattern(local, '([^A-Za-z0-9_$]|$)');
+    const positions = calls.filter(c => c.local === local);
+    if (!positions.length) continue;
+    // Arguments may mutate/escape the alias on the SAME indexed call line.
+    // Keep a hint only when the sole local token is the call callee.
+    const occurrences = identifierPattern(local, '(?=[^A-Za-z0-9_$]|$)', 'g');
+    if (positions.some(call => [...lines[call.line - 1].matchAll(occurrences)].length !== 1)) continue;
+    // Every other occurrence may be declaration, parameter, mutation or escape.
+    if (lines.some((line, i) => i + 1 !== importLine && !positions.some(c => c.line === i + 1) && token.test(line))) continue;
+    const declarations = uniqueApprovedDeclarations(targets, imported);
+    if (declarations.length !== 1) continue;
+    const exportedToken = identifierPattern(imported, '([^A-Za-z0-9_$]|$)');
+    if (targets.some((line, i) => i + 1 !== declarations[0].number && exportedToken.test(line))) continue;
+    result.push(...positions.map(call => ({ imported, local, importLine, callLine: call.line, declarationLine: declarations[0].number, declarationKind: declarations[0].kind, confidence: 'conservative-syntax-only' })));
+  }
+  return result.slice(0, 20);
 }
 
 // Only one direct declaration inside already approved text. No extra file reads.
 export function uniqueApprovedDeclarations(lines, imported) {
- if (!Array.isArray(lines) || lines.length > 20000 || typeof imported !== 'string' || !/^[A-Za-z_$][A-Za-z0-9_$]*$/.test(imported)) return [];
- const text=lines.join(String.fromCharCode(10));
- if (lines.some(line=>typeof line!=='string') || Buffer.byteLength(text)>256*1024 || text.includes('/*') || text.includes(String.fromCharCode(96)) || text.includes(String.fromCharCode(92,10)) || text.includes(String.fromCharCode(92,13,10))) return [];
- const forms = [
-  ['function', /^\s*export\s+(?:async\s+)?function\s+([A-Za-z_$][A-Za-z0-9_$]*)\s*\(/],
-  ['const', /^\s*export\s+(?:const|let)\s+([A-Za-z_$][A-Za-z0-9_$]*)\s*=/],
-  ['class', /^\s*export\s+class\s+([A-Za-z_$][A-Za-z0-9_$]*)(?=\s|\{)/]
- ];
- const found = [];
- for (let i = 0; i < lines.length; i++) {
-  for (const [kind, pattern] of forms) {
-   if (pattern.exec(lines[i])?.[1] === imported) found.push({ number: i + 1, kind });
+  if (!Array.isArray(lines) || lines.length > 20000 || typeof imported !== 'string' || !/^[A-Za-z_$][A-Za-z0-9_$]*$/.test(imported)) return [];
+  const text = lines.join(String.fromCharCode(10));
+  if (lines.some(line => typeof line !== 'string') || Buffer.byteLength(text) > 256 * 1024 || text.includes('/*') || text.includes(String.fromCharCode(96)) || text.includes(String.fromCharCode(92, 10)) || text.includes(String.fromCharCode(92, 13, 10))) return [];
+  const forms = [
+    ['function', /^\s*export\s+(?:async\s+)?function\s+([A-Za-z_$][A-Za-z0-9_$]*)\s*\(/],
+    ['const', /^\s*export\s+(?:const|let)\s+([A-Za-z_$][A-Za-z0-9_$]*)\s*=/],
+    ['class', /^\s*export\s+class\s+([A-Za-z_$][A-Za-z0-9_$]*)(?=\s|\{)/],
+  ];
+  const found = [];
+  for (let i = 0; i < lines.length; i++) {
+    for (const [kind, pattern] of forms) {
+      if (pattern.exec(lines[i])?.[1] === imported) found.push({ number: i + 1, kind });
+    }
   }
- }
- if (found.length !== 1) return [];
- const occurrences=new RegExp('(^|[^A-Za-z0-9_$])'+imported.replaceAll('$','\\$')+'(?=[^A-Za-z0-9_$]|$)','g');
- if ([...lines[found[0].number-1].matchAll(occurrences)].length!==1) return [];
- const token = new RegExp('(^|[^A-Za-z0-9_$])' + imported.replaceAll('$', '\\$') + '([^A-Za-z0-9_$]|$)');
- if (lines.some((line, i) => i + 1 !== found[0].number && token.test(line))) return [];
- return found;
+  if (found.length !== 1) return [];
+  const occurrences = identifierPattern(imported, '(?=[^A-Za-z0-9_$]|$)', 'g');
+  if ([...lines[found[0].number - 1].matchAll(occurrences)].length !== 1) return [];
+  const token = identifierPattern(imported, '([^A-Za-z0-9_$]|$)');
+  if (lines.some((line, i) => i + 1 !== found[0].number && token.test(line))) return [];
+  return found;
 }
 
 // Named imports only. Missing, duplicate, comment, or reexport names stay unresolved.
 export function namedImportDefinitions(importLine, targetText) {
- if (typeof targetText !== 'string' || Buffer.byteLength(targetText) > 256 * 1024 || /[\x60]|\/\*/.test(targetText)) return [];
- const match = /^\s*import\s+(?:[A-Za-z_$][A-Za-z0-9_$]*\s*,\s*)?\{([^}]+)\}\s+from\s+(['"])[^'"]+\2\s*;?\s*(?:\/\/.*)?$/.exec(importLine);
- if (!match) return [];
- const names = match[1].split(',').map(part => /^\s*([A-Za-z_$][A-Za-z0-9_$]*)(?:\s+as\s+([A-Za-z_$][A-Za-z0-9_$]*))?\s*$/.exec(part));
- if (!names.length || names.some(item => !item) || new Set(names.map(item => item[1])).size !== names.length || new Set(names.map(item => item[2] ?? item[1])).size !== names.length) return [];
- const lines = targetText.split(String.fromCharCode(10)), result = [];
- for (const name of names) {
-  const found = uniqueApprovedDeclarations(lines, name[1]);
-  if (found.length === 1) result.push({ imported: name[1], declarationLine: found[0].number, declarationKind: found[0].kind, confidence: 'approved-unique-syntax-only' });
- }
- return result.slice(0, 20);
+  if (typeof targetText !== 'string' || Buffer.byteLength(targetText) > 256 * 1024 || /[\x60]|\/\*/.test(targetText)) return [];
+  const match = /^\s*import\s+(?:[A-Za-z_$][A-Za-z0-9_$]*\s*,\s*)?\{([^}]+)\}\s+from\s+(['"])[^'"]+\2\s*;?\s*(?:\/\/.*)?$/.exec(importLine);
+  if (!match) return [];
+  const names = match[1].split(',').map(part => /^\s*([A-Za-z_$][A-Za-z0-9_$]*)(?:\s+as\s+([A-Za-z_$][A-Za-z0-9_$]*))?\s*$/.exec(part));
+  if (!names.length || names.some(item => !item) || new Set(names.map(item => item[1])).size !== names.length || new Set(names.map(item => item[2] ?? item[1])).size !== names.length) return [];
+  const lines = targetText.split(String.fromCharCode(10));
+  const result = [];
+  for (const name of names) {
+    const found = uniqueApprovedDeclarations(lines, name[1]);
+    if (found.length === 1) result.push({ imported: name[1], declarationLine: found[0].number, declarationKind: found[0].kind, confidence: 'approved-unique-syntax-only' });
+  }
+  return result.slice(0, 20);
 }
 
 // Unique default export inside already approved text; anonymous defaults keep their line only.
 export function defaultImportDefinition(importLine, targetText) {
- if (typeof targetText !== 'string' || Buffer.byteLength(targetText) > 256 * 1024 || /[\x60]|\/\*/.test(targetText)) return [];
- if (targetText.includes(String.fromCharCode(92,10)) || targetText.includes(String.fromCharCode(92,13,10))) return [];
- const match = /^\s*import\s+([A-Za-z_$][A-Za-z0-9_$]*)\s*(?:,\s*\{[^}]*\}\s*)?from\s+(['"])[^'"]+\2\s*;?\s*(?:\/\/.*)?$/.exec(importLine);
- if (!match) return [];
- const lines = targetText.split(String.fromCharCode(10)), declarations = [];
- for (let i = 0; i < lines.length; i++) if (/^\s*export\s+default\b/.test(lines[i])) declarations.push(i + 1);
- if (declarations.length !== 1) return [];
- const line = lines[declarations[0] - 1];
- const kind = /^\s*export\s+default\s+(?:function|class)\b/.test(line) ? 'default-declaration' : /^\s*export\s+default\s+[^=;]+;\s*(?:\/\/.*)?$/.test(line) ? 'default-expression' : undefined;
- if (!kind) return [];
- return [{ imported: 'default', local: match[1], declarationLine: declarations[0], declarationKind: kind, confidence: 'approved-default-syntax-only' }];
+  if (typeof targetText !== 'string' || Buffer.byteLength(targetText) > 256 * 1024 || /[\x60]|\/\*/.test(targetText)) return [];
+  if (targetText.includes(String.fromCharCode(92, 10)) || targetText.includes(String.fromCharCode(92, 13, 10))) return [];
+  const match = /^\s*import\s+([A-Za-z_$][A-Za-z0-9_$]*)\s*(?:,\s*\{[^}]*\}\s*)?from\s+(['"])[^'"]+\2\s*;?\s*(?:\/\/.*)?$/.exec(importLine);
+  if (!match) return [];
+  const lines = targetText.split(String.fromCharCode(10));
+  const declarations = [];
+  for (let i = 0; i < lines.length; i++) if (/^\s*export\s+default\b/.test(lines[i])) declarations.push(i + 1);
+  if (declarations.length !== 1) return [];
+  const line = lines[declarations[0] - 1];
+  const kind = /^\s*export\s+default\s+(?:function|class)\b/.test(line) ? 'default-declaration'
+    : /^\s*export\s+default\s+[^=;]+;\s*(?:\/\/.*)?$/.test(line) ? 'default-expression'
+    : undefined;
+  if (!kind) return [];
+  return [{ imported: 'default', local: match[1], declarationLine: declarations[0], declarationKind: kind, confidence: 'approved-default-syntax-only' }];
 }

package/src/job-progress.mjs

@@ -1,2 +1,21 @@
-import {recoveryCoverage} from './recovery-coverage.mjs';
-export function jobProgress(record){const r=recoveryCoverage(record),counts={completed:0,excluded:0,blocked:0,failed:0,cancelled:0,pending:0};for(const f of r.files)counts[f.status]=(counts[f.status]??0)+1;const terminal=!['queued','running'].includes(record.status);return {stage:record.stage,terminal,elapsedMs:Date.now()-Date.parse(record.createdAt),total:r.manifestSaved?r.files.length:null,counts,processed:r.files.filter(f=>!['pending'].includes(f.status)).length,percent:r.manifestSaved&&r.files.length?Math.floor(100*r.files.filter(f=>!['pending'].includes(f.status)).length/r.files.length):null,notice:'Percent measures terminal primary-file processing, not successful review or synthesis completion. Unknown capture denominator is null, never invented.'};}
+import { recoveryCoverage } from './recovery-coverage.mjs';
+
+const NOTICE = 'Percent measures terminal primary-file processing, not successful review or synthesis completion. Unknown capture denominator is null, never invented.';
+
+export function jobProgress(record) {
+  const r = recoveryCoverage(record);
+  const counts = { completed: 0, excluded: 0, blocked: 0, failed: 0, cancelled: 0, pending: 0 };
+  for (const f of r.files) counts[f.status] = (counts[f.status] ?? 0) + 1;
+  const terminal = !['queued', 'running'].includes(record.status);
+  const processed = r.files.filter(f => !['pending'].includes(f.status)).length;
+  return {
+    stage: record.stage,
+    terminal,
+    elapsedMs: Date.now() - Date.parse(record.createdAt),
+    total: r.manifestSaved ? r.files.length : null,
+    counts,
+    processed,
+    percent: r.manifestSaved && r.files.length ? Math.floor(100 * processed / r.files.length) : null,
+    notice: NOTICE,
+  };
+}

package/src/model-contract.mjs

@@ -1,2 +1,18 @@
 // Describe only transport shape; never invent evidence or fill missing fields.
-export function modelContract(input,instructions=''){let p;try{p=JSON.parse(input);}catch{return '';}if(!p||typeof p!=='object'||Array.isArray(p))return '';if(Array.isArray(p.candidates))return '本阶段必须返回 {"verdicts":[{"candidateId":"c1","verdict":"uncertain","reason":"证据不足原因","evidence":[]}]}，candidateId必须来自本次candidates；supported/refuted证据规则仍按原指令。不是findings响应。';if(/返回\{groups:/.test(instructions))return '本阶段返回groups数组，每项含fileIds和reason，文件身份必须来自输入，不是findings响应。';if(/仅制定审查计划/.test(instructions))return '本阶段返回 {"risks":[]} 或原指令要求的风险条目，不是findings。';if(p.sourceMode==='file-interaction')return '本阶段返回 {"findings":[],"limitations":[]}；发现必须包含原指令全部字段和跨文件interaction.editRefs。无足够跨文件证据时说明limitations，不编造。';if(p.file)return '本阶段最终返回 {"findings":[],"limitations":[]}。每项finding必须含fileId、severity（critical/high/medium/low）、title、evidence、trigger、impact、suggestion和anchor；fileId原样复制file.id，不用文件名替代。anchor.line用side/start/end/snippet且精确匹配原行；需要更多证据可按检索协议先返回requests。';return ''; }
+const VERDICT_CONTRACT = '本阶段必须返回 {"verdicts":[{"candidateId":"c1","verdict":"uncertain","reason":"证据不足原因","evidence":[]}]}，candidateId必须来自本次candidates；supported/refuted证据规则仍按原指令。不是findings响应。';
+const GROUPS_CONTRACT = '本阶段返回groups数组，每项含fileIds和reason，文件身份必须来自输入，不是findings响应。';
+const RISK_CONTRACT = '本阶段返回 {"risks":[]} 或原指令要求的风险条目，不是findings。';
+const INTERACTION_CONTRACT = '本阶段返回 {"findings":[],"limitations":[]}；发现必须包含原指令全部字段和跨文件interaction.editRefs。无足够跨文件证据时说明limitations，不编造。';
+const FINDINGS_CONTRACT = '本阶段最终返回 {"findings":[],"limitations":[]}。每项finding必须含fileId、severity（critical/high/medium/low）、title、evidence、trigger、impact、suggestion和anchor；fileId原样复制file.id，不用文件名替代。anchor.line用side/start/end/snippet且精确匹配原行；需要更多证据可按检索协议先返回requests。';
+
+export function modelContract(input, instructions = '') {
+  let p;
+  try { p = JSON.parse(input); } catch { return ''; }
+  if (!p || typeof p !== 'object' || Array.isArray(p)) return '';
+  if (Array.isArray(p.candidates)) return VERDICT_CONTRACT;
+  if (/返回\{groups:/.test(instructions)) return GROUPS_CONTRACT;
+  if (/仅制定审查计划/.test(instructions)) return RISK_CONTRACT;
+  if (p.sourceMode === 'file-interaction') return INTERACTION_CONTRACT;
+  if (p.file) return FINDINGS_CONTRACT;
+  return '';
+}