ts-modularity

Scan a TypeScript codebase, build a dependency graph, and serve an interactive visualization — all in one command.

npx ts-modularity

No install required. Opens a browser at http://localhost:3008.

---

Demo

---

Features

• Five views — Chord diagram, Force graph, DAG layout, Coupling matrix, Move Suggestions
• Modularity score per cluster (0 = cohesive, 1 = coupled)
• Move suggestions — per-file refactor candidates with confidence rating and ready-to-run git mv commands
• Bidirectional cycle detection highlighted in the matrix view
• tsconfig path aliases resolved automatically
• Optional config file to define explicit module boundaries
• Zero runtime dependencies

---

Usage

# Scan ./src, serve on port 3008
npx ts-modularity

# Custom source dir
npx ts-modularity --src ./packages/app/src

# Write files only, no server
npx ts-modularity --no-serve

# All options
npx ts-modularity --src ./src --out ./dep-graph-out --depth 1 --port 3008

Options

Flag	Default	Description
--src <dir>	.	Directory to scan for .ts / .tsx files
--out <dir>	./dep-graph-out	Output directory for graph.json and index.html
--depth <n>	1	Cluster grouping depth when no config file is present
--port <n>	3008	Preferred HTTP port (falls back to a random port if unavailable)
--no-serve	—	Write output files and exit without starting the server
--help	—	Print help

Output files

File	Description
dep-graph-out/graph.json	Raw graph data — clusters, edges, modularity metrics
dep-graph-out/index.html	Self-contained interactive visualization

---

Config file

Create dep-graph.config.json in your project root to define explicit module boundaries.

{
  "excludeOther": true,
  "modularityThreshold": 0.4,
  "modules": [
    "src/api/*",
    "src/app/*",
    "src/services/*",
    "src/store/*",
    "src/utils/*",
    "src/components"
  ]
}

Module rule syntax

Rules are relative to the project root (where dep-graph.config.json lives), not --src.

Pattern	Behavior
"src/api/*"	Each direct child of src/api/ becomes its own cluster (api/checkout, api/user, …)
"src/components"	Entire src/components/ is one cluster
"src/store/auth"	Exactly src/store/auth/ is one cluster
"packages/*"	Each package in a monorepo becomes its own cluster

Rules are matched in order — first match wins. Files that match no rule:

• excludeOther: false (default) — grouped into an <other> cluster
• excludeOther: true — excluded from the graph entirely

Config fields

Field	Type	Default	Description
modules	string[]	[]	Module boundary rules (see syntax above)
excludeOther	boolean	false	Drop files that match no rule
modularityThreshold	number	0.4	Informational — clusters above this score are flagged

---

Understanding the metrics

Modularity score measures how self-contained a cluster is:

modularity = internal_edges / (internal_edges + external_edges)

Score	Meaning
1.0	Fully modular — all dependencies are internal
0.5	Equal internal and external coupling
0.0	Fully coupled — no internal dependencies

Color coding in the UI: green ≥ 0.67, amber ≥ 0.34, red < 0.34.

---

Views

Chord

Default view. Arcs represent clusters; ribbons show inter-cluster imports weighted by import count.

Force graph

Physics simulation. Node size scales with file count; the instability arc shows the modularity score. Drag nodes to explore.

DAG layout

Layered top-down layout grouped by modularity bucket. Orthogonal edge routing. Use the Sort dropdown to reorder by modularity, file count, in-deps, or name.

Coupling matrix

Heatmap where row A, column B = number of imports from cluster A into cluster B. Bidirectional cells (cycle risk) are highlighted in red.

Move suggestions

Lists files whose external coupling points strongly to a different cluster. Each suggestion includes:

• Source and destination cluster
• Confidence rating (high / medium / low) based on affinity score
• A git mv command block you can copy and run directly

Adjust the threshold input and click Run to re-compute at any value. Files with score < 2 (too diffuse to have a dominant destination) are omitted.

---

Programmatic API

import { buildGraph, serve, computeSuggestions, loadModuleConfig, loadAliases } from 'ts-modularity';

const root = process.cwd();
const moduleConfig = loadModuleConfig(root);   // reads dep-graph.config.json
const aliases = loadAliases(root);             // reads tsconfig.json paths

const graph = buildGraph(root, './src', './out', 1, moduleConfig, aliases);

// graph.clusters   — ClusterNode[]
// graph.files      — FileNode[]
// graph.edges      — Edge[]
// graph.clusterEdges — ClusterEdge[]

await serve(graph, 'src', 3008);

// Compute move suggestions programmatically
const result = computeSuggestions(graph, 0.4);
// result.badClusters  — ClusterSuggestions[]
// result.gitMvCommands — string[]  (ready to run)
console.log(result.gitMvCommands.join('\n'));

Types

interface ClusterNode {
  id: string;
  label: string;
  files: number;
  outEdges: number;
  inEdges: number;
  internalEdges: number;
  modularity: number;   // 0–1
  coupling: number;
  cohesion: number;
}

interface FileNode {
  id: string;
  label: string;
  path: string;
  cluster: string;
  imports: number;
  importedBy: number;
}

interface MoveSuggestion {
  file: string;
  fromCluster: string;
  fromLabel: string;
  toCluster: string;
  toLabel: string;
  score: number;
  affinity: number;
  confidence: 'high' | 'medium' | 'low';
}

interface SuggestionsResult {
  threshold: number;
  badClusters: { cluster: ClusterNode; suggestions: MoveSuggestion[] }[];
  gitMvCommands: string[];
}

Full type definitions are exported from the package (dist/index.d.ts).

---

Requirements

• Node.js 18+
• TypeScript project with .ts / .tsx source files

---

License

MIT