@hegemonart/get-design-done 1.30.5 → 1.31.0

package/scripts/lib/figma-extract/render-md.cjs

@@ -0,0 +1,143 @@
+'use strict';
+/**
+ * Plan 31-02 — productionized from spike 001 digest.mjs buildDesignMd().
+ *
+ * Deterministic DESIGN.md renderer with a STABLE section order:
+ *   header (provenance) →
+ *   ## Tokens         (### Color, ### Typography, ### Other — only when non-empty) →
+ *   ## Components      (Total line; sets first, then ### Singleton components) →
+ *   ## Widgets / Pages
+ *
+ * Determinism guarantee: identical {tokens, components, widgets, fileMeta} input
+ * produces BYTE-IDENTICAL output. The ONLY nondeterministic value is the
+ * provenance line's `fetched_at`, which the caller injects (tests pass a fixed
+ * value). This module NEVER calls new Date()/Date.now() — required for 31-10's
+ * golden-snapshot baseline.
+ *
+ * Pure CommonJS, no external deps, no I/O.
+ */
+
+// Size-bounding slice caps (carried over verbatim from the spike for parity).
+const CAP_COLOR = 200;
+const CAP_TYPOGRAPHY = 100;
+const CAP_OTHER = 100;
+const CAP_VARIANTS = 20;
+const CAP_SINGLETONS = 100;
+const CAP_WIDGETS = 50;
+
+/**
+ * @param {object} input
+ * @param {Array} input.tokens       assembled tokens [{name,type,collection?,modes?,value?,description?}]
+ * @param {Array} input.components   from walk.cjs collectComponents().components
+ * @param {Array} input.widgets      from walk.cjs collectComponents().widgets
+ * @param {object} input.fileMeta    { file_key, fetched_at, name } — fetched_at is the only injected nondeterminism
+ * @returns {string} DESIGN.md body
+ */
+function renderDesignMd({ tokens, components, widgets, fileMeta }) {
+  const toks = Array.isArray(tokens) ? tokens : [];
+  const comps = Array.isArray(components) ? components : [];
+  const wids = Array.isArray(widgets) ? widgets : [];
+  const meta = fileMeta || {};
+
+  const colorTokens = toks.filter((t) => t.type === 'COLOR' || t.type === 'FILL');
+  const textTokens = toks.filter((t) => t.type === 'TEXT');
+  const otherTokens = toks.filter(
+    (t) => !['COLOR', 'FILL', 'TEXT'].includes(t.type)
+  );
+
+  const lines = [];
+  lines.push(`# DESIGN.md`);
+  lines.push(``);
+  lines.push(
+    `> Auto-generated from Figma file \`${meta.file_key}\` at ${meta.fetched_at}`
+  );
+  lines.push(`> Source: ${meta.name || 'Design system'}`);
+  lines.push(``);
+
+  // ── ## Tokens ──────────────────────────────────────────────────────────────
+  lines.push(`## Tokens`);
+  lines.push(``);
+
+  if (colorTokens.length) {
+    lines.push(`### Color`);
+    lines.push(``);
+    for (const t of colorTokens.slice(0, CAP_COLOR)) {
+      const modes = t.modes
+        ? Object.entries(t.modes)
+            .map(([m, v]) => `${m}: ${typeof v === 'string' ? v : JSON.stringify(v)}`)
+            .join(' | ')
+        : JSON.stringify(t.value);
+      lines.push(`- \`${t.name}\` — ${modes}`);
+    }
+    lines.push(``);
+  }
+
+  if (textTokens.length) {
+    lines.push(`### Typography`);
+    lines.push(``);
+    for (const t of textTokens.slice(0, CAP_TYPOGRAPHY)) {
+      const v = t.value || Object.values(t.modes || {})[0];
+      lines.push(`- \`${t.name}\` — ${typeof v === 'object' ? JSON.stringify(v) : v}`);
+    }
+    lines.push(``);
+  }
+
+  if (otherTokens.length) {
+    lines.push(`### Other`);
+    lines.push(``);
+    for (const t of otherTokens.slice(0, CAP_OTHER)) {
+      lines.push(`- \`${t.name}\` (${t.type})`);
+    }
+    lines.push(``);
+  }
+
+  // ── ## Components ───────────────────────────────────────────────────────────
+  lines.push(`## Components`);
+  lines.push(``);
+  const sets = comps.filter((c) => c.type === 'COMPONENT_SET');
+  const singles = comps.filter((c) => c.type === 'COMPONENT');
+  lines.push(
+    `Total: ${sets.length} component sets + ${singles.length} singleton components`
+  );
+  lines.push(``);
+
+  for (const c of sets) {
+    lines.push(`### ${c.name}`);
+    if (c.description) lines.push(`> ${c.description}`);
+    if (c.variants && c.variants.length) {
+      lines.push(`Variants (${c.variants.length}):`);
+      for (const v of c.variants.slice(0, CAP_VARIANTS)) lines.push(`- ${v}`);
+      if (c.variants.length > CAP_VARIANTS) {
+        lines.push(`- … +${c.variants.length - CAP_VARIANTS} more`);
+      }
+    }
+    if (c.props && c.props.length) {
+      lines.push(`Props:`);
+      for (const p of c.props) {
+        const opts = p.options ? ` [${p.options.join(', ')}]` : '';
+        lines.push(`- \`${p.name}\` (${p.type})${opts} — default: \`${p.default}\``);
+      }
+    }
+    lines.push(``);
+  }
+
+  if (singles.length) {
+    lines.push(`### Singleton components`);
+    lines.push(``);
+    for (const c of singles.slice(0, CAP_SINGLETONS)) {
+      lines.push(`- \`${c.name}\``);
+    }
+    lines.push(``);
+  }
+
+  // ── ## Widgets / Pages ──────────────────────────────────────────────────────
+  lines.push(`## Widgets / Pages`);
+  lines.push(``);
+  for (const w of wids.slice(0, CAP_WIDGETS)) {
+    lines.push(`- ${w.name} (\`${w.id}\`)`);
+  }
+
+  return lines.join('\n');
+}
+
+module.exports = { renderDesignMd };

