gcf-aif-ext 0.2.5 → 0.3.0

package/lib/bundle.js

@@ -0,0 +1,275 @@
+// The structured entry (GCF-PRD §11.10): `design export` glues game.md, glossary.md and the
+// units into one bundle a designer edits; `design import` brings it back without a model.
+// Each part carries the hash it was exported with, so an import tells a designer's edit from
+// an edit made in gcf/ after the export — and never overwrites the second one silently.
+import { readFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { createHash } from 'node:crypto';
+import path from 'node:path';
+import { readDesign, SLUG_RE } from './design.js';
+import { buildLedger } from './ledger.js';
+import { designCheck } from './design-check.js';
+import { atomicWrite, withFileRollback, resolveInside } from './safe-path.js';
+import { writeIndex } from './index-gen.js';
+
+const DOCS = ['game', 'glossary'];
+// A part opens with a marker comment, not with a heading: a `# notes` line inside game.md or a
+// purpose is content, and a heading boundary would cut the document there.
+const PART_RE =
+  /^<!-- gcf:part (doc|system|unit) (\S+)(?: system=(\S+))?(?: base=([0-9a-f]{8}))? -->$/;
+const HELP =
+  '<!-- gcf:help edit inside a part; a new unit is a line ' +
+  '"gcf:part unit <id> system=<system>" in a comment like this one, ' +
+  'then "## <id>" and its text -->';
+export const hashOf = (text) =>
+  createHash('sha1').update(String(text).replace(/\r\n/g, '\n').trim()).digest('hex').slice(0, 8);
+
+/** The text of one unit as it stands in its design file: header and body, no heading. */
+function unitText(u) {
+  const header = Object.entries(u.header).map(([k, v]) => `${k}: ${v}`);
+
+  return `${header.join('\n')}\n\n${u.body.trim()}`.trim();
+}
+
+const purposeOf = (preamble) =>
+  preamble
+    .trimStart()
+    .replace(/^# .*\n?/, '')
+    .trim();
+
+/** Glue the design into one bundle; `system` or `milestone` narrows which units go in. */
+export async function exportBundle(projectDir, { system = null, milestone = null } = {}) {
+  const root = path.join(path.resolve(projectDir), 'gcf');
+  const design = (await readDesign(root)).filter((d) => !system || d.system === system);
+  const inScope = (u) => !milestone || u.header.milestone === milestone;
+  const ids = design.flatMap((d) => d.units.filter(inScope).map((u) => u.id));
+  const out = [`<!-- gcf:bundle ids=${ids.join(',')} -->`, HELP];
+  const part = (head, title, text) =>
+    out.push('', `<!-- gcf:part ${head} base=${hashOf(text)} -->`, ...title, text);
+  // A doc goes as it stands, its own heading included: a title added over it would be a second
+  // `# game` a designer deletes, and the import could not tell which one was the file's.
+  for (const name of DOCS) {
+    const file = path.join(root, `${name}.md`);
+    if (existsSync(file)) part(`doc ${name}`, [], (await readFile(file, 'utf8')).trim());
+  }
+
+  for (const d of design) {
+    part(`system ${d.system}`, [`# design: ${d.system}`, ''], purposeOf(d.preamble));
+    for (const u of d.units.filter(inScope)) {
+      part(`unit ${u.id} system=${d.system}`, [`## ${u.id}`, ''], unitText(u));
+    }
+  }
+
+  return `${out.join('\n')}\n`;
+}
+
+/** @typedef {{kind: string, name: string, system: ?string, base: ?string, lines: string[]}} Part */
+
+/** The heading export writes under a marker, for a reader; import drops it when it is there. */
+const titleOf = (p) =>
+  p.kind === 'doc' ? null : p.kind === 'system' ? `# design: ${p.name}` : `## ${p.name}`;
+
+/**
+ * A marker line read into an empty part, or null; `system` is the system part above it.
+ * @returns {Part | null}
+ */
+function partOf(line, system) {
+  const m = line.trimEnd().match(PART_RE);
+  if (!m) return null;
+  const owner = m[1] === 'unit' ? (m[3] ?? system) : m[1] === 'system' ? m[2] : null;
+
+  return { kind: m[1], name: m[2], system: owner, base: m[4] ?? null, lines: [] };
+}
+
+// Text no part owns — above the first marker, or a marker the editor mangled — would vanish
+// without a word: it is reported instead.
+const strayLine = (l, i, inPart) =>
+  /^<!-- gcf:part\b/.test(l) ||
+  (!inPart && i > 0 && l.trim() !== '' && !l.startsWith('<!-- gcf:help'));
+
+/** A bundle read back: the exported ids, the docs, and per system its purpose and units. */
+export function parseBundle(text) {
+  const lines = String(text).replace(/\r\n/g, '\n').split('\n');
+  const ids = (lines[0].match(/^<!-- gcf:bundle ids=(.*) -->$/)?.[1] ?? '')
+    .split(',')
+    .filter(Boolean);
+  /** @type {Part[]} */
+  const parts = [];
+  const stray = [];
+  /** @type {?string} */
+  let system = null;
+  for (const [i, l] of lines.entries()) {
+    const p = partOf(l, system);
+    if (p) {
+      if (p.kind === 'system') system = p.name;
+      parts.push(p);
+    } else if (strayLine(l, i, parts.length > 0)) stray.push(i + 1);
+    else parts.at(-1)?.lines.push(l);
+  }
+
+  return {
+    ids,
+    stray,
+    parts: parts.map((p) => {
+      const body = p.lines.join('\n').trim().split('\n');
+      if (body[0]?.trim() === titleOf(p)) body.shift();
+
+      return { ...p, text: body.join('\n').trim() };
+    }),
+  };
+}
+
+/** Three-way: what the bundle changed, against what gcf/ changed since the export. */
+function verdict(part, current) {
+  const mine = hashOf(part.text);
+  if (part.base === null) return current === null ? 'new' : 'taken';
+  if (mine === part.base) return 'same';
+  if (current === null) return 'gone';
+
+  return hashOf(current) === part.base ? 'apply' : 'conflict';
+}
+
+/** Current text of every importable part: docs, system purposes, units in design/. */
+async function currentParts(root) {
+  const cur = new Map();
+  for (const name of DOCS) {
+    const file = path.join(root, `${name}.md`);
+    if (existsSync(file)) cur.set(`doc:${name}`, (await readFile(file, 'utf8')).trim());
+  }
+
+  for (const d of await readDesign(root)) {
+    cur.set(`system:${d.system}`, purposeOf(d.preamble));
+    for (const u of d.units) cur.set(`unit:${u.id}`, unitText(u));
+  }
+
+  return cur;
+}
+
+/** A design file with the `## <id>` section replaced by `text`, or appended when absent. */
+function putUnit(fileText, id, text) {
+  const lines = fileText.split('\n');
+  const at = lines.findIndex((l) => l.trimEnd() === `## ${id}`);
+  const section = [`## ${id}`, '', ...text.split('\n'), ''];
+  if (at < 0) return `${fileText.trimEnd()}\n\n${section.join('\n')}`;
+  let end = lines.findIndex((l, i) => i > at && /^## \S/.test(l));
+  if (end < 0) end = lines.length;
+
+  return [...lines.slice(0, at), ...section, ...lines.slice(end)].join('\n');
+}
+
+/** A design file with its preamble purpose replaced; a title of the file's own stays. */
+function putPurpose(fileText, system, purpose) {
+  const at = fileText.search(/^## \S/m);
+  const rest = at < 0 ? '' : fileText.slice(at);
+  const title = fileText.trimStart().match(/^# .*/)?.[0] ?? `# ${system}`;
+
+  return `${title}\n\n${purpose}\n${rest ? `\n${rest}` : ''}`;
+}
+
+/** A part's names become file names: a doc is one of DOCS, a system and a unit are slugs. */
+const validName = (p) =>
+  p.kind === 'doc'
+    ? DOCS.includes(p.name)
+    : SLUG_RE.test(p.name) && SLUG_RE.test(String(p.system ?? ''));
+
+/** Plan every part: which write it gets, or which report line. */
+function plan(bundle, cur, ledger) {
+  const writes = [];
+  const note = `lines outside any part: ${bundle.stray.join(', ')} (a lost gcf:part marker?)`;
+  const report = bundle.stray.length ? [{ part: 'bundle', outcome: 'invalid', note }] : [];
+  for (const p of bundle.parts) {
+    const key = `${p.kind}:${p.name}`;
+    if (!validName(p)) {
+      report.push({ part: key, outcome: 'invalid', note: 'not a gcf doc, system or unit name' });
+      continue;
+    }
+
+    const v = verdict(p, cur.get(key) ?? null);
+    if (p.kind === 'unit' && v === 'new' && ledger.known(p.name)) {
+      report.push({ part: key, outcome: 'taken', note: 'the id is used: pick another slug' });
+    } else if (['apply', 'new'].includes(v)) writes.push({ ...p, outcome: v });
+    else if (v !== 'same') report.push({ part: key, outcome: v, note: NOTES[v] });
+  }
+
+  const kept = new Set(bundle.parts.filter((p) => p.kind === 'unit').map((p) => p.name));
+  for (const id of bundle.ids.filter((i) => !kept.has(i))) {
+    report.push({
+      part: `unit:${id}`,
+      outcome: 'deleted',
+      note: `confirm with gcf drop ${id} --reason "…"`,
+    });
+  }
+
+  return { writes, report };
+}
+
+const NOTES = {
+  conflict: 'changed in the bundle and in gcf/ since the export: a D1 for the human',
+  gone: 'no longer in design/ (taken, done or dropped): an edit to it is a D1',
+  taken: 'a part without a base hash that already exists: export again and edit that',
+};
+
+/** The file each write touches. */
+function fileOf(root, w) {
+  // validName already holds a doc to DOCS; resolveInside is the second lock on the path.
+  if (w.kind === 'doc') return resolveInside(root, `${w.name}.md`);
+
+  return resolveInside(path.join(root, 'design'), `${w.kind === 'system' ? w.name : w.system}.md`);
+}
+
+async function applyWrite(root, w) {
+  const file = fileOf(root, w);
+  const text = existsSync(file)
+    ? await readFile(file, 'utf8')
+    : `# ${w.system ?? w.name}\n\npurpose: TBD\n`;
+  if (w.kind === 'doc') return atomicWrite(file, `${w.text}\n`);
+  if (w.kind === 'system') return atomicWrite(file, putPurpose(text, w.name, w.text));
+  await atomicWrite(file, putUnit(text, w.name, w.text));
+  if (w.outcome !== 'new') return;
+  const backlog = path.join(root, 'backlog.md');
+  const order = existsSync(backlog) ? (await readFile(backlog, 'utf8')).trimEnd() : '';
+  await atomicWrite(backlog, `${order}\n- ${w.name}\n`.replace(/^\n/, ''));
+}
+
+/**
+ * Bring a bundle back into gcf/. A part the bundle changed and gcf/ did not is written; a part
+ * both changed is reported, never merged. Writes land only if the design check after them has
+ * no blocking finding — otherwise every file goes back and the findings are the error.
+ */
+export async function importBundle(projectDir, bundleText) {
+  const root = path.join(path.resolve(projectDir), 'gcf');
+  const bundle = parseBundle(bundleText);
+  const ledger = await buildLedger(projectDir);
+  const { writes, report } = plan(bundle, await currentParts(root), ledger);
+  const applied = writes.map((w) => `${w.kind}:${w.name} (${w.outcome})`);
+  if (!writes.length) return { applied, report };
+  // Only the findings the bundle brings refuse it: a project with open findings can still take
+  // a clean edit. A finding is keyed without its line, which an edit above it shifts, and
+  // counted, so a second finding with the same message in the same unit is still a new one.
+  const keyOf = (i) => `${i.check}|${i.file}|${i.id}|${i.message}`;
+  const blocking = async () =>
+    (await designCheck(projectDir)).issues.filter((i) => i.severity === 'block');
+  const before = new Map();
+  for (const i of await blocking()) before.set(keyOf(i), (before.get(keyOf(i)) ?? 0) + 1);
+  const files = [...new Set(writes.map((w) => fileOf(root, w)))];
+  await withFileRollback(
+    [...files, path.join(root, 'backlog.md'), path.join(root, 'INDEX.md')],
+    async () => {
+      for (const w of writes) await applyWrite(root, w);
+      const seen = new Map();
+      const fresh = (await blocking()).filter((i) => {
+        seen.set(keyOf(i), (seen.get(keyOf(i)) ?? 0) + 1);
+
+        return seen.get(keyOf(i)) > (before.get(keyOf(i)) ?? 0);
+      });
+      if (fresh.length) {
+        const first = fresh.slice(0, 3).map((i) => `${i.file}:${i.line} ${i.check} ${i.message}`);
+        throw new Error(`the bundle would break the design check:\n${first.join('\n')}`);
+      }
+
+      await writeIndex(root);
+    },
+  );
+
+  return { applied, report };
+}

package/lib/context.js

@@ -15,14 +15,35 @@ export async function buildContext(projectDir, cardId) {
   const card = cards.find((c) => c.data.id === cardId);
   if (!card) throw new Error(`Card not found: ${cardId}`);
 
+  const systems = card.data.system ?? [];
+  const files = await readsetFiles(root, card, cards);
+  const cardText =
+    `${card.data.id} ${card.data.title ?? ''} ${systems.join(' ')} ${card.body}`.toLowerCase();
+  const graveyard_hits = await graveyardHits(root, cardText);
+  const d2 = await d2Assumptions(root, systems);
+
+  const extraTokens = tokensEst(graveyard_hits.join('\n')) + tokensEst(d2.join('\n'));
+  const total_tokens_est = files.reduce((sum, f) => sum + f.tokens_est, 0) + extraTokens;
+
+  return {
+    card: cardId,
+    files,
+    graveyard_hits,
+    d2,
+    total_tokens_est,
+    budget: config.context_budget,
+    over_budget: total_tokens_est > config.context_budget,
+  };
+}
+
+/** PILLARS, touched systems, the card, its depends — in that order, skipping absent files. */
+async function readsetFiles(root, card, cards) {
   const files = [];
   const push = async (rel) => {
     const abs = path.join(root, rel);
-    if (!existsSync(abs)) return null;
+    if (!existsSync(abs)) return;
     const text = await readFile(abs, 'utf8');
-    const entry = { path: `gcf/${rel.replaceAll('\\', '/')}`, tokens_est: tokensEst(text) };
-    files.push(entry);
-    return text;
+    files.push({ path: `gcf/${rel.replaceAll('\\', '/')}`, tokens_est: tokensEst(text) });
   };
 
   await push('PILLARS.md');
@@ -30,48 +51,46 @@ export async function buildContext(projectDir, cardId) {
   for (const s of (await listSystems(root)).filter((d) => systems.includes(d.data.system))) {
     await push(`systems/${s.name}`);
   }
+
   await push(`cards/${card.name}`);
   for (const depId of card.data.depends ?? []) {
     const dep = cards.find((c) => c.data.id === depId);
     if (dep) await push(`cards/${dep.name}`);
   }
 
-  // Graveyard: headline tags only; a hit is a tag appearing in the card's own text.
-  const graveyard_hits = [];
+  return files;
+}
+
+/** Graveyard: headline tags only; a hit is a tag appearing in the card's own text. */
+async function graveyardHits(root, cardText) {
   const gyFile = path.join(root, 'graveyard.md');
-  if (existsSync(gyFile)) {
-    const cardText = `${card.data.slug} ${systems.join(' ')} ${card.body}`.toLowerCase();
-    for (const line of (await readFile(gyFile, 'utf8')).split('\n')) {
-      const m = line.match(/^- (card-\d{3}) \| .* \| tags: (.+)$/);
-      if (!m) continue;
-      const tags = m[2].split(',').map((t) => t.trim().toLowerCase()).filter(Boolean);
-      if (tags.some((t) => cardText.includes(t))) graveyard_hits.push(line.trim());
-    }
+  if (!existsSync(gyFile)) return [];
+  const hits = [];
+  for (const line of (await readFile(gyFile, 'utf8')).split('\n')) {
+    const m = line.match(/^- (\S+) \| .* \| tags: (.+)$/);
+    if (!m) continue;
+    const tags = m[2]
+      .split(',')
+      .map((t) => t.trim().toLowerCase())
+      .filter(Boolean);
+    if (tags.some((t) => cardText.includes(t))) hits.push(line.trim());
   }
 
-  // D2 assumptions whose sys: overlaps the card's systems (GCF-PRD §9.1).
-  const d2 = [];
+  return hits;
+}
+
+/** D2 assumptions whose sys: overlaps the card's systems (GCF-PRD §9.1). */
+async function d2Assumptions(root, systems) {
   const oqFile = path.join(root, 'open-questions.md');
-  if (existsSync(oqFile)) {
-    const records = (await readFile(oqFile, 'utf8')).split(/\n(?=- id:)/);
-    for (const rec of records) {
-      if (!/^\s*-?\s*id:/m.test(rec) || !/class:\s*D2/.test(rec)) continue;
+  if (!existsSync(oqFile)) return [];
+  const records = (await readFile(oqFile, 'utf8')).split(/\n(?=- id:)/);
+
+  return records
+    .filter((rec) => /^\s*-?\s*id:/m.test(rec) && /class:\s*D2/.test(rec))
+    .filter((rec) => {
       const sys = rec.match(/sys:\s*(.+)/)?.[1] ?? '';
-      if (systems.some((s) => sys.includes(s))) {
-        d2.push(rec.trim());
-      }
-    }
-  }
 
-  const extraTokens = tokensEst(graveyard_hits.join('\n')) + tokensEst(d2.join('\n'));
-  const total_tokens_est = files.reduce((sum, f) => sum + f.tokens_est, 0) + extraTokens;
-  return {
-    card: cardId,
-    files,
-    graveyard_hits,
-    d2,
-    total_tokens_est,
-    budget: config.context_budget,
-    over_budget: total_tokens_est > config.context_budget,
-  };
+      return systems.some((s) => sys.includes(s));
+    })
+    .map((rec) => rec.trim());
 }