archlint

Fast, AST-based architecture smell detector for TypeScript/JavaScript projects

A powerful CLI tool for detecting 30+ types of architectural smells in TypeScript/JavaScript codebases. Built with Rust and oxc parser for maximum performance.

Why archlint?

Modern codebases grow complex fast. archlint helps you:

- 🔍 Detect architectural problems early before they become technical debt
- 🎯 Framework-aware analysis with presets for NestJS, Next.js, React, oclif
- ⚡ Blazingly fast - analyzes 200+ files in under 5 seconds
- 📊 Actionable insights - clear explanations, severity scores, and refactoring recommendations
- 🔄 Watch mode for real-time feedback during development
- 🧠 Smart caching for instant re-runs

Features

$3

Dependency & Structure Issues:

- Cyclic dependencies (file-level and type-level)
- Hub modules (too many connections)
- God modules (doing too much)
- Dead code (unused exports)
- Orphan types (disconnected from codebase)

Design Quality Issues:

- Low cohesion (LCOM metric)
- High coupling
- Layer violations (domain/application/infrastructure)
- SDP violations (Stable Dependencies Principle)
- Feature envy, shotgun surgery

Code Organization Issues:

- Barrel file abuse
- Scattered modules/configs
- Primitive obsession
- Long parameter lists
- Deep nesting

Framework-Specific Issues:

- Test leakage (test code in production)
- Side-effect imports
- Vendor coupling
- Unstable interfaces
- Shared mutable state

$3

Built-in presets that understand framework patterns:

- NestJS: Knows controllers are entry points, modules can have high coupling
- Next.js: Understands pages/API routes, relaxes barrel file rules
- React: Aware of component patterns, skips irrelevant checks
- oclif: Recognizes CLI commands and hooks

$3

- Table (default) - clean terminal output with colors
- Markdown - detailed reports with Mermaid dependency graphs
- JSON - machine-readable for CI/CD integration

$3

- Watch mode with debouncing for live feedback
- Smart caching using content hashes
- Severity filtering (low/medium/high/critical)
- Selective detector runs (include/exclude specific checks)
- Git integration for churn analysis
- CI-friendly quiet mode

Installation

$3

``bash
npm install -g @archlinter/cli


or use without installation


npx @archlinter/cli scan
`

$3

`bash
git clone https://github.com/superprotocol/archlint.git
cd archlint
cargo build --release
cargo install --path crates/archlint
`

Quick Start

$3

`bash
archlint scan ./my-project
`

$3

`bash
archlint scan ./my-project --config .archlint.yaml
`

$3

`bash
archlint watch --debounce 500 --clear
`

$3

`bash


Markdown with diagrams

archlint scan ./my-project --format markdown --report architecture-report.md

JSON for CI/CD

archlint scan ./my-project --format json --report report.json

Or use the shorter --json flag

archlint scan ./my-project --json --report report.json
`

$3

`bash
archlint scan --min-severity high
`

$3

`bash
archlint scan --detectors cycles,god_module,dead_code
`

$3

`bash
archlint scan --exclude-detectors barrel_file,lcom
`

Configuration

Create .archlint.yaml in your project root:

`yaml


Files/directories to ignore

ignore:
- '/node_modules/'
- '/dist/'

Path aliases (from tsconfig.json)

aliases:
'@/': 'src/'

Entry points (won't be marked as dead code)

entry_points:
- 'src/main.ts'

Rule-specific configuration

rules:
cycles: high

god_module:
severity: high
fan_in: 15
fan_out: 15
churn: 20

layer_violation:
severity: high
layers:
- name: domain
path: '/domain/'
allowed_imports: []
- name: application
path: '/application/'
allowed_imports: ['domain']

complexity:
max_complexity: 15

Rule overrides for specific paths

overrides:
- files: ['/tests/']
rules:
complexity: off
god_module: off

Scoring and grading settings

scoring:
minimum: medium
weights:
critical: 100
high: 50
medium: 20
low: 5

Framework preset

extends: nestjs
`

Available Detectors

Run archlint detectors list to see all detectors with descriptions.

| ID | Name | Default Enabled |
| ----------------- | --------------------- | --------------- |
| cycles | Circular Dependencies | ✅ |
| god_module | God Module | ✅ |
| dead_code | Dead Code | ✅ |
| layer_violation | Layer Violation | ⚠️ |
| complexity` | High Complexity | ✅ |
| ... | ... | ... |

→ See full list of detectors

License

MIT License - see LICENSE for details.

Credits

- Built with oxc - blazingly fast JS/TS parser
- Inspired by ArchUnit, madge