Truss — Architecture Boundary Enforcement Tool

Truss is a CLI tool that enforces architectural boundaries in JavaScript and TypeScript projects.

It prevents unintended dependencies between layers, such as controllers importing database modules directly, by analyzing static imports and building a dependency graph.

Truss detects both direct and transitive violations and is designed for deterministic local runs and CI pipelines.

Why Truss

As applications grow, architectural boundaries are often violated unintentionally:

• controllers start importing database modules directly
• routes bypass services
• dependencies become tangled and hard to reason about

Truss enforces these boundaries automatically, helping prevent architectural drift.

Quick Start

Run without installing:

npx truss-lint init
npx truss-lint check

Or install globally:

npm install -g truss-lint
truss-lint init
truss-lint check

Dependency Graph Visualization

Truss can render a dependency graph of your project with layer grouping and highlighted architectural violations.

Usage

1. Install

Install locally in your project:

npm install -D truss-lint

Or run directly with npx:

npx truss-lint init
npx truss-lint check

2. Initialize configuration

Create a starter configuration file in your project:

npx truss-lint init

This generates a truss.yml file in your project root.

3. Configure layers and rules

Edit the generated truss.yml to define your architecture:

version: "1"

layers:
  client:
    - "client/**/*.ts"
    - "client/**/*.tsx"
  server:
    - "server/**/*.ts"

rules:
  - name: no-client-to-server
    from: client
    disallow: [server]

4. Run analysis

npx truss-lint check

5. Generate a dependency graph

npx truss-lint graph > graph.dot
dot -Tsvg graph.dot -o graph.svg

This helps visualize architectural structure and identify problematic dependencies.

How It Works

Truss performs deterministic static analysis using a dependency graph pipeline:

1. Load and validate truss.yml
2. Discover source files (.ts, .tsx, .js, .jsx)
3. Parse imports and build dependency edges
4. Assign files to layers
5. Evaluate rules
6. Apply suppressions
7. Render human-readable or JSON output
8. Exit with a CI-friendly status code

Key Features

• Graph-based dependency analysis
• Detection of direct and transitive architectural violations via graph traversal
• Dependency cycle detection integrated into analysis diagnostics
• Layer-based architecture enforcement via configuration
• Deterministic CLI and JSON outputs
• CI integration for automated architectural checks
• Visual graph rendering with violation highlighting

Exit Code Matrix

• 0 No unsuppressed violations
• 1 One or more unsuppressed architectural violations
• 2 Configuration or CLI usage error
• 3 Internal error

Sample Output (Violation)

Truss: Architectural violations found (2)

Direct Violations (1)
--------------------------------
[VIOLATION] no-api-to-db
Layers: api -> db
src/api/user.ts:15
import { db } from "../db/client";
Reason: API layer must not depend directly on DB layer.

Transitive Violations (1)
--------------------------------
[TRANSITIVE VIOLATION] no-api-to-db
Layers: api -> db
src/api/user.ts:0
[transitive]
Path: src/api/user.ts -> src/service/status.ts -> src/db/client.ts
Reason: API layer must not depend on DB layer.

Summary:
Unsuppressed: 2
Suppressed: 0
Total: 2

Sample Output (Success)

Truss: No Architectural violations found
Checked 9000 files

Deterministic Output

Truss guarantees stable and deterministic output across runs:

• consistent sorting of violations
• stable JSON schema
• snapshot-safe CLI output

This ensures reliable CI checks and predictable developer experience.

JSON Output Contract

When --format json is provided, Truss prints exactly one JSON object to stdout.

Schema versioning

All JSON output includes:

• schemaVersion
• kind (report or error)

Report output (kind: "report")

{
  "schemaVersion": "1.1.0",
  "kind": "report",
  "exitCode": 1,
  "checkedFiles": 42,
  "edges": 137,
  "unsuppressed": [],
  "suppressed": [],
  "parserIssues": [],
  "analysis": {
    "diagnostics": [],
    "categories": {
      "parser": 0,
      "graph": 0,
      "validation": 0,
      "suppression": 0
    }
  },
  "summary": {
    "unsuppressedCount": 0,
    "suppressedCount": 0,
    "parserIssueCount": 0,
    "diagnosticCount": 0,
    "totalCount": 0
  }
}

Error output (kind: "error")

{
  "schemaVersion": "1.1.0",
  "kind": "error",
  "exitCode": 2,
  "error": "Failed to load truss.yml"
}

Continuous Integration

Truss integrates with CI pipelines to enforce architectural constraints automatically.

Fail PR on Violations

name: Truss
on:
  pull_request:
  push:
    branches: [main]

jobs:
  truss:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npm ci
      - run: npx truss-lint check

CLI Test Coverage

The integration suite uses fixture repos and committed snapshots to keep the CLI contract explicit.

• Snapshot tests for human-readable and JSON output
• Validation of exit codes (0–3)
• Coverage of clean, violation, suppressed, and error scenarios