architecture-analysis

Architecture Analysis

Purpose

Enforce the intended dependency structure of a JS/TS codebase — circular dependencies, orphan modules, and declared layer/import boundaries (e.g. "the UI layer must not import from the data layer directly"). This is structural analysis SonarQube does not do for JS/TS.

Scope / no double coverage: this skill targets JS/TS via dependency-cruiser. JVM/architecture-level analysis is intentionally not duplicated here — SonarQube Server's built-in Architecture feature (the former Structure101 engine, acquired by Sonar) already covers that, so use the sonarqube-quality skill for JVM architecture.

Core Workflow (drive to zero)

1. Analyze:

   ~/.claude/skills/architecture-analysis/scripts/scan.sh [TARGET_DIR]
   

   If the project has no .dependency-cruiser.{cjs,js,json}, the scan uses a bundled default ruleset (no-circular = error, no-orphans = warn) mounted read-only into the container — it is never written into your repo.
2. Fix violations:
   • Circular dependency: break the cycle — extract a shared module, invert a dependency, or introduce an interface.
   • Orphan: delete dead code or wire the module in.
   • Layer/import rule: route the dependency through the allowed boundary.
3. Re-run until RESULT: PASS.

Defining real architecture rules

The bundled default ruleset is only a starting point. To enforce real layering, create your own .dependency-cruiser.cjs in the project root (it is used instead of the default when present), e.g.:

{ name: 'ui-not-to-db', severity: 'error',
  from: { path: '^src/ui' },
  to:   { path: '^src/data' } }

Add forbidden/allowed/required rules; dependency-cruiser fails the run on any error-severity match.

Notes

• The npm cache is persisted in the depcruise-npm Docker volume; the first run downloads dependency-cruiser + typescript, later runs are fast.
• Source directories are auto-detected (src, lib, app, source, packages); falls back to the whole project.
• For a visual graph, set DEPCRUISE_OUTPUT_TYPE=dot (or mermaid/json). This is review-only, printed in addition to the gate — the pass/fail verdict is ALWAYS derived from an internal err-long run (the graph reporters exit 0 even when there are violations, so they must never be the gate signal).

Resources

• scripts/scan.sh — runs dependency-cruiser against a JS/TS project (source tree mounted read-only); uses a bundled read-only default ruleset (never written into the repo) unless the project ships its own; exit 1 on violations. Skips cleanly when there is no real JS/TS source.
• scripts/default.dependency-cruiser.cjs — the bundled default ruleset.