@aiready/contract-enforcement 0.2.0

package/src/__tests__/scoring.test.ts

@@ -0,0 +1,58 @@
+import { describe, it, expect } from 'vitest';
+import { calculateContractEnforcementScore } from '../scoring';
+import { ZERO_COUNTS } from '../types';
+
+describe('calculateContractEnforcementScore', () => {
+  it('returns 100 with no defensive patterns', () => {
+    const result = calculateContractEnforcementScore(ZERO_COUNTS, 1000, 10);
+    expect(result.score).toBe(100);
+    expect(result.rating).toBe('excellent');
+  });
+
+  it('returns lower score with many as-any patterns', () => {
+    const counts = { ...ZERO_COUNTS, 'as-any': 50 };
+    const result = calculateContractEnforcementScore(counts, 1000, 10);
+    expect(result.score).toBeLessThan(100);
+    expect(result.dimensions.typeEscapeHatchScore).toBeLessThan(100);
+  });
+
+  it('returns lower score with many swallowed errors', () => {
+    const counts = { ...ZERO_COUNTS, 'swallowed-error': 10 };
+    const result = calculateContractEnforcementScore(counts, 1000, 10);
+    expect(result.score).toBeLessThan(100);
+    expect(result.dimensions.errorTransparencyScore).toBeLessThan(100);
+  });
+
+  it('scores boundary validation correctly', () => {
+    const counts = {
+      ...ZERO_COUNTS,
+      'env-fallback': 20,
+      'unnecessary-guard': 10,
+    };
+    const result = calculateContractEnforcementScore(counts, 1000, 10);
+    expect(result.dimensions.boundaryValidationScore).toBeLessThan(100);
+  });
+
+  it('generates recommendations for low-scoring dimensions', () => {
+    const counts = {
+      ...ZERO_COUNTS,
+      'as-any': 30,
+      'swallowed-error': 10,
+    };
+    const result = calculateContractEnforcementScore(counts, 1000, 10);
+    expect(result.recommendations.length).toBeGreaterThan(0);
+  });
+
+  it('handles zero LOC without division errors', () => {
+    const result = calculateContractEnforcementScore(ZERO_COUNTS, 0, 0);
+    expect(result.score).toBe(100);
+    expect(isNaN(result.score)).toBe(false);
+  });
+
+  it('rates correctly across thresholds', () => {
+    // Excellent (>= 90)
+    expect(
+      calculateContractEnforcementScore(ZERO_COUNTS, 1000, 10).rating
+    ).toBe('excellent');
+  });
+});

package/src/analyzer.ts

@@ -0,0 +1,80 @@
+import { readFileSync } from 'fs';
+import { scanFiles, runBatchAnalysis } from '@aiready/core';
+import { detectDefensivePatterns } from './detector';
+import { calculateContractEnforcementScore } from './scoring';
+import type {
+  ContractEnforcementOptions,
+  ContractEnforcementReport,
+  DetectionResult,
+  PatternCounts,
+} from './types';
+import { ZERO_COUNTS } from './types';
+
+export async function analyzeContractEnforcement(
+  options: ContractEnforcementOptions
+): Promise<ContractEnforcementReport> {
+  const files = await scanFiles({
+    ...options,
+    include: options.include || ['**/*.{ts,tsx,js,jsx}'],
+  });
+
+  const allIssues: ContractEnforcementReport['issues'] = [];
+  const aggregate: PatternCounts = { ...ZERO_COUNTS };
+  let totalLines = 0;
+
+  await runBatchAnalysis(
+    files,
+    'scanning for defensive patterns',
+    'contract-enforcement',
+    options.onProgress,
+    async (f: string) => {
+      let code: string;
+      try {
+        code = readFileSync(f, 'utf-8');
+      } catch {
+        return { issues: [], counts: { ...ZERO_COUNTS }, totalLines: 0 };
+      }
+      return detectDefensivePatterns(f, code, options.minChainDepth ?? 3);
+    },
+    (result: DetectionResult) => {
+      allIssues.push(...result.issues);
+      totalLines += result.totalLines;
+      for (const key of Object.keys(aggregate) as Array<keyof PatternCounts>) {
+        aggregate[key] += result.counts[key];
+      }
+    }
+  );
+
+  const totalPatterns = Object.values(aggregate).reduce((a, b) => a + b, 0);
+  const density =
+    totalLines > 0 ? Math.round((totalPatterns / totalLines) * 10000) / 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 as number,
+        fallbackCascadeScore: scoreResult.dimensions
+          .fallbackCascadeScore as number,
+        errorTransparencyScore: scoreResult.dimensions
+          .errorTransparencyScore as number,
+        boundaryValidationScore: scoreResult.dimensions
+          .boundaryValidationScore as number,
+      },
+    },
+    issues: allIssues,
+    rawData: { ...aggregate, sourceFiles: files.length, totalLines },
+    recommendations: scoreResult.recommendations,
+  };
+}

