x-readiness-mcp 0.3.0 → 0.5.0

package/tools/execution.js

@@ -1,852 +1,231 @@
-// 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";
+// mcp/tools/execution.js
+import fs 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)
-          });
+import { evaluateRule } from "./rule-checkers.js";
+
+function reportsDir(repoPath) {
+  return path.resolve(repoPath, ".xreadiness", "reports");
+}
+
+async function ensureDir(p) {
+  await fs.mkdir(p, { recursive: true });
+}
+
+async function loadPlan(planPath) {
+  const raw = await fs.readFile(planPath, "utf8");
+  return JSON.parse(raw);
+}
+
+/**
+ * Build detailed markdown report with violation table
+ */
+function buildMarkdownReport({ runId, repoPath, plan, results }) {
+  const { readiness_summary, violations } = results;
+
+  let md = `# API X-Readiness Execution Report\n\n`;
+  md += `**Generated:** ${new Date().toISOString()}\n\n`;
+  md += `- **Run ID:** ${runId}\n`;
+  md += `- **Repository Path:** ${repoPath}\n`;
+  md += `- **Plan ID:** ${plan.plan_id}\n`;
+  md += `- **Scope:** ${plan.scope}\n`;
+  md += `- **Scope Description:** ${plan.scope_description}\n\n`;
+
+  md += `---\n\n`;
+  md += `## Summary\n\n`;
+  md += `| Metric | Count |\n`;
+  md += `|--------|-------|\n`;
+  md += `| Rules Checked | ${readiness_summary.rules_checked} |\n`;
+  md += `| ✅ Passed | ${readiness_summary.passed} |\n`;
+  md += `| ❌ Failed | ${readiness_summary.failed} |\n`;
+  md += `| ⏭️ Skipped | ${readiness_summary.skipped} |\n`;
+  md += `| ⚠️ Errors | ${readiness_summary.errors} |\n\n`;
+
+  const passRate = readiness_summary.rules_checked > 0 
+    ? ((readiness_summary.passed / readiness_summary.rules_checked) * 100).toFixed(1)
+    : 0;
+  md += `**Pass Rate:** ${passRate}%\n\n`;
+
+  md += `---\n\n`;
+  md += `## Rule Violations\n\n`;
+  
+  if (!violations.length) {
+    md += `✅ **No violations found!** Your API conforms to all checked X-Readiness rules.\n\n`;
+  } else {
+    md += `Found **${violations.length} violations** across the codebase:\n\n`;
+    md += `| Rule ID | Category | Severity | File | Line | Violation Message | Guideline |\n`;
+    md += `|---------|----------|----------|------|-----:|-------------------|------------|\n`;
+    
+    for (const v of violations) {
+      const fileLink = v.file_path;
+      const line = v.line_number || "-";
+      const message = v.message.replace(/\|/g, "\\|").replace(/\n/g, " ");
+      const guidelineLink = v.guideline_url 
+        ? `[📖 Ref](${v.guideline_url})`
+        : "-";
+      
+      md += `| \`${v.rule_id}\` | ${v.category} | ${v.severity} | \`${fileLink}\` | ${line} | ${message} | ${guidelineLink} |\n`;
+    }
+    md += `\n`;
+    
+    // Group violations by file
+    md += `### Violations by File\n\n`;
+    const byFile = {};
+    for (const v of violations) {
+      if (!byFile[v.file_path]) byFile[v.file_path] = [];
+      byFile[v.file_path].push(v);
+    }
+    
+    for (const [file, viols] of Object.entries(byFile)) {
+      md += `#### \`${file}\` (${viols.length} violations)\n\n`;
+      for (const v of viols) {
+        md += `- **Line ${v.line_number || "?"}** — Rule \`${v.rule_id}\`: ${v.message}\n`;
+        if (v.line_content) {
+          md += `  \`\`\`\n  ${v.line_content}\n  \`\`\`\n`;
         }
       }
+      md += `\n`;
     }
   }
 
-  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;
+  md += `---\n\n`;
+  md += `## Next Steps\n\n`;
+  if (violations.length > 0) {
+    md += `1. **Review the violations** listed above\n`;
+    md += `2. **Fix the issues** in your source code\n`;
+    md += `3. **Re-run the execution** to verify fixes\n`;
+    md += `4. **Or use auto-fix tool** (if available) by calling \`auto_fix\` with this run ID\n`;
+    md += `   - ⚠️ Auto-fix requires your approval before applying changes\n\n`;
+  } else {
+    md += `🎉 **Congratulations!** Your API is X-Readiness compliant for the checked scope.\n\n`;
   }
 
-  // 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: []
-      };
-  }
+  return md;
 }
 
