ts-archunit

Architecture guardrails for AI coding agents. Executable rules that catch structural violations in CI — before they reach your codebase.

Inspired by Java's ArchUnit. Powered by ts-morph.

Documentation · Getting Started · What Can It Check?

The Problem

AI coding agents don't know your architecture. They generate code that compiles, passes type checks, and looks correct in isolation — but violates the structural decisions your team spent months establishing.

An agent will:

• Call parseInt instead of the shared extractCount() helper
• Throw new Error() instead of your typed NotFoundError
• Import the database driver directly from a service instead of going through the repository
• Copy-paste a parser function instead of using the shared utility
• Skip validation in a route handler

Code review catches some of this. But at scale — with multiple agents generating PRs across a large codebase — review becomes the bottleneck. You need automated enforcement.

The Solution

ts-archunit turns your architecture decisions into executable tests. They run in CI. Violations show up inline on the PR with clear messages explaining what's wrong, why it matters, and how to fix it — exactly the context an agent needs to self-correct.

classes(p)
  .that()
  .extend('BaseRepository')
  .should()
  .notContain(newExpr('Error'))
  .rule({
    id: 'repo/typed-errors',
    because: 'Generic Error loses context and prevents consistent error handling',
    suggestion: 'Use NotFoundError, ValidationError, or DomainError instead',
  })
  .check()

When an agent violates this rule, it sees:

Architecture Violation [repo/typed-errors]

  WebhookRepository.findById contains new 'Error' at line 42
  at src/repositories/webhook.repository.ts:42

      41 |     if (!result) {
    > 42 |       throw new Error(`Webhook '${id}' not found`)
      43 |     }

  Why: Generic Error loses context and prevents consistent error handling
  Fix: Use NotFoundError, ValidationError, or DomainError instead

The because and suggestion fields give the agent everything it needs to fix the violation without human intervention.

Why Not Just Import Rules?

Every other tool (dependency-cruiser, eslint-plugin-boundaries, ts-arch) only checks which files import which. That's necessary but insufficient.

AI agents don't violate architecture by importing wrong files. They violate it by writing the wrong code in the right place — inlining logic instead of delegating, using raw APIs instead of abstractions, skipping validation, throwing generic errors.

ts-archunit checks what happens inside your functions:

// "Services must delegate to repositories, not hardcode data"
functions(p)
  .that()
  .resideInFolder('**/services/**')
  .should()
  .satisfy(mustCall(/Repository/))
  .check()

// "No eval anywhere in production code"
modules(p).that().resideInFolder('**/src/**').should().satisfy(moduleNoEval()).check()

// "Route handlers must validate input"
functions(p)
  .that()
  .resideInFolder('**/handlers/**')
  .should()
  .satisfy(mustCall(/validate|parse/))
  .check()

| Capability | ts-archunit | dependency-cruiser | eslint-plugin-boundaries | Biome | ts-arch | | -------------------------------------------------- | ----------- | -------------------------------------------------------------------- | ---------------------------------------------------------------------------------- | ---------------------------- | --------------------------------------------- | | Import path rules | Yes | Yes | Yes | Yes | Yes | | Body analysis (what's called inside functions) | Yes | No | No | No | No | | Type checking (string vs typed union) | Yes | No | No | No | No | | JSX element rules | Yes | No | No | No | No | | Cross-layer rules | Yes | No | No | No | Partial | | Cycle detection | Yes | Yes | No | No | Yes | | Code smell detection (duplicate bodies) | Yes | No | No | No | No | | Code metrics (cyclomatic, LOC) | Yes | No | No | No | No | | Pattern matching (reusable rule templates) | Yes | No | No | No | No | | Baseline (gradual adoption) | Yes | No | No | No | No | | Diff-aware / PR-only checking | Yes | No | No | No | No | | Watch mode | Yes | No | No | Yes | No | | Inline exclusion comments | Yes | No | Via ESLint | Yes | No | | GitHub PR annotations | Yes | No | Via ESLint | No | No |

Why Deterministic Rules — and Why Now

AI agents don't just make mistakes; they make the same mistakes at volume, and they produce "dark code that passes tests but undermines implicit architectural constraints" (Katie Roberts, NearForm). The field's numbers agree: AI's productivity gains dissipate in ~3 months as architectural debt accrues (Carnegie Mellon, via Sonar), while commits rose 25% as review comments fell 27% and 31% more PRs now merge with no review at all (GitHub / Faros, via eBay's ReviewDebt). Review is the bottleneck — so the architecture dimension of review has to be settled mechanically.

Two kinds of tool are converging on that job. ts-archunit is the one that stays deterministic:

• SonarQube and other scanners are computational but verify a fixed catalog — generic quality, security, complexity. They can't be taught your invariants ("repositories extend BaseRepository", "every route has a permission-matrix entry").
• LLM review agents can judge intent, but non-deterministically — "you don't want the green/red state of your pipeline to depend on an LLM's semantic interpretation" (Birgitta Böckeler, ThoughtWorks); the same PR scores differently as the model changes (eBay).

