From qa-code-quality
Run Madge against a JS/TS production source tree to detect circular dependencies, find orphan modules, and visualize the module graph. Scoped to production code via `excludeRegExp` for test files.
How this skill is triggered — by the user, by Claude, or both
Slash command
/qa-code-quality:madge-depsThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Madge analyzes JavaScript module graphs (AMD, CommonJS, ES6) and CSS
Madge analyzes JavaScript module graphs (AMD, CommonJS, ES6) and CSS preprocessor imports (Sass, Stylus, Less) per the Madge README. NPM deps and Node core modules are excluded by default.
Cannot read property X of undefined at runtime - likely a circular import causing partial
module init.npm install -g madge
# or per-project
npm install -D madge
Optional Graphviz for visual graphs:
| OS | Install |
|---|---|
| macOS | brew install graphviz |
| Ubuntu | apt-get install graphviz |
| Windows | choco install graphviz |
Per the Madge README.
# Single entry point
madge --circular src/index.ts
# Whole directory
madge --circular src/
Exit code: 0 if none found, 1 if any circular path exists. Use directly in CI.
# Files imported by nothing
madge --orphans src/
# Files that import nothing (terminal modules)
madge --leaves src/
Orphans are deletion candidates; verify usage outside source tree (scripts, configs, side-effect imports) before removal.
# Render full graph as SVG (requires Graphviz)
madge --image graph.svg src/
# Show what depends on a specific file
madge --depends src/config/db.ts src/
# Export raw DOT for custom rendering
madge --dot src/ > graph.gv
.madgerc in project root:
{
"fileExtensions": ["ts", "tsx", "js", "jsx"],
"excludeRegExp": [
"\\.test\\.(ts|tsx|js|jsx)$",
"\\.spec\\.(ts|tsx|js|jsx)$",
"__tests__/",
"__mocks__/",
"node_modules/",
"dist/",
"build/"
],
"tsConfig": "tsconfig.json"
}
Test files are excluded so tests can intentionally import production modules without flagging the production tree.
# GitHub Actions
- name: Block circular deps
run: npx madge --circular --extensions ts,tsx src/
- name: Detect new orphans (advisory)
run: npx madge --orphans --extensions ts,tsx src/ || true
The first step fails on any circular path; the second is informational only (orphans require human judgment - could be webpack entry, dynamic import, etc.).
| Anti-pattern | Why it fails | Fix |
|---|---|---|
Scan whole repo including node_modules/ | OOM on large workspaces | excludeRegExp: ["node_modules/"] (Step 5) - actually default behavior, but verify |
| Treat orphans as "always delete" | Webpack/Vite entry points + dynamic imports look orphaned | Manual review per orphan; use --depends to verify (Step 4) |
| Allow circular deps in non-prod with "we'll fix later" | Cycles compound; mid-project untangling is brutal | Block on first cycle (Step 6); waiver template if scope-exclusion needed |
Forget tsconfig.json for path aliases | Madge can't resolve @/foo imports; reports false positives | "tsConfig": "tsconfig.json" in .madgerc (Step 5) |
Run with default extensions (js only) for TS project | Misses 100% of TS files | fileExtensions: ["ts", "tsx", "js", "jsx"] (Step 5) |
import() calls and
require() with computed strings are not in the graph.npx claudepluginhub testland/qa --plugin qa-code-qualityProvides a checklist for code reviews covering functionality, security, performance, maintainability, tests, and quality. Use for pull requests, audits, team standards, and developer training.