package/scripts/lib/figma-extract/styles-resolver.cjs

@@ -0,0 +1,147 @@
+'use strict';
+// Plan 31-03 — Path B of D-04 (three-path token extraction).
+//
+// Fixes spike 001's 0-tokens bug. The spike's digest.mjs extractTokensFromStyles
+// (lines 96-132) looked up each /styles entry's `node_id` inside `file.document`
+// and found nothing — because published-style SOURCE nodes are NOT serialized into
+// the main document tree. They live in canvas frames that require a SEPARATE
+// `/files/:key/nodes?ids=...` fetch. This module implements that missing second pass:
+//
+//   step 1: read the /styles list (node_id + style_type + name)        <- caller supplies
+//   step 2: GET /files/:key/nodes?ids=<comma-joined> to read real values <- injected fetcher
+//
+// Resolution priority within D-04: Variables > plugin sync > styles. Styles (this
+// module) is the last-resort fallback for non-Enterprise, legacy-styles DSs.
+//
+// No direct network call lives here except inside the buildStylesResolver-bound
+// fetcher; tests drive resolveStyleTokens fully offline via an injected fetchNodes.
+
+// Chunk cap for /nodes?ids= requests. Figma limits URL length, so large style sets
+// are split into batches of this size and the results merged.
+const MAX_IDS_PER_REQUEST = 100;
+
+const DEFAULT_API_BASE = 'https://api.figma.com/v1';
+
+// rgb(0..1) channels → 2-hex; appends an alpha hex byte only when a < 1.
+// Ported from spike 001 digest.mjs rgbToHex (lines 13-17) — keep value shape identical.
+function rgbToHex({ r, g, b, a }) {
+  const to = (v) => Math.round((v || 0) * 255).toString(16).padStart(2, '0');
+  const hex = `#${to(r)}${to(g)}${to(b)}`;
+  return a !== undefined && a < 1 ? `${hex}${to(a)}` : hex;
+}
+
+// Split an array into contiguous chunks of at most `size`.
+function chunk(arr, size) {
+  const out = [];
+  for (let i = 0; i < arr.length; i += size) out.push(arr.slice(i, i + size));
+  return out;
+}
+
+// Figma's /nodes response wraps each node under `.document`. Tolerate both the
+// wrapped shape ({ document: <node> }) and a bare node, so the resolver is robust
+// to either the live API or a flattened fixture.
+function unwrapNode(entry) {
+  if (!entry) return undefined;
+  return entry.document !== undefined ? entry.document : entry;
+}
+
+// Resolve a single style's value from its source node, by style_type.
+// Returns undefined when the node lacks the data for that type (style is then skipped).
+function resolveValue(styleType, node) {
+  if (!node) return undefined;
+  if (styleType === 'FILL') {
+    const fill = node.fills && node.fills[0];
+    if (fill && fill.color) return rgbToHex({ ...fill.color, a: fill.opacity });
+    return undefined;
+  }
+  if (styleType === 'TEXT') {
+    const st = node.style;
+    if (!st) return undefined;
+    return {
+      family: st.fontFamily,
+      weight: st.fontWeight,
+      size: st.fontSize,
+      lineHeight: st.lineHeightPx,
+      letterSpacing: st.letterSpacing,
+    };
+  }
+  if (styleType === 'EFFECT') {
+    const eff = node.effects && node.effects[0];
+    return eff !== undefined ? eff : undefined;
+  }
+  return undefined;
+}
+
+// Core two-step resolver (Path B). Pure transform over injected data — no network.
+//   stylesList: the /styles response body
+//               ({ meta: { styles: [{ node_id, style_type, name, description }] } })
+//   fetchNodes: async (ids: string[]) => /nodes response body
+//               ({ nodes: { <id>: { document: <node> } | <node> } })
+// Returns Array<{ name, type:'FILL'|'TEXT'|'EFFECT', value, description }>.
+//   FILL   → value = hex string (rgb→hex, alpha-aware)
+//   TEXT   → value = { family, weight, size, lineHeight, letterSpacing }
+//   EFFECT → value = the first effect object
+// Returns [] when stylesList has no styles (fetchNodes is NOT called), or when every
+// node lookup misses. A style whose node_id is absent from /nodes is skipped (graceful).
+async function resolveStyleTokens({ stylesList, fetchNodes }) {
+  const styles = (stylesList && stylesList.meta && stylesList.meta.styles) || [];
+  if (styles.length === 0) return [];
+  if (typeof fetchNodes !== 'function') {
+    throw new TypeError('resolveStyleTokens: fetchNodes must be a function');
+  }
+
+  // Step 2: batch the node_ids and fetch their real source nodes, merging into one map.
+  const ids = styles.map((s) => s.node_id).filter((id) => id != null);
+  const nodeMap = {};
+  for (const idChunk of chunk(ids, MAX_IDS_PER_REQUEST)) {
+    const body = await fetchNodes(idChunk);
+    const nodes = (body && body.nodes) || {};
+    for (const id of idChunk) {
+      const node = unwrapNode(nodes[id]);
+      if (node !== undefined) nodeMap[id] = node;
+    }
+  }
+
+  // Map each style onto its resolved value. Skip styles whose node missed or whose
+  // node lacked the data for its type.
+  const out = [];
+  for (const s of styles) {
+    const node = nodeMap[s.node_id];
+    if (!node) continue;
+    const value = resolveValue(s.style_type, node);
+    if (value !== undefined) {
+      out.push({
+        name: s.name,
+        type: s.style_type,
+        value,
+        description: s.description || '',
+      });
+    }
+  }
+  return out;
+}
+
+// Bind a resolver to a live (fileKey, token, fetchImpl, apiBase) so digest.cjs can
+// inject Path B. Returns an async fn(file, styles) — exactly the `stylesResolver(file, styles)`
+// seam shape digest.cjs (31-02) calls. It ignores `file` (the document tree never holds
+// the source nodes — that is the spike bug) and resolves `styles` via a /nodes fetcher.
+// 31-07's SKILL wires this for live runs. The token is sent ONLY as the X-Figma-Token
+// header and is NEVER logged or persisted (D-10).
+function buildStylesResolver({ fileKey, token, fetchImpl, apiBase } = {}) {
+  const base = apiBase || DEFAULT_API_BASE;
+  const doFetch = fetchImpl || (typeof fetch !== 'undefined' ? fetch : undefined);
+  return async function stylesResolver(_file, styles) {
+    const fetchNodes = async (ids) => {
+      if (typeof doFetch !== 'function') {
+        throw new Error('buildStylesResolver: no fetch implementation available');
+      }
+      const url = `${base}/files/${fileKey}/nodes?ids=${ids.join(',')}`;
+      const res = await doFetch(url, { headers: { 'X-Figma-Token': token } });
+      if (!res.ok) throw new Error(`/nodes ${res.status}`);
+      return res.json();
+    };
+    return resolveStyleTokens({ stylesList: styles, fetchNodes });
+  };
+}
+
+module.exports = { resolveStyleTokens, buildStylesResolver, MAX_IDS_PER_REQUEST, rgbToHex };

