dsh-code-impact

English | 中文

dsh-code-impact is an independent DeepSeek Harness plugin that performs one read-only TypeScript/JavaScript change-impact analysis. It compares a concrete Git change, builds a temporary reverse module graph, and returns changed declarations, affected files, propagation paths, evidence locations, and ranked test candidates. Version 0.2.0 understands JSONC project configuration, tsconfig.json/jsconfig.json, extends, project references, path aliases, package exports/imports, and reuses unchanged snapshot content within one invocation. It does not maintain a repository index.

dsh-code-impact 是一个独立的 DeepSeek Harness 社区插件，用于对一次具体的 TS/JS Git 变更执行只读影响分析。它临时构建反向模块依赖图，返回变更声明、受影响文件、完整传播路径、文件行号证据和排序后的候选测试。0.2.0 支持 JSONC 项目配置、tsconfig.json/jsconfig.json、extends、项目引用、路径别名、package exports/imports，并在一次调用内复用未变化快照内容。不维护长期代码地图。

Install / 安装

npm install dsh-code-impact
dsh plugin --profile demo add dsh-code-impact
dsh --profile demo --dump-config

The package exports cordis.patch.yml through the dsh.bundle.patch manifest field. The patch expects the profile to provide the DSH tools, fs, and subprocess services. It does not install a Git provider or a filesystem provider.

该包通过 dsh.bundle.patch 暴露 cordis.patch.yml。补丁要求 profile 已提供 DSH 的 tools、fs 和 subprocess 服务，不会安装 Git provider 或文件系统 provider。

Tool calls / 工具调用

The registered tool is code_impact。

已注册的工具名为 code_impact。

{"mode":"workspace"}

Compares HEAD with the current working tree, including staged changes, unstaged changes, and untracked non-ignored files.

比较 HEAD 与当前工作树，包含已暂存、未暂存和未被忽略的未跟踪文件。

{"mode":"staged"}

Compares HEAD with the Git index。

比较 HEAD 与 Git index。

{"mode":"refs","base_ref":"origin/main","head_ref":"feature/payment"}

Validates both refs and compares the merge-base to head_ref, which matches the usual pull-request comparison semantics. base_ref and head_ref are rejected in the other modes; an invalid ref never silently falls back to another revision.

插件会校验两个引用，并比较 merge-base 到 head_ref，符合常见 Pull Request 比较语义。其他模式携带引用会直接报错；无效引用不会静默回退到其他版本。

Configuration / 配置

All fields are validated by Schemastery when the plugin is loaded。

所有字段在插件加载时通过 Schemastery 校验。

gitCommand: git
maxSourceFiles: 10000
maxTotalSourceBytes: 100000000
maxFileBytes: 2000000
maxChangedFiles: 200
maxImpactedFiles: 500
maxTraversalDepth: 5
maxCausesPerImpact: 3
maxResultChars: 24000
timeoutMs: 120000
testPatterns:
  - '**/*.test.*'
  - '**/*.spec.*'
  - '**/__tests__/**'
  - '**/test/**'
  - '**/tests/**'
excludePatterns:
  - '**/node_modules/**'
  - '**/dist/**'
  - '**/build/**'
  - '**/coverage/**'
  - '**/.git/**'

maxSourceFiles and maxTotalSourceBytes protect repository-scale scans. Exceeding them returns CODE_IMPACT_REPOSITORY_TOO_LARGE instead of a partial report. maxFileBytes prevents an individual source file from entering the parser; the report carries a warning and is incomplete. maxChangedFiles, maxImpactedFiles, maxCausesPerImpact, and maxResultChars bound the returned presentation. The report retains total counts and includes truncation when result arrays or propagation causes are shortened.

maxSourceFiles 和 maxTotalSourceBytes 保护仓库级扫描；超过时返回 CODE_IMPACT_REPOSITORY_TOO_LARGE，不会伪造部分完整结果。maxFileBytes 阻止单个超大源码进入解析，报告会包含 warning 并标记不完整。maxChangedFiles、maxImpactedFiles、maxCausesPerImpact 和 maxResultChars 限制返回结果；截断时保留总数并返回 truncation。

Result / 结果

The canonical result has kind: "code-impact-report", complete, comparison, summary, changes, impacts, tests, and warnings fields. Each impact includes a path, a relationship, a traversal distance, and at least one evidence location with a one-based line number. V0.2 adds impacts[].causes, where each cause records its changed-file origin and the bounded edge-by-edge propagation path. Existing top-level impact fields remain the shortest primary path for consumers that do not need full traces. Test candidates now include changed test files and a deterministic reason such as changed-test, direct-symbol, direct-module, or transitive.

关系类型只有：changed、symbol-import、module-import、reexport、dynamic-import 和 transitive。工具不会生成没有规则依据的风险分数。

