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

30+ Architectural Smell Detectors

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

Framework Intelligence

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

Output Formats

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

Developer Experience

• 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

Using npm (Recommended)

npm install -g @archlinter/cli
# or use without installation
npx @archlinter/cli scan

From source

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

Quick Start

Basic scan

archlint scan ./my-project

With configuration

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

Watch mode for development

archlint watch --debounce 500 --clear

Export report

# 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

Filter by severity

archlint scan --min-severity high

Run specific detectors

archlint scan --detectors cycles,god_module,dead_code

Exclude detectors

archlint scan --exclude-detectors barrel_file,lcom

Configuration

Create .archlint.yaml in your project root:

# 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.

→ 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