@aiready/contract-enforcement 0.2.0

package/dist/index.mjs

@@ -0,0 +1,456 @@
+// src/index.ts
+import { ToolRegistry } from "@aiready/core";
+
+// src/provider.ts
+import { createProvider, ToolName, groupIssuesByFile } from "@aiready/core";
+
+// src/analyzer.ts
+import { readFileSync } from "fs";
+import { scanFiles, runBatchAnalysis } from "@aiready/core";
+
+// src/detector.ts
+import { parse } from "@typescript-eslint/typescript-estree";
+import { Severity, IssueType } from "@aiready/core";
+
+// src/types.ts
+var ZERO_COUNTS = {
+  "as-any": 0,
+  "as-unknown": 0,
+  "deep-optional-chain": 0,
+  "nullish-literal-default": 0,
+  "swallowed-error": 0,
+  "env-fallback": 0,
+  "unnecessary-guard": 0,
+  "any-parameter": 0,
+  "any-return": 0
+};
+
+// src/detector.ts
+function makeIssue(pattern, severity, message, filePath, line, column, context) {
+  return {
+    type: IssueType.ContractGap,
+    severity,
+    pattern,
+    message,
+    location: { file: filePath, line, column },
+    context,
+    suggestion: getSuggestion(pattern)
+  };
+}
+function getSuggestion(pattern) {
+  switch (pattern) {
+    case "as-any":
+      return "Define a proper type or use type narrowing instead of `as any`.";
+    case "as-unknown":
+      return "Use a single validated type assertion or schema validation instead of `as unknown as`.";
+    case "deep-optional-chain":
+      return "Enforce a non-nullable type at the source to eliminate deep optional chaining.";
+    case "nullish-literal-default":
+      return "Define defaults in a typed config object rather than inline literal fallbacks.";
+    case "swallowed-error":
+      return "Log or propagate errors \u2014 silent catch blocks hide failures.";
+    case "env-fallback":
+      return "Use a validated env schema (e.g., Zod) to enforce required variables at startup.";
+    case "unnecessary-guard":
+      return "Make the parameter non-nullable in the type signature to eliminate the guard.";
+    case "any-parameter":
+      return "Define a proper type for this parameter instead of `any`.";
+    case "any-return":
+      return "Define a proper return type instead of `any`.";
+  }
+}
+function getLineContent(code, line) {
+  const lines = code.split("\n");
+  return (lines[line - 1] || "").trim().slice(0, 120);
+}
+function countOptionalChainDepth(node) {
+  let depth = 0;
+  let current = node;
+  while (current) {
+    if (current.type === "MemberExpression" && current.optional) {
+      depth++;
+      current = current.object;
+    } else if (current.type === "ChainExpression") {
+      current = current.expression;
+    } else if (current.type === "CallExpression" && current.optional) {
+      depth++;
+      current = current.callee;
+    } else {
+      break;
+    }
+  }
+  return depth;
+}
+function isLiteral(node) {
+  if (!node) return false;
+  if (node.type === "Literal") return true;
+  if (node.type === "TemplateLiteral" && node.expressions.length === 0)
+    return true;
+  if (node.type === "UnaryExpression" && (node.operator === "-" || node.operator === "+")) {
+    return isLiteral(node.argument);
+  }
+  return false;
+}
+function isProcessEnvAccess(node) {
+  return node?.type === "MemberExpression" && node.object?.type === "MemberExpression" && node.object.object?.name === "process" && node.object.property?.name === "env";
+}
+function isSwallowedCatch(body) {
+  if (body.length === 0) return true;
+  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 (stmt.type === "ThrowStatement") return false;
+  }
+  return false;
+}
+function detectDefensivePatterns(filePath, code, minChainDepth = 3) {
+  const issues = [];
+  const counts = { ...ZERO_COUNTS };
+  const totalLines = code.split("\n").length;
+  let ast;
+  try {
+    ast = parse(code, {
+      filePath,
+      loc: true,
+      range: true,
+      jsx: filePath.endsWith("x")
+    });
+  } catch {
+    return { issues, counts, totalLines };
+  }
+  const nodesAtFunctionStart = /* @__PURE__ */ new WeakSet();
+  function markFunctionParamNodes(node) {
+    if (node.type === "FunctionDeclaration" || node.type === "FunctionExpression" || node.type === "ArrowFunctionExpression") {
+      const body = node.body?.type === "BlockStatement" ? node.body.body : null;
+      if (body && body.length > 0) {
+        nodesAtFunctionStart.add(body[0]);
+      }
+    }
+  }
+  function visit(node, _parent, _keyInParent) {
+    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 (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 (node.type === "ChainExpression") {
+      const depth = countOptionalChainDepth(node);
+      if (depth >= minChainDepth) {
+        counts["deep-optional-chain"]++;
+        issues.push(
+          makeIssue(
+            "deep-optional-chain",
+            Severity.Minor,
+            `Optional chain depth of ${depth} indicates missing structural guarantees`,
+            filePath,
+            node.loc?.start.line ?? 0,
+            node.loc?.start.column ?? 0,
+            getLineContent(code, node.loc?.start.line ?? 0)
+          )
+        );
+      }
+    }
+    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 (node.type === "TryStatement" && node.handler) {
+      const catchBody = node.handler.body?.body;
+      if (catchBody && isSwallowedCatch(catchBody)) {
+        counts["swallowed-error"]++;
+        issues.push(
+          makeIssue(
+            "swallowed-error",
+            Severity.Major,
+            "Error is swallowed in catch block \u2014 failures will be silent",
+            filePath,
+            node.handler.loc?.start.line ?? 0,
+            node.handler.loc?.start.column ?? 0,
+            getLineContent(code, node.handler.loc?.start.line ?? 0)
+          )
+        );
+      }
+    }
+    if (node.type === "LogicalExpression" && node.operator === "||" && isProcessEnvAccess(node.left)) {
+      counts["env-fallback"]++;
+      issues.push(
+        makeIssue(
+          "env-fallback",
+          Severity.Minor,
+          "Environment variable with fallback \u2014 use a validated env schema instead",
+          filePath,
+          node.loc?.start.line ?? 0,
+          node.loc?.start.column ?? 0,
+          getLineContent(code, node.loc?.start.line ?? 0)
+        )
+      );
+    }
+    if (node.type === "IfStatement" && node.test?.type === "UnaryExpression" && node.test.operator === "!") {
+      const consequent = node.consequent;
+      let isReturn = false;
+      if (consequent.type === "ReturnStatement") {
+        isReturn = true;
+      } else if (consequent.type === "BlockStatement" && consequent.body?.length === 1 && consequent.body[0].type === "ReturnStatement") {
+        isReturn = true;
+      }
+      if (isReturn && nodesAtFunctionStart.has(node)) {
+        counts["unnecessary-guard"]++;
+        issues.push(
+          makeIssue(
+            "unnecessary-guard",
+            Severity.Info,
+            "Guard clause could be eliminated with non-nullable type at source",
+            filePath,
+            node.loc?.start.line ?? 0,
+            node.loc?.start.column ?? 0,
+            getLineContent(code, node.loc?.start.line ?? 0)
+          )
+        );
+      }
+    }
+    if ((node.type === "FunctionDeclaration" || node.type === "FunctionExpression" || node.type === "ArrowFunctionExpression") && node.params) {
+      for (const param of node.params) {
+        const typeAnno = param.typeAnnotation?.typeAnnotation ?? param.typeAnnotation;
+        if (typeAnno?.type === "TSAnyKeyword") {
+          counts["any-parameter"]++;
+          issues.push(
+            makeIssue(
+              "any-parameter",
+              Severity.Major,
+              "Parameter typed as `any` bypasses type safety",
+              filePath,
+              param.loc?.start.line ?? 0,
+              param.loc?.start.column ?? 0,
+              getLineContent(code, param.loc?.start.line ?? 0)
+            )
+          );
+        }
+      }
+      const returnAnno = node.returnType?.typeAnnotation ?? node.returnType;
+      if (returnAnno?.type === "TSAnyKeyword") {
+        counts["any-return"]++;
+        issues.push(
+          makeIssue(
+            "any-return",
+            Severity.Major,
+            "Return type is `any` \u2014 callers cannot rely on the result shape",
+            filePath,
+            node.returnType?.loc?.start.line ?? 0,
+            node.returnType?.loc?.start.column ?? 0,
+            getLineContent(code, node.returnType?.loc?.start.line ?? 0)
+          )
+        );
+      }
+    }
+    for (const key in node) {
+      if (key === "loc" || key === "range" || key === "parent") continue;
+      const child = node[key];
+      if (Array.isArray(child)) {
+        for (const item of child) {
+          if (item && typeof item.type === "string") {
+            visit(item, node, key);
+          }
+        }
+      } else if (child && typeof child === "object" && typeof child.type === "string") {
+        visit(child, node, key);
+      }
+    }
+  }
+  visit(ast);
+  return { issues, counts, totalLines };
+}
+
+// src/scoring.ts
+var DIMENSION_WEIGHTS = {
+  typeEscapeHatch: 0.35,
+  fallbackCascade: 0.25,
+  errorTransparency: 0.2,
+  boundaryValidation: 0.2
+};
+function clamp(v, min, max) {
+  return Math.max(min, Math.min(max, v));
+}
+function calculateContractEnforcementScore(counts, totalLines, _fileCount) {
+  const loc = Math.max(1, totalLines);
+  const typeEscapeCount = counts["as-any"] + counts["as-unknown"] + counts["any-parameter"] + counts["any-return"];
+  const fallbackCount = counts["deep-optional-chain"] + counts["nullish-literal-default"];
+  const errorCount = counts["swallowed-error"];
+  const boundaryCount = counts["env-fallback"] + counts["unnecessary-guard"];
+  const typeDensity = typeEscapeCount / loc * 1e3;
+  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 score = Math.round(
+    typeEscapeHatchScore * DIMENSION_WEIGHTS.typeEscapeHatch + fallbackCascadeScore * DIMENSION_WEIGHTS.fallbackCascade + errorTransparencyScore * DIMENSION_WEIGHTS.errorTransparency + boundaryValidationScore * DIMENSION_WEIGHTS.boundaryValidation
+  );
+  const rating = score >= 90 ? "excellent" : score >= 75 ? "good" : score >= 60 ? "moderate" : score >= 40 ? "needs-work" : "critical";
+  const recommendations = [];
+  if (typeEscapeHatchScore < 60) {
+    recommendations.push(
+      `Reduce type escape hatches (${typeEscapeCount} found): define proper types at system boundaries instead of \`as any\`/parameter \`any\`.`
+    );
+  }
+  if (fallbackCascadeScore < 60) {
+    recommendations.push(
+      `Reduce fallback cascades (${fallbackCount} found): enforce non-nullable types at the source so consumers don't need \`?.\`/?? fallbacks.`
+    );
+  }
+  if (errorTransparencyScore < 60) {
+    recommendations.push(
+      `Fix swallowed errors (${errorCount} found): log or propagate errors so failures are visible.`
+    );
+  }
+  if (boundaryValidationScore < 60) {
+    recommendations.push(
+      `Add boundary validation (${boundaryCount} gaps): use a Zod schema for env vars and API inputs instead of inline fallbacks.`
+    );
+  }
+  return {
+    score,
+    rating,
+    dimensions: {
+      typeEscapeHatchScore: Math.round(typeEscapeHatchScore),
+      fallbackCascadeScore: Math.round(fallbackCascadeScore),
+      errorTransparencyScore: Math.round(errorTransparencyScore),
+      boundaryValidationScore: Math.round(boundaryValidationScore)
+    },
+    recommendations
+  };
+}
+
+// src/analyzer.ts
+async function analyzeContractEnforcement(options) {
+  const files = await scanFiles({
+    ...options,
+    include: options.include || ["**/*.{ts,tsx,js,jsx}"]
+  });
+  const allIssues = [];
+  const aggregate = { ...ZERO_COUNTS };
+  let totalLines = 0;
+  await runBatchAnalysis(
+    files,
+    "scanning for defensive patterns",
+    "contract-enforcement",
+    options.onProgress,
+    async (f) => {
+      let code;
+      try {
+        code = readFileSync(f, "utf-8");
+      } catch {
+        return { issues: [], counts: { ...ZERO_COUNTS }, totalLines: 0 };
+      }
+      return detectDefensivePatterns(f, code, options.minChainDepth ?? 3);
+    },
+    (result) => {
+      allIssues.push(...result.issues);
+      totalLines += result.totalLines;
+      for (const key of Object.keys(aggregate)) {
+        aggregate[key] += result.counts[key];
+      }
+    }
+  );
+  const totalPatterns = Object.values(aggregate).reduce((a, b) => a + b, 0);
+  const density = totalLines > 0 ? Math.round(totalPatterns / totalLines * 1e4) / 10 : 0;
+  const scoreResult = calculateContractEnforcementScore(
+    aggregate,
+    totalLines,
+    files.length
+  );
+  return {
+    summary: {
+      sourceFiles: files.length,
+      totalDefensivePatterns: totalPatterns,
+      defensiveDensity: density,
+      score: scoreResult.score,
+      rating: scoreResult.rating,
+      dimensions: {
+        typeEscapeHatchScore: scoreResult.dimensions.typeEscapeHatchScore,
+        fallbackCascadeScore: scoreResult.dimensions.fallbackCascadeScore,
+        errorTransparencyScore: scoreResult.dimensions.errorTransparencyScore,
+        boundaryValidationScore: scoreResult.dimensions.boundaryValidationScore
+      }
+    },
+    issues: allIssues,
+    rawData: { ...aggregate, sourceFiles: files.length, totalLines },
+    recommendations: scoreResult.recommendations
+  };
+}
+
+// src/provider.ts
+var ContractEnforcementProvider = createProvider({
+  id: ToolName.ContractEnforcement,
+  alias: ["contract", "ce", "enforcement"],
+  version: "0.1.0",
+  defaultWeight: 10,
+  async analyzeReport(options) {
+    return analyzeContractEnforcement(options);
+  },
+  getResults(report) {
+    return groupIssuesByFile(report.issues);
+  },
+  getSummary(report) {
+    return report.summary;
+  },
+  getMetadata(report) {
+    return { rawData: report.rawData };
+  },
+  score(output, _options) {
+    const rawData = output.metadata?.rawData ?? {};
+    return calculateContractEnforcementScore(
+      rawData,
+      rawData.totalLines ?? 1,
+      rawData.sourceFiles ?? 1
+    );
+  }
+});
+
+// src/index.ts
+ToolRegistry.register(ContractEnforcementProvider);
+export {
+  ContractEnforcementProvider,
+  analyzeContractEnforcement,
+  calculateContractEnforcementScore,
+  detectDefensivePatterns
+};

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@aiready/contract-enforcement",
+  "version": "0.2.0",
+  "description": "Measures structural contract enforcement to reduce defensive coding cascades",
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "require": "./dist/index.cjs",
+      "import": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "@typescript-eslint/typescript-estree": "^8.53.0",
+    "@aiready/core": "0.24.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "tsup": "^8.3.5",
+    "typescript": "^5.0.0",
+    "vitest": "^4.0.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs,esm --dts",
+    "dev": "tsup src/index.ts --format cjs,esm --dts --watch",
+    "test": "vitest run",
+    "lint": "eslint src",
+    "clean": "rm -rf dist"
+  }
+}

