l4a — Linting for Agents

A TypeScript architecture linter that scores your codebase's agent-readiness. Unlike generic linters, l4a measures the structural properties that determine how well AI coding agents (Claude Code, Cursor, Copilot) can understand and modify your code.

Install

npx lint4agents analyze .

Or install globally:

npm install -g lint4agents

Usage

# Analyze current directory
l4a analyze

# Analyze a specific path
l4a analyze src/

# JSON output (for CI/scripting)
l4a analyze --format json

# Custom thresholds
l4a analyze --max-file-length 200 --max-exports 5 --max-complexity 8 --min-type-coverage 90

# Show individual violations per file
l4a analyze --verbose

# Exclude additional patterns
l4a analyze --exclude "generated/**" "legacy/**"

Exit code is 1 if any check fails — use in CI to catch architectural drift.

Metrics

| Metric | What it measures | Default threshold | |---|---|---| | File length | Lines per file | 300 | | Export count | Exported symbols per file (single responsibility proxy) | 10 | | Cyclomatic complexity | Decision points per function | 10 | | Type coverage | % of function params/returns with explicit types | 80% |

Example output

L4A Analysis Report
Target: /Users/you/project/src
Files analyzed: 42

src/utils/helpers.ts
  ✗ file-length: 487 lines (max 300)
  ✗ export-count: 23 exports (max 10)

src/api/handler.ts
  ✗ cyclomatic-complexity: processRequest: complexity 15 (max 10)

src/components/Form.tsx
  ✗ type-coverage: 45% typed (9/20, min 80%)

38 file(s) passing all checks

4 check(s) failed out of 168 total

Programmatic API

import { analyze } from "lint4agents";

const report = analyze("src/", {
  fileLength: { threshold: 250 },
  exportCount: { threshold: 8 },
  complexity: { threshold: 10 },
  typeCoverage: { threshold: 90 },
  exclude: ["node_modules", "dist"],
});

console.log(report.summary); // { totalFiles: 42, passing: 164, failing: 4 }

Why agent-readiness?

Agents work best in codebases where they can:

1. Understand -- full type signatures, low complexity, clear naming
2. Locate -- high cohesion, small files, shallow dependency graphs
3. Follow patterns -- consistent structure, uniform conventions
4. Verify -- strong test coverage, meaningful assertions

l4a measures these properties directly. The metrics are grounded in real experience running agents against legacy codebases -- not theoretical guesses.

Roadmap

• Structural metrics -- dependency graph analysis, module cohesion scoring
• Test quality metrics -- assertion density, mock-to-assertion ratio, test-to-code ratio
• LLM-graded checks (opt-in) -- naming consistency, component structure variance, test description quality
• Claude Code plugin -- real-time scoring via hooks during agentic coding sessions
• Composite Agent Readiness Score (ARS) -- weighted score across all four pillars, calibrated via evals
• GitHub App -- PR-level architecture review in CI

Requirements

• Node.js >= 18
• Works on any TypeScript project

License

MIT