ts-archunit is the deterministic, computational gate for your team's own architecture — the cell neither of the above fills. A rule is defensible in a review, and unlike a prompt or a CLAUDE.md convention (half-life: weeks), it doesn't rot when the model changes.

→ Full argument and sources: Why ts-archunit

Quick Start with Presets

One function call enforces an entire architecture pattern — layer ordering, cycles, import direction, package restrictions:

import { project } from '@nielspeter/ts-archunit'
import { layeredArchitecture } from '@nielspeter/ts-archunit/presets'

const p = project('tsconfig.json')

layeredArchitecture(p, {
  layers: {
    routes: '**/src/routes/**',
    services: '**/src/services/**',
    repositories: '**/src/repositories/**',
  },
  shared: ['**/src/shared/**'],
  strict: true,
})

This generates 5 coordinated rules. Override individual rules without disabling the preset:

layeredArchitecture(p, {
  layers: { ... },
  overrides: {
    'preset/layered/type-imports-only': 'off',
  },
})

Three presets available: layeredArchitecture, dataLayerIsolation, strictBoundaries.

Feed Your Architecture to the Agent

The explain command dumps all active rules as structured JSON — pipe it into your agent's system prompt so it knows the constraints before writing code:

npx ts-archunit explain arch.rules.ts

{
  "rules": [
    {
      "id": "repo/typed-errors",
      "rule": "that extend 'BaseRepository' should not contain new 'Error'",
      "because": "Generic Error loses context and prevents consistent error handling",
      "suggestion": "Use NotFoundError, ValidationError, or DomainError instead"
    }
  ]
}

The agent reads the rules, understands the constraints, and generates compliant code from the start. When it doesn't, CI catches it with actionable violation messages.

Custom Rules

The fluent API reads like English:

// Select → Filter → Assert → Execute
classes(p).that().extend('BaseRepository').should().notContain(call('parseInt')).check()

Body Analysis

Inspect what happens inside functions — the differentiator:

// Ban inline parseInt — use the shared helper
classes(p)
  .that()
  .extend('BaseRepository')
  .should()
  .useInsteadOf(call('parseInt'), call('this.extractCount'))
  .check()

// Services must delegate to repositories
functions(p)
  .that()
  .resideInFolder('**/services/**')
  .should()
  .satisfy(mustCall(/Repository/))
  .check()

// No process.env in domain — use dependency injection
functions(p).that().resideInFolder('**/domain/**').should().satisfy(functionNoProcessEnv()).check()

Layer Enforcement

slices(p)
  .assignedFrom({
    controllers: '**/src/controllers/**',
    services: '**/src/services/**',
    repositories: '**/src/repositories/**',
  })
  .should()
  .respectLayerOrder('controllers', 'services', 'repositories')
  .check()

slices(p).matching('src/features/*/').should().beFreeOfCycles().check()

Type-Level Rules

Check property types using the TypeScript type checker:

types(p)
  .that()
  .haveProperty('orderBy')
  .should()
  .havePropertyType('orderBy', not(isString()))
  .rule({
    because: 'Bare string orderBy is a SQL injection surface',
    suggestion: "Use a union type: orderBy?: 'created_at' | 'updated_at'",
  })
  .check()

Standard Rules Library

25+ ready-to-use rules across 8 categories:

import {
  functionNoEval,
  functionNoConsole,
  functionNoJsonParse,
} from '@nielspeter/ts-archunit/rules/security'
import { functionNoGenericErrors } from '@nielspeter/ts-archunit/rules/errors'
import { mustCall } from '@nielspeter/ts-archunit/rules/architecture'
import { noDeadModules, noStubComments, noEmptyBodies } from '@nielspeter/ts-archunit/rules/hygiene'

functions(p).that().resideInFolder('**/src/**').should().satisfy(functionNoEval()).check()
functions(p).that().resideInFolder('**/src/**').should().satisfy(noEmptyBodies()).check()
functions(p).that().resideInFolder('**/src/**').should().satisfy(noStubComments()).check()

Categories: rules/typescript, rules/security, rules/errors, rules/naming, rules/dependencies, rules/code-quality, rules/metrics, rules/architecture, rules/hygiene.

Baseline Mode

Adopt rules in existing codebases without fixing every pre-existing violation:

const baseline = withBaseline('arch-baseline.json')

// Only NEW violations fail — existing ones are recorded
classes(p).should().notContain(call('parseInt')).check({ baseline })

GitHub Actions Annotations

Violations appear inline on PR diffs — automatically detected in GitHub Actions:

classes(p).should().notContain(call('eval')).check({ format: detectFormat() })

Smell Detection

Find code drift — duplicate function bodies and inconsistent patterns:

// .check() fails the build; .warn() reports without failing. There is no
// default — pick one. An AI agent only reads failures, so prefer .check()
// and accept an existing backlog with withBaseline() rather than warning.
smells.duplicateBodies(p).inFolder('**/src/routes/**').withMinSimilarity(0.9).check()

smells
  .inconsistentSiblings(p)
  .inFolder('**/src/repositories/**')
  .forPattern(call('this.extractCount'))
  .warn()

Assert the project's own TypeScript strictness (with strict-family resolution, so strict: true implies its sub-flags):

