speclock 5.5.5 → 5.5.7

package/package.json

@@ -2,7 +2,7 @@
 
   "name": "speclock",
 
-  "version": "5.5.5",
+  "version": "5.5.7",
 
   "mcpName": "io.github.sgroy10/speclock",
 

package/src/cli/index.js

@@ -1,7 +1,7 @@
 import fs from "fs";
 import path from "path";
 import { fileURLToPath } from "url";
-import { getStagedDiff, parseDiff } from "../core/pre-commit-semantic.js";
+import { getStagedDiff, parseDiff, shouldSkipForSemanticAudit } from "../core/pre-commit-semantic.js";
 import {
   ensureInit,
   setGoal,
@@ -68,6 +68,7 @@ import {
   ensureTelemetryDecision,
   recordCommand,
   TELEMETRY_DEFAULT_ENDPOINT,
+  buildUsageStats,
 } from "../core/telemetry.js";
 import {
   isSSOEnabled,
@@ -286,7 +287,7 @@ export function initFromRulePack(root, framework) {
 
 function printHelp() {
   console.log(`
-SpecLock v5.5.5 — Your AI has rules. SpecLock makes them unbreakable.
+SpecLock v5.5.7 — Your AI has rules. SpecLock makes them unbreakable.
 Developed by Sandeep Roy (github.com/sgroy10)
 
 Usage: speclock <command> [options]
@@ -340,6 +341,7 @@ Commands:
   watch                           Start file watcher (live dashboard)
   serve [--project <path>]        Start MCP stdio server
   status                          Show project brain summary
+  stats                           Show YOUR usage dashboard from local telemetry log
   doctor                          Diagnostic health check (install, git, rules, MCP)
 
 Options:
@@ -442,6 +444,152 @@ function showStatus(root) {
   console.log("");
 }
 
+// --- Stats dashboard (speclock stats) ---
+
+/**
+ * Build a self-contained view-model for the `speclock stats` dashboard.
+ * Pure data — no console I/O — so tests can assert against it.
+ *
+ * Combines three sources:
+ *   1. Local telemetry log (~/.speclock/telemetry.jsonl) via buildUsageStats
+ *   2. Current project brain.json (enforcement mode, lock count)
+ *   3. Rule file discovery + MCP client detection (from a sample telemetry event)
+ *
+ * Falls back gracefully when telemetry is disabled or the log is missing —
+ * the "Current State" section is still populated from brain.json.
+ *
+ * @param {string} root - project root
+ * @param {object} [opts] - passed through to buildUsageStats (e.g. { events, now })
+ */
+export function buildStatsView(root, opts = {}) {
+  const usage = buildUsageStats(opts);
+
+  let lockCount = 0;
+  let enforcementMode = "unknown";
+  let brainExists = false;
+  try {
+    const brain = readBrain(root);
+    if (brain) {
+      brainExists = true;
+      const items = brain.specLock && Array.isArray(brain.specLock.items)
+        ? brain.specLock.items
+        : [];
+      lockCount = items.filter((l) => l && l.active !== false).length;
+      const cfg = getEnforcementConfig(brain);
+      // Map internal ("advisory" | "hard") to user-facing ("warn" | "hard").
+      enforcementMode = cfg.mode === "hard" ? "hard" : "warn";
+    }
+  } catch (_) { /* swallow */ }
+
+  // Rule files (from the same list guardian.js uses).
+  let ruleFiles = [];
+  try {
+    const discovered = discoverRuleFiles(root);
+    ruleFiles = discovered.map((f) => f.file);
+  } catch (_) { /* swallow */ }
+
+  // MCP clients — reuse the detector embedded in the sample telemetry event.
+  let mcpClients = [];
+  try {
+    const sample = getOptInTelemetryStatus({ eventLimit: 0 }).sampleEvent;
+    if (sample && Array.isArray(sample.mcpClientsConfigured)) {
+      mcpClients = sample.mcpClientsConfigured;
+    }
+  } catch (_) { /* swallow */ }
+
+  return {
+    ...usage,
+    brainExists,
+    enforcementMode,
+    lockCount,
+    ruleFiles,
+    mcpClients,
+  };
+}
+
+/**
+ * Render the stats view-model as a human-readable dashboard string.
+ * Kept separate from console output so tests can assert on the rendered
+ * text without capturing stdout.
+ */
+export function formatStatsDashboard(view) {
+  const lines = [];
+  const firstInstallDate = view.firstInstallIso
+    ? view.firstInstallIso.slice(0, 10)
+    : "(unknown)";
+  const installIdShort = view.installId && view.installId !== "unknown"
+    ? view.installId.slice(0, 8) + "..."
+    : "(none)";
+
+  lines.push("");
+  lines.push("SpecLock Stats — Your Usage");
+  lines.push("=".repeat(32));
+  lines.push("");
+  lines.push("Installation");
+  lines.push(`  First install:   ${firstInstallDate}`);
+  lines.push(`  Days active:     ${view.daysActive}`);
+  lines.push(`  Total events:    ${view.totalEvents}`);
+  lines.push(`  Install ID:      ${installIdShort}`);
+  lines.push("");
+
+  lines.push("Commands Used");
+  const entries = Object.entries(view.commandsByType).sort(
+    ([, a], [, b]) => b - a
+  );
+  if (entries.length === 0) {
+    if (view.telemetryEnabled) {
+      lines.push("  (no events recorded yet — run some commands!)");
+    } else {
+      lines.push("  (telemetry disabled — enable with 'speclock telemetry on' to track usage)");
+    }
+  } else {
+    const maxName = Math.max(...entries.map(([n]) => n.length));
+    for (const [name, count] of entries) {
+      lines.push(`  ${(name + ":").padEnd(maxName + 2)}${count}`);
+    }
+  }
+  lines.push("");
+
+  lines.push("Current State");
+  lines.push(`  Enforcement:  ${view.enforcementMode}`);
+  lines.push(`  Locks:        ${view.lockCount}`);
+  if (view.ruleFiles.length > 0) {
+    lines.push(`  Rule files:   ${view.ruleFiles.length} (${view.ruleFiles.join(", ")})`);
+  } else {
+    lines.push("  Rule files:   0");
+  }
+  if (view.mcpClients.length > 0) {
+    lines.push(`  MCP clients:  ${view.mcpClients.join(", ")}`);
+  } else {
+    lines.push("  MCP clients:  (none detected)");
+  }
+  lines.push("");
+
+  lines.push(`Recent Activity (last ${view.recentEvents.length})`);
+  if (view.recentEvents.length === 0) {
+    lines.push("  (no activity recorded)");
+  } else {
+    // Most recent first in the dashboard.
+    const sorted = view.recentEvents.slice().reverse();
+    for (const e of sorted) {
+      const ts = (e.timestamp || "").replace("T", " ").slice(0, 16);
+      const cmd = (e.command || "unknown").padEnd(10);
+      const exit = typeof e.exitCode === "number" ? e.exitCode : "?";
+      lines.push(`  ${ts}  ${cmd}  exit ${exit}`);
+    }
+  }
+  lines.push("");
+
+  if (!view.telemetryEnabled) {
+    lines.push("Note: telemetry is DISABLED — stats above reflect any pre-existing log");
+    lines.push("      plus the current project state from .speclock/brain.json.");
+  }
+  lines.push("Tip: Run 'speclock telemetry status' to see telemetry settings");
+  lines.push("");
+
+  return lines.join("\n");
+}
+
 // --- Main ---
 
 async function main() {
@@ -491,9 +639,16 @@ async function main() {
     console.log(`Created SPECLOCK.md (AI instructions file).`);
 
     // 4. Inject marker into package.json (so AI tools auto-discover SpecLock)
-    const pkgResult = injectPackageJsonMarker(root);
-    if (pkgResult.success) {
-      console.log("Injected SpecLock marker into package.json.");
+    //    — only when package.json actually exists. We do NOT create one.
+    const pkgJsonPath = path.join(root, "package.json");
+    const pkgJsonExistedBefore = fs.existsSync(pkgJsonPath);
+    let pkgJsonUpdated = false;
+    if (pkgJsonExistedBefore) {
+      const pkgResult = injectPackageJsonMarker(root);
+      if (pkgResult.success) {
+        pkgJsonUpdated = true;
+        console.log("Injected SpecLock marker into package.json.");
+      }
     }
 
     // 5. Apply template if specified
@@ -511,6 +666,9 @@ async function main() {
     console.log("Generated .speclock/context/latest.md");
 
     // 7. Print summary
+    const pkgJsonLine = pkgJsonUpdated
+      ? "  package.json                  — Active locks embedded (AI auto-discovery)"
+      : "  package.json (skipped — not found)";
     console.log(`
 SpecLock is ready!
 
@@ -518,7 +676,7 @@ Files created/updated:
   .speclock/brain.json          — Project memory
   .speclock/context/latest.md   — Context for AI (read this)
   SPECLOCK.md                   — AI rules (read this)
-  package.json                  — Active locks embedded (AI auto-discovery)
+${pkgJsonLine}
 
 Next steps:
   To add constraints:  npx speclock lock "Never touch auth files"
@@ -1243,6 +1401,10 @@ Tip: Run "speclock sync --all" to push constraints to Cursor, Claude, Copilot, W
   // --- AUDIT-SEMANTIC (v2.5) ---
   if (cmd === "audit-semantic") {
     const flags = parseFlags(args);
+    const verbose =
+      flags.verbose === true ||
+      process.env.SPECLOCK_VERBOSE === "1" ||
+      process.env.SPECLOCK_VERBOSE === "true";
     const result = semanticAudit(root);
 
     // --- Commit-message + diff-content semantic check ---
@@ -1269,9 +1431,15 @@ Tip: Run "speclock sync --all" to push constraints to Cursor, Claude, Copilot, W
         } catch { /* ignore */ }
       }
 
-      // 2. Collect added lines from the staged diff.
+      // 2. Collect added lines from the staged diff, skipping SpecLock-internal
+      //    files (see shouldSkipForSemanticAudit). Those files' contents literally
+      //    restate the locks, so scanning their added lines produces 100%
+      //    false-positive matches for every lock in the brain.
       const diffText = getStagedDiff(root);
-      const fileChanges = diffText ? parseDiff(diffText) : [];
+      const allParsedChanges = diffText ? parseDiff(diffText) : [];
+      const fileChanges = allParsedChanges.filter(
+        (fc) => !shouldSkipForSemanticAudit(fc.file, root)
+      );
       const addedSnippets = [];
       for (const fc of fileChanges) {
         for (const line of fc.addedLines) {
@@ -1345,24 +1513,85 @@ Tip: Run "speclock sync --all" to push constraints to Cursor, Claude, Copilot, W
         : `WARNING: ${result.violations.length} violation(s) detected. Review before proceeding.`;
     }
 
-    // Warn mode default: only exit 1 if --strict, SPECLOCK_STRICT=1, or brain is in "hard" mode
-    // (result.blocked already reflects "hard" mode from brain config).
-    const strict =
-      flags.strict === true ||
-      flags.block === true ||
+    // Warn mode default: only exit 1 if --strict, SPECLOCK_STRICT=1, or brain is in "hard" mode.
+    //
+    // Enforcement mode precedence (first match wins):
+    //   1. --strict / --block CLI flag
+    //   2. SPECLOCK_STRICT=1 env var
+    //   3. brain.enforcement.mode === "hard" from .speclock/brain.json
+    //   4. Default: warn mode (exit 0)
+    //
+    // We re-read brain.json here as a belt-and-braces fallback because
+    // semanticAudit() may early-return (no staged diff, no locks, brain
+    // missing) WITHOUT setting result.mode/result.blocked, and git hooks
+    // can run in sanitized environments where SPECLOCK_STRICT=1 on the
+    // `git commit` command line gets stripped by some shells. The
+    // persistent brain mode (set by `speclock enforce hard`) is the only
+    // reliable way to enforce hard blocking across all git/shell combos.
+    const cliStrict = flags.strict === true || flags.block === true;
+    const envStrict =
       process.env.SPECLOCK_STRICT === "1" ||
-      process.env.SPECLOCK_STRICT === "true" ||
-      result.blocked;
+      process.env.SPECLOCK_STRICT === "true";
+
+    let brainHardMode = false;
+    try {
+      const brainForMode = readBrain(root);
+      if (brainForMode) {
+        const cfg = getEnforcementConfig(brainForMode);
+        brainHardMode = cfg.mode === "hard";
+      }
+    } catch { /* brain unreadable — treat as advisory */ }
+
+    // If brain is in hard mode but semanticAudit() returned without
+    // reflecting that (early-return path), retro-fit the result so the
+    // downstream printing + blocking decision stays consistent.
+    if (brainHardMode && result.mode !== "hard") {
+      result.mode = "hard";
+      if (result.threshold === undefined) result.threshold = 70;
+    }
+    if (brainHardMode && !result.blocked) {
+      const thresh = result.threshold || 70;
+      result.blocked = (result.violations || []).some(
+        (v) => (v.confidence || 0) >= thresh
+      );
+    }
+
+    const strict = cliStrict || envStrict || brainHardMode || result.blocked;
+
+    // --- Three-tier output filter (v5.5.7) ---
+    // Investor audit: walls of LOW-confidence matches are user-hostile.
+    // Only HIGH and MEDIUM print by default. LOW rolls up into a one-liner.
+    // --verbose / SPECLOCK_VERBOSE=1 shows everything.
+    const OUTPUT_MIN_CONFIDENCE = 40;  // below this = "LOW", hidden by default
+    const MAX_VISIBLE_VIOLATIONS = 10; // hard cap on printed items
+
+    const allViolations = result.violations || [];
+    const highViolations = allViolations.filter((v) => (v.confidence || 0) >= 70);
+    const mediumViolations = allViolations.filter(
+      (v) => (v.confidence || 0) >= OUTPUT_MIN_CONFIDENCE && (v.confidence || 0) < 70
+    );
+    const lowViolations = allViolations.filter(
+      (v) => (v.confidence || 0) < OUTPUT_MIN_CONFIDENCE
+    );
+
+    // What actually gets printed
+    const visibleViolations = verbose
+      ? allViolations
+      : [...highViolations, ...mediumViolations];
 
     console.log(`\nSemantic Pre-Commit Audit`);
     console.log("=".repeat(50));
     console.log(`Mode: ${result.mode} | Threshold: ${result.threshold}%`);
-    console.log(`Files analyzed: ${result.filesChecked}`);
+    const filesLine = result.filesSkipped
+      ? `Files analyzed: ${result.filesChecked} (${result.filesSkipped} skipped)`
+      : `Files analyzed: ${result.filesChecked}`;
+    console.log(filesLine);
     console.log(`Active locks: ${result.activeLocks}`);
-    console.log(`Violations: ${result.violations.length}`);
-    if (result.violations.length > 0) {
+
+    if (visibleViolations.length > 0) {
       console.log("");
-      for (const v of result.violations) {
+      const toPrint = visibleViolations.slice(0, MAX_VISIBLE_VIOLATIONS);
+      for (const v of toPrint) {
         console.log(`  [${v.level}] ${v.file} (confidence: ${v.confidence}%)`);
         console.log(`    Lock: "${v.lockText}"`);
         console.log(`    Reason: ${v.reason}`);
@@ -1370,17 +1599,48 @@ Tip: Run "speclock sync --all" to push constraints to Cursor, Claude, Copilot, W
           console.log(`    Changes: +${v.addedLines} / -${v.removedLines} lines`);
         }
       }
+      const hiddenByCap = visibleViolations.length - toPrint.length;
+      if (hiddenByCap > 0) {
+        console.log(`  ... + ${hiddenByCap} more (output capped at ${MAX_VISIBLE_VIOLATIONS})`);
+      }
+    }
+
+    // LOW-confidence rollup
+    if (!verbose && lowViolations.length > 0) {
+      console.log(
+        `  + ${lowViolations.length} low-confidence match(es) hidden (use --verbose or SPECLOCK_VERBOSE=1 to see)`
+      );
+    }
+
+    // --- New summary line ---
+    console.log("");
+    let summaryLine;
+    if (highViolations.length === 0 && mediumViolations.length === 0) {
+      summaryLine = `[OK] ${result.filesChecked} file(s) checked, no concerns.`;
+    } else if (highViolations.length > 0) {
+      summaryLine = `[!] ${highViolations.length} HIGH-confidence concern(s) — review before merging.`;
+    } else {
+      summaryLine = `[i] ${mediumViolations.length} medium-confidence note(s) (informational).`;
+    }
+    console.log(summaryLine);
+
+    // Preserve the machine-readable status message for any callers that grep for it
+    if (result.blocked) {
+      console.log(
+        `BLOCKED: ${highViolations.length} high-confidence violation(s) — hard enforcement active.`
+      );
     }
-    console.log(`\n${result.message}`);
 
-    if (result.violations.length > 0 && !strict) {
+    if (highViolations.length > 0 && !strict) {
       console.log("\nWarning mode active — commit allowed. To enforce hard blocks, run:");
       console.log("  speclock audit-semantic --strict");
       console.log("  SPECLOCK_STRICT=1 git commit ...");
       console.log("  speclock enforce hard   (persistent, project-wide)");
     }
 
-    process.exit(strict && result.violations.length > 0 ? 1 : 0);
+    // Blocking decision is still driven by the engine's 70% threshold, so
+    // only HIGH-confidence matches can ever cause a non-zero exit.
+    process.exit(strict && highViolations.length > 0 ? 1 : 0);
   }
 
   // --- AUTH (v3.0) ---
@@ -1563,6 +1823,18 @@ Tip: Run "speclock sync --all" to push constraints to Cursor, Claude, Copilot, W
     process.exit(1);
   }
 
+  // --- STATS (user-facing usage dashboard) ---
+  if (cmd === "stats") {
+    try {
+      const view = buildStatsView(root);
+      console.log(formatStatsDashboard(view));
+    } catch (err) {
+      console.error(`Failed to build stats: ${err.message}`);
+      process.exit(1);
+    }
+    return;
+  }
+
   // --- TELEMETRY (opt-in, v5.5) ---
   if (cmd === "telemetry") {
     const sub = args[0];
@@ -1987,21 +2259,79 @@ Tip: Run "speclock sync --all" to push constraints to Cursor, Claude, Copilot, W
     lines.push("");
 
     // --- 3. Rule Files ---
+    // Doctor checks both:
+    //   (a) ORIGINAL rule files (.cursorrules, CLAUDE.md, etc.) that users author
+    //   (b) SYNCED files written by `speclock protect` / `speclock sync`
+    //       (.cursor/rules/speclock.mdc, .windsurf/rules/speclock.md, AGENTS.md
+    //        with SpecLock marker, GEMINI.md, .github/copilot-instructions.md,
+    //        .aider.conf.yml)
+    // A file is considered "synced" if it has a SpecLock auto-gen marker in its header.
     lines.push("Rule Files");
+
+    // All the files `speclock sync` can produce (mirrors FORMATS in rules-sync.js)
+    const SYNCED_OUTPUT_FILES = [
+      ".cursor/rules/speclock.mdc",
+      ".windsurf/rules/speclock.md",
+      ".github/copilot-instructions.md",
+      "GEMINI.md",
+      ".aider.conf.yml",
+      "AGENTS.md",
+    ];
+
+    // Markers that indicate a file was written by SpecLock's sync pipeline.
+    // Must match the markers used by isSpeclockGenerated() in guardian.js.
+    const SPECLOCK_DOCTOR_SYNC_MARKERS = [
+      "Auto-synced from SpecLock",
+      "Auto-synced by SpecLock",
+      "Auto-synced.",
+      "(SpecLock)",
+      "# SpecLock Constraints",
+      "Do not edit manually — run `speclock sync`",
+      "speclock sync --format",
+      "speclock_session_briefing",
+    ];
+
+    function isSyncedFile(absPath) {
+      try {
+        const content = fs.readFileSync(absPath, "utf-8");
+        const header = content.split("\n").slice(0, 10).join("\n");
+        return SPECLOCK_DOCTOR_SYNC_MARKERS.some((m) => header.includes(m));
+      } catch (_) {
+        return false;
+      }
+    }
+
     const discovered = discoverRuleFiles(root);
     const discoveredMap = new Map(discovered.map((f) => [f.file, f]));
+    const shownFiles = new Set();
     let totalRuleFilesFound = 0;
+
+    // (a) Original/authored rule files
     for (const entry of RULE_FILES) {
       const found = discoveredMap.get(entry.file);
       if (found) {
         const extracted = extractConstraints(found.content, found.file);
         lines.push(`  ✓ ${entry.file} (${extracted.locks.length} locks extracted)`);
+        shownFiles.add(entry.file);
+        totalRuleFilesFound++;
+      }
+    }
+
+    // (b) Synced files written by `speclock protect` / `speclock sync`
+    for (const relPath of SYNCED_OUTPUT_FILES) {
+      if (shownFiles.has(relPath)) continue; // already shown as an authored file
+      const abs = path.join(root, relPath);
+      if (!fs.existsSync(abs)) continue;
+      if (isSyncedFile(abs)) {
+        lines.push(`  ✓ ${relPath} (synced)`);
+        shownFiles.add(relPath);
         totalRuleFilesFound++;
-      } else {
-        lines.push(`  ✗ ${entry.file} (not found)`);
       }
     }
+
+    // If nothing at all was found, show a clear diagnostic.
     if (totalRuleFilesFound === 0) {
+      lines.push(`  ✗ No rule files found`);
       fixes.push("Run: speclock protect (auto-creates a starter CLAUDE.md)");
       issueCount++;
     }

package/src/core/compliance.js

@@ -9,7 +9,7 @@
 import { readBrain, readEvents } from "./storage.js";
 import { verifyAuditChain } from "./audit.js";
 
-const VERSION = "5.5.5";
+const VERSION = "5.5.7";
 
 // PHI-related keywords for HIPAA filtering
 const PHI_KEYWORDS = [