speclock 5.5.5 → 5.5.7

package/src/core/hooks.js

@@ -1,91 +1,109 @@
-// SpecLock Git Hook Management
-// Developed by Sandeep Roy (https://github.com/sgroy10)
-
-import fs from "fs";
-import path from "path";
-
-const HOOK_MARKER = "# SPECLOCK-HOOK";
-
-const HOOK_SCRIPT = `#!/bin/sh
-${HOOK_MARKER} — Do not remove this line
-# SpecLock pre-commit hook: runs semantic audit of staged diff + commit message
-# against active locks. Unlike the legacy 'audit' subcommand, this one feeds
-# the actual diff content AND the commit message through the semantic conflict
-# engine — the same one used by 'speclock check'.
-# Install: npx speclock hook install
-# Remove:  npx speclock hook remove
-
-npx speclock audit-semantic --pre-commit
-exit $?
-`;
-
-export function installHook(root) {
-  const hooksDir = path.join(root, ".git", "hooks");
-  if (!fs.existsSync(path.join(root, ".git"))) {
-    return { success: false, error: "Not a git repository. Run 'git init' first." };
-  }
-
-  // Ensure hooks directory exists
-  fs.mkdirSync(hooksDir, { recursive: true });
-
-  const hookPath = path.join(hooksDir, "pre-commit");
-
-  // Check if existing hook exists (not ours)
-  if (fs.existsSync(hookPath)) {
-    const existing = fs.readFileSync(hookPath, "utf-8");
-    if (existing.includes(HOOK_MARKER)) {
-      return { success: false, error: "SpecLock pre-commit hook is already installed." };
-    }
-    // Append to existing hook
-    const appended = existing.trimEnd() + "\n\n" + HOOK_SCRIPT;
-    fs.writeFileSync(hookPath, appended, { mode: 0o755 });
-    return { success: true, message: "SpecLock hook appended to existing pre-commit hook." };
-  }
-
-  fs.writeFileSync(hookPath, HOOK_SCRIPT, { mode: 0o755 });
-  return { success: true, message: "SpecLock pre-commit hook installed." };
-}
-
-export function removeHook(root) {
-  const hookPath = path.join(root, ".git", "hooks", "pre-commit");
-  if (!fs.existsSync(hookPath)) {
-    return { success: false, error: "No pre-commit hook found." };
-  }
-
-  const content = fs.readFileSync(hookPath, "utf-8");
-  if (!content.includes(HOOK_MARKER)) {
-    return { success: false, error: "Pre-commit hook exists but was not installed by SpecLock." };
-  }
-
-  // Check if lines other than our speclock block exist
-  const lines = content.split("\n");
-  const nonSpeclockLines = lines.filter((line) => {
-    const trimmed = line.trim();
-    const lower = trimmed.toLowerCase();
-    if (!trimmed || trimmed === "#!/bin/sh") return false;
-    if (lower.includes("speclock")) return false;
-    if (lower.includes("npx speclock")) return false;
-    if (trimmed === "exit $?") return false;
-    return true;
-  });
-
-  if (nonSpeclockLines.length === 0) {
-    // Entire hook was ours — remove file
-    fs.unlinkSync(hookPath);
-    return { success: true, message: "SpecLock pre-commit hook removed." };
-  }
-
-  // Other hook content exists — remove our block, keep the rest
-  const cleaned = content
-    .replace(/\n*# SPECLOCK-HOOK[^\n]*\n.*?exit \$\?\n?/s, "\n")
-    .trim();
-  fs.writeFileSync(hookPath, cleaned + "\n", { mode: 0o755 });
-  return { success: true, message: "SpecLock hook removed. Other hook content preserved." };
-}
-
-export function isHookInstalled(root) {
-  const hookPath = path.join(root, ".git", "hooks", "pre-commit");
-  if (!fs.existsSync(hookPath)) return false;
-  const content = fs.readFileSync(hookPath, "utf-8");
-  return content.includes(HOOK_MARKER);
-}
+// SpecLock Git Hook Management
+// Developed by Sandeep Roy (https://github.com/sgroy10)
+
+import fs from "fs";
+import path from "path";
+
+const HOOK_MARKER = "# SPECLOCK-HOOK";
+
+const HOOK_SCRIPT = `#!/bin/sh
+${HOOK_MARKER} — Do not remove this line
+# SpecLock pre-commit hook: runs semantic audit of staged diff + commit message
+# against active locks. Unlike the legacy 'audit' subcommand, this one feeds
+# the actual diff content AND the commit message through the semantic conflict
+# engine — the same one used by 'speclock check'.
+# Install: npx speclock hook install
+# Remove:  npx speclock hook remove
+#
+# Enforcement mode precedence (first match wins):
+#   1. SPECLOCK_STRICT=1 in the environment when git commit runs
+#   2. brain.enforcement.mode === "hard" in .speclock/brain.json
+#      (set with: speclock enforce hard)
+#   3. Default: warn mode — violations printed, commit allowed
+#
+# NOTE: Some git versions/shells sanitize the environment before running
+# hooks, which can strip SPECLOCK_STRICT. The persistent brain mode set by
+# 'speclock enforce hard' is the reliable way to enforce strict blocking.
+
+# Explicitly export SPECLOCK_STRICT so it survives any sh -c subshells the
+# CLI may spawn. If unset, leave it unset — the CLI will then fall back to
+# reading brain.enforcement.mode from .speclock/brain.json.
+if [ -n "\${SPECLOCK_STRICT:-}" ]; then
+  export SPECLOCK_STRICT
+fi
+
+# Marker so the CLI knows it's running inside the pre-commit hook.
+export SPECLOCK_HOOK=1
+
+npx speclock audit-semantic --pre-commit
+exit $?
+`;
+
+export function installHook(root) {
+  const hooksDir = path.join(root, ".git", "hooks");
+  if (!fs.existsSync(path.join(root, ".git"))) {
+    return { success: false, error: "Not a git repository. Run 'git init' first." };
+  }
+
+  // Ensure hooks directory exists
+  fs.mkdirSync(hooksDir, { recursive: true });
+
+  const hookPath = path.join(hooksDir, "pre-commit");
+
+  // Check if existing hook exists (not ours)
+  if (fs.existsSync(hookPath)) {
+    const existing = fs.readFileSync(hookPath, "utf-8");
+    if (existing.includes(HOOK_MARKER)) {
+      return { success: false, error: "SpecLock pre-commit hook is already installed." };
+    }
+    // Append to existing hook
+    const appended = existing.trimEnd() + "\n\n" + HOOK_SCRIPT;
+    fs.writeFileSync(hookPath, appended, { mode: 0o755 });
+    return { success: true, message: "SpecLock hook appended to existing pre-commit hook." };
+  }
+
+  fs.writeFileSync(hookPath, HOOK_SCRIPT, { mode: 0o755 });
+  return { success: true, message: "SpecLock pre-commit hook installed." };
+}
+
+export function removeHook(root) {
+  const hookPath = path.join(root, ".git", "hooks", "pre-commit");
+  if (!fs.existsSync(hookPath)) {
+    return { success: false, error: "No pre-commit hook found." };
+  }
+
+  const content = fs.readFileSync(hookPath, "utf-8");
+  if (!content.includes(HOOK_MARKER)) {
+    return { success: false, error: "Pre-commit hook exists but was not installed by SpecLock." };
+  }
+
+  // Strip our block (from the SPECLOCK-HOOK marker through the trailing
+  // `exit $?` that terminates the script snippet). Everything inside the
+  // block is ours — comments, env exports, the npx invocation, etc.
+  const cleaned = content
+    .replace(/\n*# SPECLOCK-HOOK[^\n]*\n[\s\S]*?exit \$\?\n?/, "\n")
+    .trim();
+
+  // If nothing meaningful remains (just #!/bin/sh or empty), remove file.
+  const remaining = cleaned
+    .split("\n")
+    .map((l) => l.trim())
+    .filter((l) => l && l !== "#!/bin/sh")
+    .join("\n");
+
+  if (remaining.length === 0) {
+    fs.unlinkSync(hookPath);
+    return { success: true, message: "SpecLock pre-commit hook removed." };
+  }
+
+  // Other hook content exists — keep the rest.
+  fs.writeFileSync(hookPath, cleaned + "\n", { mode: 0o755 });
+  return { success: true, message: "SpecLock hook removed. Other hook content preserved." };
+}
+
+export function isHookInstalled(root) {
+  const hookPath = path.join(root, ".git", "hooks", "pre-commit");
+  if (!fs.existsSync(hookPath)) return false;
+  const content = fs.readFileSync(hookPath, "utf-8");
+  return content.includes(HOOK_MARKER);
+}

package/src/core/pre-commit-semantic.js

@@ -16,6 +16,7 @@ import { analyzeConflict } from "./semantics.js";
 import { getEnforcementConfig } from "./enforcer.js";
 
 const GUARD_TAG = "SPECLOCK-GUARD";
+const SPECLOCK_AUTOGEN_MARKER = "SpecLock";
 const MAX_LINES_PER_FILE = 500;
 const BINARY_EXTENSIONS = new Set([
   "png", "jpg", "jpeg", "gif", "bmp", "ico", "svg", "webp",
@@ -27,6 +28,98 @@ const BINARY_EXTENSIONS = new Set([
   "lock", "map",
 ]);
 
+// Files / dirs that SpecLock itself auto-creates during `protect` or that
+// are just noise for semantic analysis. These are ALWAYS skipped from the
+// diff-level semantic audit because matching against them produces nothing
+// but false positives (e.g. rules files describe the same concepts the
+// locks describe, so they always "conflict" with themselves).
+const ALWAYS_SKIP_EXACT = new Set([
+  ".cursor/rules/speclock.mdc",
+  ".windsurf/rules/speclock.md",
+  ".aider.conf.yml",
+  ".mcp.json",
+  "package-lock.json",
+  "yarn.lock",
+  "pnpm-lock.yaml",
+  "Cargo.lock",
+  "poetry.lock",
+  "Gemfile.lock",
+  "composer.lock",
+]);
+
+// Directory prefixes that are always skipped.
+const ALWAYS_SKIP_DIR_PREFIXES = [
+  ".speclock/",
+  "node_modules/",
+  "dist/",
+  "build/",
+  ".next/",
+  ".nuxt/",
+  "__pycache__/",
+  ".venv/",
+  "venv/",
+  ".cache/",
+  "coverage/",
+  ".turbo/",
+];
+
+// Files that are skipped ONLY if their content carries the SpecLock
+// auto-generated marker (so hand-written AGENTS.md etc. still get audited).
+// CLAUDE.md is included because `speclock protect` seeds it with the active
+// locks — on the initial commit after protect, the file literally IS the
+// locks, so every semantic check would produce a false positive.
+const CONDITIONAL_SKIP_IF_AUTOGEN = new Set([
+  "AGENTS.md",
+  "GEMINI.md",
+  "CLAUDE.md",
+  ".github/copilot-instructions.md",
+]);
+
+/**
+ * Normalize a path to forward slashes for comparison.
+ */
+function normalizePath(p) {
+  return (p || "").replace(/\\/g, "/");
+}
+
+/**
+ * Decide whether a file should be skipped by the semantic pre-commit audit.
+ * This is the single source of truth for "is this a SpecLock internal file
+ * or generated noise we should not audit".
+ *
+ * @param {string} file - repo-relative path
+ * @param {string} root - repo root (to check content of conditional files)
+ * @returns {boolean} true if the file should be skipped
+ */
+export function shouldSkipForSemanticAudit(file, root) {
+  const norm = normalizePath(file);
+
+  // 1. Binary extensions
+  const ext = path.extname(norm).slice(1).toLowerCase();
+  if (BINARY_EXTENSIONS.has(ext)) return true;
+
+  // 2. Exact path matches (lockfiles, auto-generated rules files, .mcp.json)
+  if (ALWAYS_SKIP_EXACT.has(norm)) return true;
+
+  // 3. Directory prefix matches
+  for (const prefix of ALWAYS_SKIP_DIR_PREFIXES) {
+    if (norm === prefix.slice(0, -1) || norm.startsWith(prefix)) return true;
+  }
+
+  // 4. Conditionally-skipped files (only if they carry the auto-gen marker)
+  if (CONDITIONAL_SKIP_IF_AUTOGEN.has(norm)) {
+    try {
+      const fullPath = path.join(root, file);
+      if (fs.existsSync(fullPath)) {
+        const content = fs.readFileSync(fullPath, "utf-8");
+        if (content.includes(SPECLOCK_AUTOGEN_MARKER)) return true;
+      }
+    } catch { /* ignore read errors */ }
+  }
+
+  return false;
+}
+
 /**
  * Parse a unified diff into per-file change blocks.
  * Returns array of { file, addedLines, removedLines, hunks }.
@@ -191,8 +284,14 @@ export function semanticAudit(root) {
     };
   }
 
-  // Parse diff into per-file changes
-  const fileChanges = parseDiff(diff);
+  // Parse diff into per-file changes, then drop SpecLock-internal / generated
+  // files so we don't flood the user with false positives from files that
+  // SpecLock itself creates or manages.
+  const allFileChanges = parseDiff(diff);
+  const fileChanges = allFileChanges.filter(
+    (fc) => !shouldSkipForSemanticAudit(fc.file, root)
+  );
+  const skippedCount = allFileChanges.length - fileChanges.length;
   const violations = [];
 
   for (const fc of fileChanges) {
@@ -276,6 +375,7 @@ export function semanticAudit(root) {
     blocked,
     violations: uniqueViolations,
     filesChecked: fileChanges.length,
+    filesSkipped: skippedCount,
     activeLocks: activeLocks.length,
     mode: config.mode,
     threshold: config.blockThreshold,