speclock 2.1.1 → 2.5.0

package/src/core/memory.js

@@ -0,0 +1,191 @@
+/**
+ * SpecLock Memory Module
+ * Goal, lock, decision, note, deploy facts CRUD operations.
+ * Extracted from engine.js for modularity.
+ *
+ * Developed by Sandeep Roy (https://github.com/sgroy10)
+ */
+
+import fs from "fs";
+import path from "path";
+import {
+  nowIso,
+  newId,
+  readBrain,
+  writeBrain,
+  appendEvent,
+  bumpEvents,
+  ensureSpeclockDirs,
+  speclockDir,
+  makeBrain,
+} from "./storage.js";
+import { hasGit, getHead, getDefaultBranch } from "./git.js";
+import { ensureAuditKeyGitignored } from "./audit.js";
+
+// --- Internal helpers ---
+
+function recordEvent(root, brain, event) {
+  bumpEvents(brain, event.eventId);
+  appendEvent(root, event);
+  writeBrain(root, brain);
+}
+
+// --- Core functions ---
+
+export function ensureInit(root) {
+  ensureSpeclockDirs(root);
+  try { ensureAuditKeyGitignored(root); } catch { /* non-critical */ }
+  let brain = readBrain(root);
+  if (!brain) {
+    const gitExists = hasGit(root);
+    const defaultBranch = gitExists ? getDefaultBranch(root) : "";
+    brain = makeBrain(root, gitExists, defaultBranch);
+    if (gitExists) {
+      const head = getHead(root);
+      brain.state.head.gitBranch = head.gitBranch;
+      brain.state.head.gitCommit = head.gitCommit;
+      brain.state.head.capturedAt = nowIso();
+    }
+    const eventId = newId("evt");
+    const event = {
+      eventId,
+      type: "init",
+      at: nowIso(),
+      files: [],
+      summary: "Initialized SpecLock",
+      patchPath: "",
+    };
+    bumpEvents(brain, eventId);
+    appendEvent(root, event);
+    writeBrain(root, brain);
+  }
+  return brain;
+}
+
+export function setGoal(root, text) {
+  const brain = ensureInit(root);
+  brain.goal.text = text;
+  brain.goal.updatedAt = nowIso();
+  const eventId = newId("evt");
+  const event = {
+    eventId,
+    type: "goal_updated",
+    at: nowIso(),
+    files: [],
+    summary: `Goal set: ${text.substring(0, 80)}`,
+    patchPath: "",
+  };
+  recordEvent(root, brain, event);
+  return brain;
+}
+
+export function addLock(root, text, tags, source) {
+  const brain = ensureInit(root);
+  const lockId = newId("lock");
+  brain.specLock.items.unshift({
+    id: lockId,
+    text,
+    createdAt: nowIso(),
+    source: source || "user",
+    tags: tags || [],
+    active: true,
+  });
+  const eventId = newId("evt");
+  const event = {
+    eventId,
+    type: "lock_added",
+    at: nowIso(),
+    files: [],
+    summary: `Lock added: ${text.substring(0, 80)}`,
+    patchPath: "",
+  };
+  recordEvent(root, brain, event);
+  return { brain, lockId };
+}
+
+export function removeLock(root, lockId) {
+  const brain = ensureInit(root);
+  const lock = brain.specLock.items.find((l) => l.id === lockId);
+  if (!lock) {
+    return { brain, removed: false, error: `Lock not found: ${lockId}` };
+  }
+  lock.active = false;
+  const eventId = newId("evt");
+  const event = {
+    eventId,
+    type: "lock_removed",
+    at: nowIso(),
+    files: [],
+    summary: `Lock removed: ${lock.text.substring(0, 80)}`,
+    patchPath: "",
+  };
+  recordEvent(root, brain, event);
+  return { brain, removed: true, lockText: lock.text };
+}
+
+export function addDecision(root, text, tags, source) {
+  const brain = ensureInit(root);
+  const decId = newId("dec");
+  brain.decisions.unshift({
+    id: decId,
+    text,
+    createdAt: nowIso(),
+    source: source || "user",
+    tags: tags || [],
+  });
+  const eventId = newId("evt");
+  const event = {
+    eventId,
+    type: "decision_added",
+    at: nowIso(),
+    files: [],
+    summary: `Decision: ${text.substring(0, 80)}`,
+    patchPath: "",
+  };
+  recordEvent(root, brain, event);
+  return { brain, decId };
+}
+
+export function addNote(root, text, pinned = true) {
+  const brain = ensureInit(root);
+  const noteId = newId("note");
+  brain.notes.unshift({
+    id: noteId,
+    text,
+    createdAt: nowIso(),
+    pinned,
+  });
+  const eventId = newId("evt");
+  const event = {
+    eventId,
+    type: "note_added",
+    at: nowIso(),
+    files: [],
+    summary: `Note: ${text.substring(0, 80)}`,
+    patchPath: "",
+  };
+  recordEvent(root, brain, event);
+  return { brain, noteId };
+}
+
+export function updateDeployFacts(root, payload) {
+  const brain = ensureInit(root);
+  const deploy = brain.facts.deploy;
+  if (payload.provider !== undefined) deploy.provider = payload.provider;
+  if (typeof payload.autoDeploy === "boolean")
+    deploy.autoDeploy = payload.autoDeploy;
+  if (payload.branch !== undefined) deploy.branch = payload.branch;
+  if (payload.url !== undefined) deploy.url = payload.url;
+  if (payload.notes !== undefined) deploy.notes = payload.notes;
+  const eventId = newId("evt");
+  const event = {
+    eventId,
+    type: "fact_updated",
+    at: nowIso(),
+    files: [],
+    summary: "Updated deploy facts",
+    patchPath: "",
+  };
+  recordEvent(root, brain, event);
+  return brain;
+}

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

