speclock 2.1.1 → 3.0.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/storage.js

@@ -2,6 +2,7 @@ import fs from "fs";
 import path from "path";
 import crypto from "crypto";
 import { signEvent, isAuditEnabled } from "./audit.js";
+import { isEncryptionEnabled, encrypt, decrypt, isEncrypted } from "./crypto.js";
 
 export function nowIso() {
   return new Date().toISOString();
@@ -121,7 +122,11 @@ export function migrateBrainV1toV2(brain) {
 export function readBrain(root) {
   const p = brainPath(root);
   if (!fs.existsSync(p)) return null;
-  const raw = fs.readFileSync(p, "utf8");
+  let raw = fs.readFileSync(p, "utf8");
+  // Transparent decryption (v3.0)
+  if (isEncrypted(raw)) {
+    try { raw = decrypt(raw); } catch { return null; }
+  }
   let brain = JSON.parse(raw);
   if (brain.version < 2) {
     brain = migrateBrainV1toV2(brain);
@@ -137,7 +142,12 @@ export function readBrain(root) {
 export function writeBrain(root, brain) {
   brain.project.updatedAt = nowIso();
   const p = brainPath(root);
-  fs.writeFileSync(p, JSON.stringify(brain, null, 2));
+  let data = JSON.stringify(brain, null, 2);
+  // Transparent encryption (v3.0)
+  if (isEncryptionEnabled()) {
+    data = encrypt(data);
+  }
+  fs.writeFileSync(p, data);
 }
 
 export function appendEvent(root, event) {
@@ -149,7 +159,11 @@ export function appendEvent(root, event) {
   } catch {
     // Audit error — write event without hash (graceful degradation)
   }
-  const line = JSON.stringify(event);
+  let line = JSON.stringify(event);
+  // Transparent per-line encryption (v3.0)
+  if (isEncryptionEnabled()) {
+    line = encrypt(line);
+  }
   fs.appendFileSync(eventsPath(root), `${line}\n`);
 }
 
@@ -163,7 +177,12 @@ export function readEvents(root, opts = {}) {
 
   let events = raw.split("\n").map((line) => {
     try {
-      return JSON.parse(line);
+      // Transparent per-line decryption (v3.0)
+      let decoded = line;
+      if (isEncrypted(decoded)) {
+        try { decoded = decrypt(decoded); } catch { return null; }
+      }
+      return JSON.parse(decoded);
     } catch {
       return null;
     }