@esneiderbravo/speclaw 2.0.2 → 2.0.4

package/dist/modules/lawbook/scaffold-change.js

@@ -0,0 +1,238 @@
+import fs from "node:fs";
+import path from "node:path";
+import { gatherSignals, loadCeremonyConfig, proposeLevel, setCeremonyLevel, writeCeremonyRecord, } from "./levels.js";
+// Covers: req~feature-draft~1
+/** Change folder names are kebab-case: lowercase alphanumerics joined by single hyphens. */
+export const CHANGE_NAME_RE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+/**
+ * Generic change scaffold shared by `quick`, bug drafts, and feature drafts.
+ *
+ * Refuses an existing change directory, proposes a
+ * ceremony level from `targets`, writes the artifacts the caller asks for plus
+ * `reports/README.md`, then records `change.json`. Every refusal happens
+ * before the first write, so a rejected scaffold leaves the tree untouched.
+ *
+ * @param projectPath - Project root with `lawbook/`.
+ * @param name - Change folder name (kebab-case).
+ * @param opts - Level, change type, and artifact templates.
+ * @throws When the change exists or the level is below the proposal without a
+ *   reason. Name rules belong to the callers (feature drafts enforce kebab-case).
+ */
+export function scaffoldChange(projectPath, name, opts) {
+    const changeDir = path.join(projectPath, "lawbook", "changes", name);
+    if (fs.existsSync(changeDir)) {
+        throw new Error(`change "${name}" already exists under lawbook/changes/`);
+    }
+    const targets = opts.targets ?? { paths: [], symbols: [] };
+    const { thresholds } = loadCeremonyConfig(projectPath);
+    const signals = gatherSignals(projectPath, targets, thresholds);
+    const proposal = proposeLevel(signals, thresholds);
+    const level = typeof opts.level === "function" ? opts.level(proposal) : opts.level;
+    const stored = opts.recordProposal ? opts.recordProposal(proposal) : proposal;
+    const reason = typeof opts.reason === "function" ? opts.reason(proposal) : opts.reason;
+    // setCeremonyLevel enforces this too, but only after files exist; check first.
+    if (level !== undefined && proposal.level !== null && level < proposal.level && !reason) {
+        throw new Error(`level ${level} is below the proposed level (${proposal.level}); pass a reason to confirm it`);
+    }
+    const files = opts.artifacts({ name, proposal, level });
+    fs.mkdirSync(path.join(changeDir, "reports"), { recursive: true });
+    for (const [rel, content] of Object.entries(files)) {
+        const abs = path.join(changeDir, rel);
+        fs.mkdirSync(path.dirname(abs), { recursive: true });
+        fs.writeFileSync(abs, content);
+    }
+    fs.writeFileSync(path.join(changeDir, "reports", "README.md"), opts.reportsReadme);
+    let record;
+    if (level === undefined) {
+        record = opts.changeType ? { ...stored, changeType: opts.changeType } : { ...stored };
+        fs.writeFileSync(path.join(changeDir, "change.json"), JSON.stringify(record, null, 2) + "\n");
+    }
+    else {
+        let confirmed = setCeremonyLevel(projectPath, name, {
+            proposal: stored,
+            level,
+            confirmedBy: "human",
+            reason,
+        });
+        if (opts.changeType) {
+            confirmed = { ...confirmed, changeType: opts.changeType };
+            writeCeremonyRecord(projectPath, name, confirmed);
+        }
+        record = confirmed;
+    }
+    return {
+        change: name,
+        proposal,
+        record,
+        dir: changeDir,
+        level: level ?? null,
+        changeType: opts.changeType ?? "feature",
+        files: [...Object.keys(files), "reports/README.md", "change.json"],
+    };
+}
+const featureRecordMd = (name, level, proposal) => `# ${name}
+
+**Level:** ${level} (proposed: ${proposal.level ?? "n/a"}, confirmed by: human)
+**Why:** ${proposal.rationale}
+
+## What changes
+
+<!-- 2–5 lines: what and why. -->
+
+## Steps
+
+- [ ] Make the change
+- [ ] Add or update tests
+- [ ] Record evidence under reports/
+
+## Evidence
+
+- \`reports/\` — add a discipline report before archive
+`;
+const featureTasksMd = (name) => `# Tasks — ${name}
+
+## 0. Branch
+
+- [ ] 0.1 Create or check out the feature branch
+
+## 1. Implementation
+
+- [ ] 1.1 Implement the change
+
+## 2. Verification
+
+- [ ] 2.1 Review and update the affected tests
+- [ ] 2.2 Run the quality gates and verify they pass
+- [ ] 2.3 Write the discipline reports under reports/
+- [ ] 2.4 Archive the change within the same PR
+`;
+const featureProposalMd = (name) => `# ${name}
+
+## Why
+
+<!-- The problem and who it affects. -->
+
+## What changes
+
+<!-- The behavior after this change. -->
+
+## Impact
+
+<!-- Capabilities, modules, and APIs touched. -->
+`;
+const featureDesignMd = (name) => `# Design — ${name}
+
+## Approach
+
+<!-- Module boundaries, data flow, and decisions. -->
+`;
+/**
+ * Marks an unedited delta stub. Validate warns while it is present and sync
+ * refuses to promote it, so a placeholder capability is never synced silently.
+ */
+export const PLACEHOLDER_DELTA_MARKER = "<!-- speclaw:placeholder-delta -->";
+const PLACEHOLDER_LINE_RE = /^<!-- speclaw:placeholder-delta -->[ \t]*$/m;
+/**
+ * True when a delta still carries the placeholder marker on a line of its own.
+ * Prose that quotes the marker inline (e.g. in backticks) does not count, so a
+ * spec documenting the marker is never mistaken for a placeholder.
+ *
+ * @param content - Delta spec text.
+ */
+export function isPlaceholderDelta(content) {
+    return PLACEHOLDER_LINE_RE.test(content);
+}
+/** Starting delta for a capability with no canonical spec yet (a placeholder). */
+const featureDeltaMd = (capability, change) => `# ${capability}
+
+${PLACEHOLDER_DELTA_MARKER}
+<!-- Placeholder delta for change ${change}. Replace it with the capability's
+     full intended spec (sync overwrites the canonical spec with this file) and
+     delete the marker above, or delete this file if the change targets another
+     capability (pass --capability <name> when drafting). -->
+
+### Requirement: ${capability} behavior
+
+The system SHALL provide the behavior described in \`proposal.md\` for ${change}.
+
+#### Scenario: The change's behavior is observable
+- Given the change ${change} is implemented
+- When the behavior is exercised
+- Then the outcome described in \`proposal.md\` is observed
+`;
+/**
+ * Stub artifacts for a feature change at `level` (none when unconfirmed).
+ *
+ * Every level gets what `artifactNeeds` requires, so a fresh draft validates:
+ * level 2 includes a `design.md` stub (rather than a record justification),
+ * and levels 1–3 include a delta under `specs/<capability>/spec.md`.
+ *
+ * @param name - Change name.
+ * @param level - Confirmed level, or `undefined` for no stubs.
+ * @param proposal - Proposal quoted in `record.md`.
+ * @param delta - Capability and starting content for the delta (levels 1–3).
+ */
+export function featureStubs(name, level, proposal, delta = {
+    capability: name,
+    content: featureDeltaMd(name, name),
+}) {
+    const spec = { [`specs/${delta.capability}/spec.md`]: delta.content };
+    switch (level) {
+        case 0:
+            return { "record.md": featureRecordMd(name, 0, proposal) };
+        case 1:
+            return {
+                "record.md": featureRecordMd(name, 1, proposal),
+                "tasks.md": featureTasksMd(name),
+                ...spec,
+            };
+        case 2:
+        case 3:
+            return {
+                "proposal.md": featureProposalMd(name),
+                "design.md": featureDesignMd(name),
+                "tasks.md": featureTasksMd(name),
+                ...spec,
+            };
+        default:
+            return {};
+    }
+}
+/**
+ * Scaffold a feature change (`speclaw lawbook draft <name>` / `lawbook_change` `draft`).
+ *
+ * With `level`, the level is confirmed and its stubs are written; without it,
+ * `change.json` carries only the proposal and `changeType`, so validate applies
+ * level-3 rules until `lawbook level set` confirms one. The delta stub targets
+ * `capability` (default: the change name); when that capability already has a
+ * canonical spec, the delta starts from a copy of it, so an unedited sync
+ * changes nothing.
+ *
+ * @param projectPath - Project root with `lawbook/`.
+ * @param name - Change folder name (kebab-case).
+ * @param opts - Optional level, override reason, delta capability, and targets.
+ * @throws When `capability` is not kebab-case (plus every `scaffoldChange` refusal).
+ */
+export function scaffoldFeature(projectPath, name, opts = {}) {
+    // Only feature drafts enforce kebab-case: quick and bug drafts keep their
+    // pre-existing (unvalidated) naming so their outputs stay unchanged.
+    if (!CHANGE_NAME_RE.test(name)) {
+        throw new Error(`change name "${name}" must be kebab-case (e.g. add-widget)`);
+    }
+    const capability = opts.capability ?? name;
+    if (!CHANGE_NAME_RE.test(capability)) {
+        throw new Error(`capability "${capability}" must be kebab-case (e.g. widgets)`);
+    }
+    const canonical = path.join(projectPath, "lawbook", "specs", capability, "spec.md");
+    const content = fs.existsSync(canonical)
+        ? fs.readFileSync(canonical, "utf8")
+        : featureDeltaMd(capability, name);
+    return scaffoldChange(projectPath, name, {
+        changeType: "feature",
+        targets: opts.targets,
+        level: opts.level,
+        reason: opts.reason,
+        reportsReadme: `# Reports — ${name}\n\nAdd at least one discipline report before archive.\n`,
+        artifacts: ({ level, proposal }) => featureStubs(name, level, proposal, { capability, content }),
+    });
+}