@@ -0,0 +1,284 @@
+/**
+ * SpecLock Semantic Pre-Commit Engine
+ * Replaces filename-only pre-commit with actual code-level semantic analysis.
+ *
+ * Parses git diff output, extracts code changes per file, and runs
+ * analyzeConflict() against each change block + active locks.
+ *
+ * Developed by Sandeep Roy (https://github.com/sgroy10)
+ */
+
+import fs from "fs";
+import path from "path";
+import { execSync } from "child_process";
+import { readBrain } from "./storage.js";
+import { analyzeConflict } from "./semantics.js";
+import { getEnforcementConfig } from "./enforcer.js";
+
+const GUARD_TAG = "SPECLOCK-GUARD";
+const MAX_LINES_PER_FILE = 500;
+const BINARY_EXTENSIONS = new Set([
+  "png", "jpg", "jpeg", "gif", "bmp", "ico", "svg", "webp",
+  "mp3", "mp4", "wav", "avi", "mov", "mkv",
+  "zip", "tar", "gz", "rar", "7z",
+  "pdf", "doc", "docx", "xls", "xlsx", "ppt", "pptx",
+  "exe", "dll", "so", "dylib", "bin",
+  "woff", "woff2", "ttf", "eot", "otf",
+  "lock", "map",
+]);
+
+/**
+ * Parse a unified diff into per-file change blocks.
+ * Returns array of { file, addedLines, removedLines, hunks }.
+ */
+export function parseDiff(diffText) {
+  if (!diffText || !diffText.trim()) return [];
+
+  const files = [];
+  const fileSections = diffText.split(/^diff --git /m).filter(Boolean);
+
+  for (const section of fileSections) {
+    const lines = section.split("\n");
+
+    // Extract filename from "a/path b/path"
+    const headerMatch = lines[0]?.match(/a\/(.+?) b\/(.+)/);
+    if (!headerMatch) continue;
+
+    const file = headerMatch[2];
+    const ext = path.extname(file).slice(1).toLowerCase();
+
+    // Skip binary files
+    if (BINARY_EXTENSIONS.has(ext)) continue;
+    if (section.includes("Binary files")) continue;
+
+    const addedLines = [];
+    const removedLines = [];
+    const hunks = [];
+    let currentHunk = null;
+    let lineCount = 0;
+
+    for (const line of lines) {
+      if (lineCount >= MAX_LINES_PER_FILE) break;
+
+      if (line.startsWith("@@")) {
+        // New hunk
+        const hunkMatch = line.match(/@@ -(\d+)(?:,(\d+))? \+(\d+)(?:,(\d+))? @@(.*)/);
+        if (hunkMatch) {
+          currentHunk = {
+            oldStart: parseInt(hunkMatch[1]),
+            newStart: parseInt(hunkMatch[3]),
+            context: hunkMatch[5]?.trim() || "",
+            changes: [],
+          };
+          hunks.push(currentHunk);
+        }
+        continue;
+      }
+
+      if (!currentHunk) continue;
+
+      if (line.startsWith("+") && !line.startsWith("+++")) {
+        const content = line.substring(1).trim();
+        if (content) {
+          addedLines.push(content);
+          currentHunk.changes.push({ type: "add", content });
+          lineCount++;
+        }
+      } else if (line.startsWith("-") && !line.startsWith("---")) {
+        const content = line.substring(1).trim();
+        if (content) {
+          removedLines.push(content);
+          currentHunk.changes.push({ type: "remove", content });
+          lineCount++;
+        }
+      }
+    }
+
+    if (addedLines.length > 0 || removedLines.length > 0) {
+      files.push({ file, addedLines, removedLines, hunks });
+    }
+  }
+
+  return files;
+}
+
+/**
+ * Get the staged diff from git.
+ */
+export function getStagedDiff(root) {
+  try {
+    return execSync("git diff --cached --unified=3", {
+      cwd: root,
+      encoding: "utf-8",
+      maxBuffer: 5 * 1024 * 1024, // 5MB
+      timeout: 10000,
+    });
+  } catch {
+    return "";
+  }
+}
+
+/**
+ * Build a semantic summary of changes in a file for conflict checking.
+ * Combines added/removed lines into meaningful phrases.
+ */
+function buildChangeSummary(fileChanges) {
+  const summaries = [];
+
+  // Summarize removals (deletions are more dangerous)
+  if (fileChanges.removedLines.length > 0) {
+    const sample = fileChanges.removedLines.slice(0, 10).join(" ");
+    summaries.push(`Removing code: ${sample}`);
+  }
+
+  // Summarize additions
+  if (fileChanges.addedLines.length > 0) {
+    const sample = fileChanges.addedLines.slice(0, 10).join(" ");
+    summaries.push(`Adding code: ${sample}`);
+  }
+
+  // Add hunk contexts (function names, class names)
+  for (const hunk of fileChanges.hunks) {
+    if (hunk.context) {
+      summaries.push(`In context: ${hunk.context}`);
+    }
+  }
+
+  return summaries.join(". ");
+}
+
+/**
+ * Run semantic pre-commit audit.
+ * Parses the staged diff, analyzes each file's changes against locks.
+ */
+export function semanticAudit(root) {
+  const brain = readBrain(root);
+  if (!brain) {
+    return {
+      passed: true,
+      violations: [],
+      filesChecked: 0,
+      activeLocks: 0,
+      mode: "advisory",
+      message: "SpecLock not initialized. Audit skipped.",
+    };
+  }
+
+  const config = getEnforcementConfig(brain);
+  const activeLocks = (brain.specLock?.items || []).filter((l) => l.active !== false);
+
+  if (activeLocks.length === 0) {
+    return {
+      passed: true,
+      violations: [],
+      filesChecked: 0,
+      activeLocks: 0,
+      mode: config.mode,
+      message: "No active locks. Semantic audit passed.",
+    };
+  }
+
+  // Get staged diff
+  const diff = getStagedDiff(root);
+  if (!diff) {
+    return {
+      passed: true,
+      violations: [],
+      filesChecked: 0,
+      activeLocks: activeLocks.length,
+      mode: config.mode,
+      message: "No staged changes. Semantic audit passed.",
+    };
+  }
+
+  // Parse diff into per-file changes
+  const fileChanges = parseDiff(diff);
+  const violations = [];
+
+  for (const fc of fileChanges) {
+    // Check 1: Guard tag violation
+    const fullPath = path.join(root, fc.file);
+    if (fs.existsSync(fullPath)) {
+      try {
+        const content = fs.readFileSync(fullPath, "utf-8");
+        if (content.includes(GUARD_TAG)) {
+          violations.push({
+            file: fc.file,
+            lockId: null,
+            lockText: "(file-level guard)",
+            confidence: 100,
+            level: "HIGH",
+            reason: "File has SPECLOCK-GUARD header — it is locked and must not be modified",
+            source: "guard",
+          });
+          continue; // Don't double-report guarded files
+        }
+      } catch { /* file read error, continue */ }
+    }
+
+    // Check 2: Semantic analysis of code changes against each lock
+    const changeSummary = buildChangeSummary(fc);
+    if (!changeSummary) continue;
+
+    // Prepend file path for context
+    const fullSummary = `Modifying file ${fc.file}: ${changeSummary}`;
+
+    for (const lock of activeLocks) {
+      const result = analyzeConflict(fullSummary, lock.text);
+
+      if (result.isConflict) {
+        violations.push({
+          file: fc.file,
+          lockId: lock.id,
+          lockText: lock.text,
+          confidence: result.confidence,
+          level: result.level,
+          reason: result.reasons.join("; "),
+          source: "semantic",
+          addedLines: fc.addedLines.length,
+          removedLines: fc.removedLines.length,
+        });
+      }
+    }
+  }
+
+  // Deduplicate: keep highest confidence per file+lock pair
+  const dedupKey = (v) => `${v.file}::${v.lockId || v.lockText}`;
+  const bestByKey = new Map();
+  for (const v of violations) {
+    const key = dedupKey(v);
+    const existing = bestByKey.get(key);
+    if (!existing || v.confidence > existing.confidence) {
+      bestByKey.set(key, v);
+    }
+  }
+  const uniqueViolations = [...bestByKey.values()];
+
+  // Sort by confidence descending
+  uniqueViolations.sort((a, b) => b.confidence - a.confidence);
+
+  // In hard mode, check if any violation meets the block threshold
+  const blocked = config.mode === "hard" &&
+    uniqueViolations.some((v) => v.confidence >= config.blockThreshold);
+
+  const passed = uniqueViolations.length === 0;
+  let message;
+  if (passed) {
+    message = `Semantic audit passed. ${fileChanges.length} file(s) analyzed against ${activeLocks.length} lock(s).`;
+  } else if (blocked) {
+    message = `BLOCKED: ${uniqueViolations.length} violation(s) detected in ${fileChanges.length} file(s). Hard enforcement active — commit rejected.`;
+  } else {
+    message = `WARNING: ${uniqueViolations.length} violation(s) detected in ${fileChanges.length} file(s). Advisory mode — review before proceeding.`;
+  }
+
+  return {
+    passed,
+    blocked,
+    violations: uniqueViolations,
+    filesChecked: fileChanges.length,
+    activeLocks: activeLocks.length,
+    mode: config.mode,
+    threshold: config.blockThreshold,
+    message,
+  };
+}