package/src/__tests__/detector.test.ts

@@ -0,0 +1,148 @@
+import { describe, it, expect } from 'vitest';
+import { detectDefensivePatterns } from '../detector';
+
+describe('detectDefensivePatterns', () => {
+  const filePath = '/test/file.ts';
+
+  it('detects `as any` type assertions', () => {
+    const code = `
+      function foo(x: unknown) {
+        const y = x as any;
+        return y.bar;
+      }
+    `;
+    const result = detectDefensivePatterns(filePath, code);
+    expect(result.counts['as-any']).toBe(1);
+    expect(result.issues[0].pattern).toBe('as-any');
+  });
+
+  it('detects `as unknown as` double casts', () => {
+    const code = `
+      const x = data as unknown as Foo;
+    `;
+    const result = detectDefensivePatterns(filePath, code);
+    expect(result.counts['as-unknown']).toBe(1);
+  });
+
+  it('detects deep optional chaining (depth >= 3)', () => {
+    const code = `
+      const val = obj?.foo?.bar?.baz;
+    `;
+    const result = detectDefensivePatterns(filePath, code);
+    expect(result.counts['deep-optional-chain']).toBe(1);
+  });
+
+  it('does not flag shallow optional chaining (depth < 3)', () => {
+    const code = `
+      const val = obj?.foo?.bar;
+    `;
+    const result = detectDefensivePatterns(filePath, code, 3);
+    expect(result.counts['deep-optional-chain']).toBe(0);
+  });
+
+  it('detects nullish coalescing with literal default', () => {
+    const code = `
+      const x = value ?? 'default';
+      const y = count ?? 0;
+    `;
+    const result = detectDefensivePatterns(filePath, code);
+    expect(result.counts['nullish-literal-default']).toBe(2);
+  });
+
+  it('does not flag nullish coalescing with variable', () => {
+    const code = `
+      const x = value ?? fallback;
+    `;
+    const result = detectDefensivePatterns(filePath, code);
+    expect(result.counts['nullish-literal-default']).toBe(0);
+  });
+
+  it('detects swallowed errors (empty catch)', () => {
+    const code = `
+      try {
+        doSomething();
+      } catch {}
+    `;
+    const result = detectDefensivePatterns(filePath, code);
+    expect(result.counts['swallowed-error']).toBe(1);
+  });
+
+  it('detects swallowed errors (console.log only)', () => {
+    const code = `
+      try {
+        doSomething();
+      } catch (e) {
+        console.error(e);
+      }
+    `;
+    const result = detectDefensivePatterns(filePath, code);
+    expect(result.counts['swallowed-error']).toBe(1);
+  });
+
+  it('does not flag catch blocks with real handling', () => {
+    const code = `
+      try {
+        doSomething();
+      } catch (e) {
+        handleError(e);
+        throw e;
+      }
+    `;
+    const result = detectDefensivePatterns(filePath, code);
+    expect(result.counts['swallowed-error']).toBe(0);
+  });
+
+  it('detects process.env fallbacks', () => {
+    const code = `
+      const region = process.env.AWS_REGION || 'us-east-1';
+    `;
+    const result = detectDefensivePatterns(filePath, code);
+    expect(result.counts['env-fallback']).toBe(1);
+  });
+
+  it('detects `any` parameter types', () => {
+    const code = `
+      function handler(data: any): string {
+        return data.value;
+      }
+    `;
+    const result = detectDefensivePatterns(filePath, code);
+    expect(result.counts['any-parameter']).toBe(1);
+  });
+
+  it('detects `any` return types', () => {
+    const code = `
+      function parse(raw: string): any {
+        return JSON.parse(raw);
+      }
+    `;
+    const result = detectDefensivePatterns(filePath, code);
+    expect(result.counts['any-return']).toBe(1);
+  });
+
+  it('handles invalid code gracefully', () => {
+    const code = `this is not valid typescript {{{`;
+    const result = detectDefensivePatterns(filePath, code);
+    expect(result.totalLines).toBeGreaterThan(0);
+    expect(result.issues).toHaveLength(0);
+  });
+
+  it('detects multiple patterns in one file', () => {
+    const code = `
+      function process(data: any): any {
+        const val = data?.foo?.bar?.baz ?? 'fallback';
+        const region = process.env.REGION || 'ap-southeast-2';
+        try {
+          return val;
+        } catch {}
+      }
+    `;
+    const result = detectDefensivePatterns(filePath, code);
+    expect(result.counts['any-parameter']).toBe(1);
+    expect(result.counts['any-return']).toBe(1);
+    expect(result.counts['deep-optional-chain']).toBe(1);
+    expect(result.counts['nullish-literal-default']).toBe(1);
+    expect(result.counts['env-fallback']).toBe(1);
+    expect(result.counts['swallowed-error']).toBe(1);
+  });
+});

package/src/__tests__/provider.test.ts

@@ -0,0 +1,26 @@
+import { describe, it, expect } from 'vitest';
+import { ContractEnforcementProvider } from '../provider';
+import { ToolName } from '@aiready/core';
+
+describe('ContractEnforcementProvider', () => {
+  it('has correct tool ID', () => {
+    expect(ContractEnforcementProvider.id).toBe(ToolName.ContractEnforcement);
+  });
+
+  it('has aliases', () => {
+    expect(ContractEnforcementProvider.alias).toContain('contract');
+    expect(ContractEnforcementProvider.alias).toContain('ce');
+  });
+
+  it('has default weight', () => {
+    expect(ContractEnforcementProvider.defaultWeight).toBe(10);
+  });
+
+  it('has analyze function', () => {
+    expect(typeof ContractEnforcementProvider.analyze).toBe('function');
+  });
+
+  it('has score function', () => {
+    expect(typeof ContractEnforcementProvider.score).toBe('function');
+  });
+});