gcf-aif-ext 0.2.5 → 0.3.0

package/lib/unit-ops.js

@@ -0,0 +1,270 @@
+// The moves a design unit makes out of design/ (GCF-PRD §4): `take` into a card, `done` into
+// tests and code, `drop` into the graveyard. Each one removes the section and its backlog line
+// in the same step, so an id never lives in two places (M12).
+import { readFile, unlink } from 'node:fs/promises';
+import { existsSync, readFileSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import path from 'node:path';
+import { serialize } from './frontmatter.js';
+import { CARD_TYPES, listOf } from './design.js';
+import { buildLedger } from './ledger.js';
+import { designCheck } from './design-check.js';
+import { atomicWrite, withFileRollback } from './safe-path.js';
+import { writeIndex } from './index-gen.js';
+import { operationInProgress, commitPaths } from './git.js';
+import { upsertBlock, openSystemDoc } from './systems-doc.js';
+import { buryLine, recordLine } from './verdict-fs.js';
+
+/** A design file's text without the `## <id>` section. */
+export function removeUnit(text, id) {
+  const lines = String(text).split('\n');
+  const at = lines.findIndex((l) => l.trimEnd() === `## ${id}`);
+  if (at < 0) return text;
+  let end = lines.findIndex((l, i) => i > at && /^## \S/.test(l));
+  if (end < 0) end = lines.length;
+
+  return `${[...lines.slice(0, at), ...lines.slice(end)]
+    .join('\n')
+    .replace(/\n{3,}/g, '\n\n')
+    .trimEnd()}\n`;
+}
+
+/** backlog.md without the line of `id`. */
+export const backlogWithout = (text, id) =>
+  String(text)
+    .split('\n')
+    .filter((l) => l.match(/^- (\S+)/)?.[1] !== id)
+    .join('\n');
+
+/** The single design unit `id`, or an error naming where the id lives instead. */
+async function designUnit(projectDir, id) {
+  const ledger = await buildLedger(projectDir);
+  const { live, terminal } = ledger.where(id);
+  if (live.length !== 1 || live[0].state !== 'design') {
+    const at = live.map((p) => p.file).join(', ') || terminal.join(', ') || 'nowhere';
+    throw new Error(`${id} is not a single unit of gcf/design/ (it is: ${at})`);
+  }
+
+  const unit = ledger.design.flatMap((d) => d.units).find((u) => u.id === id);
+
+  return /** @type {import('./design.js').Unit} */ (unit);
+}
+
+/** Files a move rewrites: the design file, the backlog, then whatever the move adds. */
+function basePaths(root, unit) {
+  return { design: path.join(root, unit.file), backlog: path.join(root, 'backlog.md') };
+}
+
+async function cutUnit(paths, id) {
+  await atomicWrite(paths.design, removeUnit(await readFile(paths.design, 'utf8'), id));
+  if (existsSync(paths.backlog))
+    await atomicWrite(paths.backlog, backlogWithout(await readFile(paths.backlog, 'utf8'), id));
+}
+
+/** The frontmatter a card starts with: the unit's header plus the fields of the card stage. */
+function cardData(unit, today) {
+  const h = unit.header;
+  const pillars = listOf(h.pillars);
+
+  return {
+    schema: 2,
+    id: unit.id,
+    type: h.type,
+    ...(h.title ? { title: h.title } : {}),
+    status: 'proposed',
+    system: listOf(h.system),
+    depends: listOf(h.depends),
+    pillars: pillars === 'TBD' ? [] : pillars,
+    source: h.source,
+    ...(h.reopens ? { reopens: h.reopens } : {}),
+    tune_count: 0,
+    built_at: null,
+    created: today,
+  };
+}
+
+/**
+ * Take a ready soft unit into work: its section becomes cards/<id>.md with the same body.
+ * No commit — `/gcf-card` adds `contract` and `interactions`, and the pre-commit gate holds
+ * the card until it carries both.
+ */
+export async function takeUnit(
+  projectDir,
+  id,
+  { today = new Date().toISOString().slice(0, 10) } = {},
+) {
+  const root = path.join(path.resolve(projectDir), 'gcf');
+  const unit = await designUnit(projectDir, id);
+  if (!CARD_TYPES.includes(unit.header.type)) {
+    throw new Error(
+      `${id} is hard: close its TBD in place, run the AIF cycle, then gcf done ${id}`,
+    );
+  }
+
+  const summary = (await designCheck(projectDir)).units.find((u) => u.id === id);
+  if (!summary?.ready) {
+    const why = summary?.blocked_by.length
+      ? `blocked by ${summary.blocked_by.join(', ')}`
+      : `${summary?.tbd ?? '?'} TBD or a blocking design-check finding`;
+    throw new Error(`${id} is not ready (${why}): answer it in design/ first`);
+  }
+
+  const paths = { ...basePaths(root, unit), card: path.join(root, 'cards', `${id}.md`) };
+  if (existsSync(paths.card)) throw new Error(`gcf/cards/${id}.md already exists`);
+  await withFileRollback([...Object.values(paths), path.join(root, 'INDEX.md')], async () => {
+    await atomicWrite(paths.card, serialize(cardData(unit, today), `\n${unit.body.trim()}\n`));
+    await cutUnit(paths, id);
+    await writeIndex(root);
+  });
+
+  return { card: `gcf/cards/${id}.md` };
+}
+
+/** A file's text at a git revision spec (`HEAD:./x`, `:./x` for the index), '' when absent. */
+function gitText(projectDir, spec) {
+  const res = spawnSync('git', ['show', spec], { cwd: projectDir, encoding: 'utf8' });
+
+  return res.status === 0 ? res.stdout : '';
+}
+
+/**
+ * True when `file` differs from HEAD in the index or on disk. Line endings do not count: a file
+ * stored with CRLF and checked out with LF is not an edit.
+ */
+function uncommitted(projectDir, file) {
+  const rel = `./${path.relative(projectDir, file).replaceAll('\\', '/')}`;
+  const norm = (t) => String(t).replace(/\r\n/g, '\n').trimEnd();
+  const head = norm(gitText(projectDir, `HEAD:${rel}`));
+  const disk = norm(existsSync(file) ? readFileSync(file, 'utf8') : '');
+
+  return head !== norm(gitText(projectDir, `:${rel}`)) || head !== disk;
+}
+
+/**
+ * Run a move that ends with its fixed-format commit, all of it or none of it. The commit takes
+ * whole files and deletes the unit's section, so any uncommitted edit in them refuses the move
+ * up front — an answer in the unit itself included: it would leave in a commit that never held
+ * it, and no history would keep it.
+ */
+async function commitMove(projectDir, message, { files, mutate, commit }) {
+  const busy = commit ? operationInProgress(projectDir) : null;
+  if (busy) throw new Error(`cannot record ${message} while ${busy} is in progress`);
+  const dirty = commit ? files.filter((f) => uncommitted(projectDir, f)) : [];
+  if (dirty.length) {
+    const names = dirty.map((f) => path.relative(projectDir, f)).join(', ');
+    throw new Error(
+      `commit or stash these first (an answered unit is committed before its move), ` +
+        `${message} would carry them: ${names}`,
+    );
+  }
+
+  const root = path.join(path.resolve(projectDir), 'gcf');
+  const touched = [...files, path.join(root, 'INDEX.md')];
+  /** @type {string | null} */
+  let hash = null;
+  await withFileRollback(
+    touched,
+    async () => {
+      await mutate();
+      await writeIndex(root);
+      if (commit) hash = commitPaths(projectDir, message, touched);
+    },
+    { gitCwd: commit ? path.resolve(projectDir) : null },
+  );
+
+  return hash;
+}
+
+/**
+ * A hard unit is built and its tests are green: it leaves design/. A line every future reader
+ * of the subsystem must remember goes to the systems doc's `constraints:` (GCF-PRD §6.3).
+ */
+export async function doneUnit(projectDir, id, { constraints = [], commit = true } = {}) {
+  const root = path.join(path.resolve(projectDir), 'gcf');
+  const unit = await designUnit(projectDir, id);
+  if (CARD_TYPES.includes(unit.header.type))
+    throw new Error(`${id} is soft: it leaves design/ through a card and a verdict`);
+  const summary = (await designCheck(projectDir)).units.find((u) => u.id === id);
+  if (summary?.tbd)
+    throw new Error(`${id} still carries ${summary.tbd} TBD: it was built on a hole — answer it`);
+  const paths = basePaths(root, unit);
+  const doc = constraints.length ? await openSystemDoc(root, unit.system) : null;
+  const files = [paths.design, paths.backlog, path.join(root, 'history.md')];
+  if (doc) files.push(doc.file);
+  const mutate = async () => {
+    await cutUnit(paths, id);
+    await recordLine(root, id, 'done');
+    if (!doc) return;
+    const body = upsertBlock(
+      doc.body,
+      'constraints',
+      constraints.map((c) => `- ${c}`),
+    );
+    await atomicWrite(doc.file, serialize({ ...doc.data, updated_by: id }, body));
+  };
+
+  return {
+    id,
+    hash: await commitMove(projectDir, `gcf(done): ${id}`, { files, mutate, commit }),
+  };
+}
+
+/**
+ * A card taken into work but never built is given up: no playtest, so no verdict — a drop. Its
+ * file goes, the graveyard keeps the reason. A built card waits for its verdict instead.
+ */
+async function dropCard(projectDir, card, { reason, tags, commit }) {
+  const root = path.join(path.resolve(projectDir), 'gcf');
+  const id = String(card.data.id);
+  if (!['proposed', 'tuning'].includes(card.data.status))
+    throw new Error(`${id} is ${card.data.status}: play it and give the verdict, kill included`);
+  const rel = `./${path.relative(projectDir, card.file).replaceAll('\\', '/')}`;
+  if (commit && !gitText(projectDir, `HEAD:${rel}`)) {
+    throw new Error(
+      `${id} was taken but its card is not committed: commit it first, or undo the take ` +
+        `(delete the card, restore its section in gcf/design/ and its backlog line)`,
+    );
+  }
+
+  const files = [card.file, path.join(root, 'graveyard.md')];
+  const mutate = async () => {
+    await buryLine(root, id, reason, tags.length ? tags : (card.data.system ?? []));
+    await unlink(card.file);
+  };
+
+  return {
+    id,
+    hash: await commitMove(projectDir, `gcf(drop): ${id}`, { files, mutate, commit }),
+  };
+}
+
+/**
+ * A unit — or a card not yet built — is dropped before any playtest: a graveyard line keeps the
+ * reason (GCF-PRD §5.6).
+ */
+export async function dropUnit(projectDir, id, { reason, tags = [], commit = true }) {
+  if (!String(reason ?? '').trim())
+    throw new Error('a drop needs a reason: the graveyard keeps it');
+  const ledger = await buildLedger(projectDir);
+  const live = ledger.where(id).live;
+  if (live.length === 1 && live[0].state === 'card') {
+    const card = ledger.cards.find((c) => c.data.id === id);
+
+    return dropCard(projectDir, card, { reason, tags, commit });
+  }
+
+  const root = path.join(path.resolve(projectDir), 'gcf');
+  const unit = await designUnit(projectDir, id);
+  const paths = basePaths(root, unit);
+  const system = listOf(unit.header.system);
+  const files = [paths.design, paths.backlog, path.join(root, 'graveyard.md')];
+  const mutate = async () => {
+    await buryLine(root, id, reason, tags.length ? tags : system === 'TBD' ? [] : system);
+    await cutUnit(paths, id);
+  };
+
+  return {
+    id,
+    hash: await commitMove(projectDir, `gcf(drop): ${id}`, { files, mutate, commit }),
+  };
+}

package/lib/validate-card.js

@@ -1,37 +1,77 @@
 // Runtime mirror of schemas/card.schema.json for the pre-commit hook (no ajv in
 // production deps). The parity test keeps the two in agreement.
-const FIELDS = ['schema', 'id', 'slug', 'status', 'route', 'system', 'depends', 'source', 'tune_count', 'built_at', 'created'];
-const REQUIRED = FIELDS.filter((f) => f !== 'built_at');
+const FIELDS = [
+  'schema',
+  'id',
+  'type',
+  'title',
+  'status',
+  'system',
+  'depends',
+  'pillars',
+  'source',
+  'reopens',
+  'tune_count',
+  'built_at',
+  'created',
+];
+const OPTIONAL = ['title', 'reopens', 'built_at'];
+const REQUIRED = FIELDS.filter((f) => !OPTIONAL.includes(f));
+const SLUG = /^[a-z0-9]+(-[a-z0-9]+)*$/;
+const slugList = (v) => Array.isArray(v) && v.every((s) => SLUG.test(s));
+const text = (v) => (typeof v === 'string' && v.length > 0) || 'must be a non-empty string';
 
 const RULES = {
-  schema: (v) => v === 1 || 'schema must be 1',
-  id: (v) => /^card-\d{3}$/.test(v) || 'id must match card-NNN',
-  slug: (v) => /^[a-z0-9]+(-[a-z0-9]+)*$/.test(v) || 'slug must be a lowercase hyphen slug',
-  status: (v) => ['proposed', 'built', 'tuning'].includes(v) || `status "${v}" is not storable (П1: terminal statuses never live in a file)`,
-  route: (v) => ['soft', 'hard'].includes(v) || 'route must be soft or hard',
-  system: (v) => (Array.isArray(v) && v.length >= 1 && v.every((s) => /^[a-z0-9]+(-[a-z0-9]+)*$/.test(s))) || 'system must list >=1 subsystem slugs',
-  depends: (v) => (Array.isArray(v) && v.every((d) => /^card-\d{3}$/.test(d))) || 'depends must list card-NNN ids',
-  source: (v) => /^(GDD#[A-Za-z0-9_-]+|manual|inferred)$/.test(v) || 'source must be GDD#<id>, manual or inferred',
+  // Schema 1 cards (`card-NNN` ids, `slug`, `route`) predate the Design Model: say how to move.
+  schema: (v) =>
+    v === 2 ||
+    (v === 1
+      ? 'schema 1 card: rename the file to cards/<slug>.md, set id: <slug>, drop slug and route, ' +
+        'add type: mechanic and pillars: [], set schema: 2'
+      : 'schema must be 2'),
+  id: (v) => SLUG.test(v) || 'id must be a lowercase hyphen slug',
+  type: (v) =>
+    ['mechanic', 'resource'].includes(v) ||
+    'type must be mechanic or resource (a hard unit never becomes a card)',
+  title: (v) => text(v) === true || `title ${text(v)}`,
+  status: (v) =>
+    ['proposed', 'built', 'tuning'].includes(v) ||
+    `status "${v}" is not storable (П1: terminal statuses never live in a file)`,
+  system: (v) => (slugList(v) && v.length >= 1) || 'system must list >=1 subsystem slugs',
+  depends: (v) => slugList(v) || 'depends must list unit ids',
+  pillars: (v) => slugList(v) || 'pillars must list pillar ids',
+  source: (v) => /^(GDD#[A-Za-z0-9_-]+|manual)$/.test(v) || 'source must be GDD#<id> or manual',
+  reopens: (v) => text(v) === true || `reopens ${text(v)}`,
   tune_count: (v) => (Number.isInteger(v) && v >= 0) || 'tune_count must be an integer >= 0',
-  built_at: (v) => v === null || v === undefined || /^[0-9a-f]{7,40}$/.test(v) || 'built_at must be null or a commit hash',
+  built_at: (v) =>
+    v === null ||
+    v === undefined ||
+    /^[0-9a-f]{7,40}$/.test(v) ||
+    'built_at must be null or a commit hash',
   created: (v) => /^\d{4}-\d{2}-\d{2}$/.test(dateStr(v)) || 'created must be YYYY-MM-DD',
 };
 
 const dateStr = (v) => (v instanceof Date ? v.toISOString().slice(0, 10) : String(v));
 
-const UNTIL_OK = /^\[until:\s*(verdict\(card-\d{3}\)|retune\([a-z0-9-]+\)|manual\([^)]*\))\]$/;
+const UNTIL_OK = /^\[until:\s*(verdict\([a-z0-9-]+\)|retune\([a-z0-9-]+\)|manual\([^)]*\))\]$/;
 
 /** Validate card frontmatter. Returns a list of one-line errors (empty = valid). */
 export function validateCard(data) {
   const errors = [];
+  if (data.schema !== undefined && data.schema !== 2) return [RULES.schema(data.schema)];
   for (const key of REQUIRED) if (!(key in data)) errors.push(`missing field: ${key}`);
   for (const key of Object.keys(data)) {
-    if (!FIELDS.includes(key)) errors.push(`unknown field: ${key}${key === 'until' ? ' (until: is a line annotation, not frontmatter)' : ''}`);
+    if (!FIELDS.includes(key))
+      errors.push(
+        `unknown field: ${key}` +
+          (key === 'until' ? ' (until: is a line annotation, not frontmatter)' : ''),
+      );
     else if (key in RULES) {
       const res = RULES[key](data[key]);
       if (res !== true) errors.push(res);
     }
   }
+
   return errors;
 }
 
@@ -41,8 +81,13 @@ export function validateUntil(body) {
   const lines = String(body).split('\n');
   lines.forEach((line, i) => {
     for (const m of line.matchAll(/\[until:[^\]]*\]/g)) {
-      if (!UNTIL_OK.test(m[0])) errors.push(`line ${i + 1}: bad until annotation ${m[0]} (use verdict(card-NNN), retune(system) or manual(text))`);
+      if (!UNTIL_OK.test(m[0]))
+        errors.push(
+          `line ${i + 1}: bad until annotation ${m[0]} ` +
+            '(use verdict(<id>), retune(system) or manual(text))',
+        );
     }
   });
+
   return errors;
 }