package/src/detector.ts

@@ -0,0 +1,373 @@
+import { parse } from '@typescript-eslint/typescript-estree';
+import { Severity, IssueType } from '@aiready/core';
+import type {
+  ContractEnforcementIssue,
+  DetectionResult,
+  DefensivePattern,
+  PatternCounts,
+} from './types';
+import { ZERO_COUNTS } from './types';
+
+function makeIssue(
+  pattern: DefensivePattern,
+  severity: Severity,
+  message: string,
+  filePath: string,
+  line: number,
+  column: number,
+  context: string
+): ContractEnforcementIssue {
+  return {
+    type: IssueType.ContractGap,
+    severity,
+    pattern,
+    message,
+    location: { file: filePath, line, column },
+    context,
+    suggestion: getSuggestion(pattern),
+  };
+}
+
+function getSuggestion(pattern: DefensivePattern): string {
+  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 — 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: string, line: number): string {
+  const lines = code.split('\n');
+  return (lines[line - 1] || '').trim().slice(0, 120);
+}
+
+function countOptionalChainDepth(node: any): number {
+  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: any): boolean {
+  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: any): boolean {
+  return (
+    node?.type === 'MemberExpression' &&
+    node.object?.type === 'MemberExpression' &&
+    node.object.object?.name === 'process' &&
+    node.object.property?.name === 'env'
+  );
+}
+
+function isSwallowedCatch(body: any[]): boolean {
+  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;
+}
+
+export function detectDefensivePatterns(
+  filePath: string,
+  code: string,
+  minChainDepth: number = 3
+): DetectionResult {
+  const issues: ContractEnforcementIssue[] = [];
+  const counts: PatternCounts = { ...ZERO_COUNTS };
+  const totalLines = code.split('\n').length;
+
+  let ast: any;
+  try {
+    ast = parse(code, {
+      filePath,
+      loc: true,
+      range: true,
+      jsx: filePath.endsWith('x'),
+    });
+  } catch {
+    return { issues, counts, totalLines };
+  }
+
+  const nodesAtFunctionStart = new WeakSet<any>();
+
+  function markFunctionParamNodes(node: any) {
+    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: any, _parent?: any, _keyInParent?: string) {
+    if (!node || typeof node !== 'object') return;
+
+    markFunctionParamNodes(node);
+
+    // Pattern: as any
+    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)
+        )
+      );
+    }
+
+    // Pattern: as unknown
+    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)
+        )
+      );
+    }
+
+    // Pattern: deep optional chaining
+    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)
+          )
+        );
+      }
+    }
+
+    // Pattern: nullish coalescing with literal default
+    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)
+        )
+      );
+    }
+
+    // Pattern: swallowed error
+    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 — 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)
+          )
+        );
+      }
+    }
+
+    // Pattern: process.env.X || default
+    if (
+      node.type === 'LogicalExpression' &&
+      node.operator === '||' &&
+      isProcessEnvAccess(node.left)
+    ) {
+      counts['env-fallback']++;
+      issues.push(
+        makeIssue(
+          'env-fallback',
+          Severity.Minor,
+          'Environment variable with fallback — use a validated env schema instead',
+          filePath,
+          node.loc?.start.line ?? 0,
+          node.loc?.start.column ?? 0,
+          getLineContent(code, node.loc?.start.line ?? 0)
+        )
+      );
+    }
+
+    // Pattern: if (!x) return guard at function entry
+    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)
+          )
+        );
+      }
+    }
+
+    // Pattern: any parameter type
+    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)
+            )
+          );
+        }
+      }
+
+      // Pattern: any return type
+      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` — 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)
+          )
+        );
+      }
+    }
+
+    // Recurse
+    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 };
+}

package/src/index.ts

@@ -0,0 +1,17 @@
+import { ToolRegistry } from '@aiready/core';
+import { ContractEnforcementProvider } from './provider';
+
+ToolRegistry.register(ContractEnforcementProvider);
+
+export { analyzeContractEnforcement } from './analyzer';
+export { calculateContractEnforcementScore } from './scoring';
+export { detectDefensivePatterns } from './detector';
+export { ContractEnforcementProvider };
+export type {
+  ContractEnforcementOptions,
+  ContractEnforcementReport,
+  ContractEnforcementIssue,
+  PatternCounts,
+  DefensivePattern,
+  DetectionResult,
+} from './types';

package/src/provider.ts

@@ -0,0 +1,40 @@
+import { createProvider, ToolName, groupIssuesByFile } from '@aiready/core';
+import type { ScanOptions, AnalysisResult, SpokeOutput } from '@aiready/core';
+import { analyzeContractEnforcement } from './analyzer';
+import { calculateContractEnforcementScore } from './scoring';
+import type {
+  ContractEnforcementOptions,
+  ContractEnforcementReport,
+} from './types';
+
+export const ContractEnforcementProvider = createProvider({
+  id: ToolName.ContractEnforcement,
+  alias: ['contract', 'ce', 'enforcement'],
+  version: '0.1.0',
+  defaultWeight: 10,
+
+  async analyzeReport(options: ScanOptions) {
+    return analyzeContractEnforcement(options as ContractEnforcementOptions);
+  },
+
+  getResults(report: ContractEnforcementReport): AnalysisResult[] {
+    return groupIssuesByFile(report.issues);
+  },
+
+  getSummary(report: ContractEnforcementReport) {
+    return report.summary;
+  },
+
+  getMetadata(report: ContractEnforcementReport) {
+    return { rawData: report.rawData };
+  },
+
+  score(output: SpokeOutput, _options: ScanOptions) {
+    const rawData = (output.metadata as any)?.rawData ?? {};
+    return calculateContractEnforcementScore(
+      rawData,
+      rawData.totalLines ?? 1,
+      rawData.sourceFiles ?? 1
+    ) as any;
+  },
+});

package/src/scoring.ts

@@ -0,0 +1,94 @@
+import type { PatternCounts, ScoreResult } from './types';
+
+const DIMENSION_WEIGHTS = {
+  typeEscapeHatch: 0.35,
+  fallbackCascade: 0.25,
+  errorTransparency: 0.2,
+  boundaryValidation: 0.2,
+};
+
+function clamp(v: number, min: number, max: number): number {
+  return Math.max(min, Math.min(max, v));
+}
+
+export function calculateContractEnforcementScore(
+  counts: PatternCounts,
+  totalLines: number,
+  _fileCount: number
+): ScoreResult {
+  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'];
+
+  // Density: patterns per 1000 LOC
+  const typeDensity = (typeEscapeCount / loc) * 1000;
+  const fallbackDensity = (fallbackCount / loc) * 1000;
+  const errorDensity = (errorCount / loc) * 1000;
+  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);
+
+  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: string[] = [];
+  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,
+  };
+}