package/dist/shared/compass-calls.js

@@ -0,0 +1,197 @@
+import fs from "node:fs";
+import path from "node:path";
+// Covers: req~compass-call-log~1
+/** Live call-log file name under `.speclaw/`. */
+export const COMPASS_CALL_LOG = "compass-calls.jsonl";
+/** The live log rotates to `.1` once it grows past this many bytes. */
+export const CALL_LOG_ROTATE_BYTES = 256 * 1024;
+/** Readers never look further back than this many bytes of the live log. */
+export const CALL_LOG_READ_BYTES = 64 * 1024;
+/**
+ * Compass tools whose calls count as "looked through the graph" evidence.
+ * `compass_index` and nudge entries are logged too but are not evidence.
+ */
+export const EVIDENCE_TOOLS = new Set([
+    "compass_explore",
+    "compass_find",
+    "compass_diff_context",
+    "compass_impact",
+    "compass_trace",
+    "compass_search",
+    "compass_recall",
+]);
+/** Tool name the Compass-first nudge records for its rate limit. */
+export const NUDGE_ENTRY = "nudge";
+/** True when `tool` counts as Compass evidence. */
+export function isEvidenceTool(tool) {
+    return EVIDENCE_TOOLS.has(tool);
+}
+function logPath(projectPath) {
+    return path.join(projectPath, ".speclaw", COMPASS_CALL_LOG);
+}
+/**
+ * Rotate the live log to `.1` when it is over the cap, tolerating a race with
+ * other processes doing the same.
+ *
+ * The live file is first renamed to a name unique to this process, so two
+ * rotators can never both move the same file onto `.1`. If what was claimed is
+ * not over the cap, another process rotated first and this one grabbed its
+ * fresh live file: those lines are appended back to the live log instead of
+ * replacing `.1`, so `.1` always holds a full previous generation and no
+ * recent entry disappears. A missing live file (lost race) is ignored.
+ *
+ * @param file - Absolute path of the live log.
+ */
+export function rotateCallLog(file) {
+    const claimed = `${file}.${process.pid}.${Date.now()}.${Math.random().toString(36).slice(2)}.tmp`;
+    try {
+        fs.renameSync(file, claimed);
+    }
+    catch {
+        return; // nothing to rotate, or another process already took it
+    }
+    try {
+        if (fs.statSync(claimed).size > CALL_LOG_ROTATE_BYTES) {
+            fs.renameSync(claimed, `${file}.1`);
+            return;
+        }
+        fs.appendFileSync(file, fs.readFileSync(claimed));
+        fs.rmSync(claimed, { force: true });
+    }
+    catch {
+        /* best-effort: a leftover .tmp is harmless and never read */
+    }
+}
+/**
+ * Append one `{at, tool}` line to `.speclaw/compass-calls.jsonl`.
+ *
+ * Best effort: creates `.speclaw/` when missing, rotates the live log to
+ * `.jsonl.1` (replacing any earlier generation) when it exceeds 256 KiB — see
+ * {@link rotateCallLog} — and never throws: a failed write must not fail or
+ * delay the Compass tool.
+ *
+ * @param projectPath - Project root.
+ * @param tool - MCP tool name the call maps to.
+ * @param at - Call time; defaults to now.
+ */
+export function recordCompassCall(projectPath, tool, at = new Date()) {
+    try {
+        const file = logPath(projectPath);
+        fs.mkdirSync(path.dirname(file), { recursive: true });
+        let size = 0;
+        try {
+            size = fs.statSync(file).size;
+        }
+        catch {
+            /* no live log yet */
+        }
+        if (size > CALL_LOG_ROTATE_BYTES)
+            rotateCallLog(file);
+        fs.appendFileSync(file, JSON.stringify({ at: at.toISOString(), tool }) + "\n", "utf8");
+    }
+    catch {
+        /* best-effort */
+    }
+}
+/** Read the last `maxBytes` of `file`; `fromStart` when the whole file was read. */
+function readTail(file, maxBytes) {
+    let fd;
+    try {
+        fd = fs.openSync(file, "r");
+        const size = fs.fstatSync(fd).size;
+        // Read one byte before the window so a cut that lands exactly on a line
+        // boundary keeps that whole first line.
+        const start = Math.max(0, size - maxBytes - 1);
+        const len = size - start;
+        const buf = Buffer.alloc(len);
+        fs.readSync(fd, buf, 0, len, start);
+        let raw = buf.toString("utf8");
+        // Mid-file: everything up to the first newline is a partial (or the extra
+        // boundary byte) and is dropped.
+        if (start > 0) {
+            const nl = raw.indexOf("\n");
+            raw = nl === -1 ? "" : raw.slice(nl + 1);
+        }
+        return { raw, fromStart: start === 0 };
+    }
+    catch {
+        return null;
+    }
+    finally {
+        if (fd !== undefined) {
+            try {
+                fs.closeSync(fd);
+            }
+            catch {
+                /* ignore */
+            }
+        }
+    }
+}
+/** Parse log lines, skipping malformed ones. */
+function parseLines(raw) {
+    const out = [];
+    for (const line of raw.split("\n")) {
+        if (!line.trim())
+            continue;
+        let row;
+        try {
+            row = JSON.parse(line);
+        }
+        catch {
+            continue;
+        }
+        if (!row || typeof row !== "object")
+            continue;
+        const { at, tool } = row;
+        if (typeof at !== "string" || typeof tool !== "string")
+            continue;
+        const ms = Date.parse(at);
+        if (Number.isNaN(ms))
+            continue;
+        out.push({ at, tool, ms });
+    }
+    return out;
+}
+/**
+ * Read the bounded tail of the call log.
+ *
+ * Reads at most `maxBytes` from the end of the live file, drops a partial
+ * first line, and skips lines that fail to parse. When the whole live file fit
+ * in that window but does not reach back to `sinceMs` (or no `sinceMs` was
+ * given), the tail of the previous generation `.1` is read too — at most
+ * another `maxBytes` — so a rotation never hides evidence from the current
+ * window. Returns `[]` when no log exists.
+ *
+ * @param projectPath - Project root.
+ * @param opts - Optional `sinceMs` filter and per-generation tail size.
+ */
+export function readCompassCalls(projectPath, opts = {}) {
+    const maxBytes = Math.max(1, opts.maxBytes ?? CALL_LOG_READ_BYTES);
+    const file = logPath(projectPath);
+    const live = readTail(file, maxBytes);
+    const liveRows = live ? parseLines(live.raw) : [];
+    let rows = liveRows;
+    const oldest = liveRows.length ? Math.min(...liveRows.map((r) => r.ms)) : Infinity;
+    const reachesSince = opts.sinceMs !== undefined && oldest <= opts.sinceMs;
+    if ((!live || live.fromStart) && !reachesSince) {
+        const prev = readTail(`${file}.1`, maxBytes);
+        if (prev)
+            rows = [...parseLines(prev.raw), ...liveRows];
+    }
+    const out = [];
+    for (const { at, tool, ms } of rows) {
+        if (opts.sinceMs !== undefined && ms < opts.sinceMs)
+            continue;
+        out.push({ at, tool });
+    }
+    return out;
+}
+/** Count evidence calls in `calls`. */
+export function countEvidence(calls) {
+    let n = 0;
+    for (const c of calls)
+        if (isEvidenceTool(c.tool))
+            n++;
+    return n;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@esneiderbravo/speclaw",
-  "version": "2.0.2",
+  "version": "2.0.4",
   "publishConfig": {
     "access": "public"
   },