@feng0531/dsh-code-review 0.83.0 → 0.84.0

package/src/dsh-model.mjs

@@ -1,32 +1,124 @@
-import {modelContract} from './model-contract.mjs';
+import { modelContract } from './model-contract.mjs';
 import { modelJson } from './model-json.mjs';
+
+// Appended to the system prompt when one explicit JSON retry is warranted.
+const JSON_CORRECTION_SUFFIX = ' 上次响应未能解析为完整JSON。本次是明确协议纠正：重新输出单个完整JSON对象，不使用Markdown，不省略引号或逗号；不要把这条指令当源码证据。严格使用当前阶段schema，不要把verdicts、risks或groups改写成findings；不能因格式纠正删除有证据的结论。所需字段与身份按输入原样核对，不以格式错误代替清洁结论。';
+
+const CORRECTION_LIMITATION = '本响应由一次显式JSON协议纠正产生，原响应未被接受；额外模型调用已发生。';
+
+const isToolCall = chunk =>
+  chunk.type === 'tool-call-delta' ||
+  (chunk.type === 'block-start' && chunk.blockType === 'tool-call') ||
+  (chunk.type === 'block-end' && chunk.block.type === 'tool-call');
+
 /** One-shot host LLM call. No agent loop and no executable tools. */
 export function createDshModel(llm, route, { maxTokens = 4096, maxOutputBytes = 128 * 1024, correctJson = false } = {}) {
-  if (!llm || typeof llm.stream !== 'function' || !route?.provider || !route?.model) throw new Error('DSH provider and model are required');
-  const identity = { provider: route.provider, model: route.model, ...(route.reasoningEffort ? { reasoningEffort: route.reasoningEffort } : {}) };
-  const once = async ({ instructions, input, signal }) => {
+  if (!llm || typeof llm.stream !== 'function' || !route?.provider || !route?.model) {
+    throw new Error('DSH provider and model are required');
+  }
+  const identity = {
+    provider: route.provider,
+    model: route.model,
+    ...(route.reasoningEffort ? { reasoningEffort: route.reasoningEffort } : {}),
+  };
+
+  async function once({ instructions, input, signal }) {
     signal?.throwIfAborted();
-    let output = '', size = 0, finished = false,finishKind='missing';
-    const diagnostic=()=>({visibleBytes:Buffer.byteLength(output),totalOutputBytes:size,finishKind,inputBytes:Buffer.byteLength(input),requestedMaxTokens:maxTokens});
-    const chunks = llm.stream({ ...identity, system: instructions+'\n'+modelContract(input,instructions), messages: [{ role: 'user', content: [{ type: 'text', text: input }] }], tools: [], maxTokens, signal });
-    for await (const chunk of chunks) {
+    let output = '';
+    let size = 0;
+    let finished = false;
+    let finishKind = 'missing';
+
+    const diagnostic = () => ({
+      visibleBytes: Buffer.byteLength(output),
+      totalOutputBytes: size,
+      finishKind,
+      inputBytes: Buffer.byteLength(input),
+      requestedMaxTokens: maxTokens,
+    });
+
+    const providerCode = reason =>
+      typeof reason.error?.code === 'string' ? reason.error.code
+        : typeof reason.code === 'string' ? reason.code
+        : undefined;
+
+    const stream = llm.stream({
+      ...identity,
+      system: instructions + '\n' + modelContract(input, instructions),
+      messages: [{ role: 'user', content: [{ type: 'text', text: input }] }],
+      tools: [],
+      maxTokens,
+      signal,
+    });
+
+    for await (const chunk of stream) {
       signal?.throwIfAborted();
       if (finished) throw new Error('Model emitted data after finish');
-      if (chunk.type === 'tool-call-delta' || (chunk.type === 'block-start' && chunk.blockType === 'tool-call') || (chunk.type === 'block-end' && chunk.block.type === 'tool-call')) throw new Error('Review model attempted a tool call');
+      if (isToolCall(chunk)) throw new Error('Review model attempted a tool call');
+
       if (chunk.type === 'text-delta' || chunk.type === 'reasoning-delta') {
         size += Buffer.byteLength(chunk.text);
         if (size > maxOutputBytes) throw new Error('Model output limit exceeded');
         if (chunk.type === 'text-delta') output += chunk.text;
       }
+
       if (chunk.type === 'finish') {
-        finishKind=chunk.reason.kind;
-        if (finishKind !== 'stop') throw Object.assign(new Error('Model did not complete: '+finishKind),{code:'MODEL_INCOMPLETE_OUTPUT',diagnostic:{...diagnostic(),providerCode:typeof chunk.reason.error?.code==='string'?chunk.reason.error.code:typeof chunk.reason.code==='string'?chunk.reason.code:undefined}});
+        finishKind = chunk.reason.kind;
+        if (finishKind !== 'stop') {
+          throw Object.assign(new Error('Model did not complete: ' + finishKind), {
+            code: 'MODEL_INCOMPLETE_OUTPUT',
+            diagnostic: { ...diagnostic(), providerCode: providerCode(chunk.reason) },
+          });
+        }
         finished = true;
       }
     }
-    if (!finished) throw Object.assign(new Error('Model stream ended without finish'),{code:'MODEL_INCOMPLETE_OUTPUT',diagnostic:diagnostic()});
-    try{return modelJson(output);}catch(error){error.diagnostic=diagnostic();throw error;}
+
+    if (!finished) {
+      throw Object.assign(new Error('Model stream ended without finish'), {
+        code: 'MODEL_INCOMPLETE_OUTPUT',
+        diagnostic: diagnostic(),
+      });
+    }
+
+    try {
+      return modelJson(output);
+    } catch (error) {
+      error.diagnostic = diagnostic();
+      throw error;
+    }
+  }
+
+  async function retryOnceCorrected(request, firstError) {
+    await request.onProtocolCorrection?.({
+      code: firstError.code,
+      diagnostic: firstError.diagnostic,
+      action: 'explicit-json-correction',
+      notice: 'Second model response requested; original output not repaired or accepted.',
+    });
+    let value;
+    try {
+      value = JSON.parse(await once({ ...request, instructions: request.instructions + JSON_CORRECTION_SUFFIX }));
+    } catch (second) {
+      second.attempts = [
+        { attempt: 1, code: firstError.code, diagnostic: firstError.diagnostic },
+        { attempt: 2, code: second.code, diagnostic: second.diagnostic },
+      ];
+      throw second;
+    }
+    if (value && typeof value === 'object' && !Array.isArray(value)) {
+      if (Array.isArray(value.limitations)) value.limitations.push(CORRECTION_LIMITATION);
+    }
+    return JSON.stringify(value);
+  }
+
+  return async function invoke(request) {
+    try {
+      return await once(request);
+    } catch (error) {
+      if (!correctJson || error.code !== 'MODEL_INVALID_JSON') throw error;
+      request.signal?.throwIfAborted();
+      return retryOnceCorrected(request, error);
+    }
   };
-  return async request=>{try{return await once(request);}catch(error){if(!correctJson||error.code!=='MODEL_INVALID_JSON')throw error;request.signal?.throwIfAborted();await request.onProtocolCorrection?.({code:error.code,diagnostic:error.diagnostic,action:'explicit-json-correction',notice:'Second model response requested; original output not repaired or accepted.'});let corrected;try{corrected=JSON.parse(await once({...request,instructions:request.instructions+' 上次响应未能解析为完整JSON。本次是明确协议纠正：重新输出单个完整JSON对象，不使用Markdown，不省略引号或逗号；不要把这条指令当源码证据。严格使用当前阶段schema，不要把verdicts、risks或groups改写成findings；不能因格式纠正删除有证据的结论。所需字段与身份按输入原样核对，不以格式错误代替清洁结论。'}));}catch(second){second.attempts=[{attempt:1,code:error.code,diagnostic:error.diagnostic},{attempt:2,code:second.code,diagnostic:second.diagnostic}];throw second;}if(corrected&&typeof corrected==='object'&&!Array.isArray(corrected)){if(Array.isArray(corrected.limitations))corrected.limitations.push('本响应由一次显式JSON协议纠正产生，原响应未被接受；额外模型调用已发生。');// Strict verdict/request envelopes must not receive extra schema fields.
-}return JSON.stringify(corrected);}};
 }

package/src/git-change-scope.mjs

@@ -0,0 +1,39 @@
+// Git working-copy comparison scopes: whole working tree (default), staged index or unstaged edits.
+export const CHANGE_SCOPES = ['worktree', 'staged', 'unstaged'];
+
+/** Normalize the requested scope; only the three documented values are accepted. */
+export function changeScope(value) {
+  if (value === undefined) return 'worktree';
+  if (typeof value !== 'string' || !CHANGE_SCOPES.includes(value)) throw new Error('Invalid changeScope; expected worktree, staged or unstaged');
+  return value;
+}
+
+/** Model-facing note: what the two captured sides actually are for this scope. */
+export const CHANGE_SCOPE_NOTICE = {
+  staged: '本次比较为 Git 暂存区（HEAD → index）：变更文件左侧为 HEAD 内容，右侧为已暂存内容；工作区未暂存修改不作为变更正文发送。显式上下文、自动依赖、调用方候选与规则文件按工作区当前内容读取，可能包含未暂存修改。',
+  unstaged: '本次比较为 Git 未暂存改动（index → 工作区）：左侧为已暂存内容，仅作旧侧基线；右侧为工作区文件。已暂存内容不代表由本次未暂存改动引入。',
+};
+
+/** Preview/report label: disclose the exact comparison and its exclusions. */
+export const CHANGE_SCOPE_LABEL = {
+  staged: 'Git 暂存区（HEAD → index），不包含工作区未暂存修改；上下文与规则文件按工作区读取',
+  unstaged: 'Git 未暂存改动（index → 工作区），已暂存内容仅作旧侧基线',
+};
+
+/** Preview notice: tell the user what will be sent before confirmation. */
+export const CHANGE_SCOPE_PREVIEW_NOTICE = {
+  staged: '本次审查范围是 Git 暂存区（HEAD → index）：只发送已暂存变更内容，工作区未暂存修改不作为变更正文；如选择上下文、自动依赖、调用方或规则文件，它们按工作区当前内容读取。',
+  unstaged: '本次审查范围是 Git 未暂存改动（index → 工作区）：已暂存内容只作为旧侧基线。',
+};
+
+export function changeScopeNotice(scope) {
+  return CHANGE_SCOPE_NOTICE[scope];
+}
+
+export function changeScopeLabel(scope) {
+  return CHANGE_SCOPE_LABEL[scope];
+}
+
+export function changeScopePreviewNotice(scope) {
+  return CHANGE_SCOPE_PREVIEW_NOTICE[scope];
+}

package/src/git-history.mjs

@@ -1,59 +1,205 @@
-import {captureHistoryCallers} from './history-caller-capture.mjs';
+import { captureHistoryCallers } from './history-caller-capture.mjs';
 import { isSecretPath, assertNonSecretPath } from './secret-path.mjs';
-import {captureProjectRules} from './project-rules.mjs';
-import {captureHistoryDependencyChain} from './history-dependency-chain.mjs';
-import {realpath} from 'node:fs/promises';
-import {checked} from './process.mjs';
-import {hash,decode,relativePath} from './content.mjs';
-const utf8=b=>new TextDecoder('utf-8',{fatal:true}).decode(b);
+import { captureProjectRules } from './project-rules.mjs';
+import { captureHistoryDependencyChain } from './history-dependency-chain.mjs';
+import { realpath } from 'node:fs/promises';
+import { checked } from './process.mjs';
+import { hash, decode, relativePath } from './content.mjs';
+
+const utf8 = b => new TextDecoder('utf-8', { fatal: true }).decode(b);
+const SHA = /^(?:[a-f0-9]{40}|[a-f0-9]{64})$/;
+const REGULAR_BLOB = e => e?.type === 'blob' && ['100644', '100755'].includes(e.mode);
+
+const gitAt = (root, args, options, limit = 1024 * 1024) =>
+  checked('git', ['--no-optional-locks', '-c', 'core.fsmonitor=false', '-c', 'core.untrackedCache=false', ...args], { ...options, cwd: root, maxBytes: limit });
+
+async function resolveCommit(root, ref, options) {
+  if (typeof ref !== 'string' || !ref || ref.length > 256 || ref.startsWith('-') || /[\s\0]/.test(ref)) throw new Error('Invalid revision');
+  const oid = utf8(await gitAt(root, ['rev-parse', '--verify', '--end-of-options', ref + '^{commit}'], options)).trim();
+  if (!SHA.test(oid)) throw new Error('Invalid commit object');
+  return oid;
+}
+
+function parseCommitParents(objectText) {
+  const header = objectText.split('\n\n', 1)[0];
+  const parents = header.split('\n').filter(line => line.startsWith('parent ')).map(line => line.slice(7));
+  if (parents.some(oid => !SHA.test(oid))) throw new Error('Invalid commit parent');
+  return parents;
+}
+
+/** Parse \`git diff-tree --raw -z\` into left/right blob maps plus the sorted path list. */
+function parseDiffMeta(raw) {
+  if (raw.at(-1) === '') raw.pop();
+  if (raw.length % 2) throw new Error('Invalid historical diff metadata');
+  const left = new Map(), right = new Map(), names = [];
+  for (let i = 0; i < raw.length; i += 2) {
+    const m = /^:(\d{6}) (\d{6}) ([\da-f]{40}|[\da-f]{64}) ([\da-f]{40}|[\da-f]{64}) ([AMDT])$/.exec(raw[i]);
+    if (!m) throw new Error('Invalid historical diff metadata');
+    const name = relativePath(raw[i + 1]);
+    if (names.includes(name)) throw new Error('Duplicate historical change');
+    names.push(name);
+    for (const [map, mode, oid] of [[left, m[1], m[3]], [right, m[2], m[4]]]) {
+      if (mode !== '000000') map.set(name, { mode, type: mode === '160000' ? 'commit' : 'blob', oid });
+    }
+  }
+  names.sort();
+  return { left, right, names };
+}
+
+// Literal, nonrecursive lookups cannot enumerate a supplied directory or wildcard.
+async function lookupPaths(root, oid, map, requested, options) {
+  if (!oid) return;
+  const pending = [...new Set(requested)].filter(p => !map.has(p));
+  for (let i = 0; i < pending.length; i++) {
+    const paths = pending.slice(i, i + 1);
+    paths.forEach(relativePath);
+    const records = utf8(await gitAt(root, ['--literal-pathspecs', 'ls-tree', '-z', '--full-tree', oid, '--', ...paths], options)).split('\0').filter(Boolean);
+    for (const r of records) {
+      const m = /^(\d{6}) (blob|commit|tree) ([a-f0-9]+)\t([\s\S]+)$/.exec(r);
+      if (!m || !paths.includes(m[4])) throw new Error('Invalid historical path lookup');
+      map.set(m[4], { mode: m[1], type: m[2], oid: m[3] });
+    }
+  }
+}
+
 // Object-only capture: no checkout, worktree reads, external diff or fetch.
-export async function captureGitHistory(cwd, options={}) {
- const {commit,baseRevision,targetRevision,selectedPaths,signal,maxFiles=200,maxFileBytes=256*1024,maxSnapshotBytes=4*1024*1024}=options;
- if(!Number.isSafeInteger(maxFiles)||maxFiles<1||maxFiles>200||!Number.isSafeInteger(maxFileBytes)||maxFileBytes<1||maxFileBytes>256*1024||!Number.isSafeInteger(maxSnapshotBytes)||maxSnapshotBytes<1||maxSnapshotBytes>4*1024*1024)throw new Error('Invalid historical capture limits');
- if(selectedPaths!==undefined&&(!Array.isArray(selectedPaths)||selectedPaths.some(p=>relativePath(p)!==p)))throw new Error('Invalid selected paths');
- const git=(root,args,limit=1024*1024)=>checked('git',['--no-optional-locks','-c','core.fsmonitor=false','-c','core.untrackedCache=false',...args],{...options,cwd:root,maxBytes:limit});
- const root=await realpath(utf8(await git(cwd,['rev-parse','--show-toplevel'])).trim());
- const resolve=async ref=>{if(typeof ref!=='string'||!ref||ref.length>256||ref.startsWith('-')||/[\s\0]/.test(ref))throw new Error('Invalid revision');const oid=utf8(await git(root,['rev-parse','--verify','--end-of-options',ref+'^{commit}'])).trim();if(!/^(?:[a-f0-9]{40}|[a-f0-9]{64})$/.test(oid))throw new Error('Invalid commit object');return oid;};
- let base,target;
- if(commit!==undefined){if(baseRevision!==undefined||targetRevision!==undefined)throw new Error('Commit and range are mutually exclusive');target=await resolve(commit);const object=utf8(await git(root,['cat-file','commit',target]));const header=object.split('\n\n',1)[0];const parents=header.split('\n').filter(line=>line.startsWith('parent ')).map(line=>line.slice(7));if(parents.some(oid=>!/^(?:[a-f0-9]{40}|[a-f0-9]{64})$/.test(oid)))throw new Error('Invalid commit parent');if(parents.length>1)throw new Error('Merge commit requires explicit revision range');base=parents[0]??null;}
- else {base=await resolve(baseRevision);target=await resolve(targetRevision);}
- // Metadata scales with changed paths, not every tracked file in either tree.
- const raw=utf8(await git(root,['diff-tree','--no-abbrev','--raw','-z','-r','--no-renames','--no-ext-diff','--no-textconv','--no-commit-id',...(base?[base,target]:['--root',target]),'--'])).split('\0');
- if(raw.at(-1)==='')raw.pop();
- const left=new Map(),right=new Map(),names=[];
- if(raw.length%2)throw new Error('Invalid historical diff metadata');
- for(let i=0;i<raw.length;i+=2){const m=/^:(\d{6}) (\d{6}) ([a-f0-9]{40}|[a-f0-9]{64}) ([a-f0-9]{40}|[a-f0-9]{64}) ([AMDT])$/.exec(raw[i]);if(!m)throw new Error('Invalid historical diff metadata');const name=relativePath(raw[i+1]);if(names.includes(name))throw new Error('Duplicate historical change');names.push(name);for(const [map,mode,oid] of [[left,m[1],m[3]],[right,m[2],m[4]]])if(mode!=='000000')map.set(name,{mode,type:mode==='160000'?'commit':'blob',oid});}
- names.sort();
- // Literal, nonrecursive lookups cannot enumerate a supplied directory or wildcard.
- const lookup=async (oid,map,requested)=>{if(!oid)return;const pending=[...new Set(requested)].filter(p=>!map.has(p));for(let i=0;i<pending.length;i++){const paths=pending.slice(i,i+1);paths.forEach(relativePath);const records=utf8(await git(root,['--literal-pathspecs','ls-tree','-z','--full-tree',oid,'--',...paths])).split('\0').filter(Boolean);for(const r of records){const m=/^(\d{6}) (blob|commit|tree) ([a-f0-9]+)\t([\s\S]+)$/.exec(r);if(!m||!paths.includes(m[4]))throw new Error('Invalid historical path lookup');map.set(m[4],{mode:m[1],type:m[2],oid:m[3]});}}};
- if(names.length>maxFiles)throw new Error('Historical change count limit exceeded');if(selectedPaths?.some(p=>!names.includes(p)))throw new Error('Selected path is not a historical change');
- const files=[];for(const name of names){signal?.throwIfAborted();const l=left.get(name),r=right.get(name),item={id:hash(name),path:name,rawStatus:!l?'A':!r?'D':'M',eligibility:'reviewable',properties:[]};files.push(item);if(isSecretPath(name)){item.eligibility='excluded';item.reason='Credential path excluded';continue;}if(selectedPaths&&!selectedPaths.includes(name)){item.eligibility='excluded';item.reason='Not explicitly selected';continue;}try{for(const e of [l,r].filter(Boolean))if(e.type!=='blob'||!['100644','100755'].includes(e.mode))throw new Error('Historical link or submodule excluded');const read=async e=>decode(e?await git(root,['cat-file','blob',e.oid],maxFileBytes):Buffer.alloc(0));item.left=await read(l);item.right=await read(r);item.rightExists=!!r;if(l&&r&&item.left.hash===item.right.hash){item.eligibility='excluded';item.reason='Mode-only historical change not analyzed';}}catch(error){signal?.throwIfAborted();item.eligibility='blocked';item.reason=error.message;delete item.left;delete item.right;}if(Buffer.byteLength(JSON.stringify(files))>maxSnapshotBytes)throw new Error('Historical snapshot limit exceeded');}
- const rulePaths=options.rulePaths ?? [];
- const contextPaths=options.contextPaths ?? [], oldContextPaths=options.oldContextPaths ?? [], maxContextFiles=options.maxContextFiles ?? 20;
- if(!Array.isArray(oldContextPaths)||oldContextPaths.length>20||new Set(oldContextPaths).size!==oldContextPaths.length)throw new Error('Invalid old context paths');
- for(const name of oldContextPaths){relativePath(name);assertNonSecretPath(name);}
- if(oldContextPaths.length&&!base)throw new Error('Old context requires nonempty historical baseline');
- if(!Array.isArray(contextPaths)||!Array.isArray(rulePaths))throw new Error('Invalid historical context or rule paths');
- if(oldContextPaths.some(p=>contextPaths.includes(p)||rulePaths.includes(p)))throw new Error('Old context paths must be separate');
- if(contextPaths.length+oldContextPaths.length>maxContextFiles)throw new Error('Historical context file limit exceeded');
- if(!Array.isArray(contextPaths)||!Number.isSafeInteger(maxContextFiles)||maxContextFiles<1||maxContextFiles>20||contextPaths.length>maxContextFiles)throw new Error('Historical context file limit exceeded');
- if(options.autoContext!==undefined&&typeof options.autoContext!=='boolean')throw new Error('Invalid autoContext option');
- if(!Array.isArray(rulePaths)||rulePaths.length>4||rulePaths.some(p=>contextPaths.includes(p)))throw new Error('Rule paths must be separate from context paths');
- await lookup(target,right,[...contextPaths,...rulePaths]);await lookup(base,left,[...contextPaths,...oldContextPaths]);
- const context=[], regular=e=>e?.type==='blob'&&['100644','100755'].includes(e.mode);
- const captureContext=async name=>{relativePath(name);assertNonSecretPath(name);const changed=files.find(f=>f.path===name);if(changed){if(changed.eligibility!=='reviewable'||changed.rightExists===false)throw new Error('Historical context is excluded blocked or deleted');return {path:name,...changed.right};}const entry=right.get(name);if(!regular(entry))throw new Error('Historical context not a target regular blob');const content=decode(await git(root,['cat-file','blob',entry.oid],maxFileBytes));const previous=left.get(name);return {path:name,...content,revision:target,...(regular(previous)?{oldText:decode(await git(root,['cat-file','blob',previous.oid],maxFileBytes)).text,oldRevision:base}:{})};};
- for(const name of [...new Set(contextPaths)].sort())context.push(await captureContext(name));
- for(const name of [...oldContextPaths].sort()){
-  const changed=files.find(f=>f.path===name);
-  if(changed){if(changed.eligibility!=='reviewable'||!left.has(name))throw new Error('Old context conflicts with excluded blocked or absent old change');continue;}
-  const entry=left.get(name);if(!regular(entry))throw new Error('Old context not a baseline regular blob');
-  const content=decode(await git(root,['cat-file','blob',entry.oid],maxFileBytes));
-  context.push({path:name,oldOnly:true,oldText:content.text,oldHash:hash(content.text),oldBlobOid:entry.oid,oldRevision:base});
- }
- const rules=await captureProjectRules(root,rulePaths,{signal,files,read:async (_root,name,{maxFileBytes:limit})=>{const entry=right.get(name);if(!regular(entry))throw new Error('Historical rule not a target regular blob');return decode(await git(root,['cat-file','blob',entry.oid],limit));}});
- let autoContext;
- if(options.autoContext===true)autoContext=await captureHistoryDependencyChain(root,files,{base,target},context,options);
- let callerDiscovery;
- if(options.callerScopePaths!==undefined){const callers=await captureHistoryCallers(root,files,{base,target},options.callerScopePaths,options);callerDiscovery=callers.discovery;for(const item of callers.context){const matches=callerDiscovery.candidates.filter(c=>c.fromPath===item.path),present=context.find(c=>c.path===item.path);if(present){if((present.text!==undefined&&present.text!==item.text)||(present.oldText!==undefined&&present.oldText!==item.oldText))throw new Error('Historical caller context identity conflict');for(const c of matches){const available=c.side==='old'?present.oldText!==undefined:present.text!==undefined;c.status=available?'reused-context':'blocked';if(!available)c.captureReason='Existing context did not approve this version side';}continue;}if(context.length>=maxContextFiles){for(const c of matches){c.status='blocked';c.captureReason='Context file limit exceeded';}continue;}context.push(item);callerDiscovery.capturedPaths.push(item.path);for(const c of matches)c.status='captured';}}
- const snapshot={context,...(callerDiscovery?{callerDiscovery}:{}),...(rules.length?{rules}:{}),...(autoContext?{autoContext}:{}),schemaVersion:1,vcs:'git',root,baseline:base,history:{mode:commit!==undefined?'commit':'range',base,target,semantics:'exact-tree-endpoints; renames represented as add/delete'},files};const serialized=JSON.stringify(snapshot);if(Buffer.byteLength(serialized)>maxSnapshotBytes)throw new Error('Historical snapshot limit exceeded');return {...snapshot,id:hash(serialized)};
+export async function captureGitHistory(cwd, options = {}) {
+  const { commit, baseRevision, targetRevision, selectedPaths, signal, maxFiles = 200, maxFileBytes = 256 * 1024, maxSnapshotBytes = 4 * 1024 * 1024 } = options;
+  if (!Number.isSafeInteger(maxFiles) || maxFiles < 1 || maxFiles > 200 || !Number.isSafeInteger(maxFileBytes) || maxFileBytes < 1 || maxFileBytes > 256 * 1024 || !Number.isSafeInteger(maxSnapshotBytes) || maxSnapshotBytes < 1 || maxSnapshotBytes > 4 * 1024 * 1024) throw new Error('Invalid historical capture limits');
+  if (selectedPaths !== undefined && (!Array.isArray(selectedPaths) || selectedPaths.some(p => relativePath(p) !== p))) throw new Error('Invalid selected paths');
+
+  const root = await realpath(utf8(await gitAt(cwd, ['rev-parse', '--show-toplevel'], options)).trim());
+
+  // Resolve the two endpoints: commit compares against its sole parent; range uses explicit endpoints.
+  let base, target;
+  if (commit !== undefined) {
+    if (baseRevision !== undefined || targetRevision !== undefined) throw new Error('Commit and range are mutually exclusive');
+    target = await resolveCommit(root, commit, options);
+    const object = utf8(await gitAt(root, ['cat-file', 'commit', target], options));
+    const parents = parseCommitParents(object);
+    if (parents.length > 1) throw new Error('Merge commit requires explicit revision range');
+    base = parents[0] ?? null;
+  } else {
+    base = await resolveCommit(root, baseRevision, options);
+    target = await resolveCommit(root, targetRevision, options);
+  }
+
+  // Metadata scales with changed paths, not every tracked file in either tree.
+  const raw = utf8(await gitAt(root, ['diff-tree', '--no-abbrev', '--raw', '-z', '-r', '--no-renames', '--no-ext-diff', '--no-textconv', '--no-commit-id', ...(base ? [base, target] : ['--root', target]), '--'], options)).split('\0');
+  const { left, right, names } = parseDiffMeta(raw);
+
+  if (names.length > maxFiles) throw new Error('Historical change count limit exceeded');
+  if (selectedPaths?.some(p => !names.includes(p))) throw new Error('Selected path is not a historical change');
+
+  const files = [];
+  for (const name of names) {
+    signal?.throwIfAborted();
+    const l = left.get(name), r = right.get(name);
+    const item = { id: hash(name), path: name, rawStatus: !l ? 'A' : !r ? 'D' : 'M', eligibility: 'reviewable', properties: [] };
+    files.push(item);
+    if (isSecretPath(name)) { item.eligibility = 'excluded'; item.reason = 'Credential path excluded'; continue; }
+    if (selectedPaths && !selectedPaths.includes(name)) { item.eligibility = 'excluded'; item.reason = 'Not explicitly selected'; continue; }
+    try {
+      for (const e of [l, r].filter(Boolean)) if (e.type !== 'blob' || !['100644', '100755'].includes(e.mode)) throw new Error('Historical link or submodule excluded');
+      const read = async e => decode(e ? await gitAt(root, ['cat-file', 'blob', e.oid], options, maxFileBytes) : Buffer.alloc(0));
+      item.left = await read(l);
+      item.right = await read(r);
+      item.rightExists = !!r;
+      if (l && r && item.left.hash === item.right.hash) { item.eligibility = 'excluded'; item.reason = 'Mode-only historical change not analyzed'; }
+    } catch (error) {
+      signal?.throwIfAborted();
+      item.eligibility = 'blocked'; item.reason = error.message;
+      delete item.left; delete item.right;
+    }
+    if (Buffer.byteLength(JSON.stringify(files)) > maxSnapshotBytes) throw new Error('Historical snapshot limit exceeded');
+  }
+
+  const rulePaths = options.rulePaths ?? [];
+  const contextPaths = options.contextPaths ?? [], oldContextPaths = options.oldContextPaths ?? [], maxContextFiles = options.maxContextFiles ?? 20;
+  if (!Array.isArray(oldContextPaths) || oldContextPaths.length > 20 || new Set(oldContextPaths).size !== oldContextPaths.length) throw new Error('Invalid old context paths');
+  for (const name of oldContextPaths) { relativePath(name); assertNonSecretPath(name); }
+  if (oldContextPaths.length && !base) throw new Error('Old context requires nonempty historical baseline');
+  if (!Array.isArray(contextPaths) || !Array.isArray(rulePaths)) throw new Error('Invalid historical context or rule paths');
+  if (oldContextPaths.some(p => contextPaths.includes(p) || rulePaths.includes(p))) throw new Error('Old context paths must be separate');
+  if (contextPaths.length + oldContextPaths.length > maxContextFiles) throw new Error('Historical context file limit exceeded');
+  if (!Array.isArray(contextPaths) || !Number.isSafeInteger(maxContextFiles) || maxContextFiles < 1 || maxContextFiles > 20 || contextPaths.length > maxContextFiles) throw new Error('Historical context file limit exceeded');
+  if (options.autoContext !== undefined && typeof options.autoContext !== 'boolean') throw new Error('Invalid autoContext option');
+  if (!Array.isArray(rulePaths) || rulePaths.length > 4 || rulePaths.some(p => contextPaths.includes(p))) throw new Error('Rule paths must be separate from context paths');
+
+  await lookupPaths(root, target, right, [...contextPaths, ...rulePaths], options);
+  await lookupPaths(root, base, left, [...contextPaths, ...oldContextPaths], options);
+
+  const context = [];
+  const readBlob = (oid, limit = maxFileBytes) => gitAt(root, ['cat-file', 'blob', oid], options, limit);
+
+  const captureContext = async name => {
+    relativePath(name); assertNonSecretPath(name);
+    const changed = files.find(f => f.path === name);
+    if (changed) {
+      if (changed.eligibility !== 'reviewable' || changed.rightExists === false) throw new Error('Historical context is excluded blocked or deleted');
+      return { path: name, ...changed.right };
+    }
+    const entry = right.get(name);
+    if (!REGULAR_BLOB(entry)) throw new Error('Historical context not a target regular blob');
+    const content = decode(await readBlob(entry.oid));
+    const previous = left.get(name);
+    return { path: name, ...content, revision: target, ...(REGULAR_BLOB(previous) ? { oldText: decode(await readBlob(previous.oid)).text, oldRevision: base } : {}) };
+  };
+
+  for (const name of [...new Set(contextPaths)].sort()) context.push(await captureContext(name));
+
+  for (const name of [...oldContextPaths].sort()) {
+    const changed = files.find(f => f.path === name);
+    if (changed) {
+      if (changed.eligibility !== 'reviewable' || !left.has(name)) throw new Error('Old context conflicts with excluded blocked or absent old change');
+      continue;
+    }
+    const entry = left.get(name);
+    if (!REGULAR_BLOB(entry)) throw new Error('Old context not a baseline regular blob');
+    const content = decode(await readBlob(entry.oid));
+    context.push({ path: name, oldOnly: true, oldText: content.text, oldHash: hash(content.text), oldBlobOid: entry.oid, oldRevision: base });
+  }
+
+  const rules = await captureProjectRules(root, rulePaths, {
+    signal, files,
+    read: async (_root, name, { maxFileBytes: limit }) => {
+      const entry = right.get(name);
+      if (!REGULAR_BLOB(entry)) throw new Error('Historical rule not a target regular blob');
+      return decode(await readBlob(entry.oid, limit));
+    },
+  });
+
+  let autoContext;
+  if (options.autoContext === true) autoContext = await captureHistoryDependencyChain(root, files, { base, target }, context, options);
+
+  let callerDiscovery;
+  if (options.callerScopePaths !== undefined) {
+    const callers = await captureHistoryCallers(root, files, { base, target }, options.callerScopePaths, options);
+    callerDiscovery = callers.discovery;
+    for (const item of callers.context) {
+      const matches = callerDiscovery.candidates.filter(c => c.fromPath === item.path);
+      const present = context.find(c => c.path === item.path);
+      if (present) {
+        if ((present.text !== undefined && present.text !== item.text) || (present.oldText !== undefined && present.oldText !== item.oldText)) throw new Error('Historical caller context identity conflict');
+        for (const c of matches) {
+          const available = c.side === 'old' ? present.oldText !== undefined : present.text !== undefined;
+          c.status = available ? 'reused-context' : 'blocked';
+          if (!available) c.captureReason = 'Existing context did not approve this version side';
+        }
+        continue;
+      }
+      if (context.length >= maxContextFiles) {
+        for (const c of matches) { c.status = 'blocked'; c.captureReason = 'Context file limit exceeded'; }
+        continue;
+      }
+      context.push(item);
+      callerDiscovery.capturedPaths.push(item.path);
+      for (const c of matches) c.status = 'captured';
+    }
+  }
+
+  const snapshot = { context, ...(callerDiscovery ? { callerDiscovery } : {}), ...(rules.length ? { rules } : {}), ...(autoContext ? { autoContext } : {}), schemaVersion: 1, vcs: 'git', root, baseline: base, history: { mode: commit !== undefined ? 'commit' : 'range', base, target, semantics: 'exact-tree-endpoints; renames represented as add/delete' }, files };
+  const serialized = JSON.stringify(snapshot);
+  if (Buffer.byteLength(serialized) > maxSnapshotBytes) throw new Error('Historical snapshot limit exceeded');
+  return { ...snapshot, id: hash(serialized) };
 }