projectstore-codex 0.0.1 → 0.28.1

package/node_modules/projectstore/scripts/codemap.mjs

@@ -0,0 +1,99 @@
+#!/usr/bin/env node
+// projectstore — codemap.mjs
+// Derives code-map.md — the epic↔code overview — from epic/story frontmatter
+// `code_refs` (ADR-004). Same one-way pattern as kanban.mjs: frontmatter is
+// the source of truth, this file is a regenerated view.
+//
+// Output: JSON { path, content, stats } — compute only. The applier is
+// reconcile.mjs --write (atomic replace, recompute-at-write), not the
+// harness: no Write-tool step remains in the derived-view flows.
+
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import { readConfig, loadLayout, folderByKind, parseFrontmatter, nowIso, isMain } from "./lib.mjs";
+
+function die(msg) {
+  process.stderr.write(`projectstore/codemap: ${msg}\n`);
+  process.exit(1);
+}
+
+function parseRefs(raw) {
+  if (!raw || raw === "[]") return [];
+  try {
+    const v = JSON.parse(raw);
+    return Array.isArray(v) ? v.filter((x) => typeof x === "string") : [];
+  } catch {
+    return [];
+  }
+}
+
+function main() {
+  const cfg = readConfig();
+  if (!cfg) die("No projectstore config. Run /projectstore:bind first.");
+  const layout = loadLayout(cfg.layout);
+  const folder = folderByKind(layout, "epic");
+  if (!folder) die("Layout has no epic folder — nothing to map.");
+
+  const root = join(cfg.vault_path, folder.path);
+  const epics = [];
+  const storyRows = [];
+  if (existsSync(root)) {
+    for (const id of readdirSync(root).sort()) {
+      const epicMd = join(root, id, "epic.md");
+      if (!existsSync(epicMd)) continue;
+      const fm = parseFrontmatter(readFileSync(epicMd, "utf8")).data;
+      epics.push({ id, title: fm.title || id, status: fm.status || "planned", refs: parseRefs(fm.code_refs) });
+      const storiesDir = join(root, id, "stories");
+      if (!existsSync(storiesDir)) continue;
+      for (const f of readdirSync(storiesDir).sort()) {
+        if (!f.endsWith(".md")) continue;
+        const sfm = parseFrontmatter(readFileSync(join(storiesDir, f), "utf8")).data;
+        const refs = parseRefs(sfm.code_refs);
+        if (refs.length) {
+          storyRows.push({ epic: id, story: f.replace(/\.md$/, ""), title: sfm.title || f, refs });
+        }
+      }
+    }
+  }
+
+  const lines = [
+    "---",
+    "",
+    "projectstore: derived",
+    // Full ISO, not date-only: freshness comparison on an active day is
+    // ill-defined otherwise (spec contract 6). Normalizers strip the line.
+    `generated_at: ${nowIso()}`,
+    "",
+    "---",
+    "",
+    "# Code map",
+    "",
+    "Epic ↔ code mapping, derived from frontmatter `code_refs` (source of truth).",
+    "Regenerate via `/projectstore:codemap`; edit refs via `/projectstore:codemap set`.",
+    "",
+    "| Epic | Title | Status | code_refs |",
+    "|------|-------|--------|-----------|",
+  ];
+  for (const e of epics) {
+    const refs = e.refs.length ? e.refs.map((r) => `\`${r}\``).join(", ") : "—";
+    lines.push(`| [[${folder.path}/${e.id}/epic\\|${e.id}]] | ${e.title} | ${e.status} | ${refs} |`);
+  }
+  if (storyRows.length) {
+    lines.push("", "## Story-level refs (files each story touched)", "",
+      "| Epic | Story | code_refs |", "|------|-------|-----------|");
+    for (const s of storyRows) {
+      lines.push(`| ${s.epic} | ${s.title} | ${s.refs.map((r) => `\`${r}\``).join(", ")} |`);
+    }
+  }
+  lines.push("");
+
+  process.stdout.write(JSON.stringify({
+    path: join(cfg.vault_path, "code-map.md"),
+    content: lines.join("\n"),
+    stats: { epics: epics.length, epics_with_refs: epics.filter((e) => e.refs.length).length, story_rows: storyRows.length },
+  }, null, 2) + "\n");
+}
+
+if (isMain(import.meta.url)) {
+  main();
+}

package/node_modules/projectstore/scripts/diff-refs.mjs

@@ -0,0 +1,127 @@
+#!/usr/bin/env node
+// projectstore — diff-refs.mjs (PS-SPEC story-009)
+// Computes the files a story touched, for the reviewer's proposed code_refs.
+// Our own extension: neither Backlog.md nor projectstore derived code mapping
+// from git before this. Pure compute — the write path stays
+// /projectstore:codemap set, approval-gated.
+//
+//   node diff-refs.mjs --since <iso-timestamp> [--range <git-range>]
+//
+// Range derivation is STORY-SCOPED: `--since` is the story's started_at (set
+// by /projectstore:story plan). Branch-wide ranges (merge-base..HEAD) are
+// deliberately not the default — shared feature branches over-attribute and
+// direct-to-main work yields an empty diff (research note, adoption item 3).
+// Output: { since, range, files, uncommitted, fallback } — fallback=true
+// means the caller must ask the user for an explicit range instead of
+// guessing.
+//
+// Git runs in the PROJECT (the directory the harness hands us), never the vault — the vault
+// is typically not a git repository.
+
+import { spawnSync } from "node:child_process";
+import { resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { projectRoot, SOURCE_IGNORE } from "./lib.mjs";
+
+// One definition, in lib.mjs, shared with the entry-rule hook and doctor —
+// three consumers of "is this a source file" that must not drift apart.
+const IGNORE = SOURCE_IGNORE;
+
+// The default 15 s is a batch budget — diff-refs runs off the hot path. A caller
+// on a user-facing path must pass its own: SessionStart's gather budget is 200 ms,
+// so a stalled git there would hold session start for fifteen seconds.
+export function gitIn(cwd, args, { timeout = 15000 } = {}) {
+  const r = spawnSync("git", args, {
+    cwd,
+    encoding: "utf8",
+    timeout,
+  });
+  return r.status === 0 ? r.stdout : null;
+}
+
+const git = (args) => gitIn(projectRoot(), args);
+
+// Doctor's only route to git. Kept here rather than in lib.mjs, whose header
+// pins it as dependency-free with no subprocess anywhere.
+export function uncommittedProjectFiles(cwd = projectRoot(), ignore = IGNORE) {
+  // A non-repository, a shallow clone with no HEAD, or a detached worktree with
+  // no commits all make these fail — null means "cannot tell", which is not the
+  // same as "nothing uncommitted" and must not be reported as a finding.
+  const tracked = gitIn(cwd, ["diff", "--name-only", "HEAD"]);
+  const untracked = gitIn(cwd, ["ls-files", "--others", "--exclude-standard"]);
+  if (tracked === null && untracked === null) return null;
+  return [...new Set([...(tracked || "").split("\n"), ...(untracked || "").split("\n")])]
+    .map((f) => f.trim())
+    .filter((f) => f && !ignore.some((rx) => rx.test(f)))
+    .sort();
+}
+
+// Newest commit timestamp, ms, or null when git cannot answer.
+export function lastCommitMs(cwd = projectRoot()) {
+  const out = gitIn(cwd, ["log", "-1", "--format=%cI"]);
+  if (!out) return null;
+  const t = Date.parse(out.trim());
+  return Number.isFinite(t) ? t : null;
+}
+
+function filterFiles(list) {
+  return [...new Set(list)]
+    .map((f) => f.trim())
+    .filter((f) => f && !IGNORE.some((rx) => rx.test(f)))
+    .sort();
+}
+
+function main() {
+  const args = process.argv.slice(2);
+  const since = args.includes("--since") ? args[args.indexOf("--since") + 1] : null;
+  const range = args.includes("--range") ? args[args.indexOf("--range") + 1] : null;
+
+  let committed = [];
+  let usedRange = null;
+  if (range) {
+    const out = git(["diff", "--name-only", range]);
+    if (out === null) {
+      process.stdout.write(JSON.stringify({ error: `git diff ${range} failed`, fallback: true }) + "\n");
+      return;
+    }
+    committed = out.split("\n");
+    usedRange = range;
+  } else if (since) {
+    // committer-date window; work committed before the story went in-progress
+    // is invisible by design (story-scoped attribution).
+    //
+    // A bare YYYY-MM-DD gets midnight appended, and it is not cosmetic. Git's
+    // approxidate reads a date with no time as THAT DATE AT THE CURRENT TIME OF
+    // DAY, so `--since=2026-09-08` run at 17:46 silently excludes everything
+    // committed earlier the same day. `started_at` is written as a bare date,
+    // so a story started and finished in one day proposed `files: []` and the
+    // caller had no way to tell that from "nothing was committed" (measured
+    // 2026-09-08: --since=2026-09-08 returned nothing while
+    // --since="2026-09-08 00:00" returned the day's commit).
+    const window = /^\d{4}-\d{2}-\d{2}$/.test(since) ? `${since} 00:00:00` : since;
+    const out = git(["log", `--since=${window}`, "--name-only", "--pretty=format:"]);
+    committed = out ? out.split("\n") : [];
+    usedRange = `--since=${window}`;
+  }
+
+  // ls-files --others expands untracked DIRECTORIES to individual files
+  // (porcelain would collapse them to "tests/") and needs no column slicing.
+  const uncommitted = filterFiles([
+    ...(git(["diff", "--name-only", "HEAD"]) || "").split("\n"),
+    ...(git(["ls-files", "--others", "--exclude-standard"]) || "").split("\n"),
+  ]);
+  const files = filterFiles(committed);
+
+  const fallback = !range && !since || (files.length === 0 && uncommitted.length === 0);
+  process.stdout.write(JSON.stringify({
+    since: since || null,
+    range: usedRange,
+    files,
+    uncommitted,
+    fallback,
+  }, null, 2) + "\n");
+}
+
+if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  main();
+}