@aiready/contract-enforcement

AIReady Spoke: Measures structural type safety and contract enforcement to reduce downstream fallback cascades for AI agents.

Overview

AI agents rely on strong structural contracts to navigate codebases safely. When type safety is bypassed or errors are swallowed, agents lose context and may hallucinate or fail silently. The Contract Enforcement analyzer detects defensive coding anti-patterns and scores how well the codebase enforces structural contracts.

🏛️ Architecture

                    🎯 USER
                      │
                      ▼
         🎛️  @aiready/cli (orchestrator)
          │     │     │     │     │     │     │     │     │     │
          ▼     ▼     ▼     ▼     ▼     ▼     ▼     ▼     ▼     ▼
        [PAT] [CTX] [CON] [AMP] [DEP] [DOC] [SIG] [AGT] [TST] [CTR]
          │     │     │     │     │     │     │     │     │     │
          └─────┴─────┴─────┴─────┴─────┴─────┴─────┴─────┴─────┴─────┘
                               │
                               ▼
                      🏢 @aiready/core

Legend:
  PAT = pattern-detect        CTX = context-analyzer
  CON = consistency           AMP = change-amplification
  DEP = deps-health           DOC = doc-drift
  SIG = ai-signal-clarity     AGT = agent-grounding
  TST = testability           CTR = contract-enforcement ★
  ★   = YOU ARE HERE

Features

• Type Escape Hatches: Detects as any, as unknown, and any parameter/return types that bypass type safety.
• Fallback Cascades: Identifies deep optional chaining (?.?.?) and nullish coalescing with literal defaults that suggest missing upstream guarantees.
• Error Transparency: Flags swallowed catch blocks where errors are silenced, hiding failures from agents.
• Boundary Validation: Detects unvalidated environment variable access and unnecessary guard clauses that could be handled via stronger types at the source.

Scoring Dimensions

• Type Escape Hatches (35%): Measures the density of any and unknown bypasses.
• Fallback Cascades (25%): Evaluates reliance on inline defaults vs. structural guarantees.
• Error Transparency (20%): penalizes silent failures and swallowed exceptions.
• Boundary Validation (20%): Assesses the use of validated schemas vs. ad-hoc guards.

Installation

pnpm add @aiready/contract-enforcement

Usage

This tool is designed to be run through the unified AIReady CLI.

# Scan for contract enforcement quality
aiready scan . --tools contract-enforcement

License

MIT