@aiready/contract-enforcement 0.2.0 → 0.2.2

package/.turbo/turbo-build.log

@@ -1,5 +1,5 @@
 
-> @aiready/contract-enforcement@0.2.0 build /Users/pengcao/projects/aiready/packages/contract-enforcement
+> @aiready/contract-enforcement@0.2.2 build /Users/pengcao/projects/aiready/packages/contract-enforcement
 > tsup src/index.ts --format cjs,esm --dts
 
 CLI Building entry: src/index.ts
@@ -8,11 +8,11 @@ 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
+ESM dist/index.mjs 16.58 KB
+ESM ⚡️ Build success in 159ms
+CJS dist/index.js 18.01 KB
+CJS ⚡️ Build success in 159ms
 DTS Build start
-DTS ⚡️ Build success in 4708ms
+DTS ⚡️ Build success in 7234ms
 DTS dist/index.d.ts  2.45 KB
 DTS dist/index.d.mts 2.45 KB

package/.turbo/turbo-test.log

@@ -1,16 +1,16 @@
 
-> @aiready/contract-enforcement@0.1.0 test /Users/pengcao/projects/aiready/packages/contract-enforcement
+> @aiready/contract-enforcement@0.2.1 test /Users/pengcao/projects/aiready/packages/contract-enforcement
 > vitest run
 
 
  RUN  v4.1.1 /Users/pengcao/projects/aiready/packages/contract-enforcement
 
- ✓ src/__tests__/scoring.test.ts (7 tests) 3ms
- ✓ src/__tests__/detector.test.ts (14 tests) 23ms
+ ✓ src/__tests__/scoring.test.ts (7 tests) 62ms
+ ✓ src/__tests__/detector.test.ts (14 tests) 90ms
  ✓ src/__tests__/provider.test.ts (5 tests) 2ms
 
  Test Files  3 passed (3)
       Tests  26 passed (26)
-   Start at  15:17:54
-   Duration  2.10s (transform 511ms, setup 0ms, import 3.00s, tests 28ms, environment 0ms)
+   Start at  14:03:18
+   Duration  3.32s (transform 1.63s, setup 0ms, import 5.02s, tests 154ms, environment 0ms)
 

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/dist/index.js