package/scripts/lib/figma-extract/walk.cjs

@@ -0,0 +1,100 @@
+'use strict';
+/**
+ * Plan 31-02 — productionized from spike 001 digest.mjs walk() + summarizeWidgets().
+ *
+ * Node-tree walker with VARIANT ROLLUP (decision D-02, variant rollup default-on).
+ *
+ * The spike proved a naive walk inflates the component count ~16× (2,593 vs 167
+ * entries) because each COMPONENT_SET's variant children are counted as separate
+ * components. The fix — locked here as the non-optional default — is to SKIP the
+ * COMPONENT children of a COMPONENT_SET and record their names as a `variants[]`
+ * field on the parent set. A COMPONENT_SET with N variant children therefore
+ * yields exactly ONE component entry, not N (+1).
+ *
+ * Pure CommonJS, no external deps, no I/O, no network.
+ *
+ * Exports:
+ *   walkDocument(node, ctx, parentIsSet)  — low-level recursive helper (unit-testable)
+ *   collectComponents(documentNode)       — top-level entry over file.document
+ */
+
+/**
+ * Recursive tree walker. Mutates `ctx` in place.
+ *
+ * @param {object|null|undefined} node          a Figma node (document/canvas/frame/component/…)
+ * @param {{components:Array, widgets:Array, depth:number}} ctx accumulator
+ * @param {boolean} [parentIsSet=false]         true when the parent node is a COMPONENT_SET
+ */
+function walkDocument(node, ctx, parentIsSet = false) {
+  if (!node) return;
+
+  // Rollup core: a COMPONENT is only a standalone component when its parent is
+  // NOT a COMPONENT_SET. COMPONENT children of a set are variants — skipped here
+  // (they are recorded as variants[] on the parent set below).
+  const isStandaloneComponent = node.type === 'COMPONENT' && !parentIsSet;
+
+  if (node.type === 'COMPONENT_SET' || isStandaloneComponent) {
+    ctx.components.push({
+      id: node.id,
+      name: node.name,
+      type: node.type,
+      description: node.description || '',
+      // Variant names live on the set's children; standalone components have none.
+      variants:
+        node.type === 'COMPONENT_SET'
+          ? (node.children || []).map((c) => c.name)
+          : undefined,
+      // componentPropertyDefinitions → flattened props. Figma suffixes prop keys
+      // with '#<id>' for uniqueness; strip it for the human-facing name.
+      props: node.componentPropertyDefinitions
+        ? Object.entries(node.componentPropertyDefinitions).map(([k, v]) => ({
+            name: k.split('#')[0],
+            type: v.type,
+            default: v.defaultValue,
+            options: v.variantOptions,
+          }))
+        : undefined,
+    });
+  }
+
+  // Top-level FRAMEs (depth 1 — direct children of a page/canvas) are widget /
+  // page candidates for downstream classification.
+  if (ctx.depth === 1 && node.type === 'FRAME') {
+    ctx.widgets.push({ id: node.id, name: node.name });
+  }
+
+  if (node.children) {
+    ctx.depth++;
+    // Children of a COMPONENT_SET are variants — flag so they are not re-pushed.
+    const childParentIsSet = node.type === 'COMPONENT_SET';
+    for (const child of node.children) walkDocument(child, ctx, childParentIsSet);
+    ctx.depth--;
+  }
+}
+
+/**
+ * Collect components (with variant rollup) and top-level frames from a document.
+ *
+ * @param {object} documentNode  file.document — has .children = pages (CANVAS nodes)
+ * @returns {{components:Array, widgets:Array}}
+ *   components: Array<{ id, name, type:'COMPONENT_SET'|'COMPONENT', description,
+ *                       variants?:string[], props?:Array<{name,type,default,options}> }>
+ *   widgets:    Array<{ id, name }>  — top-level FRAMEs (depth 1)
+ */
+function collectComponents(documentNode) {
+  const ctx = { components: [], widgets: [], depth: 0 };
+  if (!documentNode || !documentNode.children) {
+    return { components: ctx.components, widgets: ctx.widgets };
+  }
+  // Pages (CANVAS) sit at depth 0; their children are depth 1 — that's where
+  // top-level frames become widget candidates. Mirror the spike's depth handling
+  // by entering each page's children at depth 1.
+  for (const page of documentNode.children) {
+    if (!page || !page.children) continue;
+    ctx.depth = 1;
+    for (const child of page.children) walkDocument(child, ctx, false);
+  }
+  return { components: ctx.components, widgets: ctx.widgets };
+}
+
+module.exports = { walkDocument, collectComponents };

