changeledger 0.3.0

package/src/atomic-write.mjs

@@ -0,0 +1,134 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+let counter = 0;
+// Timeout-based staleness: a lock is stale if it's held for longer than
+// DEFAULT_LOCK_WAIT_MS. Simpler and portable, appropriate for file-mutation
+// exclusion where contention is short-lived. Contrast with acquireIdLock in
+// new.mjs, which uses PID liveness — better for id-collision prevention across
+// processes where a lock might outlive a slow but still-running agent.
+const DEFAULT_LOCK_WAIT_MS = 5_000;
+const DEFAULT_LOCK_RETRY_MS = 10;
+
+export function writeFileAtomic(file, data, options = {}) {
+  const { encoding = 'utf8', fsImpl = fs } =
+    typeof options === 'string' ? { encoding: options } : options;
+  const dir = path.dirname(file);
+  const tmp = path.join(
+    dir,
+    `.${path.basename(file)}.${process.pid}.${Date.now()}.${counter++}.tmp`,
+  );
+  let fd = null;
+
+  try {
+    fd = fsImpl.openSync(tmp, 'wx');
+    fsImpl.writeFileSync(fd, data, { encoding });
+    fsImpl.fsyncSync(fd);
+    fsImpl.closeSync(fd);
+    fd = null;
+    fsImpl.renameSync(tmp, file);
+    fsyncDir(dir, fsImpl);
+  } catch (e) {
+    if (fd !== null) {
+      try {
+        fsImpl.closeSync(fd);
+      } catch {
+        // best effort cleanup below
+      }
+    }
+    try {
+      fsImpl.rmSync(tmp, { force: true });
+    } catch {
+      // preserve the original error
+    }
+    throw e;
+  }
+}
+
+export function mutateFileAtomic(file, mutate, options = {}) {
+  const { encoding = 'utf8', fsImpl = fs } = options;
+  return withFileLock(
+    file,
+    () => {
+      const before = fsImpl.readFileSync(file, encoding);
+      const after = mutate(before);
+      if (after === undefined) return undefined;
+      writeFileAtomic(file, after, { encoding, fsImpl });
+      return after;
+    },
+    options,
+  );
+}
+
+export function withFileLock(file, fn, options = {}) {
+  const { fsImpl = fs, waitMs = DEFAULT_LOCK_WAIT_MS, retryMs = DEFAULT_LOCK_RETRY_MS } = options;
+  const lock = lockPath(file);
+  const start = Date.now();
+  let fd = null;
+
+  while (fd === null) {
+    try {
+      fd = fsImpl.openSync(lock, 'wx');
+      try {
+        fsImpl.writeFileSync(
+          fd,
+          JSON.stringify({ pid: process.pid, created: new Date().toISOString() }),
+        );
+      } catch (e) {
+        cleanupLock(lock, fd, fsImpl);
+        fd = null;
+        throw e;
+      }
+    } catch (e) {
+      if (e.code !== 'EEXIST') throw e;
+      if (Date.now() - start > waitMs) {
+        throw new Error(`timed out waiting for lock ${lock}`);
+      }
+      sleepSync(retryMs);
+    }
+  }
+
+  try {
+    return fn();
+  } finally {
+    cleanupLock(lock, fd, fsImpl);
+  }
+}
+
+function lockPath(file) {
+  return path.join(path.dirname(file), `.${path.basename(file)}.lock`);
+}
+
+function cleanupLock(lock, fd, fsImpl) {
+  try {
+    fsImpl.closeSync(fd);
+  } finally {
+    try {
+      fsImpl.rmSync(lock, { force: true });
+    } catch {
+      // preserve the original result/error
+    }
+  }
+}
+
+function sleepSync(ms) {
+  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+
+function fsyncDir(dir, fsImpl) {
+  let fd = null;
+  try {
+    fd = fsImpl.openSync(dir, 'r');
+    fsImpl.fsyncSync(fd);
+  } catch {
+    // Some platforms/filesystems do not support directory fsync.
+  } finally {
+    if (fd !== null) {
+      try {
+        fsImpl.closeSync(fd);
+      } catch {
+        // best effort
+      }
+    }
+  }
+}

package/src/change.mjs

@@ -0,0 +1,102 @@
+// Parses a ChangeLedger change file: frontmatter + stages + tasks.
+// Stage bodies are kept raw (markdown) — the viewer renders them.
+
+import { parseYaml } from './yaml.mjs';
+
+const FRONTMATTER = /^---\n([\s\S]*?)\n---\n?/;
+const TASK = /^- \[( |x|!)\]\s+(.*)$/;
+const STATE_BY_MARK = { ' ': 'todo', x: 'done', '!': 'blocked' };
+
+export function parseChange(text) {
+  const fm = text.match(FRONTMATTER);
+  if (!fm) throw new Error('Change is missing its frontmatter block');
+  const frontmatter = parseYaml(fm[1]);
+  const body = text.slice(fm[0].length);
+
+  const stages = splitStages(body);
+  const plan = stages.find((s) => s.key === 'plan');
+  const tasks = plan ? parseTasks(plan.body) : [];
+  const spec = stages.find((s) => s.key === 'specification');
+  const criterionBlocks = spec ? parseCriteria(spec.body) : [];
+  const criteria = criterionBlocks.map((c) => c.id);
+  const progress = {
+    total: tasks.length,
+    done: tasks.filter((t) => t.state === 'done').length,
+    blocked: tasks.filter((t) => t.state === 'blocked').length,
+  };
+
+  return { frontmatter, stages, tasks, criteria, criterionBlocks, progress };
+}
+
+// Acceptance criteria declared in `## Specification` as `### CRn — name` blocks.
+function parseCriteria(specBody) {
+  const blocks = [];
+  let current = null;
+  for (const line of specBody.split('\n')) {
+    const m = line.match(/^###\s+(CR\d+)\b/);
+    if (m) {
+      current = { id: m[1], steps: [] };
+      blocks.push(current);
+      continue;
+    }
+    const step = line.match(/^-\s+\*\*(Given|When|Then|And)\*\*/);
+    if (current && step) current.steps.push(step[1]);
+  }
+  return blocks;
+}
+
+function splitStages(body) {
+  const stages = [];
+  let current = null;
+  let fence = null;
+  for (const line of body.split('\n')) {
+    const fenceMark = line.match(/^(`{3,}|~{3,})/);
+    if (fenceMark) {
+      if (!fence) fence = { char: fenceMark[1][0], length: fenceMark[1].length };
+      else if (fenceMark[1][0] === fence.char && fenceMark[1].length >= fence.length) fence = null;
+      if (current) current.body += `${line}\n`;
+      continue;
+    }
+
+    const m = fence ? null : line.match(/^##\s+(.+?)\s*$/);
+    if (m) {
+      current = { key: m[1].trim().toLowerCase(), heading: m[1].trim(), body: '' };
+      stages.push(current);
+    } else if (current) {
+      current.body += `${line}\n`;
+    }
+  }
+  for (const s of stages) s.body = s.body.trim();
+  return stages;
+}
+
+function parseTasks(planBody) {
+  const tasks = [];
+  for (const line of planBody.split('\n')) {
+    const m = line.trim().match(TASK);
+    if (!m) continue;
+    const state = STATE_BY_MARK[m[1]];
+    let rest = m[2].trim();
+    let resolvedAt;
+    let reason;
+    let suffix;
+
+    const dash = rest.lastIndexOf(' — ');
+    if (dash !== -1) {
+      suffix = rest.slice(dash + 3).trim();
+      rest = rest.slice(0, dash).trim();
+      if (state === 'done') resolvedAt = suffix;
+      else if (state === 'blocked') reason = suffix;
+    }
+
+    let criteria = [];
+    const crMatch = rest.match(/\(([^)]*\bCR\d+[^)]*)\)\s*$/);
+    if (crMatch) {
+      criteria = crMatch[1].match(/CR\d+/g) ?? [];
+      rest = rest.slice(0, crMatch.index).trim();
+    }
+
+    tasks.push({ text: rest, state, criteria, resolvedAt, reason, suffix });
+  }
+  return tasks;
+}