@aiready/contract-enforcement 0.2.0 → 0.2.1

package/.turbo/turbo-build.log

@@ -1,18 +1,19 @@
-
-> @aiready/contract-enforcement@0.2.0 build /Users/pengcao/projects/aiready/packages/contract-enforcement
-> tsup src/index.ts --format cjs,esm --dts
-
-CLI Building entry: src/index.ts
-CLI Using tsconfig: tsconfig.json
-CLI tsup v8.5.1
-CLI Target: es2020
-CJS Build start
-ESM Build start
-ESM dist/index.mjs 15.46 KB
-ESM ⚡️ Build success in 76ms
-CJS dist/index.js 16.88 KB
-CJS ⚡️ Build success in 86ms
-DTS Build start
-DTS ⚡️ Build success in 4708ms
-DTS dist/index.d.ts  2.45 KB
-DTS dist/index.d.mts 2.45 KB
+
+
+> @aiready/contract-enforcement@0.2.1 build /Users/pengcao/projects/aiready/packages/contract-enforcement
+> tsup src/index.ts --format cjs,esm --dts
+
+CLI Building entry: src/index.ts
+CLI Using tsconfig: tsconfig.json
+CLI tsup v8.5.1
+CLI Target: es2020
+CJS Build start
+ESM Build start
+CJS dist/index.js 16.88 KB
+CJS ⚡️ Build success in 287ms
+ESM dist/index.mjs 15.46 KB
+ESM ⚡️ Build success in 289ms
+DTS Build start
+DTS ⚡️ Build success in 5891ms
+DTS dist/index.d.ts  2.45 KB
+DTS dist/index.d.mts 2.45 KB

package/README.md

@@ -0,0 +1,68 @@
+# @aiready/contract-enforcement
+
+> AIReady Spoke: Measures structural type safety and contract enforcement to reduce downstream fallback cascades for AI agents.
+
+[![npm version](https://img.shields.io/npm/v/@aiready/contract-enforcement.svg)](https://npmjs.com/package/@aiready/contract-enforcement)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## 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
+
+```bash
+pnpm add @aiready/contract-enforcement
+```
+
+## Usage
+
+This tool is designed to be run through the unified AIReady CLI.
+
+```bash
+# Scan for contract enforcement quality
+aiready scan . --tools contract-enforcement
+```
+
+## License
+
+MIT

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@aiready/contract-enforcement",
-  "version": "0.2.0",
-  "description": "Measures structural contract enforcement to reduce defensive coding cascades",
+  "version": "0.2.1",
+  "description": "Measures structural type safety and boundary validation to reduce fallback cascades for AI agents",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",
   "types": "./dist/index.d.ts",
@@ -12,9 +12,27 @@
       "import": "./dist/index.js"
     }
   },
+  "keywords": [
+    "aiready",
+    "contract-enforcement",
+    "type-safety",
+    "static-analysis",
+    "ai-ready",
+    "typescript",
+    "structural-contracts",
+    "defensive-coding",
+    "error-handling"
+  ],
+  "author": "AIReady Team",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/caopengau/aiready-contract-enforcement.git"
+  },
+  "homepage": "https://github.com/caopengau/aiready-contract-enforcement",
   "dependencies": {
     "@typescript-eslint/typescript-estree": "^8.53.0",
-    "@aiready/core": "0.24.0"
+    "@aiready/core": "0.24.1"
   },
   "devDependencies": {
     "@types/node": "^24.0.0",
@@ -30,6 +48,7 @@
     "dev": "tsup src/index.ts --format cjs,esm --dts --watch",
     "test": "vitest run",
     "lint": "eslint src",
-    "clean": "rm -rf dist"
+    "clean": "rm -rf dist",
+    "release": "pnpm build && pnpm publish --no-git-checks"
   }
 }