@guilhermefsousa/open-spec-kit 0.1.0

package/src/commands/validate.js

@@ -0,0 +1,599 @@
+/**
+ * osk validate — Spec consistency validator
+ *
+ * 32 deterministic rules, 3 output modes (chalk, json, trace).
+ * See docs/plans/validate-turbo-plan.md for rule reference.
+ */
+
+import chalk from 'chalk';
+import ora from 'ora';
+import { readFile, readdir, access } from 'fs/promises';
+import { join, basename } from 'path';
+import { execSync } from 'child_process';
+import {
+  parseSections, findSection, findAllSections,
+  parseTable, extractUniqueMatches, getSectionFullContent,
+} from '../parsers/markdown-sections.js';
+import { parseAndValidateProjects } from '../schemas/projects.schema.js';
+import * as rules from '../schemas/spec.schema.js';
+
+// =============================================================================
+// ARTIFACT PARSERS — transform markdown into structured objects for Zod rules
+// =============================================================================
+
+function parseBrief(content) {
+  const sections = parseSections(content);
+  return {
+    lineCount: content.split('\n').length,
+    hasProblema: !!findSection(sections, /problema|contexto|visão\s*geral|overview|background|objetivo\s+do\s+produto|situação\s*atual|descri[çc][aã]o|identifica[çc][aã]o/i),
+    hasForaDeEscopo: !!findSection(sections, /fora\s+de\s+escopo/i),
+    reqIds: extractUniqueMatches(content, /REQ-\w+/g),
+    rawContent: content,
+  };
+}
+
+function parseScenarios(content) {
+  const sections = parseSections(content);
+  const CT_HEADING_RE = /^CT-(\d{3}-\d{2}):\s*(.+?)(?:\s*\(REQ-(\d{3})\))?$/;
+  const CT_ID_RE = /CT-\d{3}-\d{2}/g;
+  const REQ_REF_RE = /REQ-\d{3}/g;
+
+  const allCtIds = [];
+  const allReqRefs = [];
+  const scenarioList = [];
+  const requirementList = [];
+
+  // REQ sections are ## level
+  const reqSections = findAllSections(sections, /^REQ-\d{3}/);
+
+  for (const reqSection of reqSections) {
+    const reqIdMatch = reqSection.title.match(/REQ-(\d{3})/);
+    const reqId = reqIdMatch ? `REQ-${reqIdMatch[1]}` : reqSection.title;
+
+    const reqScenarios = [];
+
+    for (const child of reqSection.children) {
+      const ctMatch = child.title.match(CT_HEADING_RE);
+      const fullContent = getSectionFullContent(child);
+      const GIVEN_RE = /\b(Given|Dado)\b/i;
+      const WHEN_RE = /\b(When|Quando)\b/i;
+      const THEN_RE = /\b(Then|Ent[aã]o)\b/i;
+
+      const scenario = {
+        id: ctMatch ? `CT-${ctMatch[1]}` : child.title,
+        title: ctMatch ? ctMatch[2].trim() : child.title,
+        reqRef: ctMatch && ctMatch[3] ? `REQ-${ctMatch[3]}` : reqId,
+        hasGiven: GIVEN_RE.test(fullContent),
+        hasWhen: WHEN_RE.test(fullContent),
+        hasThen: THEN_RE.test(fullContent),
+      };
+
+      scenarioList.push(scenario);
+      reqScenarios.push(scenario);
+
+      // Collect IDs
+      const ctIds = extractUniqueMatches(child.title, CT_ID_RE);
+      allCtIds.push(...ctIds);
+      const refs = extractUniqueMatches(child.title, REQ_REF_RE);
+      allReqRefs.push(...refs);
+    }
+
+    requirementList.push({ id: reqId, title: reqSection.title, scenarios: reqScenarios });
+  }
+
+  // Also extract from full content for backwards compat (headings without CT IDs)
+  const globalCtIds = extractUniqueMatches(content, CT_ID_RE);
+  const globalReqRefs = extractUniqueMatches(content, REQ_REF_RE);
+
+  return {
+    requirements: requirementList,
+    scenarios: scenarioList,
+    allCtIds: [...new Set([...allCtIds, ...globalCtIds])],
+    allReqRefs: [...new Set([...allReqRefs, ...globalReqRefs])],
+    rawContent: content,
+  };
+}
+
+function parseContracts(content) {
+  const sections = parseSections(content);
+
+  // Extract endpoint table — look for explicit "Endpoints/Rotas" section first (anchored, avoids matching
+  // the spec title like "# TD-001 — API Contracts" which contains "api" but has no table).
+  // Falls back to detecting individual endpoint sections (## METHOD /path/).
+  const endpointTableSection = findSection(sections, /^(endpoints?|rotas?)\b/i);
+  let endpoints = endpointTableSection ? parseTable(endpointTableSection.content) : [];
+
+  if (endpoints.length === 0) {
+    // Individual endpoint sections: ## GET /api/..., ## POST /api/..., etc.
+    const HTTP_METHOD_RE = /^(GET|POST|PUT|PATCH|DELETE|HEAD|OPTIONS)\s+\//i;
+    const individualSections = findAllSections(sections, HTTP_METHOD_RE);
+    if (individualSections.length > 0) {
+      endpoints = individualSections.map(s => {
+        const parts = s.title.split(/\s+/);
+        return { method: parts[0], metodo: parts[0], route: parts[1] || '', rota: parts[1] || '' };
+      });
+    }
+  }
+
+  if (endpoints.length === 0) {
+    // Prefixed format: ## Endpoint: GET /path or ## Rota: POST /api/...
+    const ENDPOINT_PREFIX_RE = /^(endpoint|rota):\s*(GET|POST|PUT|PATCH|DELETE|HEAD|OPTIONS)\s+\//i;
+    const prefixedSections = findAllSections(sections, ENDPOINT_PREFIX_RE);
+    if (prefixedSections.length > 0) {
+      endpoints = prefixedSections.map(s => {
+        const m = s.title.match(/(GET|POST|PUT|PATCH|DELETE|HEAD|OPTIONS)\s+(\/\S*)/i);
+        return { method: m?.[1] || '', metodo: m?.[1] || '', route: m?.[2] || '', rota: m?.[2] || '' };
+      });
+    }
+  }
+
+  // Extract entities (## Entidade: Name, ## Entity: Name, ## Modelo: Name, ## Tipo: Name, etc.)
+  const entitySections = findAllSections(sections, /^(entidades?|entit(?:y|ies)|modelos?|models?|tipos?|types?)\b/i);
+  const entities = entitySections.map(es => {
+    const fullContent = getSectionFullContent(es);
+    const fields = parseTable(fullContent);
+    return { name: es.title.replace(/^(Entidades?|Entity|Entities|Modelos?|Models?|Tipos?|Types?):?\s*[—-]?\s*/i, '').trim(), fields, fullContent };
+  });
+
+  // Extract events (## Evento: Name or ## Event: Name)
+  const eventSections = findAllSections(sections, /^evento|^event/i);
+  const events = eventSections.map(es => ({
+    name: es.title.replace(/^(Evento|Event):?\s*/i, '').trim(),
+  }));
+
+  // Detect stack-specific sections (## Contratos C#, ## Contratos TypeScript, etc.)
+  const stackSections = findAllSections(sections, /^contratos?\s/i).map(s => s.title);
+
+  // Content for response example checks — code blocks and example sections ONLY
+  // Exclude the endpoint table itself to avoid self-matching route strings
+  const exampleSections = findAllSections(sections, /exemplo|example|payload|response|c#|typescript|java|python|json/i);
+  const examplesContent = exampleSections.length > 0
+    ? exampleSections.map(s => getSectionFullContent(s)).join('\n')
+    : '';
+
+  return {
+    endpoints,
+    entities,
+    events,
+    stackSections,
+    examplesContent,
+    rawContent: content,
+  };
+}
+
+function parseTasks(content) {
+  const headingMatches = content.match(/^##\s+(.+)$/gm) || [];
+  const repoHeadings = headingMatches.map(m => m.replace(/^##\s+/, '').trim());
+  const reqRefs = extractUniqueMatches(content, /REQ-\d{3}/g);
+
+  return { repoHeadings, reqRefs, rawContent: content };
+}
+
+// =============================================================================
+// CROSS-SPEC RULES (25-27)
+// =============================================================================
+
+function crossSpec25_typeDuplication(allContracts) {
+  // Map entity name → list of spec dirs that define it
+  const entityMap = new Map();
+  for (const { specDir, contracts } of allContracts) {
+    for (const entity of contracts.entities) {
+      if (!entityMap.has(entity.name)) entityMap.set(entity.name, []);
+      entityMap.get(entity.name).push(specDir);
+    }
+  }
+
+  const duplicates = [];
+  for (const [name, dirs] of entityMap) {
+    if (dirs.length > 1) {
+      // Check if the SPECIFIC contracts that define this entity reference each other
+      const relevantContracts = allContracts.filter(({ specDir }) => dirs.includes(specDir));
+      const hasReference = relevantContracts.some(({ contracts }) =>
+        /ver contracts\.md da feature/i.test(contracts.rawContent),
+      );
+      if (!hasReference) {
+        duplicates.push(`${name} defined in: ${dirs.join(', ')}`);
+      }
+    }
+  }
+
+  return {
+    rule: 25, pass: duplicates.length === 0, severity: 'WARNING',
+    message: duplicates.length === 0
+      ? `No cross-spec type duplication`
+      : `Type/entity redefinition across specs: ${duplicates.join('; ')}`,
+    ...(duplicates.length > 0 ? { details: duplicates } : {}),
+  };
+}
+
+function crossSpec26_staleness(specPaths) {
+  const stale = [];
+  for (const { specDir, specPath } of specPaths) {
+    const conformancePath = join(specPath, 'conformance-report.json');
+    const contractsPath = join(specPath, 'contracts.md');
+    try {
+      const conformanceStat = execSync(`git log -1 --format=%ct -- "${conformancePath}"`, { encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'] }).trim();
+      const contractsStat = execSync(`git log -1 --format=%ct -- "${contractsPath}"`, { encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'] }).trim();
+
+      if (conformanceStat && contractsStat && parseInt(contractsStat) > parseInt(conformanceStat)) {
+        stale.push(specDir);
+      }
+    } catch {
+      // git not available or files not tracked — skip
+    }
+  }
+
+  return {
+    rule: 26, pass: stale.length === 0, severity: 'WARNING',
+    message: stale.length === 0
+      ? `All conformance reports are fresh`
+      : `Stale conformance reports (contracts changed after last check): ${stale.join(', ')}`,
+    ...(stale.length > 0 ? { details: stale } : {}),
+  };
+}
+
+function crossSpec27_refValidation(allSpecs) {
+  const specNumbers = new Set(allSpecs.map(s => s.specDir.match(/^(\d{3})/)?.[1]).filter(Boolean));
+
+  const errors = [];
+  const collisions = new Map(); // entity name → set of spec dirs
+
+  for (const { specDir, briefContent, contractsContent } of allSpecs) {
+    const combined = (briefContent || '') + '\n' + (contractsContent || '');
+
+    // Check feature references
+    let match;
+    const refRe = /(?:feature|spec|specs\/)\s*(\d{3})/gi;
+    while ((match = refRe.exec(combined)) !== null) {
+      const refNum = match[1];
+      if (refNum !== specDir.match(/^(\d{3})/)?.[1] && !specNumbers.has(refNum)) {
+        errors.push(`${specDir}: references feature ${refNum} which doesn't exist`);
+      }
+    }
+
+    // Check entity references and track collisions
+    const entRefRe = /entidade\s+(\w+)\s+(?:da|de|defined in)\s+(?:feature|spec)?\s*(\d{3})/gi;
+    while ((match = entRefRe.exec(combined)) !== null) {
+      const entityName = match[1];
+      const refNum = match[2];
+
+      if (!collisions.has(entityName)) collisions.set(entityName, new Set());
+      collisions.get(entityName).add(specDir);
+
+      // Validate the referenced spec has that entity
+      const targetSpec = allSpecs.find(s => s.specDir.startsWith(refNum));
+      if (targetSpec && targetSpec.contracts) {
+        const hasEntity = targetSpec.contracts.entities.some(e =>
+          e.name.toLowerCase() === entityName.toLowerCase(),
+        );
+        if (!hasEntity) {
+          errors.push(`${specDir}: references entity "${entityName}" in feature ${refNum}, but it doesn't exist there`);
+        }
+      }
+    }
+  }
+
+  // Generate collision warnings
+  const collisionWarnings = [];
+  for (const [name, dirs] of collisions) {
+    if (dirs.size > 1) {
+      collisionWarnings.push(`Entity "${name}" referenced by: ${[...dirs].join(', ')}`);
+    }
+  }
+
+  const allIssues = [...errors, ...collisionWarnings];
+  return {
+    rule: 27,
+    pass: errors.length === 0,
+    severity: errors.length > 0 ? 'ERROR' : (collisionWarnings.length > 0 ? 'WARNING' : 'ERROR'),
+    message: allIssues.length === 0
+      ? `All cross-spec references are valid`
+      : errors.length > 0
+        ? `Invalid cross-spec references: ${errors.join('; ')}`
+        : `Cross-spec entity collisions detected (not errors, but review): ${collisionWarnings.join('; ')}`,
+    ...(allIssues.length > 0 ? { details: allIssues } : {}),
+  };
+}
+
+// =============================================================================
+// OUTPUT FORMATTERS
+// =============================================================================
+
+function formatChalk(specDir, results) {
+  console.log(chalk.bold(`\n  specs/${specDir}/`));
+  for (const r of results) {
+    const icon = r.pass ? chalk.green('✓') : (r.severity === 'ERROR' ? chalk.red('✗') : chalk.yellow('⚠'));
+    const label = `[${r.rule}]`;
+    console.log(`    ${icon} ${chalk.dim(label)} ${r.message}`);
+  }
+}
+
+function formatTrace(specDir, brief, scenarios) {
+  console.log(chalk.bold(`\n  Traceability: specs/${specDir}/\n`));
+  for (const reqId of brief.reqIds) {
+    const cts = scenarios.scenarios.filter(s => s.reqRef === reqId).map(s => s.id);
+    const icon = cts.length > 0 ? chalk.green('✓') : chalk.red('✗');
+    console.log(`    ${icon} ${reqId} → ${cts.length > 0 ? cts.join(', ') : 'NO SCENARIOS'}`);
+  }
+
+  // Orphan CTs (referencing REQs not in brief)
+  const briefReqSet = new Set(brief.reqIds);
+  const orphanCts = scenarios.scenarios.filter(s => !briefReqSet.has(s.reqRef));
+  if (orphanCts.length > 0) {
+    console.log(chalk.yellow(`\n    Orphan CTs (reference non-existent REQs):`));
+    for (const ct of orphanCts) {
+      console.log(chalk.yellow(`    ⚠ ${ct.id} → ${ct.reqRef} (not in brief)`));
+    }
+  }
+
+  const coverage = brief.reqIds.length > 0
+    ? Math.round((brief.reqIds.filter(r => scenarios.allReqRefs.includes(r)).length / brief.reqIds.length) * 100)
+    : 0;
+  console.log(`\n    Coverage: ${coverage}% (${brief.reqIds.length} REQs)\n`);
+}
+
+// =============================================================================
+// MAIN COMMAND
+// =============================================================================
+
+export async function validateCommand(options = {}) {
+  const isJson = options.json || false;
+  const isTrace = options.trace || false;
+  const specFilter = options.spec || null;
+
+  if (!isJson) {
+    console.log(chalk.bold('\n  open-spec-kit validate\n'));
+  }
+
+  const cwd = process.cwd();
+  const spinner = isJson ? null : ora('Reading configuration...').start();
+
+  try {
+    // --- Read projects.yml ---
+    let preset = 'standard';
+    let repoNames = [];
+    let repoStacks = new Map();
+    try {
+      const projectsRaw = await readFile(join(cwd, 'projects.yml'), 'utf-8');
+      const parsed = parseAndValidateProjects(projectsRaw);
+      preset = parsed.preset;
+      repoNames = parsed.repoNames;
+      repoStacks = parsed.repoStacks;
+    } catch { /* no projects.yml */ }
+
+    // --- Discover specs ---
+    if (spinner) spinner.text = 'Scanning specs...';
+    const specsDir = join(cwd, 'specs');
+    let specDirs;
+    try {
+      const entries = await readdir(specsDir, { withFileTypes: true });
+      specDirs = entries.filter(e => e.isDirectory()).map(e => e.name).sort();
+    } catch {
+      if (spinner) spinner.fail('Directory specs/ not found.');
+      if (isJson) console.log(JSON.stringify({ version: 1, specs: [], summary: { pass: 0, warn: 0, fail: 0 } }));
+      return;
+    }
+
+    if (specFilter) {
+      specDirs = specDirs.filter(d => d.startsWith(specFilter));
+      if (specDirs.length === 0) {
+        if (spinner) spinner.fail(`No spec matching "${specFilter}" found.`);
+        return;
+      }
+    }
+
+    if (specDirs.length === 0) {
+      if (spinner) spinner.info('No specs found in specs/.');
+      return;
+    }
+
+    if (spinner) spinner.succeed(`${specDirs.length} spec(s) found — preset: ${preset}`);
+
+    // --- Global rules (30 only — rule 29 is per-spec) ---
+    const globalResults = [];
+    globalResults.push(rules.rule30_specNumbersUnique(specDirs));
+
+    // --- Per-spec validation ---
+    const allSpecData = [];
+    const allResults = new Map(); // specDir → results[]
+
+    for (const specDir of specDirs) {
+      const specPath = join(specsDir, specDir);
+      const results = [];
+
+      // List existing files
+      const files = await readdir(specPath).catch(() => []);
+      const fileNames = Array.isArray(files) ? (files.map ? files.map(f => typeof f === 'string' ? f : f.name) : []) : [];
+
+      // Rule 29: Directory naming (per-spec)
+      results.push(rules.rule29_specDirNaming(specDir));
+
+      // Rule 1: Required files
+      results.push(rules.rule01_requiredFiles(fileNames, preset));
+
+      // Read artifacts
+      const readSafe = async (name) => {
+        try { return await readFile(join(specPath, name), 'utf-8'); } catch { return null; }
+      };
+
+      const briefRaw = await readSafe('brief.md');
+      const scenariosRaw = await readSafe('scenarios.md');
+      const contractsRaw = await readSafe('contracts.md');
+      const tasksRaw = await readSafe('tasks.md');
+      const linksRaw = await readSafe('links.md');
+      const auditRaw = await readSafe('audit-report.md');
+
+      // Parse artifacts
+      const brief = briefRaw ? parseBrief(briefRaw) : null;
+      const scenarios = scenariosRaw ? parseScenarios(scenariosRaw) : null;
+      const contracts = contractsRaw ? parseContracts(contractsRaw) : null;
+      const tasks = tasksRaw ? parseTasks(tasksRaw) : null;
+
+      // Enrich brief with REQs from scenarios (union) — covers specs where brief doesn't list REQs
+      if (brief && scenarios) {
+        brief.reqIds = [...new Set([...brief.reqIds, ...scenarios.allReqRefs])];
+      }
+
+      // Rules 2-6: Brief
+      if (brief) {
+        results.push(rules.rule02_briefMaxLines(brief));
+        results.push(rules.rule03_briefHasProblema(brief));
+        results.push(rules.rule04_briefHasForaDeEscopo(brief));
+        results.push(rules.rule05_reqIdFormat(brief));
+        results.push(rules.rule06_noDuplicateReqIds(brief));
+      }
+
+      // Rule 7: CT IDs
+      if (scenarios) {
+        results.push(rules.rule07_ctIdFormat(scenarios));
+      }
+
+      // Rules 8-11: Traceability
+      if (brief && scenarios) {
+        results.push(rules.rule08_everyReqHasCt(brief, scenarios));
+        results.push(rules.rule09_everyCtRefsValidReq(brief, scenarios));
+      }
+      if (tasks && scenarios) {
+        results.push(rules.rule10_everyTaskReqHasCt(tasks, scenarios));
+        results.push(rules.rule11_everyCtHasTask(scenarios, tasks));
+      }
+
+      // Rules 12-15: Scenarios
+      if (scenarios) {
+        results.push(rules.rule12_scenarioHasGiven(scenarios));
+        results.push(rules.rule13_scenarioHasWhen(scenarios));
+        results.push(rules.rule14_scenarioHasThen(scenarios));
+        results.push(rules.rule15_minOneScenarioPerReq(scenarios));
+      }
+
+      // Rules 16-20: Contracts
+      if (contracts) {
+        results.push(rules.rule16_contractsHasContent(contracts));
+        const uniqueStacks = [...new Set(repoNames.map(r => repoStacks.get(r)).filter(Boolean))];
+        results.push(rules.rule17_multiStackContracts(contracts, uniqueStacks));
+        results.push(rules.rule18_entityHasTimestamps(contracts));
+        results.push(rules.rule19_auth401Scenario(contracts, scenariosRaw || ''));
+        results.push(rules.rule20_paginationScenarios(contractsRaw || '', scenariosRaw || '', contracts));
+      }
+
+      // Rules 21-24: Tasks & Links
+      if (tasks) {
+        results.push(rules.rule21_taskReposMatchProjects(tasks, repoNames));
+      }
+      results.push(rules.rule22_auditReportClean(auditRaw));
+      if (linksRaw) {
+        results.push(rules.rule23_linksHasUrl(linksRaw));
+        results.push(rules.rule24_linksPrTableHeaders(linksRaw));
+      }
+
+      // Rule 28: Unresolved markers
+      const markerContents = [briefRaw, scenariosRaw, contractsRaw].filter(Boolean);
+      if (markerContents.length > 0) {
+        results.push(rules.rule28_noUnresolvedMarkers(markerContents));
+      }
+
+      // Rule 31: Endpoint response examples
+      if (contracts) {
+        results.push(rules.rule31_endpointsHaveResponseExample(contracts));
+      }
+
+      // Rule 32: Duplicate scenario headings
+      if (scenarios) {
+        results.push(rules.rule32_noDuplicateScenarioHeadings(scenarios));
+      }
+
+      allResults.set(specDir, results);
+
+      // Store for cross-spec checks
+      allSpecData.push({
+        specDir,
+        specPath,
+        contracts,
+        briefContent: briefRaw,
+        contractsContent: contractsRaw,
+      });
+
+      // Output per-spec results
+      if (!isJson) {
+        if (isTrace && brief && scenarios) {
+          formatTrace(specDir, brief, scenarios);
+        }
+        formatChalk(specDir, results);
+      }
+    }
+
+    // --- Cross-spec rules (25-27) ---
+    const crossSpecResults = [];
+    if (allSpecData.length > 1) {
+      const contractData = allSpecData.filter(s => s.contracts).map(s => ({
+        specDir: s.specDir,
+        contracts: s.contracts,
+      }));
+      if (contractData.length > 1) {
+        crossSpecResults.push(crossSpec25_typeDuplication(contractData));
+      }
+      crossSpecResults.push(crossSpec26_staleness(allSpecData));
+      crossSpecResults.push(crossSpec27_refValidation(allSpecData));
+    }
+
+    // Rule 33: open decisions in architecture.md
+    let architectureContent = null;
+    try {
+      architectureContent = await readFile(join(cwd, 'docs', 'architecture.md'), 'utf-8');
+    } catch { /* file not found — ok */ }
+    const rule33Result = rules.rule33_openDecisions(architectureContent);
+    crossSpecResults.push(rule33Result);
+
+    if (!isJson && crossSpecResults.length > 0) {
+      console.log(chalk.bold('\n  Cross-spec checks'));
+      for (const r of crossSpecResults) {
+        const icon = r.pass ? chalk.green('✓') : (r.severity === 'ERROR' ? chalk.red('✗') : chalk.yellow('⚠'));
+        console.log(`    ${icon} [${r.rule}] ${r.message}`);
+      }
+    }
+
+    // Global results (rule 30 only — rule 29 is per-spec)
+    if (!isJson && globalResults.length > 0) {
+      console.log(chalk.bold('\n  Directory checks'));
+      for (const r of globalResults) {
+        const icon = r.pass ? chalk.green('✓') : (r.severity === 'ERROR' ? chalk.red('✗') : chalk.yellow('⚠'));
+        console.log(`    ${icon} [${r.rule}] ${r.message}`);
+      }
+    }
+
+    // --- Summary ---
+    const allRuleResults = [
+      ...globalResults,
+      ...[...allResults.values()].flat(),
+      ...crossSpecResults,
+    ];
+
+    const totalPass = allRuleResults.filter(r => r.pass).length;
+    const totalWarn = allRuleResults.filter(r => !r.pass && r.severity === 'WARNING').length;
+    const totalFail = allRuleResults.filter(r => !r.pass && r.severity === 'ERROR').length;
+
+    if (isJson) {
+      const output = {
+        version: 1,
+        specs: [...allResults.entries()].map(([dir, res]) => ({ spec: dir, rules: res })),
+        crossSpec: crossSpecResults,
+        global: globalResults,
+        summary: { pass: totalPass, warn: totalWarn, fail: totalFail, total: allRuleResults.length },
+      };
+      console.log(JSON.stringify(output, null, 2));
+    } else {
+      console.log(chalk.bold('\n  Summary:\n'));
+      console.log(`    ${chalk.green('✓')} ${totalPass} passed`);
+      if (totalWarn > 0) console.log(`    ${chalk.yellow('⚠')} ${totalWarn} warnings`);
+      if (totalFail > 0) console.log(`    ${chalk.red('✗')} ${totalFail} failed`);
+      console.log(`    Total: ${allRuleResults.length} checks\n`);
+    }
+
+    if (totalFail > 0) process.exit(1);
+
+  } catch (err) {
+    if (spinner) spinner.fail(`Error: ${err.message}`);
+    if (isJson) console.log(JSON.stringify({ version: 1, error: err.message }));
+    process.exit(1);
+  }
+}