package/src/core/sessions.js

@@ -0,0 +1,128 @@
+/**
+ * SpecLock Sessions Module
+ * Session briefing, start, end, and history management.
+ * Extracted from engine.js for modularity.
+ *
+ * Developed by Sandeep Roy (https://github.com/sgroy10)
+ */
+
+import {
+  nowIso,
+  newId,
+  writeBrain,
+  appendEvent,
+  bumpEvents,
+  readEvents,
+} from "./storage.js";
+import { ensureInit } from "./memory.js";
+
+// --- Internal helpers ---
+
+function recordEvent(root, brain, event) {
+  bumpEvents(brain, event.eventId);
+  appendEvent(root, event);
+  writeBrain(root, brain);
+}
+
+// --- Core functions ---
+
+export function startSession(root, toolName = "unknown") {
+  const brain = ensureInit(root);
+
+  // Auto-close previous session if open
+  if (brain.sessions.current) {
+    const prev = brain.sessions.current;
+    prev.endedAt = nowIso();
+    prev.summary = prev.summary || "Session auto-closed (new session started)";
+    brain.sessions.history.unshift(prev);
+    if (brain.sessions.history.length > 50) {
+      brain.sessions.history = brain.sessions.history.slice(0, 50);
+    }
+  }
+
+  const session = {
+    id: newId("ses"),
+    startedAt: nowIso(),
+    endedAt: null,
+    summary: "",
+    toolUsed: toolName,
+    eventsInSession: 0,
+  };
+  brain.sessions.current = session;
+
+  const eventId = newId("evt");
+  const event = {
+    eventId,
+    type: "session_started",
+    at: nowIso(),
+    files: [],
+    summary: `Session started (${toolName})`,
+    patchPath: "",
+  };
+  recordEvent(root, brain, event);
+  return { brain, session };
+}
+
+export function endSession(root, summary) {
+  const brain = ensureInit(root);
+  if (!brain.sessions.current) {
+    return { brain, ended: false, error: "No active session to end." };
+  }
+
+  const session = brain.sessions.current;
+  session.endedAt = nowIso();
+  session.summary = summary;
+
+  const events = readEvents(root, { since: session.startedAt });
+  session.eventsInSession = events.length;
+
+  brain.sessions.history.unshift(session);
+  if (brain.sessions.history.length > 50) {
+    brain.sessions.history = brain.sessions.history.slice(0, 50);
+  }
+  brain.sessions.current = null;
+
+  const eventId = newId("evt");
+  const event = {
+    eventId,
+    type: "session_ended",
+    at: nowIso(),
+    files: [],
+    summary: `Session ended: ${summary.substring(0, 100)}`,
+    patchPath: "",
+  };
+  recordEvent(root, brain, event);
+  return { brain, ended: true, session };
+}
+
+export function getSessionBriefing(root, toolName = "unknown") {
+  const { brain, session } = startSession(root, toolName);
+
+  const lastSession =
+    brain.sessions.history.length > 0 ? brain.sessions.history[0] : null;
+
+  let changesSinceLastSession = 0;
+  let warnings = [];
+
+  if (lastSession && lastSession.endedAt) {
+    const eventsSince = readEvents(root, { since: lastSession.endedAt });
+    changesSinceLastSession = eventsSince.length;
+
+    const revertsSince = eventsSince.filter(
+      (e) => e.type === "revert_detected"
+    );
+    if (revertsSince.length > 0) {
+      warnings.push(
+        `${revertsSince.length} revert(s) detected since last session. Verify current state before proceeding.`
+      );
+    }
+  }
+
+  return {
+    brain,
+    session,
+    lastSession,
+    changesSinceLastSession,
+    warnings,
+  };
+}

