@aiready/contract-enforcement 0.2.1 → 0.2.2

package/.turbo/turbo-build.log

@@ -1,19 +1,18 @@
-
-
-> @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
+
+> @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
+CLI Using tsconfig: tsconfig.json
+CLI tsup v8.5.1
+CLI Target: es2020
+CJS Build start
+ESM Build start
+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 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/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,6 +1,6 @@
 {
   "name": "@aiready/contract-enforcement",
-  "version": "0.2.1",
+  "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",
@@ -32,7 +32,7 @@
   "homepage": "https://github.com/caopengau/aiready-contract-enforcement",
   "dependencies": {
     "@typescript-eslint/typescript-estree": "^8.53.0",
-    "@aiready/core": "0.24.1"
+    "@aiready/core": "0.24.2"
   },
   "devDependencies": {
     "@types/node": "^24.0.0",

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 +