@@ -121,13 +121,37 @@ function isLiteral(node) {
 function isProcessEnvAccess(node) {
   return node?.type === "MemberExpression" && node.object?.type === "MemberExpression" && node.object.object?.name === "process" && node.object.property?.name === "env";
 }
-function isSwallowedCatch(body) {
+function isSstResourceAccess(node) {
+  if (!node) return false;
+  let current = node;
+  if (current.type === "ChainExpression") {
+    current = current.expression;
+  }
+  while (current && current.type === "MemberExpression") {
+    if (current.object?.type === "Identifier" && current.object.name === "Resource") {
+      return true;
+    }
+    current = current.object;
+  }
+  if (current?.type === "Identifier" && current.name === "Resource") {
+    return true;
+  }
+  return false;
+}
+function isSwallowedCatch(body, filePath) {
   if (body.length === 0) return true;
+  const isUiComponent = filePath.endsWith(".tsx") || filePath.endsWith(".jsx");
   if (body.length === 1) {
     const stmt = body[0];
     if (stmt.type === "ExpressionStatement" && stmt.expression?.type === "CallExpression") {
       const callee = stmt.expression.callee;
       if (callee?.object?.name === "console") return true;
+      if (isUiComponent) {
+        const calleeName = callee?.name || callee?.property?.name || "";
+        if (/telemetry|analytics|track|logEvent/i.test(calleeName)) {
+          return false;
+        }
+      }
     }
     if (stmt.type === "ThrowStatement") return false;
   }
@@ -161,32 +185,36 @@ function detectDefensivePatterns(filePath, code, minChainDepth = 3) {
     if (!node || typeof node !== "object") return;
     markFunctionParamNodes(node);
     if (node.type === "TSAsExpression" && node.typeAnnotation?.type === "TSAnyKeyword") {
-      counts["as-any"]++;
-      issues.push(
-        makeIssue(
-          "as-any",
-          import_core.Severity.Major,
-          "`as any` type assertion bypasses type safety",
-          filePath,
-          node.loc?.start.line ?? 0,
-          node.loc?.start.column ?? 0,
-          getLineContent(code, node.loc?.start.line ?? 0)
-        )
-      );
+      if (!isSstResourceAccess(node.expression) && !isProcessEnvAccess(node.expression)) {
+        counts["as-any"]++;
+        issues.push(
+          makeIssue(
+            "as-any",
+            import_core.Severity.Major,
+            "`as any` type assertion bypasses type safety",
+            filePath,
+            node.loc?.start.line ?? 0,
+            node.loc?.start.column ?? 0,
+            getLineContent(code, node.loc?.start.line ?? 0)
+          )
+        );
+      }
     }
     if (node.type === "TSAsExpression" && node.typeAnnotation?.type === "TSUnknownKeyword") {
-      counts["as-unknown"]++;
-      issues.push(
-        makeIssue(
-          "as-unknown",
-          import_core.Severity.Major,
-          "`as unknown` double-cast bypasses type safety",
-          filePath,
-          node.loc?.start.line ?? 0,
-          node.loc?.start.column ?? 0,
-          getLineContent(code, node.loc?.start.line ?? 0)
-        )
-      );
+      if (!isSstResourceAccess(node.expression) && !isProcessEnvAccess(node.expression)) {
+        counts["as-unknown"]++;
+        issues.push(
+          makeIssue(
+            "as-unknown",
+            import_core.Severity.Major,
+            "`as unknown` double-cast bypasses type safety",
+            filePath,
+            node.loc?.start.line ?? 0,
+            node.loc?.start.column ?? 0,
+            getLineContent(code, node.loc?.start.line ?? 0)
+          )
+        );
+      }
     }
     if (node.type === "ChainExpression") {
       const depth = countOptionalChainDepth(node);
@@ -206,22 +234,24 @@ function detectDefensivePatterns(filePath, code, minChainDepth = 3) {
       }
     }
     if (node.type === "LogicalExpression" && node.operator === "??" && isLiteral(node.right)) {
-      counts["nullish-literal-default"]++;
-      issues.push(
-        makeIssue(
-          "nullish-literal-default",
-          import_core.Severity.Minor,
-          "Nullish coalescing with literal default suggests missing upstream type guarantee",
-          filePath,
-          node.loc?.start.line ?? 0,
-          node.loc?.start.column ?? 0,
-          getLineContent(code, node.loc?.start.line ?? 0)
-        )
-      );
+      if (!isSstResourceAccess(node.left) && !isProcessEnvAccess(node.left)) {
+        counts["nullish-literal-default"]++;
+        issues.push(
+          makeIssue(
+            "nullish-literal-default",
+            import_core.Severity.Minor,
+            "Nullish coalescing with literal default suggests missing upstream type guarantee",
+            filePath,
+            node.loc?.start.line ?? 0,
+            node.loc?.start.column ?? 0,
+            getLineContent(code, node.loc?.start.line ?? 0)
+          )
+        );
+      }
     }
     if (node.type === "TryStatement" && node.handler) {
       const catchBody = node.handler.body?.body;
-      if (catchBody && isSwallowedCatch(catchBody)) {
+      if (catchBody && isSwallowedCatch(catchBody, filePath)) {
         counts["swallowed-error"]++;
         issues.push(
           makeIssue(
@@ -345,10 +375,10 @@ function calculateContractEnforcementScore(counts, totalLines, _fileCount) {
   const fallbackDensity = fallbackCount / loc * 1e3;
   const errorDensity = errorCount / loc * 1e3;
   const boundaryDensity = boundaryCount / loc * 1e3;
-  const typeEscapeHatchScore = clamp(100 - typeDensity * 15, 0, 100);
-  const fallbackCascadeScore = clamp(100 - fallbackDensity * 12, 0, 100);
-  const errorTransparencyScore = clamp(100 - errorDensity * 25, 0, 100);
-  const boundaryValidationScore = clamp(100 - boundaryDensity * 10, 0, 100);
+  const typeEscapeHatchScore = clamp(100 - typeDensity * 10, 0, 100);
+  const fallbackCascadeScore = clamp(100 - fallbackDensity * 8, 0, 100);
+  const errorTransparencyScore = clamp(100 - errorDensity * 15, 0, 100);
+  const boundaryValidationScore = clamp(100 - boundaryDensity * 7, 0, 100);
   const score = Math.round(
     typeEscapeHatchScore * DIMENSION_WEIGHTS.typeEscapeHatch + fallbackCascadeScore * DIMENSION_WEIGHTS.fallbackCascade + errorTransparencyScore * DIMENSION_WEIGHTS.errorTransparency + boundaryValidationScore * DIMENSION_WEIGHTS.boundaryValidation
   );

package/dist/index.mjs

@@ -94,13 +94,37 @@ function isLiteral(node) {
 function isProcessEnvAccess(node) {
   return node?.type === "MemberExpression" && node.object?.type === "MemberExpression" && node.object.object?.name === "process" && node.object.property?.name === "env";
 }
-function isSwallowedCatch(body) {
+function isSstResourceAccess(node) {
+  if (!node) return false;
+  let current = node;
+  if (current.type === "ChainExpression") {
+    current = current.expression;
+  }
+  while (current && current.type === "MemberExpression") {
+    if (current.object?.type === "Identifier" && current.object.name === "Resource") {
+      return true;
+    }
+    current = current.object;
+  }
+  if (current?.type === "Identifier" && current.name === "Resource") {
+    return true;
+  }
+  return false;
+}
+function isSwallowedCatch(body, filePath) {
   if (body.length === 0) return true;
+  const isUiComponent = filePath.endsWith(".tsx") || filePath.endsWith(".jsx");
   if (body.length === 1) {
     const stmt = body[0];
     if (stmt.type === "ExpressionStatement" && stmt.expression?.type === "CallExpression") {
       const callee = stmt.expression.callee;
       if (callee?.object?.name === "console") return true;
+      if (isUiComponent) {
+        const calleeName = callee?.name || callee?.property?.name || "";
+        if (/telemetry|analytics|track|logEvent/i.test(calleeName)) {
+          return false;
+        }
+      }
     }
     if (stmt.type === "ThrowStatement") return false;
   }
@@ -134,32 +158,36 @@ function detectDefensivePatterns(filePath, code, minChainDepth = 3) {
     if (!node || typeof node !== "object") return;
     markFunctionParamNodes(node);
     if (node.type === "TSAsExpression" && node.typeAnnotation?.type === "TSAnyKeyword") {
-      counts["as-any"]++;
-      issues.push(
-        makeIssue(
-          "as-any",
-          Severity.Major,
-          "`as any` type assertion bypasses type safety",
-          filePath,
-          node.loc?.start.line ?? 0,
-          node.loc?.start.column ?? 0,
-          getLineContent(code, node.loc?.start.line ?? 0)
-        )
-      );
+      if (!isSstResourceAccess(node.expression) && !isProcessEnvAccess(node.expression)) {
+        counts["as-any"]++;
+        issues.push(
+          makeIssue(
+            "as-any",
+            Severity.Major,
+            "`as any` type assertion bypasses type safety",
+            filePath,
+            node.loc?.start.line ?? 0,
+            node.loc?.start.column ?? 0,
+            getLineContent(code, node.loc?.start.line ?? 0)
+          )
+        );
+      }
     }
     if (node.type === "TSAsExpression" && node.typeAnnotation?.type === "TSUnknownKeyword") {
-      counts["as-unknown"]++;
-      issues.push(
-        makeIssue(
-          "as-unknown",
-          Severity.Major,
-          "`as unknown` double-cast bypasses type safety",
-          filePath,
-          node.loc?.start.line ?? 0,
-          node.loc?.start.column ?? 0,
-          getLineContent(code, node.loc?.start.line ?? 0)
-        )
-      );
+      if (!isSstResourceAccess(node.expression) && !isProcessEnvAccess(node.expression)) {
+        counts["as-unknown"]++;
+        issues.push(
+          makeIssue(
+            "as-unknown",
+            Severity.Major,
+            "`as unknown` double-cast bypasses type safety",
+            filePath,
+            node.loc?.start.line ?? 0,
+            node.loc?.start.column ?? 0,
+            getLineContent(code, node.loc?.start.line ?? 0)
+          )
+        );
+      }
     }
     if (node.type === "ChainExpression") {
       const depth = countOptionalChainDepth(node);
@@ -179,22 +207,24 @@ function detectDefensivePatterns(filePath, code, minChainDepth = 3) {
       }
     }
     if (node.type === "LogicalExpression" && node.operator === "??" && isLiteral(node.right)) {
-      counts["nullish-literal-default"]++;
-      issues.push(
-        makeIssue(
-          "nullish-literal-default",
-          Severity.Minor,
-          "Nullish coalescing with literal default suggests missing upstream type guarantee",
-          filePath,
-          node.loc?.start.line ?? 0,
-          node.loc?.start.column ?? 0,
-          getLineContent(code, node.loc?.start.line ?? 0)
-        )
-      );
+      if (!isSstResourceAccess(node.left) && !isProcessEnvAccess(node.left)) {
+        counts["nullish-literal-default"]++;
+        issues.push(
+          makeIssue(
+            "nullish-literal-default",
+            Severity.Minor,
+            "Nullish coalescing with literal default suggests missing upstream type guarantee",
+            filePath,
+            node.loc?.start.line ?? 0,
+            node.loc?.start.column ?? 0,
+            getLineContent(code, node.loc?.start.line ?? 0)
+          )
+        );
+      }
     }
     if (node.type === "TryStatement" && node.handler) {
       const catchBody = node.handler.body?.body;
-      if (catchBody && isSwallowedCatch(catchBody)) {
+      if (catchBody && isSwallowedCatch(catchBody, filePath)) {
         counts["swallowed-error"]++;
         issues.push(
           makeIssue(
@@ -318,10 +348,10 @@ function calculateContractEnforcementScore(counts, totalLines, _fileCount) {
   const fallbackDensity = fallbackCount / loc * 1e3;
   const errorDensity = errorCount / loc * 1e3;
   const boundaryDensity = boundaryCount / loc * 1e3;
-  const typeEscapeHatchScore = clamp(100 - typeDensity * 15, 0, 100);
-  const fallbackCascadeScore = clamp(100 - fallbackDensity * 12, 0, 100);
-  const errorTransparencyScore = clamp(100 - errorDensity * 25, 0, 100);
-  const boundaryValidationScore = clamp(100 - boundaryDensity * 10, 0, 100);
+  const typeEscapeHatchScore = clamp(100 - typeDensity * 10, 0, 100);
+  const fallbackCascadeScore = clamp(100 - fallbackDensity * 8, 0, 100);
+  const errorTransparencyScore = clamp(100 - errorDensity * 15, 0, 100);
+  const boundaryValidationScore = clamp(100 - boundaryDensity * 7, 0, 100);
   const score = Math.round(
     typeEscapeHatchScore * DIMENSION_WEIGHTS.typeEscapeHatch + fallbackCascadeScore * DIMENSION_WEIGHTS.fallbackCascade + errorTransparencyScore * DIMENSION_WEIGHTS.errorTransparency + boundaryValidationScore * DIMENSION_WEIGHTS.boundaryValidation
   );

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.2",
+  "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.2"
   },
   "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"
   }
 }

package/src/detector.ts

@@ -98,8 +98,39 @@ function isProcessEnvAccess(node: any): boolean {
   );
 }
 
-function isSwallowedCatch(body: any[]): boolean {
+function isSstResourceAccess(node: any): boolean {
+  if (!node) return false;
+  let current = node;
+  // Handle ChainExpression for optional chaining like Resource.MySecret?.value
+  if (current.type === 'ChainExpression') {
+    current = current.expression;
+  }
+
+  // Recursively check for 'Resource' identifier at the base of the member chain
+  while (current && current.type === 'MemberExpression') {
+    if (
+      current.object?.type === 'Identifier' &&
+      current.object.name === 'Resource'
+    ) {
+      return true;
+    }
+    current = current.object;
+  }
+
+  // Also check if the node itself is 'Resource' (rare but possible in some contexts)
+  if (current?.type === 'Identifier' && current.name === 'Resource') {
+    return true;
+  }
+
+  return false;
+}
+
+function isSwallowedCatch(body: any[], filePath: string): boolean {
   if (body.length === 0) return true;
+
+  // UI components often have intentional silent catches for telemetry/analytics
+  const isUiComponent = filePath.endsWith('.tsx') || filePath.endsWith('.jsx');
+
   if (body.length === 1) {
     const stmt = body[0];
     if (
@@ -107,10 +138,20 @@ function isSwallowedCatch(body: any[]): boolean {
       stmt.expression?.type === 'CallExpression'
     ) {
       const callee = stmt.expression.callee;
+      // console.log/warn/error is still considered "swallowed" but might be acceptable
       if (callee?.object?.name === 'console') return true;
+
+      // If it's a UI component and looks like telemetry, it's a false positive
+      if (isUiComponent) {
+        const calleeName = callee?.name || callee?.property?.name || '';
+        if (/telemetry|analytics|track|logEvent/i.test(calleeName)) {
+          return false; // Not "swallowed" in a bad way
+        }
+      }
     }
     if (stmt.type === 'ThrowStatement') return false;
   }
+
   return false;
 }
 
@@ -160,18 +201,24 @@ export function detectDefensivePatterns(
       node.type === 'TSAsExpression' &&
       node.typeAnnotation?.type === 'TSAnyKeyword'
     ) {
-      counts['as-any']++;
-      issues.push(
-        makeIssue(
-          'as-any',
-          Severity.Major,
-          '`as any` type assertion bypasses type safety',
-          filePath,
-          node.loc?.start.line ?? 0,
-          node.loc?.start.column ?? 0,
-          getLineContent(code, node.loc?.start.line ?? 0)
-        )
-      );
+      // Ignore if it's acting on an SST resource or process.env, common "necessary escape hatches"
+      if (
+        !isSstResourceAccess(node.expression) &&
+        !isProcessEnvAccess(node.expression)
+      ) {
+        counts['as-any']++;
+        issues.push(
+          makeIssue(
+            'as-any',
+            Severity.Major,
+            '`as any` type assertion bypasses type safety',
+            filePath,
+            node.loc?.start.line ?? 0,
+            node.loc?.start.column ?? 0,
+            getLineContent(code, node.loc?.start.line ?? 0)
+          )
+        );
+      }
     }
 
     // Pattern: as unknown
@@ -179,18 +226,24 @@ export function detectDefensivePatterns(
       node.type === 'TSAsExpression' &&
       node.typeAnnotation?.type === 'TSUnknownKeyword'
     ) {
-      counts['as-unknown']++;
-      issues.push(
-        makeIssue(
-          'as-unknown',
-          Severity.Major,
-          '`as unknown` double-cast bypasses type safety',
-          filePath,
-          node.loc?.start.line ?? 0,
-          node.loc?.start.column ?? 0,
-          getLineContent(code, node.loc?.start.line ?? 0)
-        )
-      );
+      // Ignore if it's acting on an SST resource or process.env
+      if (
+        !isSstResourceAccess(node.expression) &&
+        !isProcessEnvAccess(node.expression)
+      ) {
+        counts['as-unknown']++;
+        issues.push(
+          makeIssue(
+            'as-unknown',
+            Severity.Major,
+            '`as unknown` double-cast bypasses type safety',
+            filePath,
+            node.loc?.start.line ?? 0,
+            node.loc?.start.column ?? 0,
+            getLineContent(code, node.loc?.start.line ?? 0)
+          )
+        );
+      }
     }
 
     // Pattern: deep optional chaining
@@ -218,24 +271,27 @@ export function detectDefensivePatterns(
       node.operator === '??' &&
       isLiteral(node.right)
     ) {
-      counts['nullish-literal-default']++;
-      issues.push(
-        makeIssue(
-          'nullish-literal-default',
-          Severity.Minor,
-          'Nullish coalescing with literal default suggests missing upstream type guarantee',
-          filePath,
-          node.loc?.start.line ?? 0,
-          node.loc?.start.column ?? 0,
-          getLineContent(code, node.loc?.start.line ?? 0)
-        )
-      );
+      // Ignore if it's an SST Resource or process.env - the standard way to handle fallbacks
+      if (!isSstResourceAccess(node.left) && !isProcessEnvAccess(node.left)) {
+        counts['nullish-literal-default']++;
+        issues.push(
+          makeIssue(
+            'nullish-literal-default',
+            Severity.Minor,
+            'Nullish coalescing with literal default suggests missing upstream type guarantee',
+            filePath,
+            node.loc?.start.line ?? 0,
+            node.loc?.start.column ?? 0,
+            getLineContent(code, node.loc?.start.line ?? 0)
+          )
+        );
+      }
     }
 
     // Pattern: swallowed error
     if (node.type === 'TryStatement' && node.handler) {
       const catchBody = node.handler.body?.body;
-      if (catchBody && isSwallowedCatch(catchBody)) {
+      if (catchBody && isSwallowedCatch(catchBody, filePath)) {
         counts['swallowed-error']++;
         issues.push(
           makeIssue(

package/src/scoring.ts

@@ -35,10 +35,11 @@ export function calculateContractEnforcementScore(
   const boundaryDensity = (boundaryCount / loc) * 1000;
 
   // Dimension scores: 100 = no patterns, 0 = very high density
-  const typeEscapeHatchScore = clamp(100 - typeDensity * 15, 0, 100);
-  const fallbackCascadeScore = clamp(100 - fallbackDensity * 12, 0, 100);
-  const errorTransparencyScore = clamp(100 - errorDensity * 25, 0, 100);
-  const boundaryValidationScore = clamp(100 - boundaryDensity * 10, 0, 100);
+  // Adjusted to be more lenient - many defensive patterns are valid practices
+  const typeEscapeHatchScore = clamp(100 - typeDensity * 10, 0, 100);
+  const fallbackCascadeScore = clamp(100 - fallbackDensity * 8, 0, 100);
+  const errorTransparencyScore = clamp(100 - errorDensity * 15, 0, 100);
+  const boundaryValidationScore = clamp(100 - boundaryDensity * 7, 0, 100);
 
   const score = Math.round(
     typeEscapeHatchScore * DIMENSION_WEIGHTS.typeEscapeHatch +