package/src/core/tracking.js

@@ -0,0 +1,98 @@
+/**
+ * SpecLock Tracking Module
+ * Change logging, file event handling, event management.
+ * Extracted from engine.js for modularity.
+ *
+ * Developed by Sandeep Roy (https://github.com/sgroy10)
+ */
+
+import fs from "fs";
+import path from "path";
+import {
+  nowIso,
+  newId,
+  writeBrain,
+  appendEvent,
+  bumpEvents,
+  speclockDir,
+  addRecentChange,
+  addRevert,
+} from "./storage.js";
+import { captureDiff } from "./git.js";
+import { ensureInit } from "./memory.js";
+
+// --- Internal helpers ---
+
+function recordEvent(root, brain, event) {
+  bumpEvents(brain, event.eventId);
+  appendEvent(root, event);
+  writeBrain(root, brain);
+}
+
+function writePatch(root, eventId, content) {
+  const patchPath = path.join(
+    speclockDir(root),
+    "patches",
+    `${eventId}.patch`
+  );
+  fs.writeFileSync(patchPath, content);
+  return path.join(".speclock", "patches", `${eventId}.patch`);
+}
+
+// --- Core functions ---
+
+export function logChange(root, summary, files = []) {
+  const brain = ensureInit(root);
+  const eventId = newId("evt");
+  let patchPath = "";
+  if (brain.facts.repo.hasGit) {
+    const diff = captureDiff(root);
+    if (diff && diff.trim().length > 0) {
+      patchPath = writePatch(root, eventId, diff);
+    }
+  }
+  const event = {
+    eventId,
+    type: "manual_change",
+    at: nowIso(),
+    files,
+    summary,
+    patchPath,
+  };
+  addRecentChange(brain, {
+    eventId,
+    summary,
+    files,
+    at: event.at,
+  });
+  recordEvent(root, brain, event);
+  return { brain, eventId };
+}
+
+export function handleFileEvent(root, brain, type, filePath) {
+  const eventId = newId("evt");
+  const rel = path.relative(root, filePath);
+  let patchPath = "";
+  if (brain.facts.repo.hasGit) {
+    const diff = captureDiff(root);
+    const patchContent =
+      diff && diff.trim().length > 0 ? diff : "(no diff available)";
+    patchPath = writePatch(root, eventId, patchContent);
+  }
+  const summary = `${type.replace("_", " ")}: ${rel}`;
+  const event = {
+    eventId,
+    type,
+    at: nowIso(),
+    files: [rel],
+    summary,
+    patchPath,
+  };
+  addRecentChange(brain, {
+    eventId,
+    summary,
+    files: [rel],
+    at: event.at,
+  });
+  recordEvent(root, brain, event);
+}