@feng0531/dsh-code-review 0.39.1 → 0.40.0

package/CHANGELOG.md

@@ -2,12 +2,16 @@
 
 本文件介绍对使用者有意义的变化。安装与参数见 [README](README.md)，本次发布正文见 [发布说明](RELEASE-NOTES.md)。历史提交和安装包保留在 [GitHub Releases](https://github.com/f-e-n-g-0531/dsh-code-review/releases)；本文不把开发日志当作功能介绍。
 
+## 0.40.0 — 手动上下文的依赖导航
+
+Git 工作区启用 autoContext 后，也沿 contextPaths 指定文件的静态依赖取得必要实现。手动与自动来源共享数量、正文和时间限制；不改变未启用时的行为，不把排除变更或未跟踪依赖重新纳入。历史与 SVN 仍仅直接导航。
+
 ## 0.39.1 — 文档整理
 
 - 重写安装、使用、参数和报告说明，去掉开发流水账与未解释术语。
 - 分开用户说明、开发发布流程、能力差距和评测观察。
 - GitHub Release 使用专门编写的发布说明，不再只展示自动生成的提交列表。
-- 不改变审查工具参数或运行行为。正式交付需完成本版发布验证。
+- 不改变审查工具参数或运行行为。已正式发布；四组 CI 通过，npm 与 GitHub Release 的实际安装包和保存原包一致，发布正文为新版用户说明。
 
 ## 0.39.0 — Git 工作区依赖上下文
 

package/CORE-ALIGNMENT-TASKS.md

@@ -30,15 +30,15 @@
 | 5 | 剩余预算组合与端到端矩阵 | 分组、窗口、检索、多次审查的终态与覆盖一致 |
 | 后置 | 真实模型质量评测 | 保存真实输出，人工裁决，分开统计失败和未完成 |
 
-Git 工作区三层字面依赖链已实现并通过测试。这解决了“导入转发文件后，未取得后续实现正文”的部分问题，但仍不是完整定义绑定。历史与 SVN 不具备同样的链式能力。
+Git 工作区三层字面依赖链已实现并通过测试。这解决了“导入转发文件后，未取得后续实现正文”的部分问题，但仍不是完整定义绑定。本批还补齐了手动上下文作为链入口，真实 Git、服务与独立安装四项测试通过，388 项全量回归和实际宿主检查通过，待正式发布。历史与 SVN 不具备同样的链式能力。
 
 ## 当前验证结论
 
-- 最近完整回归：383 项通过。
+- 最近完整回归：388 项通过。
 - 实际 DSH 工具运行时检查通过；模型响应受控，不是质量成绩。
 - v0.39.0 独立安装包的真实 Git、服务与预算测试：5 项通过。
-- 已核验正式交付至 v0.38.0。v0.39.0 已冻结标签，本文不在缺少公开安装包核验时把它算作正式交付。
-- 当前优先任务是文档重构与新正式版本；文档发布完成不代表本表的核心差距完成。
+- v0.39.1 已正式交付，包含 Git 工作区三层依赖能力。四组 CI 通过；npm、Release 与保存原包的 91,502 字节完全一致，SHA-256、SHA-512 和校验清单通过。v0.39.0 不单独计作已核验交付。
+- 文档重构与正式发布已完成。新增文档一致性检查通过；本表中的核心差距仍未完成。
 
 ## 不在范围内
 

package/DEVELOPMENT.md

@@ -18,7 +18,7 @@
 
 - 每个主文件的模型与检索阶段共享默认 120 秒；关联综合沿用相关主文件的生命周期，不因切换阶段重新计时。
 - 每阶段最多三轮检索；全局最多 50 次读取请求，返回内容累计 256 KiB，单次最多 64 KiB，读取最多 200 行。
-- Git 工作区依赖链最多三层、512 个精确路径查询、20 个候选、1 MiB 正文；文件读取与最终复核共享 30 秒。
+- Git 工作区依赖链最多三层、512 个精确路径查询、20 个候选、手动入口与自动依赖共享 1 MiB 正文；文件读取与最终复核共享 30 秒。
 - 引用方发现最多四个不重叠的非根目录；128 个候选正文共 1 MiB，目录索引最多 256 条／64 KiB，竞争路径最多 512 个。发现与复核共享 30 秒。
 
 达到上限必须阻断或说明未完成，不能静默扩大范围、丢弃证据或重新计时。

package/README.md

@@ -58,7 +58,7 @@ DSH 的只读代码审查插件。它比较 Git 或 SVN 中的代码变更，使
 | selectedPaths | 只审查选中的变更文件 | ["src/api.ts"] |
 | repositoryPath | 指定工作区内的子仓库 | "project-a" |
 | contextPaths | 手动加入理解代码所需的文件 | ["src/types.ts"] |
-| autoContext | 自动寻找有限范围内的直接依赖；Git 工作区最多沿三层依赖链读取 | true |
+| autoContext | 从变更及手动上下文寻找依赖；Git 工作区最多沿三层依赖链读取 | true |
 | callerScopePaths | 在指定目录中寻找引用变更文件的代码 | ["src/clients"] |
 | oldContextPaths | Git 历史审查中，只加入旧版本的上下文 | ["src/removed-helper.ts"] |
 | rulePaths | 加入项目审查规则，最多四个 UTF-8 Markdown 或文本文件 | ["review-rules.md"] |

package/RELEASE-NOTES.md

@@ -1,26 +1,23 @@
-# v0.39.1 发布说明
+# v0.40.0 发布说明
 
-## 本版解决什么问题
+## 新增：沿手动上下文取得必要实现
 
-项目文档此前混入了大量开发过程、测试编号和内部术语，难以回答“怎么安装、怎么使用、有哪些限制”。本版重新组织文档，让使用说明、版本变化、开发流程和能力差距各自独立。
+在 Git 工作区同时设置 contextPaths 和 autoContext: true 时，自动上下文现在也从手动选定的文件出发。若该文件导入或转发其他实现，插件最多沿三层静态依赖取得正文，帮助理解变更所需的类型与实现。
 
-## 主要变化
+不启用 autoContext 时，手动上下文仍只包含指定文件。无需新增参数。
 
-- README 改为安装、第一次使用、常用参数、报告解读和安全限制。
-- 发布说明与变更记录使用面向用户的描述，不再把流水线编号和校验日志混入功能介绍。
-- 检查评测与能力对照文档，区分已完成、部分实现和未验证，删除过时的过程叙述。
-- 发布流程使用本说明作为 GitHub Release 正文，避免自动生成的提交列表代替产品说明。
+## 范围与限制
 
-## 升级是否需要改用法
+- 手动文件和自动依赖共享 20 个上下文名额。
+- 手动入口正文和自动依赖共享 1 MiB 来源上限；单文件不超过 256 KiB。
+- 依赖查询、入口检查及执行前重新采集沿用有限范围和时间上限。
+- 自动依赖必须来自 Git 跟踪路径；不会重新纳入排除的变更。
+- 文件在预览后发生变化时，必须重新预览，不能沿旧快照发送。
 
-不需要。工具名称和参数保持不变；没有增加审批、模型配置或代码修改能力。新安装包保留 Git 工作区最多三层依赖上下文的能力，Git 历史与 SVN 仍只做直接依赖导航。
+这是保守的文本导航，不是完整符号解析。Git 历史和 SVN 的链式上下文尚未完成，动态调用和实例绑定仍可能无法解析。
 
-升级后请确认 DSH 已加载新包，并重新预览审查范围。旧预览不应用于升级后的执行。
+## 验证
 
-## 验证与限制
+真实 Git 和受控模型测试覆盖手动入口、启用开关、上下文数量、正文预算、未跟踪依赖、排除变更和过期拒绝。正式发布还须通过全量回归、独立安装及四组 CI。测试证明流程边界，不证明模型检出率。
 
-发布前运行完整回归测试、安装包检查和 DSH 工具运行时检查；正式发布还需通过 Ubuntu、Windows 与 Node.js 22、24 的四个组合测试。
-
-这些验证证明插件流程和边界符合测试预期，不证明真实模型的检出率或误报率。完整语义调用者、历史与 SVN 依赖链及部分语言指导仍未完成。
-
-安装方法见 [README](README.md)。开发和安装包一致性验证方法见 [开发与发布指南](DEVELOPMENT.md)。
+使用方法见 [README](README.md)，发布步骤见 [开发指南](DEVELOPMENT.md)。

package/index.mjs

@@ -12,7 +12,7 @@ export function apply(ctx, config = {}) {
   };
   ctx.tools.register({
     name: 'code_review_preview', description: 'Preview Git/SVN working-copy or Git commit/range review scope and model destination without sending source to a model. repositoryPath selects an explicit child repository relative to session workspace; file paths are repository-relative. Preview each repository separately. Show the preview before execution.',
-    parameters: { type: 'object', additionalProperties: false, properties: { reviewRounds: { type: 'integer', minimum: 1, maximum: 3, description: 'Explicit independent review passes, default 1. Preview discloses extra sends; later passes omit the first risk plan. Shares existing timeout, call and retrieval budgets, not provider reasoning effort. Bound to this preview; execute cannot override.' }, oldContextPaths: { type: 'array', maxItems: 20, items: { type: 'string' }, description: 'Explicit Git historical baseline-only blob context paths. Shares 20 context slots. No target text is inferred; selected old changes reuse their original identity, excluded changes cannot reenter. Unsupported on working reviews and SVN.' }, callerScopePaths: { type: 'array', minItems: 1, maxItems: 4, items: { type: 'string' }, description: 'Explicit non-root repository-relative directories for bounded tracked literal reverse import/include discovery. Git/SVN working review or Git fixed commit/range review. SVN uses offline normal nodes, rejects unsafe ancestor states and special/keyword properties. Historical sides share scan budgets and use object blobs only. Preview reads candidate bodies, including nonmatches; only captured matching context is sent. Navigation only, not complete caller coverage.' }, businessRequirement: { type: 'string', maxLength: 16384, description: 'Optional business constraint text up to 16KiB UTF8; untrusted data, not evidence or permission. Bound to preview and sent in review phases.' }, commit: { type: 'string', description: 'Git commit versus sole parent; root empty, merge requires range.' }, baseRevision: { type: 'string', description: 'Git old endpoint; requires targetRevision, mutually exclusive with commit.' }, targetRevision: { type: 'string', description: 'Git new endpoint, exact tree endpoints not merge-base. Explicit context uses target tree with available baseline provenance; oldContextPaths is baseline-only. Historical caller discovery scans fixed sides; explicit rules use target-tree blobs.' }, repositoryPath: { type: 'string', description: 'Workspace-relative explicit child Git/SVN repository root, forward slashes; omit for current repository.' }, selectedPaths: { type: 'array', items: { type: 'string' }, maxItems: 200 }, autoContext: { type: 'boolean', description: 'Opt in to tracked literal import/include context shown in preview. Working Git follows at most 3 dependency layers under shared 512 exact probes, 20 candidates/context slots, 1MiB source and 30s verification budget. SVN and Git history remain direct navigation. Not semantic binding or complete definitions.' }, contextPaths: { type: 'array', items: { type: 'string' }, maxItems: 20 }, rulePaths: { type: 'array', items: { type: 'string' }, maxItems: 4 } } },
+    parameters: { type: 'object', additionalProperties: false, properties: { reviewRounds: { type: 'integer', minimum: 1, maximum: 3, description: 'Explicit independent review passes, default 1. Preview discloses extra sends; later passes omit the first risk plan. Shares existing timeout, call and retrieval budgets, not provider reasoning effort. Bound to this preview; execute cannot override.' }, oldContextPaths: { type: 'array', maxItems: 20, items: { type: 'string' }, description: 'Explicit Git historical baseline-only blob context paths. Shares 20 context slots. No target text is inferred; selected old changes reuse their original identity, excluded changes cannot reenter. Unsupported on working reviews and SVN.' }, callerScopePaths: { type: 'array', minItems: 1, maxItems: 4, items: { type: 'string' }, description: 'Explicit non-root repository-relative directories for bounded tracked literal reverse import/include discovery. Git/SVN working review or Git fixed commit/range review. SVN uses offline normal nodes, rejects unsafe ancestor states and special/keyword properties. Historical sides share scan budgets and use object blobs only. Preview reads candidate bodies, including nonmatches; only captured matching context is sent. Navigation only, not complete caller coverage.' }, businessRequirement: { type: 'string', maxLength: 16384, description: 'Optional business constraint text up to 16KiB UTF8; untrusted data, not evidence or permission. Bound to preview and sent in review phases.' }, commit: { type: 'string', description: 'Git commit versus sole parent; root empty, merge requires range.' }, baseRevision: { type: 'string', description: 'Git old endpoint; requires targetRevision, mutually exclusive with commit.' }, targetRevision: { type: 'string', description: 'Git new endpoint, exact tree endpoints not merge-base. Explicit context uses target tree with available baseline provenance; oldContextPaths is baseline-only. Historical caller discovery scans fixed sides; explicit rules use target-tree blobs.' }, repositoryPath: { type: 'string', description: 'Workspace-relative explicit child Git/SVN repository root, forward slashes; omit for current repository.' }, selectedPaths: { type: 'array', items: { type: 'string' }, maxItems: 200 }, autoContext: { type: 'boolean', description: 'Opt in to tracked literal import/include context shown in preview. Working Git follows changed and explicitly selected context sources at most 3 dependency layers under shared 512 exact probes, 20 candidates/context slots, 1MiB source and 30s verification budget. SVN and Git history remain direct navigation. Not semantic binding or complete definitions.' }, contextPaths: { type: 'array', items: { type: 'string' }, maxItems: 20 }, rulePaths: { type: 'array', items: { type: 'string' }, maxItems: 4 } } },
     output,
     async execute(args, exec) { const preview = await service.preview(args, exec); return { json: JSON.stringify(preview), markdown: '' }; },
   });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@feng0531/dsh-code-review",
-  "version": "0.39.1",
+  "version": "0.40.0",
   "private": false,
   "license": "SEE LICENSE IN LICENSE",
   "publishConfig": { "access": "public", "registry": "https://registry.npmjs.org/" },

package/src/dependency-chain.mjs

@@ -6,12 +6,23 @@ export async function captureDependencyChain(root,files,options={}){
  const signal=AbortSignal.any([AbortSignal.timeout(30000),...(options.signal?[options.signal]:[])]);
  const scoped={...options,maxFileBytes:Math.min(options.maxFileBytes??256*1024,256*1024),signal},probes=new Set(),visited=new Set(files.map(f=>f.path)),context=[],candidates=[];
  const reserved=new Set([...(options.contextPaths??[]),...(options.rulePaths??[])]),limit=Math.min(options.maxContextFiles??20,20);
- let frontier=files,index,bytes=0,truncated=false,depth=0;
+ let frontier=[...files],index,bytes=0,truncated=false,depth=0;
+ const explicitSeeds=[];
+ if(new Set(options.contextPaths??[]).size>limit)throw new Error('Context file limit exceeded');
+ for(const name of [...new Set(options.contextPaths??[])].sort()){
+  const changed=files.find(f=>f.path===name);
+  if(changed){if(changed.eligibility!=='reviewable'||changed.rightExists===false)throw new Error('Context path is an excluded blocked or deleted change');continue;}
+  const item={path:name,...await readLocal(root,name,scoped)};
+  bytes+=item.bytes;if(bytes>1024*1024)throw new Error('Dependency source byte limit exceeded');
+  explicitSeeds.push(item);visited.add(name);frontier.push({path:name,eligibility:'reviewable',right:item});
+ }
+ // Seeds are already explicitly selected, but descendants must still pass exact tracked probes.
+
  const onProbe=paths=>{for(const p of paths)probes.add(p);if(probes.size>512)throw new Error('Git context lookup limit exceeded');};
  for(depth=1;depth<=3&&frontier.length;depth++){
-  signal.throwIfAborted();contextCandidates(frontier,[],{onProbe});
+  signal.throwIfAborted();for(let i=0;i<frontier.length;i+=200)contextCandidates(frontier.slice(i,i+200),[],{onProbe});
   index=await gitContextIndex(root,{...scoped,probePaths:[...probes]});
-  const plan=contextCandidates(frontier,index.paths);truncated ||= plan.truncated;
+  const plans=[];for(let i=0;i<frontier.length;i+=200)plans.push(contextCandidates(frontier.slice(i,i+200),index.paths));const plan={candidates:plans.flatMap(p=>p.candidates),truncated:plans.some(p=>p.truncated)};truncated ||= plan.truncated;
   const next=[];
   for(const entry of plan.candidates){
    if(visited.has(entry.path)||reserved.has(entry.path))continue;
@@ -29,5 +40,5 @@ export async function captureDependencyChain(root,files,options={}){
  }
  if(frontier.length)truncated=true;
  const indexOptions={...scoped,probePaths:[...probes]};
- return {context,index,indexOptions,autoContext:{candidates,capturedPaths:context.map(c=>c.path),truncated,maxDepth:3,probeCount:probes.size,sourceBytes:bytes,notice:'Bounded current-side literal dependency navigation, depth <=3, 512 shared exact probes, 20 candidates/context slots, 1MiB source bytes and 30s through verification. Not symbol binding, caller coverage or complete definitions.'}};
+ return {context,index,indexOptions,explicitSeeds,autoContext:{candidates,capturedPaths:context.map(c=>c.path),truncated,maxDepth:3,probeCount:probes.size,sourceBytes:bytes,notice:'Bounded current-side literal dependency navigation from changed and explicit context sources, depth <=3, 512 shared exact probes, 20 candidates/context slots, 1MiB source bytes and 30s through verification. Not symbol binding, caller coverage or complete definitions.'}};
 }

package/src/snapshot.mjs

@@ -49,10 +49,10 @@ export async function captureSnapshot(cwd, options = {}) {
   if (!Array.isArray(rulePaths) || rulePaths.some(name => contextPaths.includes(name))) throw new Error('Rule paths must be separate from context paths');
   const rules = await captureProjectRules(snapshot.root, rulePaths, { signal: options.signal, files: snapshot.files });
   const context = [];
-  let autoContext, index, indexOptions = options;
+  let autoContext, index, explicitSeeds = [], indexOptions = options;
   if (options.autoContext === true && type==='git') {
     const chain=await captureDependencyChain(snapshot.root,snapshot.files,options);
-    context.push(...chain.context);autoContext=chain.autoContext;index=chain.index;indexOptions=chain.indexOptions;
+    explicitSeeds=chain.explicitSeeds;context.push(...chain.context);autoContext=chain.autoContext;index=chain.index;indexOptions=chain.indexOptions;
   } else if (options.autoContext === true) {
     if(type==='git'){const probes=new Set();contextCandidates(snapshot.files,[],{onProbe:paths=>{for(const p of paths)probes.add(p);if(probes.size>512)throw new Error('Git context lookup limit exceeded');}});indexOptions={...options,probePaths:[...probes]};}
     index = await (type === 'git' ? gitContextIndex : svnContextIndex)(snapshot.root, indexOptions);
@@ -72,7 +72,12 @@ export async function captureSnapshot(cwd, options = {}) {
       if (changed.eligibility !== 'reviewable') throw new Error('Context path is an excluded or blocked change');
       if (changed.rightExists === false) throw new Error('Deleted path cannot be working context');
       context.push({ path: name, ...changed.right });
-    } else context.push({ path: name, ...await readLocal(snapshot.root, name, options) });
+    } else {
+      const item={path:name,...await readLocal(snapshot.root,name,indexOptions)};
+      const seed=explicitSeeds.find(c=>c.path===name);
+      if(seed&&seed.hash!==item.hash)throw new Error('Explicit dependency seed changed during capture');
+      context.push(item);
+    }
   }
   let callerDiscovery, verifyCallers;
   if (options.callerScopePaths !== undefined) {
@@ -93,7 +98,7 @@ export async function captureSnapshot(cwd, options = {}) {
     }
   }
   // Re-capture verifies both selected sides while collecting explicit context.
-  if ((await capture(cwd, options)).id !== snapshot.id) throw new Error('Snapshot changed while collecting context');
+  if ((await capture(cwd, indexOptions)).id !== snapshot.id) throw new Error('Snapshot changed while collecting context');
   for (const item of context) if ((await readLocal(snapshot.root, item.path, indexOptions)).hash !== item.hash) throw new Error('Context changed during capture');
   if (index && (await (type === 'git' ? gitContextIndex : svnContextIndex)(snapshot.root, indexOptions)).fingerprint !== index.fingerprint) throw new Error('Tracked context index changed during capture');
   const verifiedRules = await captureProjectRules(snapshot.root, rulePaths, { signal: options.signal, files: snapshot.files });