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 | | -------------------------------------------------- | ----------- | ------------------ | ------------------------ | | Import path rules | Yes | Yes | Yes | | Body analysis (what's called inside functions) | Yes | No | No | | Type checking (string vs typed union) | Yes | No | No | | Cycle detection | Yes | Yes | No | | Baseline (gradual adoption) | Yes | No | No | | GitHub PR annotations | Yes | No | No |

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:

smells.duplicateBodies(p).inFolder('src/routes/**').withMinSimilarity(0.9).warn()

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

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, --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 | | ------------------------------------------------- | ----------- | -------------------------------------------------------------------- | -------------------------------------------------------- | | Import path rules | Yes | Yes | Yes | | Body analysis (calls, access, constructors) | Yes | No | No | | Type checking (resolved types via ts-morph) | Yes | No | No | | Class rules (inheritance, decorators, members) | Yes | No | No | | Function rules (params, return types, async) | Yes | No | No | | Cycle detection | Yes | Yes | Yes | | Parameterized presets | Yes | Flat config | No | | Baseline / gradual adoption | Yes | No | No | | GitHub PR annotations | Yes | No | No | | Violation messages with fix suggestions | Yes | No | No | | explain command (dump rules as JSON for agents) | Yes | No | No | | OO metrics (LCOM, coupling, instability) | No | No | Yes | | PlantUML diagram compliance | No | No | Yes | | Dependency graph visualization | No | Yes (dot, HTML) | No | | License checking | No | Yes | No | | Nx monorepo support | No | No | Yes |

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()".

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 ts-archunit + dependency-cruiser together if you want both body-level enforcement and dependency graph visualization.

Install

npm install -D @nielspeter/ts-archunit

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

License

MIT