dsh-change-impact

dsh-change-impact

English | 简体中文

The change impact analysis plugin for DeepSeek Harness: it lifts a code change into an evidence-backed impact analysis and verification plan (CHANGE-IMPACT.md + change-impact.json).

Turn a code change into an evidence-backed impact and verification plan.

Positioning

dsh-change-impact covers the "one change → impact, risk and verification" step. Repository structure, symbols, dependencies and entry points come from dsh-repo-scanner (an npm dependency; scanner source is never copied), while this plugin owns change fact parsing, reverse propagation, risk scoring and report assembly.

It answers:

• Which modules, entry points and public exports are affected by this change?
• How risky is it, and what is the evidence (every level carries factors and a confidence)?
• Which verification commands should run instead of blindly running the full suite?
• Do docs, migration scripts and release notes need a matching update?

Boundaries:

• Read-only by default: never modifies source, tests, docs or config; never creates commits/branches/PRs.
• Never runs repository commands: verification commands are recommendations only (requires_confirmation is always true); working_tree/base_head modes only run whitelisted read-only git queries (rev-parse / diff / status), disclosed in the report appendix.
• Never invents conclusions: no speculative runtime call chains; missing commands are explicitly marked as "unidentified"; fully_covered is never emitted.

Output preview

# Change Impact Analysis
> Baseline: HEAD (uncommitted working tree changes)
> Tool: dsh-change-impact 0.1.0; scanner dsh-repo-scanner 0.1.2

## 1. Summary
- [Fact] 1 changed file (1 analyzed), +2/-1 lines; reverse propagation
  reaches 2 files in 2 modules.
- [Inference] Highest risk level: high (…computed by the fixed rules in docs/risk-rules.md).
- [Fact] 1 entry point affected: `src/server.ts`.

## 2. Change scope
| `src/auth/service.ts` | modified | +2/-1 | source | `src/auth` |

## 3. Propagation
| `src/auth/service.ts` | … | src/auth/service.ts -> src/api/routes.ts -> src/server.ts | `src/server.ts` |

## 5. Verification plan
| P0 (minimal set) | `node --test` | Web/service entry affected… API/integration tests advised | package.json | yes |

Rule boundaries live in docs/risk-rules.md; known impact relations for the test fixtures live in test/fixtures/.

Install

As a DSH plugin:

dsh plugin --profile web add "github:duyanta123/dsh-change-impact#v0.1.0"

Or from npm (as a library or standalone CLI):

npm install dsh-change-impact

Compatibility layers: the standalone CLI / library requires Node.js >= 18; as a DSH 0.2.1-rc.2 plugin it is verified with Node.js >= 22.19 (the compat baseline is enforced by npm run test:compat and the CI compat job). Run npm test locally (the CI matrix covers Windows + Ubuntu × Node 18/20/22 + the DSH compat job).

After installing, restart dsh --profile web and use the change-impact-runbook skill.

Quick start

1. As a DSH skill

Ask the agent to "analyze the impact of this change in /path/to/repo" and state the baseline mode; the skill follows the runbook: input intake → change facts → impact propagation → risk and verification → report output, then hands you CHANGE-IMPACT.md and change-impact.json.

2. As a standalone CLI

# Working tree changes relative to HEAD (default mode)
node scripts/change-impact.mjs .

# Changes between two Git refs
node scripts/change-impact.mjs . --base origin/main --head HEAD

# Explicit unified diff file (works without a Git directory)
node scripts/change-impact.mjs . --diff change.patch

# Manually provided changed-file list (non-Git projects)
node scripts/change-impact.mjs . --changed-files src/a.ts,src/b.ts

# Output directory plus a Mermaid diagram; warnings listed on stderr
node scripts/change-impact.mjs . --output reports --mermaid --strict

3. As a library dependency

import { analyze, writeReportFiles } from 'dsh-change-impact/core';

const result = await analyze({ repo_path: '.', base: 'origin/main' });
// result is the change-impact.json payload: changed_files / propagation / risks / verification
await writeReportFiles(result, { output: 'reports' });

CLI options