package/scripts/lib/graph/atomic-write.mjs

@@ -0,0 +1,68 @@
+// scripts/lib/graph/atomic-write.mjs — Plan 30.6-02 Task 1
+//
+// Atomic JSON write seam per D-05: writeFile(tmp) + rename(tmp, target) in
+// the SAME directory (Windows atomicity guarantee — fs.rename is only
+// atomic across same-volume same-device renames). No proper-lockfile.
+// Single-writer assumption for the design pipeline; revisit in Phase 41
+// if multi-writer becomes a real need.
+
+import {
+  writeFileSync,
+  renameSync,
+  unlinkSync,
+  mkdirSync,
+  existsSync,
+} from 'node:fs';
+import { dirname, basename, join, resolve } from 'node:path';
+
+/**
+ * Atomically write a JSON payload to `target` using the tmp+rename pattern.
+ *
+ * Guarantees:
+ *   - Readers either see the previous file or the new file, never a
+ *     partial write.
+ *   - If rename fails, the tmp file is unlinked (no orphan tmp files).
+ *   - Tmp file lives in the SAME directory as target (Windows-safe).
+ *
+ * @param {string} target  - Absolute or repo-relative path to final file
+ * @param {unknown} payload - JSON-serializable value (stringified pretty 2-space)
+ */
+export function atomicWriteJson(target, payload) {
+  const parent = dirname(target);
+  const base = basename(target);
+  const tmp = join(
+    parent,
+    `.${base}.tmp.${process.pid}.${Date.now()}.${Math.random().toString(36).slice(2, 8)}`,
+  );
+
+  // Defense per D-05: assert tmp is in same dir as target (cross-device
+  // rename is NOT atomic on Windows). Resolve both to normalize forward-
+  // vs back-slash separators on Windows so the comparison is path-shape-
+  // agnostic — string equality on dirname() outputs is fragile when the
+  // caller passes a POSIX-style path on Windows (`/tmp/foo`) and Node
+  // resolves it to a native-style temp dir (`C:\...\Temp\foo`).
+  if (resolve(dirname(tmp)) !== resolve(parent)) {
+    throw new Error(
+      `atomicWriteJson invariant: tmp not in same dir as target (tmp=${tmp}, target=${target})`,
+    );
+  }
+
+  mkdirSync(parent, { recursive: true });
+
+  const body = JSON.stringify(payload, null, 2) + '\n';
+
+  try {
+    writeFileSync(tmp, body, 'utf8');
+    renameSync(tmp, target);
+  } catch (err) {
+    // Clean up orphan tmp file on failure (best-effort).
+    if (existsSync(tmp)) {
+      try {
+        unlinkSync(tmp);
+      } catch {
+        // Swallow cleanup errors — original throw takes precedence.
+      }
+    }
+    throw err;
+  }
+}

