dsh-refactor-insight
English | 简体中文
A DSH skill plugin: turns codebase smells into an executable refactoring plan with locations, priorities, and dependency ordering — a structural health check, not a diff review.
> Turn codebase smells into an executable, priority-ordered refactoring plan.
Positioning
Complementary by design: arch-doc looks at whole-repo structure (understanding the current state), existing code-review tools look at PRs/diffs (gating changes), and this plugin looks at whole-repo smells (outputting an action plan).
It answers:
- Which files, functions, and classes exceed healthy thresholds (length / nesting / method count)?
- Which modules are too coupled, and are there dependency cycles?
- How should findings be prioritized by severity and fix cost?
- In what dependency order should the refactoring proceed?
Boundaries (red lines): outputs a plan only — never modifies code automatically; high-risk refactoring items are flagged by the LLM and require human confirmation. The script only yields hard facts (deterministic scanning, all six rule thresholds overridable); severity / cost / suggested actions are added by the LLM after pruning false positives, marked as inference.
Capabilities (v0)
Six deterministic smell rules (zero-dependency heuristics):
- Oversized files (default > 400 lines)
- Long functions (Python indent blocks / JS-TS brace pairing / Go function declarations; body > 80 lines)
- Deep nesting (default max indent / brace depth > 5)
- God objects (> 10 class methods or class body > 300 lines / Go receiver method count)
- Highly coupled modules (reuses
arch-profile --depsoutput; hub modules by in/out degree + Tarjan cycle detection) - TODO/FIXME density (noise metric, reported per 1k lines plus the first marker line)
Installation
As a DSH plugin (recommended):
dsh plugin --profile web add "github:duyanta123/dsh-refactor-insight#v0.2.0"
Or from npm:
npm install dsh-refactor-insight
Compatibility tiers: the standalone diagnostic scripts (refactor-smell.mjs / arch-profile.mjs) run on Node.js >= 18; as a DSH 0.2.1-rc.2 plugin it is verified with Node.js >= 22.19. Run npm run test:compat to execute an isolated-profile add, dump-config, and startup smoke test.
Local development: add "dsh-refactor-insight": "file:/dsh-refactor-insight" to the profile's package.json and "dsh-refactor-insight" to the bundles array.
Quick Start
1. Use as a DSH skill
After installing, restart the profile and tell the agent:
Use refactor-insight to health-check /path/to/repo
The skill runs a four-phase runbook (intake → scan → diagnose → prioritize & orchestrate) and generates REFACTOR-PLAN.md following the docs/refactor-plan-template.md skeleton.
2. Run only the diagnostic CLI (zero dependencies, works without DSH)
# All six rules
node scripts/refactor-smell.mjs
# Reuse arch-profile's dependency output for coupling/cycle detection
node scripts/arch-profile.mjs --deps > deps.json
node scripts/refactor-smell.mjs --deps-json deps.json
CLI Options
| Option | Default | Description |
|---|---|---|
--max-lines |
400 | Oversized file threshold (lines) |
--max-func-lines |
80 | Long function threshold (body lines) |
--max-nesting |
5 | Deep nesting threshold (indent/brace depth) |
--max-methods |
10 | God object threshold (class method count) |
--max-class-lines |
300 | God object threshold (class body lines) |
--max-coupling |
4 | High-coupling threshold (in/out degree) |
--max-depth |
4 | Directory scan depth (1–10) |
--include-dirs |
- | Analyze only these directories |
--exclude-dirs |
- | Extra excluded directories |
--deps-json |
- | Reuse arch-profile --deps output for coupling/cycle detection |
Sample output (excerpt):
{
"language": "javascript/typescript",
"smells": [
{
"rule": "god-object",
"type": "god_object",
"path": "src/lib/GodService.js",
"name": "GodService",
"methods": 12,
"threshold": 10,
"severity": 2,
"cost": "M"
}
]
}
Output
REFACTOR-PLAN.md: a structured refactoring plan with the fixed skeleton of summary → findings table (location/type/evidence/severity/cost/suggested action/risk) → priority ordering → dependency-ordered orchestration → appendix (rule thresholds, scan scope, generation time).
Safety Boundaries
- Plan only: no diffs generated, no automatic code changes; high-risk items require human confirmation.
- Read-only scanning: the diagnostic scripts have zero dependencies, no subprocesses, no network, and never modify the target repo's source.
- Facts vs. inference: the script emits hard facts; severity/cost/suggestions added by the LLM are always marked as inference.
Troubleshooting
No coupling/cycle findings?
That rule needs a dependency graph as input: run node scripts/arch-profile.mjs --deps > deps.json first, then pass it via --deps-json deps.json (see Quick Start).
The findings include false positives?
By design: the script emits deterministic hard facts, and false-positive pruning is the LLM's job in the runbook phase (checked one by one with added context); when using the CLI alone, judge by the severity / cost fields plus the rule-specific fact fields (e.g. lines, max_depth, methods).
Many TODO/FIXME density findings?
That rule is a noise metric (per-1k-line counts plus the first marker line) and does not require action; it carries the lowest weight in plan ordering.
Old sessions won't open after upgrading the DSH host to 0.1.5.x?
The Session format V3 migration is irreversible and is host behavior; back up session logs before upgrading the host (see the 0.1.3 entry in CHANGELOG.md).
Documentation
- docs/refactor-plan-template.md — the
REFACTOR-PLAN.mdoutput skeleton - CHANGELOG.md — release notes
- PLUGIN-MAINTENANCE.md — repo maintenance runbook
- DSH-REFACTOR-INSIGHT-开发计划.md — design decisions and iteration history
License
MIT
