Architecture Analyzer

Framework-agnostic tool for architectural governance and metric analysis.

Input

Analyzes a dependency graph (graph.json). Does not analyze source code directly (except for optional Knip integration).

Pairing with architecture-diagram-generator

The file that architecture-diagram-generator -o architecture.json writes is consumed directly, with no adapter. The CLI accepts either shape:

• a bare graph — { "nodes": [...], "edges": [...] }
• a wrapper with the graph under a graph key — { "graph": { "nodes": [...] }, ... }

Do not write a shim to unwrap .graph yourself, and do not hand-inject fields the generator did not emit. In particular an empty "entrypoints": [] is not a neutral default — it declares that the graph has no entrypoints. It is ignored with a warning.

Example graph.json

{
  "entrypoints": ["src/cli.ts"],
  "nodes": [
    {
      "id": "src/cli.ts",
      "metadata": { "layer": "UI", "type": "module" }
    },
    {
      "id": "lib/core.ts",
      "metadata": { "layer": "Core", "type": "module" }
    }
  ],
  "edges": [
    { "from": "src/cli.ts", "to": "lib/core.ts", "type": "import" }
  ]
}

Key Features

• Knip Integration: High-confidence detection of unused modules and exports, used only when the analyzed project already has knip installed.
• Explicit Entrypoints: Nodes listed in entrypoints are exempted from the rules that would otherwise flag them for having no dependents.
• Input Sanity Checks: Warns when the graph looks like it came from a generator that failed to resolve imports — an unresolved module is indistinguishable from an unused one, and would otherwise be reported as a violation with full confidence.
• Architectural Drift: Prevent degradation in CI/CD by comparing snapshots.
• Precision Metrics: Calculates Instability ($I$), Abstractness ($A$), and Distance ($D$) from the Main Sequence. (type-only edge filtering is implemented in MetricsCalculator but not yet enabled on the CLI path.)
• Hotspot Detection: Identifies architectural hotspots by default. Cyclomatic-complexity hotspots and prohibited inheritance (e.g. Domain extending Infrastructure) are opt-in — enable detect-complexity-hotspots / detect-inheritance-violation in .archanalyzerrc. The latter also needs params.prohibitions, or it matches nothing.
• AI-Ready: Generates optimized prompts for LLM refactoring plans.

Usage

# Basic Analysis (Knip runs only if the project depends on it; --no-knip to skip)
npx architecture-analyzer analyze graph.json

# CI/CD Drift Detection
npx architecture-analyzer analyze graph.json --baseline baseline.json

# Generate AI Refactoring Prompt
npx architecture-analyzer analyze graph.json --ai-prompt

# Skip the Knip pass
npx architecture-analyzer analyze graph.json --no-knip

TL;DR

1. Generate graph: npx architecture-diagram-generator
2. Analyze: npx architecture-analyzer analyze architecture.json --baseline last-stable.json