package/scripts/lib/graph/build.mjs

@@ -0,0 +1,124 @@
+// scripts/lib/graph/build.mjs — Plan 30.6-02 Task 2
+//
+// buildGraph: read .design/intel/graph.json, transform per RESEARCH.md
+// intel→graph mapping, validate against schema 1.0, atomic-write to
+// .design/graph/graph.json. Deterministic when `now` is passed (test seam).
+
+import { readFileSync, existsSync } from 'node:fs';
+import { compileValidator, SCHEMA_VERSION } from './schema.mjs';
+import { atomicWriteJson } from './atomic-write.mjs';
+
+const DEFAULT_INTEL = '.design/intel/graph.json';
+const DEFAULT_OUT = '.design/graph/graph.json';
+const DEFAULT_BUILDER_VERSION = '1.30.6';
+const DEFAULT_SOURCE_MARKER = 'gdd-intel-store';
+
+/**
+ * Build .design/graph/graph.json from a .design/intel/graph.json slice.
+ *
+ * @param {object} opts
+ * @param {string} [opts.intelPath]      - default '.design/intel/graph.json'
+ * @param {string} [opts.outPath]        - default '.design/graph/graph.json'
+ * @param {string} [opts.builderVersion] - default '1.30.6'
+ * @param {string} [opts.now]            - ISO timestamp override (deterministic tests)
+ * @returns {{ok: true, nodeCount: number, edgeCount: number, outPath: string}}
+ * @throws on missing intel, parse failure, schema-invalid output
+ */
+export function buildGraph({
+  intelPath = DEFAULT_INTEL,
+  outPath = DEFAULT_OUT,
+  builderVersion = DEFAULT_BUILDER_VERSION,
+  now = undefined,
+} = {}) {
+  if (!existsSync(intelPath)) {
+    const err = new Error(`buildGraph: intel file not found at ${intelPath}`);
+    err.code = 'INTEL_MISSING';
+    throw err;
+  }
+
+  let intel;
+  try {
+    intel = JSON.parse(readFileSync(intelPath, 'utf8'));
+  } catch (e) {
+    const err = new Error(
+      `buildGraph: failed to parse intel JSON at ${intelPath}: ${e.message}`,
+    );
+    err.code = 'INTEL_PARSE_FAILED';
+    err.cause = e;
+    throw err;
+  }
+
+  const nodes = (Array.isArray(intel.nodes) ? intel.nodes : []).map(
+    (n) => transformNode(n),
+  );
+  const edges = (Array.isArray(intel.edges) ? intel.edges : []).map(
+    (e) => transformEdge(e),
+  );
+
+  const payload = {
+    schemaVersion: SCHEMA_VERSION,
+    metadata: {
+      generatedAt: now ?? new Date().toISOString(),
+      intelSource: intelPath,
+      nodeCount: nodes.length,
+      edgeCount: edges.length,
+      builderVersion,
+    },
+    nodes,
+    edges,
+  };
+
+  const validate = compileValidator();
+  if (!validate(payload)) {
+    const err = new Error('buildGraph: payload failed schema validation');
+    err.code = 'SCHEMA_INVALID';
+    err.schemaErrors = validate.errors;
+    throw err;
+  }
+
+  atomicWriteJson(outPath, payload);
+  return {
+    ok: true,
+    nodeCount: nodes.length,
+    edgeCount: edges.length,
+    outPath,
+  };
+}
+
+/**
+ * Intel → graph node transform per RESEARCH.md §Intel → graph transformation.
+ * intel.name → graph.label; any extra fields land in attrs blob.
+ */
+function transformNode(n) {
+  if (!n || typeof n !== 'object') return n;
+  // Pull off named intel fields; spread rest into attrs (lenient passthrough).
+  const { id, type, name, label, attrs, source, ...rest } = n;
+  const out = { id, type };
+  // Honor explicit label first; fall back to intel.name; otherwise omit.
+  const labelOut = label ?? name;
+  if (labelOut !== undefined) out.label = labelOut;
+  // Merge intel-extra fields into attrs (existing attrs win).
+  const restKeys = Object.keys(rest);
+  if (attrs || restKeys.length) {
+    out.attrs = { ...rest, ...(attrs || {}) };
+  }
+  out.source = source ?? DEFAULT_SOURCE_MARKER;
+  return out;
+}
+
+/**
+ * Intel → graph edge transform. Edges already use {from,to,kind} verbatim
+ * per D-03.b — pure passthrough plus attrs absorption.
+ */
+function transformEdge(e) {
+  if (!e || typeof e !== 'object') return e;
+  const { from, to, kind, weight, attrs, source, ...rest } = e;
+  const out = { from, to, kind };
+  if (typeof weight === 'number') out.weight = weight;
+  const restKeys = Object.keys(rest);
+  if (attrs || restKeys.length) {
+    out.attrs = { ...rest, ...(attrs || {}) };
+  }
+  out.source = source ?? DEFAULT_SOURCE_MARKER;
+  return out;
+}

