dsh-code-impact

Readme

# 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 / 安装

```sh
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`。

```json
{"mode":"workspace"}
```

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

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

```json
{"mode":"staged"}
```

Compares `HEAD` with the Git index。

比较 `HEAD` 与 Git index。

```json
{"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 校验。

```yaml
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 / 开发

```sh
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。