speclock 1.6.0 → 2.0.0

package/src/core/engine.js

@@ -13,8 +13,11 @@ import {
   addRecentChange,
   addRevert,
   readEvents,
+  addViolation,
 } from "./storage.js";
-import { hasGit, getHead, getDefaultBranch, captureDiff } from "./git.js";
+import { hasGit, getHead, getDefaultBranch, captureDiff, getStagedFiles } from "./git.js";
+import { getTemplateNames, getTemplate } from "./templates.js";
+import { analyzeConflict } from "./semantics.js";
 
 // --- Internal helpers ---
 
@@ -249,7 +252,8 @@ export function handleFileEvent(root, brain, type, filePath) {
   recordEvent(root, brain, event);
 }
 
-// --- Synonym groups for semantic matching ---
+// --- Legacy synonym groups (deprecated — kept for backward compatibility) ---
+// @deprecated Use analyzeConflict() from semantics.js instead
 const SYNONYM_GROUPS = [
   ["remove", "delete", "drop", "eliminate", "destroy", "kill", "purge", "wipe"],
   ["add", "create", "introduce", "insert", "new"],
@@ -268,12 +272,13 @@ const SYNONYM_GROUPS = [
   ["enable", "activate", "turn-on", "switch-on"],
 ];
 
-// Negation words that invert meaning
+// @deprecated
 const NEGATION_WORDS = ["no", "not", "never", "without", "dont", "don't", "cannot", "can't", "shouldn't", "mustn't", "avoid", "prevent", "prohibit", "forbid", "disallow"];
 
-// Destructive action words
+// @deprecated
 const DESTRUCTIVE_WORDS = ["remove", "delete", "drop", "destroy", "kill", "purge", "wipe", "break", "disable", "revert", "rollback", "undo"];
 
+// @deprecated — use analyzeConflict() from semantics.js
 function expandWithSynonyms(words) {
   const expanded = new Set(words);
   for (const word of words) {
@@ -286,17 +291,20 @@ function expandWithSynonyms(words) {
   return [...expanded];
 }
 
+// @deprecated
 function hasNegation(text) {
   const lower = text.toLowerCase();
   return NEGATION_WORDS.some((neg) => lower.includes(neg));
 }
 
+// @deprecated
 function isDestructiveAction(text) {
   const lower = text.toLowerCase();
   return DESTRUCTIVE_WORDS.some((w) => lower.includes(w));
 }
 
 // Check if a proposed action conflicts with any active SpecLock
+// v2: Uses the semantic analysis engine from semantics.js
 export function checkConflict(root, proposedAction) {
   const brain = ensureInit(root);
   const activeLocks = brain.specLock.items.filter((l) => l.active !== false);
@@ -308,61 +316,18 @@ export function checkConflict(root, proposedAction) {
     };
   }
 
-  const actionLower = proposedAction.toLowerCase();
-  const actionWords = actionLower.split(/\s+/).filter((w) => w.length > 2);
-  const actionExpanded = expandWithSynonyms(actionWords);
-  const actionIsDestructive = isDestructiveAction(actionLower);
-
   const conflicting = [];
   for (const lock of activeLocks) {
-    const lockLower = lock.text.toLowerCase();
-    const lockWords = lockLower.split(/\s+/).filter((w) => w.length > 2);
-    const lockExpanded = expandWithSynonyms(lockWords);
-
-    // Direct keyword overlap
-    const directOverlap = actionWords.filter((w) => lockWords.includes(w));
-
-    // Synonym-expanded overlap
-    const synonymOverlap = actionExpanded.filter((w) => lockExpanded.includes(w));
-    const uniqueSynonymMatches = synonymOverlap.filter((w) => !directOverlap.includes(w));
-
-    // Negation analysis: lock says "No X" and action does X
-    const lockHasNegation = hasNegation(lockLower);
-    const actionHasNegation = hasNegation(actionLower);
-    const negationConflict = lockHasNegation && !actionHasNegation && synonymOverlap.length > 0;
-
-    // Calculate confidence score
-    let confidence = 0;
-    let reasons = [];
-
-    if (directOverlap.length > 0) {
-      confidence += directOverlap.length * 30;
-      reasons.push(`direct keyword match: ${directOverlap.join(", ")}`);
-    }
-    if (uniqueSynonymMatches.length > 0) {
-      confidence += uniqueSynonymMatches.length * 15;
-      reasons.push(`synonym match: ${uniqueSynonymMatches.join(", ")}`);
-    }
-    if (negationConflict) {
-      confidence += 40;
-      reasons.push("lock prohibits this action (negation detected)");
-    }
-    if (actionIsDestructive && synonymOverlap.length > 0) {
-      confidence += 20;
-      reasons.push("destructive action against locked constraint");
-    }
-
-    confidence = Math.min(confidence, 100);
+    const result = analyzeConflict(proposedAction, lock.text);
 
-    if (confidence >= 15) {
-      const level = confidence >= 70 ? "HIGH" : confidence >= 40 ? "MEDIUM" : "LOW";
+    if (result.isConflict) {
       conflicting.push({
         id: lock.id,
         text: lock.text,
-        matchedKeywords: [...new Set([...directOverlap, ...uniqueSynonymMatches])],
-        confidence,
-        level,
-        reasons,
+        matchedKeywords: [],
+        confidence: result.confidence,
+        level: result.level,
+        reasons: result.reasons,
       });
     }
   }
@@ -371,7 +336,7 @@ export function checkConflict(root, proposedAction) {
     return {
       hasConflict: false,
       conflictingLocks: [],
-      analysis: `Checked against ${activeLocks.length} active lock(s). No conflicts detected (keyword + synonym + negation analysis). Proceed with caution.`,
+      analysis: `Checked against ${activeLocks.length} active lock(s). No conflicts detected (semantic analysis v2). Proceed with caution.`,
     };
   }
 
@@ -385,11 +350,38 @@ export function checkConflict(root, proposedAction) {
     )
     .join("\n");
 
-  return {
+  const result = {
     hasConflict: true,
     conflictingLocks: conflicting,
     analysis: `Potential conflict with ${conflicting.length} lock(s):\n${details}\nReview before proceeding.`,
   };
+
+  // Record violation for reporting
+  addViolation(brain, {
+    at: nowIso(),
+    action: proposedAction,
+    locks: conflicting.map((c) => ({ id: c.id, text: c.text, confidence: c.confidence, level: c.level })),
+    topLevel: conflicting[0].level,
+    topConfidence: conflicting[0].confidence,
+  });
+  writeBrain(root, brain);
+
+  return result;
+}
+
+// Async version — uses LLM if available, falls back to heuristic
+export async function checkConflictAsync(root, proposedAction) {
+  // Try LLM first (if llm-checker is available)
+  try {
+    const { llmCheckConflict } = await import("./llm-checker.js");
+    const llmResult = await llmCheckConflict(root, proposedAction);
+    if (llmResult) return llmResult;
+  } catch (_) {
+    // LLM checker not available or failed — fall through to heuristic
+  }
+
+  // Fallback to heuristic
+  return checkConflict(root, proposedAction);
 }
 
 // --- Auto-lock suggestions ---
@@ -464,7 +456,7 @@ export function suggestLocks(root) {
   return { suggestions, totalLocks: brain.specLock.items.filter((l) => l.active).length };
 }
 
-// --- Drift detection ---
+// --- Drift detection (v2: uses semantic engine) ---
 export function detectDrift(root) {
   const brain = ensureInit(root);
   const activeLocks = brain.specLock.items.filter((l) => l.active !== false);
@@ -474,29 +466,20 @@ export function detectDrift(root) {
 
   const drifts = [];
 
-  // Check recent changes against locks
+  // Check recent changes against locks using the semantic engine
   for (const change of brain.state.recentChanges) {
-    const changeLower = change.summary.toLowerCase();
-    const changeWords = changeLower.split(/\s+/).filter((w) => w.length > 2);
-    const changeExpanded = expandWithSynonyms(changeWords);
-
     for (const lock of activeLocks) {
-      const lockLower = lock.text.toLowerCase();
-      const lockWords = lockLower.split(/\s+/).filter((w) => w.length > 2);
-      const lockExpanded = expandWithSynonyms(lockWords);
-
-      const overlap = changeExpanded.filter((w) => lockExpanded.includes(w));
-      const lockHasNegation = hasNegation(lockLower);
+      const result = analyzeConflict(change.summary, lock.text);
 
-      if (overlap.length >= 2 && lockHasNegation) {
+      if (result.isConflict) {
         drifts.push({
           lockId: lock.id,
           lockText: lock.text,
           changeEventId: change.eventId,
           changeSummary: change.summary,
           changeAt: change.at,
-          matchedTerms: overlap,
-          severity: overlap.length >= 3 ? "high" : "medium",
+          matchedTerms: result.reasons,
+          severity: result.level === "HIGH" ? "high" : "medium",
         });
       }
     }
@@ -777,6 +760,11 @@ npx speclock unguard <file>                      # Remove file protection
 npx speclock lock remove <lockId>                # Unlock (only after explicit permission)
 npx speclock log-change "what changed"           # Log changes
 npx speclock decide "decision"                   # Record a decision
+npx speclock template list                       # List constraint templates
+npx speclock template apply <name>               # Apply a template (nextjs, react, etc.)
+npx speclock report                              # Show violation stats
+npx speclock hook install                        # Install git pre-commit hook
+npx speclock audit                               # Audit staged files vs locks
 npx speclock context                             # Refresh context file
 \`\`\`
 
@@ -1042,3 +1030,188 @@ export function unguardFile(root, relativeFilePath) {
 
   return { success: true };
 }
+
+// --- Constraint Templates ---
+
+export function listTemplates() {
+  const names = getTemplateNames();
+  return names.map((name) => {
+    const t = getTemplate(name);
+    return {
+      name: t.name,
+      displayName: t.displayName,
+      description: t.description,
+      lockCount: t.locks.length,
+      decisionCount: t.decisions.length,
+    };
+  });
+}
+
+export function applyTemplate(root, templateName) {
+  const template = getTemplate(templateName);
+  if (!template) {
+    return { applied: false, error: `Template not found: "${templateName}". Available: ${getTemplateNames().join(", ")}` };
+  }
+
+  ensureInit(root);
+
+  let locksAdded = 0;
+  let decisionsAdded = 0;
+
+  for (const lockText of template.locks) {
+    addLock(root, lockText, [template.name], "agent");
+    autoGuardRelatedFiles(root, lockText);
+    locksAdded++;
+  }
+
+  for (const decText of template.decisions) {
+    addDecision(root, decText, [template.name], "agent");
+    decisionsAdded++;
+  }
+
+  syncLocksToPackageJson(root);
+
+  return {
+    applied: true,
+    templateName: template.name,
+    displayName: template.displayName,
+    locksAdded,
+    decisionsAdded,
+  };
+}
+
+// --- Violation Report ---
+
+export function generateReport(root) {
+  const brain = ensureInit(root);
+  const violations = brain.state.violations || [];
+
+  if (violations.length === 0) {
+    return {
+      totalViolations: 0,
+      violationsByLock: {},
+      mostTestedLocks: [],
+      recentViolations: [],
+      summary: "No violations recorded yet. SpecLock is watching.",
+    };
+  }
+
+  // Count violations per lock
+  const byLock = {};
+  for (const v of violations) {
+    for (const lock of v.locks) {
+      if (!byLock[lock.text]) {
+        byLock[lock.text] = { count: 0, lockId: lock.id, text: lock.text };
+      }
+      byLock[lock.text].count++;
+    }
+  }
+
+  // Sort by count descending
+  const mostTested = Object.values(byLock).sort((a, b) => b.count - a.count);
+
+  // Recent 10
+  const recent = violations.slice(0, 10).map((v) => ({
+    at: v.at,
+    action: v.action,
+    topLevel: v.topLevel,
+    topConfidence: v.topConfidence,
+    lockCount: v.locks.length,
+  }));
+
+  // Time range
+  const oldest = violations[violations.length - 1];
+  const newest = violations[0];
+
+  return {
+    totalViolations: violations.length,
+    timeRange: { from: oldest.at, to: newest.at },
+    violationsByLock: byLock,
+    mostTestedLocks: mostTested.slice(0, 5),
+    recentViolations: recent,
+    summary: `SpecLock blocked ${violations.length} violation(s). Most tested lock: "${mostTested[0].text}" (${mostTested[0].count} blocks).`,
+  };
+}
+
+// --- Pre-commit Audit ---
+
+export function auditStagedFiles(root) {
+  const brain = ensureInit(root);
+  const activeLocks = brain.specLock.items.filter((l) => l.active !== false);
+
+  if (activeLocks.length === 0) {
+    return { passed: true, violations: [], checkedFiles: 0, activeLocks: 0, message: "No active locks. Audit passed." };
+  }
+
+  const stagedFiles = getStagedFiles(root);
+  if (stagedFiles.length === 0) {
+    return { passed: true, violations: [], checkedFiles: 0, activeLocks: activeLocks.length, message: "No staged files. Audit passed." };
+  }
+
+  const violations = [];
+
+  for (const file of stagedFiles) {
+    // Check 1: Does the file have a SPECLOCK-GUARD header?
+    const fullPath = path.join(root, file);
+    if (fs.existsSync(fullPath)) {
+      try {
+        const content = fs.readFileSync(fullPath, "utf-8");
+        if (content.includes(GUARD_TAG)) {
+          violations.push({
+            file,
+            reason: "File has SPECLOCK-GUARD header — it is locked and must not be modified",
+            lockText: "(file-level guard)",
+            severity: "HIGH",
+          });
+          continue;
+        }
+      } catch (_) {}
+    }
+
+    // Check 2: Does the file path match any lock keywords?
+    const fileLower = file.toLowerCase();
+    for (const lock of activeLocks) {
+      const lockLower = lock.text.toLowerCase();
+      const lockHasNegation = hasNegation(lockLower);
+      if (!lockHasNegation) continue;
+
+      // Check if any FILE_KEYWORD_PATTERNS keywords from the lock match this file
+      for (const group of FILE_KEYWORD_PATTERNS) {
+        const lockMatchesKeyword = group.keywords.some((kw) => lockLower.includes(kw));
+        if (!lockMatchesKeyword) continue;
+
+        const fileMatchesPattern = group.patterns.some((pattern) => patternMatchesFile(pattern, fileLower) || patternMatchesFile(pattern, fileLower.split("/").pop()));
+        if (fileMatchesPattern) {
+          violations.push({
+            file,
+            reason: `File matches lock keyword pattern`,
+            lockText: lock.text,
+            severity: "MEDIUM",
+          });
+          break;
+        }
+      }
+    }
+  }
+
+  // Deduplicate by file
+  const seen = new Set();
+  const unique = violations.filter((v) => {
+    if (seen.has(v.file)) return false;
+    seen.add(v.file);
+    return true;
+  });
+
+  const passed = unique.length === 0;
+  const message = passed
+    ? `Audit passed. ${stagedFiles.length} file(s) checked against ${activeLocks.length} lock(s).`
+    : `AUDIT FAILED: ${unique.length} violation(s) in ${stagedFiles.length} staged file(s).`;
+
+  return {
+    passed,
+    violations: unique,
+    checkedFiles: stagedFiles.length,
+    activeLocks: activeLocks.length,
+    message,
+  };
+}

package/src/core/git.js

@@ -108,3 +108,9 @@ export function getDiffSummary(root) {
   if (!res.ok) return "";
   return res.stdout;
 }
+
+export function getStagedFiles(root) {
+  const res = safeGit(root, ["diff", "--cached", "--name-only"]);
+  if (!res.ok || !res.stdout) return [];
+  return res.stdout.split("\n").filter(Boolean);
+}

package/src/core/hooks.js

@@ -0,0 +1,87 @@
+// SpecLock Git Hook Management
+
+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: checks staged files against active locks
+# Install: npx speclock hook install
+# Remove:  npx speclock hook remove
+
+npx speclock audit
+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);
+}