package/scripts/lib/graph/diff.mjs

@@ -0,0 +1,90 @@
+// scripts/lib/graph/diff.mjs — Plan 30.6-02 Task 2
+//
+// diffGraph: compare two graph.json files, emit {addedNodes, removedNodes,
+// changedNodes, addedEdges, removedEdges}. Node identity = .id; edge
+// identity = `${from}::${to}::${kind}` per upstream-key formula.
+
+import { readFileSync, existsSync } from 'node:fs';
+import { isDeepStrictEqual } from 'node:util';
+import { compileValidator } from './schema.mjs';
+
+/**
+ * Diff two graphs by file path.
+ *
+ * @param {object} opts
+ * @param {string} opts.fromPath - baseline graph path
+ * @param {string} opts.toPath   - current graph path
+ * @returns {{addedNodes: any[], removedNodes: any[], changedNodes: Array<{id:string, before:any, after:any}>, addedEdges: any[], removedEdges: any[]}}
+ */
+export function diffGraph({ fromPath, toPath } = {}) {
+  if (!fromPath || !toPath) {
+    const err = new Error('diffGraph: fromPath and toPath are required');
+    err.code = 'DIFF_ARGS_MISSING';
+    throw err;
+  }
+  const from = readAndValidate(fromPath, 'fromPath');
+  const to = readAndValidate(toPath, 'toPath');
+
+  const fromNodeMap = new Map(from.nodes.map((n) => [n.id, n]));
+  const toNodeMap = new Map(to.nodes.map((n) => [n.id, n]));
+
+  const addedNodes = [];
+  const removedNodes = [];
+  const changedNodes = [];
+
+  for (const [id, after] of toNodeMap) {
+    if (!fromNodeMap.has(id)) {
+      addedNodes.push(after);
+    } else {
+      const before = fromNodeMap.get(id);
+      if (!isDeepStrictEqual(before, after)) {
+        changedNodes.push({ id, before, after });
+      }
+    }
+  }
+  for (const [id, before] of fromNodeMap) {
+    if (!toNodeMap.has(id)) removedNodes.push(before);
+  }
+
+  const edgeKey = (e) => `${e.from}::${e.to}::${e.kind}`;
+  const fromEdgeMap = new Map(from.edges.map((e) => [edgeKey(e), e]));
+  const toEdgeMap = new Map(to.edges.map((e) => [edgeKey(e), e]));
+
+  const addedEdges = [];
+  const removedEdges = [];
+  for (const [k, e] of toEdgeMap) if (!fromEdgeMap.has(k)) addedEdges.push(e);
+  for (const [k, e] of fromEdgeMap) if (!toEdgeMap.has(k)) removedEdges.push(e);
+
+  return {
+    addedNodes,
+    removedNodes,
+    changedNodes,
+    addedEdges,
+    removedEdges,
+  };
+}
+
+function readAndValidate(path, label) {
+  if (!existsSync(path)) {
+    const err = new Error(`diffGraph: ${label} not found at ${path}`);
+    err.code = 'DIFF_FILE_MISSING';
+    throw err;
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(readFileSync(path, 'utf8'));
+  } catch (e) {
+    const err = new Error(`diffGraph: ${label} parse failed: ${e.message}`);
+    err.code = 'DIFF_PARSE_FAILED';
+    err.cause = e;
+    throw err;
+  }
+  const validate = compileValidator();
+  if (!validate(parsed)) {
+    const err = new Error(`diffGraph: ${label} failed schema validation`);
+    err.code = 'DIFF_SCHEMA_INVALID';
+    err.schemaErrors = validate.errors;
+    throw err;
+  }
+  return parsed;
+}

package/scripts/lib/graph/index.mjs

@@ -0,0 +1,14 @@
+// scripts/lib/graph/index.mjs — Plan 30.6-02 Task 2
+//
+// Barrel re-export for graph subcommand handlers. 30.6-03 layers query,
+// upsertNode, upsertEdge on top of these exports + the schema/atomic-write
+// foundation; 30.6-04 verifies the union decouples from upstream GSD.
+
+export { buildGraph } from './build.mjs';
+export { statusGraph } from './status.mjs';
+export { diffGraph } from './diff.mjs';
+export { compileValidator, SCHEMA_VERSION, SCHEMA } from './schema.mjs';
+export { atomicWriteJson } from './atomic-write.mjs';
+export { queryGraph } from './query.mjs';                  // 30.6-03 Task 1
+export { estimateTokens } from './token-estimate.mjs';     // 30.6-03 Task 1
+export { upsertNode, upsertEdge } from './upsert.mjs';     // 30.6-03 Task 2