Integration

Review Intelligence

Automatic architectural review built into codeledger verify. Runs with zero configuration and detects six categories of structural risk.

Run it

npx codeledger verify

Add --explain for richer reasoning, or --json for machine-readable output in CI.

What it detects

Runtime validation

P1

Detects typed route handlers that accept request bodies without runtime validation (e.g. Zod or Joi). A missing validation layer is a silent data-integrity risk.

// RI-RV-001: POST /api/users — body accepted but not validated at runtime

Outbound I/O timeouts

P1

Detects outbound HTTP or fetch calls that have no explicit timeout configured. Calls without timeouts can cascade under load.

// RI-OI-001: fetch() call in payments.ts has no timeout option

Platform helper bypass

P2

Detects code that reimplements functionality already provided by a shared helper in the repo. Bypassing shared helpers creates duplicate truth and divergence risk.

// RI-PH-001: custom JWT decode in user.ts — use shared authHelper instead

Circular dependencies

P1

Detects circular import chains and layer/boundary violations using the repo dependency graph. Circular deps cause build instability and hard-to-test modules.

// RI-AG-001: packages/core → packages/engine → packages/core (circular)

Build / runtime mismatches

P1

Detects code patterns that build successfully but fail at runtime — type narrowing gaps, missing null checks at API boundaries, env var references without guards.

// RI-BR-001: process.env.SECRET used without null guard — will throw in production

Brittle test patterns

P2

Detects test patterns that are likely to produce false confidence — snapshot tests with no assertion rationale, empty catch blocks that swallow errors, tests that mock the database.

// RI-TI-001: test expects snapshot with 847 lines — brittle, hard to review

Triaging findings

Accept into baseline

Findings you accept are stored in .codeledger/review-baseline.json and hidden on subsequent runs. CI blocks only on new findings — not baselined ones.

npx codeledger verify --update-baseline

Inline suppressions

Suppress a specific finding at the source with a comment. Always include a reason.

// codeledger: ignore runtime_validation -- legacy endpoint, validation in middleware

Show suppressed findings

npx codeledger verify --show-triaged

Auto-fix

Some P2 findings can be automatically fixed. Run codeledger fix to apply safe patches:

npx codeledger fix

Auto-fix is conservative — it only patches cases where the correct fix is unambiguous. Review the diff before committing.

Finding dispositions

DispositionMeaningBlocks CI
newFirst time this finding appearsP0 / P1 only
baselinedAccepted via --update-baselineNever
suppressedInline codeledger: ignore commentNever