Merge pull request #23 from mvanhorn/feat/5-verbose-flag

feat: add --verbose flag to mex check

Author: theDakshJaitly

src/cli.ts

@@ -1,7 +1,7 @@
 import chalk from "chalk";
 import { Command } from "commander";
 import { findConfig } from "./config.js";
-import { reportConsole, reportQuiet, reportJSON } from "./reporter.js";
+import { reportConsole, reportQuiet, reportJSON, reportVerbose } from "./reporter.js";
 
 const program = new Command();
 
@@ -32,17 +32,19 @@ program
   .option("--json", "Output full drift report as JSON")
   .option("--quiet", "Single-line summary only")
   .option("--fix", "Run sync to fix any issues found")
+  .option("--verbose", "Show detailed diagnostic output")
   .action(async (opts) => {
     try {
       const config = findConfig();
       const { runDriftCheck } = await import("./drift/index.js");
-      const report = await runDriftCheck(config);
+      const report = await runDriftCheck(config, { verbose: opts.verbose });
 
       if (opts.json) {
-        reportJSON(report);
+        reportJSON(report, { verbose: opts.verbose });
       } else if (opts.quiet) {
         reportQuiet(report);
       } else {
+        if (opts.verbose) reportVerbose(report);
         reportConsole(report);
       }
 

src/drift/index.ts

@@ -15,13 +15,17 @@ import { checkCrossFile } from "./checkers/cross-file.js";
 import { checkScriptCoverage } from "./checkers/script-coverage.js";
 
 /** Run full drift detection across all scaffold files */
-export async function runDriftCheck(config: MexConfig): Promise<DriftReport> {
+export async function runDriftCheck(
+  config: MexConfig,
+  opts: { verbose?: boolean } = {}
+): Promise<DriftReport> {
   const { projectRoot, scaffoldRoot } = config;
 
   // Find all markdown files in scaffold
   const scaffoldFiles = findScaffoldFiles(projectRoot, scaffoldRoot);
   const allClaims: Claim[] = [];
   const allIssues: DriftIssue[] = [];
+  const checkerIssueCounts: Array<[string, number]> = [];
 
   // Extract claims from all files
   for (const filePath of scaffoldFiles) {
@@ -36,34 +40,55 @@ export async function runDriftCheck(config: MexConfig): Promise<DriftReport> {
 
     // Frontmatter edge check
     const frontmatter = parseFrontmatter(filePath);
-    allIssues.push(
-      ...checkEdges(frontmatter, filePath, source, projectRoot, scaffoldRoot)
-    );
+    const edgeIssues = checkEdges(frontmatter, filePath, source, projectRoot, scaffoldRoot);
+    allIssues.push(...edgeIssues);
 
     // Staleness check
     const stalenessIssues = await checkStaleness(source, source, projectRoot);
     allIssues.push(...stalenessIssues);
+
+    checkerIssueCounts.push([`edges:${source}`, edgeIssues.length]);
+    checkerIssueCounts.push([`staleness:${source}`, stalenessIssues.length]);
   }
 
   // Run checkers that work on claims
-  allIssues.push(...checkPaths(allClaims, projectRoot, scaffoldRoot));
-  allIssues.push(...checkCommands(allClaims, projectRoot));
-  allIssues.push(...checkDependencies(allClaims, projectRoot));
-  allIssues.push(...checkCrossFile(allClaims));
+  const pathIssues = checkPaths(allClaims, projectRoot, scaffoldRoot);
+  allIssues.push(...pathIssues);
+  checkerIssueCounts.push(["paths", pathIssues.length]);
+
+  const commandIssues = checkCommands(allClaims, projectRoot);
+  allIssues.push(...commandIssues);
+  checkerIssueCounts.push(["commands", commandIssues.length]);
+
+  const dependencyIssues = checkDependencies(allClaims, projectRoot);
+  allIssues.push(...dependencyIssues);
+  checkerIssueCounts.push(["dependencies", dependencyIssues.length]);
+
+  const crossFileIssues = checkCrossFile(allClaims);
+  allIssues.push(...crossFileIssues);
+  checkerIssueCounts.push(["cross-file", crossFileIssues.length]);
 
   // Run structural checkers
-  allIssues.push(...checkIndexSync(projectRoot, scaffoldRoot));
+  const indexSyncIssues = checkIndexSync(projectRoot, scaffoldRoot);
+  allIssues.push(...indexSyncIssues);
+  checkerIssueCounts.push(["index-sync", indexSyncIssues.length]);
 
   // Run coverage checkers (reality → scaffold direction)
-  allIssues.push(...checkScriptCoverage(scaffoldFiles, projectRoot));
+  const scriptCoverageIssues = checkScriptCoverage(scaffoldFiles, projectRoot);
+  allIssues.push(...scriptCoverageIssues);
+  checkerIssueCounts.push(["script-coverage", scriptCoverageIssues.length]);
 
   const score = computeScore(allIssues);
+  const verboseLog = opts.verbose
+    ? buildVerboseLog(scaffoldFiles.length, allClaims, checkerIssueCounts)
+    : undefined;
 
   return {
     score,
     issues: allIssues,
     filesChecked: scaffoldFiles.length,
     timestamp: new Date().toISOString(),
+    verboseLog,
   };
 }
 
@@ -108,3 +133,21 @@ function findScaffoldFiles(
   // Deduplicate
   return [...new Set(files)];
 }
+
+export function buildVerboseLog(
+  filesScanned: number,
+  claims: Claim[],
+  checkerIssueCounts: Array<[string, number]>
+): string[] {
+  const pathClaims = claims.filter((claim) => claim.kind === "path").length;
+  const commandClaims = claims.filter((claim) => claim.kind === "command").length;
+  const dependencyClaims = claims.filter((claim) => claim.kind === "dependency").length;
+
+  return [
+    `Scaffold files scanned: ${filesScanned}`,
+    `Claims extracted: ${claims.length} (path: ${pathClaims}, command: ${commandClaims}, dependency: ${dependencyClaims})`,
+    ...checkerIssueCounts.map(
+      ([checker, count]) => `Checker ${checker}: ${count} issue${count === 1 ? "" : "s"}`
+    ),
+  ];
+}

src/reporter.ts

@@ -56,8 +56,18 @@ export function reportQuiet(report: DriftReport): void {
   console.log(`mex: drift score ${color(`${report.score}/100`)}${detail}`);
 }
 
-export function reportJSON(report: DriftReport): void {
-  console.log(JSON.stringify(report, null, 2));
+export function reportJSON(report: DriftReport, opts?: { verbose?: boolean }): void {
+  const output = opts?.verbose ? report : { ...report, verboseLog: undefined };
+  console.log(JSON.stringify(output, null, 2));
+}
+
+export function reportVerbose(report: DriftReport): void {
+  if (!report.verboseLog?.length) return;
+  console.log(chalk.dim("── Verbose ──"));
+  for (const line of report.verboseLog) {
+    console.log(chalk.dim(`  ${line}`));
+  }
+  console.log();
 }
 
 function printSummary(report: DriftReport): void {

src/types.ts

@@ -57,6 +57,7 @@ export interface DriftReport {
   issues: DriftIssue[];
   filesChecked: number;
   timestamp: string;
+  verboseLog?: string[];
 }
 
 // ── Frontmatter ──

test/verbose.test.ts

@@ -0,0 +1,80 @@
+import { describe, it, expect, vi } from "vitest";
+import { buildVerboseLog } from "../src/drift/index.js";
+import { reportJSON } from "../src/reporter.js";
+import type { Claim, DriftReport } from "../src/types.js";
+
+function makeClaim(kind: Claim["kind"]): Claim {
+  return {
+    kind,
+    value: "test-value",
+    file: "test.md",
+    line: 1,
+    raw: "test raw",
+  };
+}
+
+function makeReport(opts?: { verboseLog?: string[] }): DriftReport {
+  return {
+    score: 85,
+    issues: [],
+    filesChecked: 3,
+    timestamp: "2026-04-10T00:00:00.000Z",
+    verboseLog: opts?.verboseLog,
+  };
+}
+
+describe("buildVerboseLog", () => {
+  it("returns file count and claim breakdown", () => {
+    const claims: Claim[] = [
+      makeClaim("path"),
+      makeClaim("path"),
+      makeClaim("command"),
+      makeClaim("dependency"),
+    ];
+    const checkerCounts: Array<[string, number]> = [
+      ["path", 1],
+      ["edges", 0],
+    ];
+
+    const log = buildVerboseLog(5, claims, checkerCounts);
+
+    expect(log[0]).toBe("Scaffold files scanned: 5");
+    expect(log[1]).toContain("Claims extracted: 4");
+    expect(log[1]).toContain("path: 2");
+    expect(log[1]).toContain("command: 1");
+    expect(log[1]).toContain("dependency: 1");
+    expect(log[2]).toBe("Checker path: 1 issue");
+    expect(log[3]).toBe("Checker edges: 0 issues");
+  });
+
+  it("handles empty claims and checkers", () => {
+    const log = buildVerboseLog(0, [], []);
+    expect(log).toHaveLength(2);
+    expect(log[0]).toBe("Scaffold files scanned: 0");
+    expect(log[1]).toContain("Claims extracted: 0");
+  });
+});
+
+describe("reportJSON verbose gating", () => {
+  it("excludes verboseLog from JSON when verbose is off", () => {
+    const report = makeReport({ verboseLog: ["line1", "line2"] });
+    const spy = vi.spyOn(console, "log").mockImplementation(() => {});
+
+    reportJSON(report);
+
+    const output = JSON.parse(spy.mock.calls[0][0]);
+    expect(output.verboseLog).toBeUndefined();
+    spy.mockRestore();
+  });
+
+  it("includes verboseLog in JSON when verbose is on", () => {
+    const report = makeReport({ verboseLog: ["line1", "line2"] });
+    const spy = vi.spyOn(console, "log").mockImplementation(() => {});
+
+    reportJSON(report, { verbose: true });
+
+    const output = JSON.parse(spy.mock.calls[0][0]);
+    expect(output.verboseLog).toEqual(["line1", "line2"]);
+    spy.mockRestore();
+  });
+});