The parser uses the TypeScript Compiler API for the supported .ts, .tsx, .mts, .cts, .js, .jsx, .mjs, and .cjs extensions. It understands static imports/exports, string-literal dynamic imports, CommonJS require, declaration ranges, common tsconfig path aliases, project references represented by repository configs, and package metadata visible in the snapshot. The base and target snapshots are parsed independently so deleted declarations and old reference sites remain inspectable.

解析器使用 TypeScript Compiler API 支持上述八种扩展名，识别静态 import/export、type-only import/export、默认和 namespace import、字符串形式的动态 import、CommonJS require、声明范围、JSONC 配置、extends、references、项目归属、路径别名和快照中可见的 package exports/imports 元数据。基线和目标快照分别建图，因此删除的声明和旧引用者仍可被定位；未变化 blob 的解析结果在同一次调用内复用。

Safety and limitations / 安全边界与限制

• The tool only reads Git metadata/objects and files through DSH services. It never checks out, writes the index, creates a worktree, runs tests, edits files, or accesses the network.

• Git is invoked with argv, never through a shell. Refs are verified with rev-parse --verify --end-of-options.

• Non-TS/JS files remain in changes, but do not receive fabricated symbol-level impacts.

• Symlinks that resolve outside the workspace, binary files, submodules, unresolved related imports, malformed project configuration, and traversal limits become explicit warnings and set complete: false.

• Version 0.2 still has no LSP, call graph, cross-language analysis, persistent index, PR API, test execution, risk score, or dedicated web panel.

• 工具只通过 DSH service 读取 Git 元数据、Git 对象和文件，不 checkout、不写 index、不创建 worktree、不执行测试、不修改文件、不访问网络。

• Git 使用 argv 调用，不经过 Shell；引用通过 rev-parse --verify --end-of-options 校验。

• 非 TS/JS 文件仍出现在 changes，但不会伪造符号级影响。

• 越界符号链接、二进制文件、子模块、相关路径上未解析的 import、无法解析的项目配置和传播深度限制都会形成显式 warning，并令 complete: false。

• 0.2 版本仍不包含 LSP、调用图、跨语言分析、持久化索引、PR 平台 API、测试执行、风险评分或专用 Web 面板。

Compatibility / 兼容版本

The initial package targets:

• Node ^22.19.0 || >=24.0.0
• @deepseek-ai/cordis 4.0.1
• @deepseek-ai/dsh-fs 0.0.1-rc.1
• @deepseek-ai/dsh-subprocess 0.0.1-rc.1
• @deepseek-ai/dsh-tools 0.0.1-rc.1

These DSH peer versions are intentionally exact. A DSH upgrade must update the peer versions and run the compatibility matrix before publishing a new plugin version.

本版本目标兼容 Node ^22.19.0 || >=24.0.0、Cordis 4.0.1 以及 npm 当前发布的 DSH 0.0.1-rc.1 的 fs、subprocess、tools 接口。DSH peer 版本刻意固定；升级 DSH 时必须先更新 peer 版本并运行兼容性矩阵，再发布新插件版本。

Development / 开发

npm run typecheck
npm test
npm run build
npm pack --dry-run

The repository CI runs the same checks on Windows, Linux, and macOS with Node 22.19 and Node 24. Before publishing, install the tarball into a temporary DSH profile, run dsh --profile <name> --dump-config, invoke code_impact once, and verify dsh plugin add/remove.

发布前应把 tarball 安装到临时 DSH profile，执行 dsh --profile <name> --dump-config，真实调用一次 code_impact，并验证 dsh plugin add/remove。

Model Experience

Code impact tool result

What the model sees

The tool returns a compact summary followed by changes, impacted files with evidence, and candidate tests. The canonical JSON result remains available to Code Mode callers。

Token effect

The result is bounded by maxResultChars; omitted arrays are counted in truncation and complete becomes false。

KV Cache effect

Independent per-tool-result content; it does not alter the session system prompt。

Migration from 0.1 / 从 0.1 迁移

The tool arguments and existing top-level report fields are unchanged. Consumers that construct report fixtures must add causes to impacts, reason to test candidates, and severity to warnings. TestCandidate.relationship may now be changed so a modified test can be recommended explicitly. maxCausesPerImpact defaults to 3.

工具参数和已有顶层报告字段保持不变。自行构造报告 fixture 的调用方需要为 impact 增加 causes、为测试候选增加 reason、为 warning 增加 severity。TestCandidate.relationship 现在允许 changed，因此变更中的测试可以被明确推荐。maxCausesPerImpact 默认值为 3。

Known Limitations and Deferred Work

• Repository semantics — TypeScript resolution is snapshot-based and conservative; unusual custom loaders or generated virtual modules may remain unresolved.
• Scale — The implementation is intentionally bounded by configuration and does not reuse a persistent cross-call index.
• Language coverage — Only TS/JS module relationships are analyzed in the initial release。