x-readiness-mcp 0.3.0

package/tools/execution.js

@@ -0,0 +1,852 @@
+// tools/execution.js
+// X-API Readiness Execution Tool (STRICT, no silent skips)
+//
+// Guarantees:
+// - Every checklist rule returns a row in rule_evidence[] with a status + reason
+// - No "silent SKIPPED": unsupported categories => NOT_IMPLEMENTED
+// - PASS requires positive evidence (not just "no violations found")
+// - If any rule is NOT_EVALUATED / NOT_IMPLEMENTED => overall status INCOMPLETE + score "N/A" (strict_default)
+// - 100% only possible when ALL rules are evaluated (PASS/FAIL only) and failures=0
+//
+// Optional behavior knobs (recommended defaults below):
+// - strict: true  => score becomes N/A if any rule not evaluated / not implemented
+// - treatUnknownAsFail: false => if true, unknown rules count as FAIL (harsh mode)
+
+import fs from "node:fs";
+import fsp from "node:fs/promises";
+import path from "node:path";
+import crypto from "node:crypto";
+
+export async function executionTool(repoPath, checklist, options = {}) {
+  const startTime = new Date();
+
+  const strict = options.strict ?? true; // default strict: blocks score if anything unknown
+  const treatUnknownAsFail = options.treatUnknownAsFail ?? false;
+
+  if (!repoPath || !fs.existsSync(repoPath)) {
+    throw new Error(`Repository path does not exist: ${repoPath}`);
+  }
+
+  const normalizedChecklist = normalizeChecklist(checklist);
+  if (!normalizedChecklist.rules?.length) {
+    throw new Error("Checklist must contain a non-empty rules[] or features[] array");
+  }
+
+  // Discover + parse files
+  const sourceFiles = await discoverSourceFiles(repoPath);
+  const parsedFiles = await parseSourceFiles(sourceFiles);
+
+  // Detect API signals (so we can decide if we can truly evaluate API rules)
+  const signals = detectApiSignals(parsedFiles);
+
+  // Rule execution + accounting
+  const violations = [];
+  const ruleEvidence = [];
+
+  let pass = 0;
+  let fail = 0;
+  let notEvaluated = 0;
+  let notImplemented = 0;
+
+  for (const rule of normalizedChecklist.rules) {
+    const r = await executeRuleCheck(parsedFiles, rule, normalizedChecklist.scope, signals);
+
+    // If treatUnknownAsFail=true, convert NOT_EVALUATED / NOT_IMPLEMENTED into FAIL
+    if (treatUnknownAsFail && (r.status === "NOT_EVALUATED" || r.status === "NOT_IMPLEMENTED")) {
+      r.status = "FAIL";
+      r.reason = `${r.reason} (treated as FAIL due to treatUnknownAsFail=true)`;
+      // No concrete file/line exists here, so we attach a synthetic violation
+      r.violations = r.violations || [];
+      r.violations.push({
+        scope: normalizedChecklist.scope,
+        category: rule.category,
+        ruleId: rule.ruleId,
+        ruleName: rule.ruleName,
+        referenceUrl: rule.referenceUrl ?? null,
+        normative: rule.normative ?? null,
+        severity: rule.severity ?? "medium",
+        filePath: null,
+        lineNumber: null,
+        columnNumber: null,
+        description: `Rule could not be evaluated: ${r.reason}`,
+        currentCode: null,
+        suggestedFix: "Implement a checker for this rule/category OR provide API specs/source signals to evaluate it."
+      });
+    }
+
+    // Count statuses
+    if (r.status === "PASS") pass++;
+    else if (r.status === "FAIL") fail++;
+    else if (r.status === "NOT_EVALUATED") notEvaluated++;
+    else if (r.status === "NOT_IMPLEMENTED") notImplemented++;
+
+    // Accumulate violations (only real FAIL should add)
+    if (r.status === "FAIL" && Array.isArray(r.violations) && r.violations.length) {
+      violations.push(...r.violations);
+    }
+
+    // Rule evidence row (always)
+    ruleEvidence.push({
+      scope: normalizedChecklist.scope,
+      category: rule.category,
+      rule_id: rule.ruleId,
+      rule_name: rule.ruleName,
+      normative: rule.normative ?? null,
+      severity: rule.severity ?? "medium",
+      reference_url: rule.referenceUrl ?? null,
+
+      status: r.status,
+      reason: r.reason,
+
+      evidence_locations: (r.evidence_locations ?? []).slice(0, 10),
+      violations_found: r.violations?.length ?? 0
+    });
+  }
+
+  // Readiness scoring rules:
+  // - Evaluated rules = PASS + FAIL
+  // - If strict and any unknown/not implemented => score N/A
+  const evaluated = pass + fail;
+  const total = normalizedChecklist.rules.length;
+
+  let score = null;
+  let scoreText = "N/A";
+  let status = "INCOMPLETE";
+  let message = "Some rules were not evaluated or not implemented. Score is not available in strict mode.";
+
+  if (!strict && evaluated > 0) {
+    score = Math.round((pass / evaluated) * 100);
+    scoreText = `${score}%`;
+    status = score >= 80 ? "GOOD" : score >= 60 ? "FAIR" : "NEEDS_IMPROVEMENT";
+    message = `Your repository is ${score}% X-API ready (based on evaluated rules only).`;
+  }
+
+  // Only allow a real % score in strict mode if ALL rules were evaluated
+  if (strict && evaluated === total) {
+    score = Math.round((pass / evaluated) * 100);
+    scoreText = `${score}%`;
+    status = score === 100 ? "GOOD" : score >= 80 ? "GOOD" : score >= 60 ? "FAIR" : "NEEDS_IMPROVEMENT";
+    message = `All rules evaluated. Your repository is ${score}% X-API ready.`;
+  }
+
+  // Never allow 100% unless evaluated === total and fail === 0
+  if (score === 100 && (evaluated !== total || fail !== 0)) {
+    score = null;
+    scoreText = "N/A";
+    status = "INCOMPLETE";
+    message = "100% suppressed because not all rules were fully evaluated.";
+  }
+
+  const executionTimeMs = new Date() - startTime;
+
+  const violationsFlat = violations.map(v => ({
+    scope: v.scope,
+    category: v.category,
+    rule_id: v.ruleId,
+    rule_name: v.ruleName,
+    reference_url: v.referenceUrl,
+    normative: v.normative,
+    severity: v.severity,
+    file_path: v.filePath,
+    line_number: v.lineNumber,
+    column_number: v.columnNumber ?? null,
+    violation_description: v.description,
+    current_code: v.currentCode,
+    suggested_fix: v.suggestedFix
+  }));
+
+  const coverage = total === 0 ? 0 : Math.round((evaluated / total) * 100);
+
+  const reportPayload = {
+    readiness_summary: {
+      score: scoreText,
+      score_value: score,
+      status,
+      message,
+
+      rules_total: total,
+      rules_evaluated: evaluated,
+      rules_passed: pass,
+      rules_failed: fail,
+      rules_not_evaluated: notEvaluated,
+      rules_not_implemented: notImplemented,
+
+      evaluation_coverage_percent: coverage,
+
+      total_violations: violationsFlat.length,
+      files_discovered: sourceFiles.length,
+      files_parsed: parsedFiles.length,
+
+      api_signals: signals // super important for debugging why rules aren't evaluatable
+    },
+
+    // Always detailed per-rule status (so no rule is missed)
+    rule_evidence: ruleEvidence,
+
+    // Only populated if failures exist
+    violations: violationsFlat,
+
+    recommended_actions: generateRecommendations(violations),
+
+    detailed_results: {
+      checklist_id: normalizedChecklist.checklist_id || "unknown",
+      scope: normalizedChecklist.scope,
+      intent: normalizedChecklist.intent || "X-API readiness check",
+      checked_at: startTime.toISOString(),
+      repository: repoPath,
+      execution_time_ms: executionTimeMs,
+      options_used: { strict, treatUnknownAsFail }
+    }
+  };
+
+  // Persist report files
+  const reports = await writeReports(reportPayload);
+  reportPayload.reports = reports;
+
+  return reportPayload;
+}
+
+// -----------------------------
+// Checklist normalization
+// -----------------------------
+function normalizeChecklist(checklist) {
+  const normalized = {
+    checklist_id: checklist?.checklist_id,
+    intent: checklist?.intent,
+    scope: checklist?.scope || checklist?.readiness_scope || "x_api_readiness",
+    rules: []
+  };
+
+  const normalizeCategoryKey = (v) => {
+    if (!v) return "UNKNOWN";
+    const up = String(v).trim().replace(/[\s\-]+/g, "_").toUpperCase();
+    const map = {
+      "API_VERSIONING": "VERSIONING",
+      "VERSIONING": "VERSIONING",
+      "ERROR_HANDLING": "ERROR_HANDLING",
+      "MEDIA_TYPES": "MEDIA_TYPES",
+      "NAMING_CONVENTIONS": "NAMING_CONVENTIONS",
+      "PAGINATION": "PAGINATION",
+      "SECURITY": "SECURITY",
+      "COMMON_OPERATIONS": "COMMON_OPERATIONS"
+    };
+    return map[up] || up;
+  };
+
+  const pushRule = (rule, fallbackCategoryKey) => {
+    if (!rule || typeof rule !== "object") return;
+
+    const categoryKey = normalizeCategoryKey(
+      rule.categoryKey ||
+      rule.category_key ||
+      rule.category ||
+      fallbackCategoryKey
+    );
+
+    const ruleId = rule.ruleId || rule.rule_id || rule.id;
+    const ruleName = rule.ruleName || rule.rule_name || rule.name;
+    if (!ruleId || !ruleName) return;
+
+    normalized.rules.push({
+      ruleId,
+      ruleName,
+      category: categoryKey,
+      categoryKey,
+      normative: rule.normative || null,
+      severity: rule.severity || "medium",
+      referenceUrl: rule.referenceUrl || rule.reference_url || rule.reference || rule.url || null
+    });
+  };
+
+  if (Array.isArray(checklist?.rules)) {
+    checklist.rules.forEach((r) => pushRule(r));
+  }
+
+  if (normalized.rules.length === 0 && Array.isArray(checklist?.features)) {
+    for (const feature of checklist.features) {
+      const fallbackCategoryKey =
+        feature?.category_key ||
+        feature?.categoryKey ||
+        feature?.category ||
+        feature?.feature_id ||
+        null;
+
+      const featureRules = Array.isArray(feature?.rules) ? feature.rules : [];
+      featureRules.forEach((r) => pushRule(r, fallbackCategoryKey));
+    }
+  }
+
+  return normalized;
+}
+
+// -----------------------------
+// File discovery / parsing
+// -----------------------------
+async function discoverSourceFiles(repoPath) {
+  const files = [];
+  const extensions = [".js", ".mjs", ".cjs", ".ts", ".tsx", ".json", ".yml", ".yaml"];
+
+  const excludeDirs = ["node_modules", ".git", "dist", "build", "coverage", ".next", "out"];
+  const excludeFiles = new Set([
+    "package-lock.json",
+    "package.json",
+    "yarn.lock",
+    "pnpm-lock.yaml",
+    "npm-shrinkwrap.json"
+  ]);
+
+  function scanDirectory(dir, depth = 0) {
+    if (depth > 12) return;
+    if (!fs.existsSync(dir)) return;
+
+    const entries = fs.readdirSync(dir, { withFileTypes: true });
+    for (const entry of entries) {
+      const fullPath = path.join(dir, entry.name);
+
+      if (entry.isDirectory()) {
+        if (excludeDirs.includes(entry.name) || entry.name.startsWith(".")) continue;
+        scanDirectory(fullPath, depth + 1);
+      } else if (entry.isFile()) {
+        if (excludeFiles.has(entry.name)) continue;
+        const ext = path.extname(entry.name);
+        if (extensions.includes(ext)) {
+          files.push({
+            absolutePath: fullPath,
+            relativePath: path.relative(repoPath, fullPath),
+            fileName: entry.name,
+            extension: ext,
+            type: determineFileType(entry.name, fullPath)
+          });
+        }
+      }
+    }
+  }
+
+  scanDirectory(repoPath);
+  return files;
+}
+
+function determineFileType(fileName, fullPath) {
+  const lower = fileName.toLowerCase();
+  const rel = fullPath.toLowerCase();
+
+  if (lower.includes("openapi") || lower.includes("swagger")) return "openapi";
+  if (lower.endsWith(".schema.json") || rel.includes("/schema") || rel.includes("\\schema")) return "schema";
+  if (lower.includes("route") || lower.includes("router")) return "routes";
+  if (lower.includes("controller")) return "controller";
+  if (lower.includes("service")) return "service";
+  if (lower.includes("config")) return "config";
+  return "other";
+}
+
+async function parseSourceFiles(sourceFiles) {
+  const parsed = [];
+  for (const file of sourceFiles) {
+    try {
+      const content = fs.readFileSync(file.absolutePath, "utf8");
+      const lines = content.split("\n");
+      parsed.push({
+        ...file,
+        content,
+        lines,
+        lineCount: lines.length,
+        analysis: analyzeFileContent(content, lines)
+      });
+    } catch {
+      // skip unreadable
+    }
+  }
+  return parsed;
+}
+
+function analyzeFileContent(content, lines) {
+  const analysis = {
+    routes: [],
+    statusCodes: [],
+    paginationPatterns: [],
+    versionPatterns: [],
+    securityPatterns: []
+  };
+
+  // Express-like routes
+  const routePatterns = [
+    /router\.(get|post|put|patch|delete)\s*\(\s*['"`]([^'"`]+)['"`]/gi,
+    /app\.(get|post|put|patch|delete)\s*\(\s*['"`]([^'"`]+)['"`]/gi
+  ];
+  routePatterns.forEach(pattern => {
+    let match;
+    while ((match = pattern.exec(content)) !== null) {
+      analysis.routes.push({
+        method: match[1].toUpperCase(),
+        path: match[2],
+        lineNumber: content.substring(0, match.index).split("\n").length
+      });
+    }
+  });
+
+  // Status codes
+  lines.forEach((line, index) => {
+    const m = line.match(/\b(res|response)\.status\s*\(\s*(\d{3})\s*\)/);
+    if (m) analysis.statusCodes.push({ code: parseInt(m[2], 10), lineNumber: index + 1 });
+  });
+
+  // Pagination keywords
+  const paginationKeywords = ["limit", "offset", "page", "cursor"];
+  lines.forEach((line, index) => {
+    for (const keyword of paginationKeywords) {
+      if (new RegExp(`\\b${keyword}\\b`, "i").test(line)) {
+        analysis.paginationPatterns.push({ keyword, lineNumber: index + 1 });
+      }
+    }
+  });
+
+  // Versioning
+  lines.forEach((line, index) => {
+    const m = line.match(/\/v(\d+)\//i);
+    if (m) analysis.versionPatterns.push({ version: m[1], lineNumber: index + 1 });
+  });
+
+  // Security (http://)
+  lines.forEach((line, index) => {
+    if (/http:\/\//i.test(line) && !/localhost|127\.0\.0\.1/i.test(line)) {
+      analysis.securityPatterns.push({ keyword: "insecure-http", lineNumber: index + 1, line: line.trim() });
+    }
+  });
+
+  return analysis;
+}
+
+// -----------------------------
+// API signal detection
+// -----------------------------
+function detectApiSignals(parsedFiles) {
+  const routes = parsedFiles.reduce((acc, f) => acc + (f.analysis?.routes?.length ?? 0), 0);
+  const statusCalls = parsedFiles.reduce((acc, f) => acc + (f.analysis?.statusCodes?.length ?? 0), 0);
+  const hasOpenApi = parsedFiles.some(f => f.type === "openapi");
+  const hasControllersOrRoutes = parsedFiles.some(f => f.type === "routes" || f.type === "controller");
+
+  return {
+    routes_found: routes,
+    status_calls_found: statusCalls,
+    openapi_found: hasOpenApi,
+    route_or_controller_files_found: hasControllersOrRoutes,
+    api_surface_detected: hasOpenApi || routes > 0 || hasControllersOrRoutes
+  };
+}
+
+// -----------------------------
+// Rule execution: no silent skips
+// -----------------------------
+async function executeRuleCheck(parsedFiles, rule, scope, signals) {
+  // default: NOT_EVALUATED until proven PASS/FAIL or NOT_IMPLEMENTED
+  const result = {
+    status: "NOT_EVALUATED",
+    reason: "No positive evidence found yet.",
+    evidence_locations: [],
+    violations: []
+  };
+
+  const categoryKey = rule.categoryKey || rule.category;
+
+  // If we don't even detect API surface, API rules cannot be evaluated meaningfully
+  // (except some security checks that can still run)
+  const apiRequiredCategories = new Set([
+    "PAGINATION",
+    "ERROR_HANDLING",
+    "VERSIONING",
+    "COMMON_OPERATIONS",
+    "MEDIA_TYPES",
+    "NAMING_CONVENTIONS"
+  ]);
+
+  if (apiRequiredCategories.has(categoryKey) && !signals.api_surface_detected) {
+    result.status = "NOT_EVALUATED";
+    result.reason = "No API surface detected (no routes/controllers/OpenAPI). Cannot evaluate this rule.";
+    return result;
+  }
+
+  // Dispatch
+  switch (categoryKey) {
+    case "PAGINATION":
+      return checkPaginationRules(parsedFiles, rule, scope);
+    case "ERROR_HANDLING":
+      return checkErrorHandlingRules(parsedFiles, rule, scope);
+    case "SECURITY":
+      return checkSecurityRules(parsedFiles, rule, scope);
+    case "VERSIONING":
+      return checkVersioningRules(parsedFiles, rule, scope);
+    case "COMMON_OPERATIONS":
+      return checkCommonOperations(parsedFiles, rule, scope);
+    case "NAMING_CONVENTIONS":
+      return checkNamingConventionsRules(parsedFiles, rule, scope);
+    case "MEDIA_TYPES":
+      return checkMediaTypesRules(parsedFiles, rule, scope);
+    default:
+      return {
+        status: "NOT_IMPLEMENTED",
+        reason: `No checker implemented for category '${categoryKey}'.`,
+        evidence_locations: [],
+        violations: []
+      };
+  }
+}
+
+// -----------------------------
+// Checkers must produce one of: PASS/FAIL/NOT_EVALUATED
+// PASS must include positive evidence_locations (>=1)
+// FAIL must include violations (>=1)
+// NOT_EVALUATED must have reason
+// -----------------------------
+function checkPaginationRules(parsedFiles, rule, scope) {
+  const relevantFiles = parsedFiles.filter(f => f.type === "routes" || f.type === "controller");
+  if (relevantFiles.length === 0) {
+    return { status: "NOT_EVALUATED", reason: "No routes/controllers found to evaluate pagination.", evidence_locations: [], violations: [] };
+  }
+
+  const evidence = [];
+  const violations = [];
+
+  for (const file of relevantFiles) {
+    for (const hit of (file.analysis.paginationPatterns || []).slice(0, 5)) {
+      evidence.push({ file_path: file.relativePath, line_number: hit.lineNumber, snippet: file.lines[hit.lineNumber - 1]?.trim() ?? "" });
+    }
+    // For MUST pagination rules: if a route exists and there is no pagination keyword anywhere, mark violation (heuristic)
+    if ((file.analysis.routes?.length ?? 0) > 0 && (file.analysis.paginationPatterns?.length ?? 0) === 0 && rule.normative === "MUST") {
+      const ln = file.analysis.routes[0].lineNumber;
+      violations.push({
+        scope, category: rule.category, ruleId: rule.ruleId, ruleName: rule.ruleName,
+        referenceUrl: rule.referenceUrl ?? null, normative: rule.normative ?? null, severity: rule.severity ?? "high",
+        filePath: file.relativePath, lineNumber: ln, columnNumber: null,
+        description: "Routes found but no pagination signals (limit/offset/page/cursor) detected.",
+        currentCode: file.lines[ln - 1]?.trim() ?? "",
+        suggestedFix: "Add pagination support (limit/offset or cursor) for collection endpoints."
+      });
+    }
+  }
+
+  if (violations.length) return { status: "FAIL", reason: "Pagination violations detected.", evidence_locations: evidence, violations };
+  if (evidence.length) return { status: "PASS", reason: "Pagination signals detected in code.", evidence_locations: evidence, violations: [] };
+  return { status: "NOT_EVALUATED", reason: "No pagination signals detected; cannot confirm compliance.", evidence_locations: [], violations: [] };
+}
+
+function checkErrorHandlingRules(parsedFiles, rule, scope) {
+  const relevantFiles = parsedFiles.filter(f => f.type === "routes" || f.type === "controller");
+  if (relevantFiles.length === 0) {
+    return { status: "NOT_EVALUATED", reason: "No routes/controllers found to evaluate error handling.", evidence_locations: [], violations: [] };
+  }
+
+  const evidence = [];
+  const violations = [];
+
+  for (const file of relevantFiles) {
+    file.lines.forEach((line, idx) => {
+      const ln = idx + 1;
+
+      if (/\b(res|response)\.status\s*\(\s*\d{3}\s*\)/.test(line)) {
+        if (evidence.length < 10) evidence.push({ file_path: file.relativePath, line_number: ln, snippet: line.trim() });
+      }
+
+      if (/\b(res|response)\.(send|json)\s*\(/.test(line) && !/\b(res|response)\.status\s*\(/.test(line)) {
+        violations.push({
+          scope, category: rule.category, ruleId: rule.ruleId, ruleName: rule.ruleName,
+          referenceUrl: rule.referenceUrl ?? null, normative: rule.normative ?? null, severity: rule.severity ?? "high",
+          filePath: file.relativePath, lineNumber: ln, columnNumber: null,
+          description: "Response sent without explicit HTTP status code.",
+          currentCode: line.trim(),
+          suggestedFix: "Use res.status(<code>).json()/send() consistently."
+        });
+      }
+    });
+  }
+
+  if (violations.length) return { status: "FAIL", reason: "Missing explicit status codes detected.", evidence_locations: evidence, violations };
+  if (evidence.length) return { status: "PASS", reason: "Explicit status code usage detected.", evidence_locations: evidence, violations: [] };
+  return { status: "NOT_EVALUATED", reason: "No status code usage detected; cannot confirm error handling behavior.", evidence_locations: [], violations: [] };
+}
+
+function checkSecurityRules(parsedFiles, rule, scope) {
+  const evidence = [];
+  const violations = [];
+
+  for (const file of parsedFiles) {
+    for (const pattern of (file.analysis.securityPatterns || [])) {
+      evidence.push({ file_path: file.relativePath, line_number: pattern.lineNumber, snippet: pattern.line?.trim() ?? "" });
+      violations.push({
+        scope, category: rule.category, ruleId: rule.ruleId, ruleName: rule.ruleName,
+        referenceUrl: rule.referenceUrl ?? null, normative: "MUST", severity: "critical",
+        filePath: file.relativePath, lineNumber: pattern.lineNumber, columnNumber: null,
+        description: "Insecure http:// usage detected (must use https://).",
+        currentCode: pattern.line,
+        suggestedFix: "Replace http:// with https:// or ensure TLS termination."
+      });
+    }
+  }
+
+  if (violations.length) return { status: "FAIL", reason: "Security violations detected (http://).", evidence_locations: evidence, violations };
+  // For SECURITY, PASS needs positive evidence; otherwise NOT_EVALUATED (don’t claim secure just because nothing found)
+  return { status: "NOT_EVALUATED", reason: "No explicit security evidence detected; security cannot be confirmed by heuristic.", evidence_locations: [], violations: [] };
+}
+
+function checkVersioningRules(parsedFiles, rule, scope) {
+  const relevantFiles = parsedFiles.filter(f => f.type === "routes" || f.type === "controller");
+  if (relevantFiles.length === 0) {
+    return { status: "NOT_EVALUATED", reason: "No routes/controllers found to evaluate versioning.", evidence_locations: [], violations: [] };
+  }
+
+  const evidence = [];
+  const violations = [];
+
+  for (const file of relevantFiles) {
+    for (const hit of (file.analysis.versionPatterns || []).slice(0, 5)) {
+      evidence.push({ file_path: file.relativePath, line_number: hit.lineNumber, snippet: file.lines[hit.lineNumber - 1]?.trim() ?? "" });
+    }
+
+    if ((file.analysis.routes?.length ?? 0) > 0 && (file.analysis.versionPatterns?.length ?? 0) === 0 && rule.normative === "MUST") {
+      const ln = file.analysis.routes[0].lineNumber;
+      violations.push({
+        scope, category: rule.category, ruleId: rule.ruleId, ruleName: rule.ruleName,
+        referenceUrl: rule.referenceUrl ?? null, normative: rule.normative ?? null, severity: rule.severity ?? "medium",
+        filePath: file.relativePath, lineNumber: ln, columnNumber: null,
+        description: "Routes found but no versioning signals (/v1/) detected.",
+        currentCode: file.lines[ln - 1]?.trim() ?? "",
+        suggestedFix: "Prefix API routes with a version (e.g., /api/v1/...)."
+      });
+    }
+  }
+
+  if (violations.length) return { status: "FAIL", reason: "Versioning violations detected.", evidence_locations: evidence, violations };
+  if (evidence.length) return { status: "PASS", reason: "Versioning signals detected (/vN/).", evidence_locations: evidence, violations: [] };
+  return { status: "NOT_EVALUATED", reason: "No versioning signals detected; cannot confirm compliance.", evidence_locations: [], violations: [] };
+}
+
+function checkCommonOperations(parsedFiles, rule, scope) {
+  const relevantFiles = parsedFiles.filter(f => f.type === "routes" || f.type === "controller");
+  if (relevantFiles.length === 0) {
+    return { status: "NOT_EVALUATED", reason: "No routes/controllers found to evaluate common operations.", evidence_locations: [], violations: [] };
+  }
+
+  const evidence = [];
+  const violations = [];
+
+  for (const file of relevantFiles) {
+    for (const route of (file.analysis.routes || [])) {
+      if (evidence.length < 10) {
+        evidence.push({ file_path: file.relativePath, line_number: route.lineNumber, snippet: `${route.method} ${route.path}` });
+      }
+      if (route.method === "GET" && /create|add|insert/i.test(route.path)) {
+        violations.push({
+          scope, category: rule.category, ruleId: rule.ruleId, ruleName: rule.ruleName,
+          referenceUrl: rule.referenceUrl ?? null, normative: rule.normative ?? "SHOULD", severity: rule.severity ?? "medium",
+          filePath: file.relativePath, lineNumber: route.lineNumber, columnNumber: null,
+          description: "GET used for resource creation-like endpoint.",
+          currentCode: `${route.method} ${route.path}`,
+          suggestedFix: "Use POST for creating resources."
+        });
+      }
+    }
+  }
+
+  if (violations.length) return { status: "FAIL", reason: "HTTP method misuse detected.", evidence_locations: evidence, violations };
+  if (evidence.length) return { status: "PASS", reason: "Route evidence found; no method misuse detected by heuristic.", evidence_locations: evidence, violations: [] };
+  return { status: "NOT_EVALUATED", reason: "No route evidence; cannot evaluate operations.", evidence_locations: [], violations: [] };
+}
+
+// OpenAPI-focused checks
+function checkNamingConventionsRules(parsedFiles, rule, scope) {
+  const apiSpecFiles = parsedFiles.filter(f => f.type === "openapi" || f.type === "schema");
+  if (apiSpecFiles.length === 0) {
+    return { status: "NOT_EVALUATED", reason: "No OpenAPI/schema files found; naming rules require API spec to evaluate reliably.", evidence_locations: [], violations: [] };
+  }
+
+  const evidence = [];
+  const violations = [];
+
+  for (const file of apiSpecFiles) {
+    if (file.extension !== ".json") continue;
+    let json;
+    try { json = JSON.parse(file.content); } catch { continue; }
+
+    const keys = extractOpenApiSchemaPropertyKeys(json);
+    if (keys.length === 0) continue;
+
+    for (const key of keys.slice(0, 10)) {
+      const ln = findKeyLine(file.lines, key);
+      evidence.push({ file_path: file.relativePath, line_number: ln, snippet: file.lines[ln - 1]?.trim() ?? `"${key}": ...` });
+    }
+
+    for (const key of keys) {
+      if (!/^[a-z][a-zA-Z0-9]*$/.test(key) && key !== "_id" && !key.startsWith("$")) {
+        const ln = findKeyLine(file.lines, key);
+        violations.push({
+          scope, category: rule.category, ruleId: rule.ruleId, ruleName: rule.ruleName,
+          referenceUrl: rule.referenceUrl ?? null, normative: rule.normative ?? null, severity: rule.severity ?? "medium",
+          filePath: file.relativePath, lineNumber: ln, columnNumber: null,
+          description: `Schema property '${key}' not camelCase.`,
+          currentCode: file.lines[ln - 1]?.trim() ?? `"${key}": ...`,
+          suggestedFix: "Rename schema properties to camelCase and update clients."
+        });
+      }
+    }
+  }
+
+  if (violations.length) return { status: "FAIL", reason: "Naming violations found in API specs.", evidence_locations: evidence, violations };
+  if (evidence.length) return { status: "PASS", reason: "API spec schema properties inspected; no naming violations detected.", evidence_locations: evidence, violations: [] };
+  return { status: "NOT_EVALUATED", reason: "OpenAPI/schema present but no schema properties found.", evidence_locations: [], violations: [] };
+}
+
+function checkMediaTypesRules(parsedFiles, rule, scope) {
+  const openapiFiles = parsedFiles.filter(f => f.type === "openapi" && f.extension === ".json");
+  if (openapiFiles.length === 0) {
+    return { status: "NOT_EVALUATED", reason: "No OpenAPI JSON found; media type rules require OpenAPI spec to evaluate.", evidence_locations: [], violations: [] };
+  }
+
+  const evidence = [];
+  const violations = [];
+
+  for (const file of openapiFiles) {
+    let json;
+    try { json = JSON.parse(file.content); } catch { continue; }
+    if (!looksLikeOpenApi(json)) continue;
+
+    const mtypes = findOpenApiMediaTypes(json);
+    for (const mt of Array.from(mtypes).slice(0, 10)) {
+      evidence.push({ file_path: file.relativePath, line_number: findAnyLineContaining(file.lines, `"${mt}"`) || 1, snippet: mt });
+    }
+
+    if (!mtypes.has("application/json") && rule.normative === "MUST") {
+      const ln = findAnyLineContaining(file.lines, '"content"') || 1;
+      violations.push({
+        scope, category: rule.category, ruleId: rule.ruleId, ruleName: rule.ruleName,
+        referenceUrl: rule.referenceUrl ?? null, normative: rule.normative ?? null, severity: rule.severity ?? "high",
+        filePath: file.relativePath, lineNumber: ln, columnNumber: null,
+        description: "OpenAPI spec missing application/json content declaration.",
+        currentCode: file.lines[ln - 1]?.trim() ?? "",
+        suggestedFix: 'Add content: { "application/json": { schema: ... } } to requestBody/responses.'
+      });
+    }
+  }
+
+  if (violations.length) return { status: "FAIL", reason: "Media type violations found in OpenAPI spec.", evidence_locations: evidence, violations };
+  if (evidence.length) return { status: "PASS", reason: "OpenAPI media types inspected; application/json present.", evidence_locations: evidence, violations: [] };
+  return { status: "NOT_EVALUATED", reason: "OpenAPI present but no media type evidence found.", evidence_locations: [], violations: [] };
+}
+
+// -----------------------------
+// OpenAPI helpers
+// -----------------------------
+function looksLikeOpenApi(json) {
+  return typeof json?.openapi === "string" || typeof json?.swagger === "string" || (json?.paths && typeof json.paths === "object");
+}
+
+function extractOpenApiSchemaPropertyKeys(json) {
+  if (!looksLikeOpenApi(json)) return [];
+  const schemas = json?.components?.schemas;
+  if (!schemas || typeof schemas !== "object") return [];
+  const keys = [];
+  for (const schemaName of Object.keys(schemas)) {
+    const props = schemas[schemaName]?.properties;
+    if (props && typeof props === "object") {
+      for (const k of Object.keys(props)) keys.push(k);
+    }
+  }
+  return keys;
+}
+
+function findOpenApiMediaTypes(json) {
+  const set = new Set();
+  if (!looksLikeOpenApi(json)) return set;
+
+  const paths = json.paths || {};
+  for (const p of Object.keys(paths)) {
+    const item = paths[p] || {};
+    for (const method of Object.keys(item)) {
+      const op = item[method];
+      if (!op || typeof op !== "object") continue;
+
+      const rb = op.requestBody?.content;
+      if (rb && typeof rb === "object") Object.keys(rb).forEach(k => set.add(k));
+
+      const res = op.responses || {};
+      for (const code of Object.keys(res)) {
+        const content = res[code]?.content;
+        if (content && typeof content === "object") Object.keys(content).forEach(k => set.add(k));
+      }
+    }
+  }
+  return set;
+}
+
+// -----------------------------
+// Report persistence
+// -----------------------------
+async function writeReports(payload) {
+  const reportsDir = path.resolve("mcp", "reports");
+  await fsp.mkdir(reportsDir, { recursive: true });
+
+  const runId = `run_${new Date().toISOString().replace(/[:.]/g, "-")}_${crypto.randomUUID()}`;
+  const jsonPath = path.join(reportsDir, `${runId}.json`);
+
+  await fsp.writeFile(jsonPath, JSON.stringify(payload, null, 2), "utf8");
+
+  return { run_id: runId, json_path: jsonPath };
+}
+
+// -----------------------------
+// Recommendations (same idea as before)
+// -----------------------------
+function generateRecommendations(violations) {
+  const actions = [];
+  const fixGroups = {};
+
+  for (const v of violations) {
+    if (!v.suggestedFix) continue;
+    const key = `${v.category}::${v.suggestedFix}`;
+    if (!fixGroups[key]) {
+      fixGroups[key] = {
+        fix: v.suggestedFix,
+        category: v.category,
+        severity: v.severity,
+        files: [],
+        ruleIds: new Set()
+      };
+    }
+    if (v.filePath) fixGroups[key].files.push(v.filePath);
+    fixGroups[key].ruleIds.add(v.ruleId);
+  }
+
+  for (const group of Object.values(fixGroups)) {
+    const priority = group.severity === "critical" ? 1 : group.severity === "high" ? 2 : 3;
+    actions.push({
+      priority,
+      severity: group.severity,
+      category: group.category,
+      action: group.fix,
+      affected_files: [...new Set(group.files)].length,
+      total_occurrences: group.files.length,
+      reference_rules: Array.from(group.ruleIds)
+    });
+  }
+
+  actions.sort((a, b) => a.priority - b.priority);
+  return actions;
+}
+
+// -----------------------------
+// Generic helpers
+// -----------------------------
+function findKeyLine(lines, key) {
+  for (let i = 0; i < lines.length; i++) {
+    if (lines[i].includes(`"${key}"`)) return i + 1;
+  }
+  return 1;
+}
+
+function findAnyLineContaining(lines, needle) {
+  const n = String(needle);
+  for (let i = 0; i < lines.length; i++) {
+    if (lines[i].includes(n)) return i + 1;
+  }
+  return null;
+}
+
+export default executionTool;