tsconfig(p).requires({ strict: true, noUncheckedIndexedAccess: true }).check()

More Features

• Call matching — framework-agnostic route/handler inspection (Express, Fastify, Hono)
• Scoped rules — within(routes).functions() for callback-level rules
• Pattern templates — enforce return type shapes ({ items, total, skip, limit })
• GraphQL rules — schema and resolver conventions
• Cross-layer validation — route/schema/SDK consistency
• Custom predicates and conditions — definePredicate(), defineCondition(), and/or/not combinators
• Metrics — cyclomatic complexity, lines of code, method count limits
• CLI — check, baseline, explain, doctor, --watch mode

Entry Points

| Function | Operates on | Use case | | -------------- | ----------------------------------------- | ----------------------------------------------- | | modules(p) | Source files | Import/dependency rules | | classes(p) | Class declarations | Inheritance, decorators, methods, body analysis | | functions(p) | Functions, arrow functions, class methods | Naming, parameters, body analysis | | types(p) | Interfaces + type aliases | Property types, type safety | | slices(p) | Groups of files | Cycles, layer ordering | | calls(p) | Call expressions | Framework-agnostic route/handler matching | | within(sel) | Scoped callbacks | Rules inside matched call callbacks |

Compared to Other Tools

| Capability | ts-archunit | dependency-cruiser | ArchUnitTS | Biome | ts-arch | | ------------------------------------------------- | --------------- | -------------------------------------------------------------------- | -------------------------------------------------------- | ---------------------------- | --------------------------------------------- | | Import path rules | Yes | Yes | Yes | Yes (noRestrictedImports) | Yes | | Body analysis (calls, access, constructors) | Yes | No | No | No | No | | Type checking (resolved types via ts-morph) | Yes | No | No | No | No | | Class rules (inheritance, decorators, members) | Yes | No | No | No | No | | Function rules (params, return types, async) | Yes | No | No | No | No | | JSX element rules | Yes | No | No | No | No | | Cross-layer rules (pair-condition per layer) | Yes | No | No | No | Partial (layered slices) | | Cycle detection | Yes | Yes | Yes | No | Yes | | Parameterized presets | Yes | Flat config | No | No | No | | Pattern matching (reusable rule templates) | Yes | No | No | No | No | | Code smell detection (duplicate bodies, siblings) | Yes | No | No | No | No | | Code metrics | Cyclomatic, LOC | No | LCOM, coupling, instability | No | No | | Baseline / gradual adoption | Yes | No | No | No | No | | Diff-aware / PR-only checking | Yes | No | No | No | No | | Watch mode | Yes | No | No | Yes | No | | Inline exclusion comments | Yes | No | No | Yes (biome-ignore) | No | | JSON output format | Yes | Yes | Via vitest | Yes | Via test runner | | GitHub PR annotations | Yes | No | No | No | No | | Violation messages with fix suggestions | Yes | No | No | Partial (autofixes) | No | | explain command (dump rules as JSON for agents) | Yes | No | No | No | No | | PlantUML diagram compliance | No | No | Yes | No | No | | Dependency graph visualization | No | Yes (dot, HTML) | No | No | No | | License checking | No | Yes | No | No | No | | Nx monorepo support | No | No | Yes | No | No |

Use ts-archunit when you need to enforce what happens inside functions — call patterns, error types, missing delegation, stub comments — and when AI agents are generating code that needs architectural guardrails. This is the only tool that catches "service calls parseInt instead of extractCount()", flags duplicate function bodies as smells, and can restrict checking to only the files changed in a PR.

Use dependency-cruiser when you only need import direction rules and want fast graph visualization, license compliance checking, or stability metrics. It's faster (no ts-morph project load) and has mature HTML/dot reporting.

Use ArchUnitTS when you need OO metrics (LCOM cohesion, coupling factor, distance from main sequence), PlantUML diagram validation, or Nx monorepo project-graph awareness.

Use Biome when you want a fast Rust-based lint + format toolchain and only need lint-level import restrictions (noRestrictedImports) — not architecture rules over class hierarchies, function bodies, or slice cycles. Pair it with ts-archunit if you want both.

Use ts-arch when you want the classic ArchUnit-style fluent API scoped to file/folder dependency rules and layered slices, and don't need body analysis, type-checker rules, or CI integrations like baselines, diff-aware runs, or GitHub annotations.

Use ts-archunit + dependency-cruiser together if you want both body-level enforcement and dependency graph visualization.

Install

npm install -D @nielspeter/ts-archunit
npx ts-archunit init   # scaffold config + rules + npm scripts

init generates a ts-archunit.config.ts, an arch.rules.ts seeded with the recommended safety floor (or --preset agent-guardrails), and arch / arch:baseline scripts — then run npm run arch.

Requires Node.js >= 24 and a tsconfig.json. Works with vitest (recommended) or jest.

Upgrading

CHANGELOG.md ships inside the package, so it is readable at node_modules/@nielspeter/ts-archunit/CHANGELOG.md without a network round trip — which matters because several releases require an action rather than merely describing one. Each entry carries an Upgrading section naming what to run before you upgrade and what changes after.

License

MIT