-// -----------------------------
-// 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: [] };
-  }
+/**
+ * Main execution tool - checks each rule systematically
+ */
+export async function executeTool({ repoPath, planPath }) {
+  console.error(`[executeTool] Loading plan from: ${planPath}`);
+  const plan = await loadPlan(planPath);
 
-  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."
+  // Extract all rules from plan categories
+  const allRules = [];
+  for (const category of plan.categories ?? []) {
+    for (const rule of category.rules ?? []) {
+      allRules.push({
+        ...rule,
+        category: category.name,
+        priority: category.priority,
+        guideline_url: category.guideline_url
       });
     }
   }
 
-  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: [] };
-  }
+  console.error(`[executeTool] Checking ${allRules.length} rules...`);
 
   const evidence = [];
   const violations = [];
+  let errorCount = 0;
 
-  for (const file of relevantFiles) {
-    file.lines.forEach((line, idx) => {
-      const ln = idx + 1;
+  // Execute each rule check
+  for (let idx = 0; idx < allRules.length; idx++) {
+    const rule = allRules[idx];
+    console.error(`[executeTool] [${idx + 1}/${allRules.length}] Checking rule: ${rule.rule_id}`);
 
-      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() ?? "" });
-    }
+    try {
+      const result = await evaluateRule(repoPath, rule);
 
-    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/...)."
+      evidence.push({
+        rule_id: rule.rule_id,
+        rule_name: rule.rule_name,
+        category: rule.category,
+        status: result.status,
+        reason: result.reason || null
       });
-    }
-  }
-
-  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."
-        });
+      // Collect violations
+      if (result.status === "FAIL") {
+        for (const v of result.violations ?? []) {
+          violations.push({
+            rule_id: rule.rule_id,
+            category: rule.category,
+            severity: rule.priority || "medium",
+            file_path: v.file_path,
+            line_number: v.line_number,
+            line_content: v.line_content,
+            message: v.message,
+            guideline_url: rule.guideline_url
+          });
+        }
       }
-    }
-  }
-
-  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 (result.status === "ERROR") {
+        errorCount++;
       }
-    }
-  }
-
-  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.'
+    } catch (error) {
+      console.error(`[executeTool] Error checking rule ${rule.rule_id}:`, error);
+      evidence.push({
+        rule_id: rule.rule_id,
+        rule_name: rule.rule_name,
+        category: rule.category,
+        status: "ERROR",
+        reason: error.message
       });
+      errorCount++;
     }
   }
 
-  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 };
-}
+  const readiness_summary = {
+    rules_checked: allRules.length,
+    passed: evidence.filter((e) => e.status === "PASS").length,
+    failed: evidence.filter((e) => e.status === "FAIL").length,
+    skipped: evidence.filter((e) => e.status === "SKIPPED").length,
+    errors: errorCount
+  };
 
-// -----------------------------
-// Recommendations (same idea as before)
-// -----------------------------
-function generateRecommendations(violations) {
-  const actions = [];
-  const fixGroups = {};
+  const runId = `run_${new Date().toISOString().replace(/[:.]/g, "-")}_${crypto.randomUUID().slice(0, 8)}`;
+  const dir = reportsDir(repoPath);
+  await ensureDir(dir);
+
+  const report = {
+    status: readiness_summary.failed > 0 ? "INCOMPLETE" : "COMPLETED",
+    run_id: runId,
+    plan_id: plan.plan_id,
+    scope: plan.scope,
+    scope_description: plan.scope_description,
+    executed_at: new Date().toISOString(),
+    readiness_summary,
+    rule_evidence: evidence,
+    violations
+  };
 
-  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);
-  }
+  const reportJsonPath = path.join(dir, `${runId}.json`);
+  const reportMdPath = path.join(dir, `${runId}.md`);
 
-  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)
-    });
-  }
+  await fs.writeFile(reportJsonPath, JSON.stringify(report, null, 2), "utf8");
+  await fs.writeFile(reportMdPath, buildMarkdownReport({ runId, repoPath, plan, results: report }), "utf8");
 
-  actions.sort((a, b) => a.priority - b.priority);
-  return actions;
-}
+  console.error(`[executeTool] Execution complete. Report saved to: ${reportMdPath}`);
 
-// -----------------------------
-// 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;
+  return {
+    status: report.status,
+    run_id: runId,
+    report_json_path: reportJsonPath,
+    report_md_path: reportMdPath,
+    readiness_summary,
+    violations_count: violations.length,
+    message: `✅ Execution completed!\n\n📊 Results:\n- ${readiness_summary.passed} rules passed\n- ${readiness_summary.failed} rules failed\n- ${readiness_summary.skipped} rules skipped\n- ${violations.length} violations found\n\n📄 Full report saved to:\n- JSON: ${reportJsonPath}\n- Markdown: ${reportMdPath}\n\n${violations.length > 0 ? "⚠️ Next step: Review violations and fix issues, or call 'auto_fix' tool (requires approval)" : "🎉 No violations found!"}`,
+    next_step: violations.length > 0 ? {
+      tool: "auto_fix",
+      parameters: {
+        repoPath: repoPath,
+        runId: runId,
+        mode: "propose"
+      },
+      note: "Auto-fix requires approval code"
+    } : null
+  };
 }
 
-export default executionTool;