Option	Default	Description
<repo>	.	Target repository path (first positional argument, optional)
--base <ref> / --head <ref>	-	Git ref range; --head requires --base
--diff <path>	-	Unified diff file (explicit diff takes priority over Git refs)
--changed-files <value>	-	Changed-file list: read as "one path per line (# comments allowed)" when the value is an existing file, otherwise parsed as a comma-separated list
--max-depth N	4	Scanner directory/dependency scan depth
--max-propagation N	3	Reverse propagation depth cap
--max-files N	scanner default (2000)	Scanner file-count cap
--include-dirs a,b	all	Restrict scanning to these directories (scanner matches by path prefix; prefer top-level dirs; repeatable)
--exclude-dirs a,b	none extra	Extra excluded directories (matched as path segment names; repeatable)
--include-untracked / --no-include-untracked	on	Include untracked files
--include-tests / --no-include-tests	on	Include test-file changes in the analysis
--format json|markdown|both	both	Output format
--output <path>	CHANGE-IMPACT.md	Extension-less paths are treated as directories; change-impact.md pairs with change-impact.json in the same directory; a .json output pairs with the same-named .md
--mermaid	off	Also emit change-impact.mmd (the diagram is not the source of truth)
--strict	off	Write warnings and pending items to stderr (does not change the exit code)
--help, -h	-	Show help

Exit codes: 0 success; 1 warnings, scan truncation or low-confidence results (mapped from result.flags); 2 missing input, invalid Git ref or missing directory; 3 scanner schema incompatible or report write failure. Existing output files are overwritten by default.

Output

Artifact	Description
CHANGE-IMPACT.md	Fixed 8 sections + appendix: summary / change scope / propagation / risk list / verification plan / test protection and gaps / docs and release impact / limits and pending items; facts, inferences and pending items are tagged [Fact], [Inference], [Pending] ([事实] / [推断] / [待确认] in the rendered Chinese report)
change-impact.json	Machine-readable analysis result (schema_version 1.0): changed_files, five-layer impact objects, propagation, risks, verification, test_gaps, warnings, flags
change-impact.mmd	Optional Mermaid impact diagram; the diagram is not the source of truth — tables and evidence stand alone

Safety boundaries

• Read-only promise: the analysis never writes to the repository and never runs repository scripts or run_methods commands; every read-only git query executed by working_tree/base_head modes is disclosed in the report appendix.
• Transparent rules: risk levels are computed by the fixed rules in docs/risk-rules.md; every conclusion carries factors, evidence and a confidence. Scores assist decisions and are never presented as objective truth.
• Schema contract: the scanner report's schema_version must be 1.x; anything else fails deterministically (exit code 3) instead of degrading silently.
• No overwrite protection note: this tool overwrites existing output files by default (PLAN §8 defines no --force, unlike some sibling plugins).

Combining with other plugins

arch-doc             → describes "what is": architecture baseline and entry-point notes
dsh-repo-scanner     → unified facts, symbols and dependencies (this plugin's npm dependency)
dsh-change-impact    → describes "what this change affects": propagation + risk + verification plan (this plugin)
dsh-refactor-insight → describes "what to refactor long-term": long-term tech debt and structural risk
dsh-test-insight     → describes "which behavior needs test protection": test plans and gaps from impact results

Recommended chain: fix the architecture baseline with arch-doc, run dsh-change-impact on the change to get impact and the minimal verification set, feed propagation.impacted_files and test_gaps to dsh-test-insight for a test plan, and use dsh-refactor-insight's long-term debt list to explain why some areas have a large blast radius. Plugins integrate only through their artifacts (JSON reports) and never run each other's commands.

Troubleshooting

"The target directory is not a usable Git repository"? working_tree/base_head modes require a Git repository; for non-Git directories use --diff or --changed-files.

Exit code 1 but the report looks fine? Exit code 1 means warnings, scan truncation or low-confidence results exist (e.g. propagation hit the 3-level cap, or the changed_paths mode has no line-level facts); use --strict to list warnings, or raise --max-propagation and re-run.

"Scanner report contract validation failed" or exit code 3? The installed dsh-repo-scanner is incompatible (schema 1.x required); upgrade the scanner into the range declared in package.json (^0.1.2).

"Report write failed" for the output path? Pointing --output inside a file path (using a file path where a directory is expected) triggers exit code 3; only extension-less paths are treated as directories.

Some changed paths show "not in the scan index"? Those paths were filtered out by scanner exclusions or no longer exist (e.g. --exclude-dirs, binary/generated files); dependency and symbol facts are missing for them, so conclusions fall back to file level.

Documentation

• docs/risk-rules.md — authoritative risk-scoring rules and fixture-pinned boundaries
• schema/change-impact-result.v1.md — change-impact.json result schema (v1.0) field contract
• src/README.md — core module tour (public API via src/index.mjs)
• skills/change-impact-runbook/SKILL.md — DSH skill runbook (five stages + red lines)
• CHANGELOG.md — release history
• PLUGIN-MAINTENANCE.md — repository maintenance rules
• PUBLISHING.md — publishing handbook

License

MIT