@hegemonart/get-design-done 1.51.0 → 1.52.0

package/reference/schemas/design-context.schema.json

@@ -0,0 +1,130 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://github.com/hegemonart/get-design-done/reference/schemas/design-context.schema.json",
+  "title": "Design Context Graph",
+  "description": "The canonical typed knowledge graph of a design system, persisted at .design/context-graph.json. Nodes are design entities (tokens, components, screens, patterns); edges are typed relationships between them (uses-token, composes, transitions-to). Built by a two-phase mapper: a deterministic extract pass emits node/edge skeletons, then an LLM summary pass fills each node summary. Validated structurally by scripts/validate-design-context.cjs and queried by scripts/lib/design-context-query.cjs.",
+  "type": "object",
+  "required": ["schema_version", "nodes", "edges"],
+  "properties": {
+    "schema_version": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Schema version of this graph document (e.g. \"52.0\")."
+    },
+    "generated_at": {
+      "type": "string",
+      "format": "date-time",
+      "description": "ISO-8601 timestamp the graph was last assembled (optional)."
+    },
+    "nodes": {
+      "type": "array",
+      "description": "All design entities in the graph. Node ids must be unique.",
+      "items": { "$ref": "#/definitions/node" }
+    },
+    "edges": {
+      "type": "array",
+      "description": "All typed relationships. Every source/target must resolve to a node id.",
+      "items": { "$ref": "#/definitions/edge" }
+    }
+  },
+  "additionalProperties": true,
+  "definitions": {
+    "node": {
+      "type": "object",
+      "required": ["id", "type", "name", "summary", "complexity"],
+      "properties": {
+        "id": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Stable unique identifier for the node (referenced by edge source/target)."
+        },
+        "type": {
+          "type": "string",
+          "description": "The kind of design entity this node represents.",
+          "enum": [
+            "token",
+            "component",
+            "variant",
+            "state",
+            "motion-fragment",
+            "a11y-pattern",
+            "screen",
+            "layer",
+            "pattern",
+            "anti-pattern"
+          ]
+        },
+        "name": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Human-readable name of the entity."
+        },
+        "summary": {
+          "type": "string",
+          "description": "One-line LLM-authored description of what the entity is and does. A stub summary (empty or identical to name) is flagged by the validator as a soft warning."
+        },
+        "tags": {
+          "type": "array",
+          "description": "Controlled-vocabulary tags grouping the node by concern (see reference/design-context-tag-vocab.md). Unknown tags are a soft warning, not a hard error.",
+          "items": { "type": "string" }
+        },
+        "complexity": {
+          "type": "string",
+          "description": "Coarse complexity bucket for the entity.",
+          "enum": ["simple", "moderate", "complex"]
+        },
+        "subtype": {
+          "type": "string",
+          "description": "Optional finer classification. For token nodes one of color/spacing/typography/radius/shadow; for layer nodes one of Atomic/Molecular/Organism/Template. Free-form for other node types."
+        }
+      },
+      "additionalProperties": true
+    },
+    "edge": {
+      "type": "object",
+      "required": ["source", "target", "type", "direction", "weight"],
+      "properties": {
+        "source": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Node id the edge originates from."
+        },
+        "target": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Node id the edge points to."
+        },
+        "type": {
+          "type": "string",
+          "description": "The kind of relationship between source and target.",
+          "enum": [
+            "uses-token",
+            "composes",
+            "extends",
+            "transitions-to",
+            "depends-on",
+            "mirrors",
+            "conflicts-with",
+            "referenced-by",
+            "tested-by",
+            "documented-by",
+            "consumes-context",
+            "provides-context"
+          ]
+        },
+        "direction": {
+          "type": "string",
+          "description": "Whether the relationship reads source-to-target (forward), target-to-source (backward), or both ways (bidirectional).",
+          "enum": ["forward", "backward", "bidirectional"]
+        },
+        "weight": {
+          "type": "number",
+          "minimum": 0,
+          "maximum": 1,
+          "description": "Relationship strength in the inclusive range 0..1."
+        }
+      },
+      "additionalProperties": true
+    }
+  }
+}

package/reference/schemas/mcp-gdd-tools.schema.json

@@ -7,7 +7,7 @@
   "properties": {
     "tools": {
       "type": "object",
-      "description": "Per-tool input/output schemas keyed by tool name. Exactly 12 entries (D-03 hard cap).",
+      "description": "Per-tool input/output schemas keyed by tool name. Exactly 13 entries (D-03 cap, raised 12 -> 13 in Phase 52 for gdd_context_query).",
       "additionalProperties": false,
       "properties": {
         "gdd_status": {
@@ -33,6 +33,39 @@
             }
           }
         },
+        "gdd_context_query": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["input", "output"],
+          "properties": {
+            "input": {
+              "type": "object",
+              "additionalProperties": false,
+              "required": ["op"],
+              "properties": {
+                "op": {
+                  "type": "string",
+                  "enum": ["nodes", "edges", "path", "consumers-of", "unreachable", "cycles", "coverage"]
+                },
+                "type": { "type": "string" },
+                "tag": { "type": "string" },
+                "from": { "type": "string" },
+                "to": { "type": "string" },
+                "id": { "type": "string" }
+              }
+            },
+            "output": {
+              "type": "object",
+              "required": ["op", "graph_present", "result"],
+              "properties": {
+                "op": { "type": "string" },
+                "graph_present": { "type": "boolean" },
+                "path": { "type": "string" },
+                "result": { "type": ["array", "object", "null"] }
+              }
+            }
+          }
+        },
         "gdd_phase_current": {
           "type": "object",
           "additionalProperties": false,

package/reference/skill-graph.md

@@ -9,7 +9,7 @@ is a `composes_with` edge (the source calls the target as sub-orchestration); a
 a `next_skills` edge (a pipeline hint for what runs next). Stage grouping is best-effort and
 inferred from the skill name; skills with no stage keyword fall under Utility.
 
-Skills: 89. Composition edges: 0 composes_with, 6 next_skills.
+Skills: 91. Composition edges: 0 composes_with, 6 next_skills.
 
 ```mermaid
 flowchart TD
@@ -72,6 +72,7 @@ flowchart TD
     n_cache_manager["cache-manager"]
     n_check_update["check-update"]
     n_connections["connections"]
+    n_context["context"]
     n_continue["continue"]
     n_debug["debug"]
     n_extract_learnings["extract-learnings"]
@@ -83,6 +84,7 @@ flowchart TD
     n_instinct["instinct"]
     n_list_pins["list-pins"]
     n_locale["locale"]
+    n_migrate_context["migrate-context"]
     n_new_skill["new-skill"]
     n_next["next"]
     n_note["note"]

package/scripts/lib/design-context/extract-a11y.mjs

@@ -0,0 +1,188 @@
+#!/usr/bin/env node
+// scripts/lib/design-context/extract-a11y.mjs — Phase 52 (DesignContext graph), executor B.
+//
+// Deterministic, dependency-free accessibility extractor. Regex-scans source
+// for ARIA attributes, role=, keyboard handlers, focus states, semantic
+// landmarks, skip links, and image alt coverage, and emits a Fragment
+// (schema_version 52.0) of `a11y-pattern` nodes with `documented-by` /
+// `referenced-by` edges:
+//   - component file --referenced-by--> a11y-pattern  (the file exhibits the pattern)
+//   - a11y-pattern --documented-by--> wcag:<criterion> node  (when a known pattern
+//     maps to a WCAG criterion we recognize)
+//
+// Semantics mirror agents/a11y-mapper.md (ARIA / keyboard / focus / landmarks /
+// alt). Static-only — no live browser. Structural pass: summary='' and
+// complexity='moderate' are stubs the LLM/mapper phase fills later. No network,
+// no deps, no top-level Date.now() (stamped in main()).
+//
+// Public API:
+//   extract(roots, opts?) -> Fragment   (pure)
+//   main()                              -> prints Fragment JSON to stdout
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+const MAPPER = 'a11y-mapper';
+const SCHEMA_VERSION = '52.0';
+
+const SCANNABLE_EXT = new Set([
+  '.tsx', '.jsx', '.ts', '.js',
+  '.vue', '.svelte', '.html', '.htm',
+  '.css', '.scss',
+]);
+const SKIP_DIRS = new Set([
+  'node_modules', '.git', 'dist', 'build', '.next', 'coverage',
+  '.design', '.planning', 'out', '.cache', '.turbo', '.svelte-kit',
+]);
+
+function walk(root) {
+  const out = [];
+  let st;
+  try { st = fs.statSync(root); } catch { return out; }
+  if (st.isFile()) {
+    if (SCANNABLE_EXT.has(path.extname(root).toLowerCase())) out.push(root);
+    return out;
+  }
+  const stack = [root];
+  while (stack.length) {
+    const dir = stack.pop();
+    let entries;
+    try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch { continue; }
+    for (const e of entries) {
+      const full = path.join(dir, e.name);
+      if (e.isDirectory()) { if (!SKIP_DIRS.has(e.name)) stack.push(full); }
+      else if (e.isFile() && SCANNABLE_EXT.has(path.extname(e.name).toLowerCase())) out.push(full);
+    }
+  }
+  return out;
+}
+
+function slug(s) {
+  return String(s).trim().toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 60) || 'x';
+}
+function stubNode(id, type, name, extra) {
+  return { id, type, name, summary: '', tags: [], complexity: 'moderate', ...extra };
+}
+
+// ---------------------------------------------------------------------------
+// A11y matchers + WCAG mapping.
+// ---------------------------------------------------------------------------
+
+const ARIA_ATTR = /\baria-([a-z]+)\s*=/g;
+const ROLE_ATTR = /\brole\s*=\s*["']([a-z]+)["']/g;
+const KEYBOARD = /\b(?:tabIndex|tabindex|onKeyDown|onKeyPress|onKeyUp|on:keydown)\b/g;
+const FOCUS_STATE = /:focus(?:-visible)?|focus-visible:|focus:/g;
+const LANDMARK = /<(header|nav|main|section|article|aside|footer)\b/g;
+const SKIP_LINK = /(?:skip-nav|skip-to-content|skip-link|#main-content)/g;
+const IMG_TAG = /<img\b[^>]*>/gi;
+
+// pattern-id -> WCAG criterion it satisfies/relates to.
+const WCAG_FOR_PATTERN = {
+  'aria-attributes': '4.1.2',
+  'role-semantics': '4.1.2',
+  'keyboard-support': '2.1.1',
+  'focus-visible': '2.4.7',
+  'semantic-landmarks': '1.3.1',
+  'skip-link': '2.4.1',
+  'image-alt': '1.1.1',
+};
+
+function collect(re, content, mapFn) {
+  const out = [];
+  re.lastIndex = 0;
+  let m;
+  while ((m = re.exec(content)) !== null) {
+    const v = mapFn(m);
+    if (v != null) out.push(v);
+    if (m.index === re.lastIndex) re.lastIndex++;
+  }
+  return out;
+}
+
+/**
+ * Pure extractor.
+ * @param {string[]|string} roots
+ * @param {{generatedAt?: string}} [opts]
+ * @returns {object} Fragment
+ */
+export function extract(roots, opts = {}) {
+  const rootList = (Array.isArray(roots) ? roots : [roots]).filter(Boolean);
+  const nodeMap = new Map();
+  const edgeSet = new Map();
+
+  const addPattern = (patternId, name, extra) => {
+    const id = `a11y-pattern:${patternId}`;
+    if (!nodeMap.has(id)) nodeMap.set(id, stubNode(id, 'a11y-pattern', name, extra || {}));
+    return id;
+  };
+  const addEdge = (source, target, type, weight) => {
+    const key = `${source}--${type}-->${target}`;
+    if (!edgeSet.has(key)) edgeSet.set(key, { source, target, type, direction: 'forward', weight });
+  };
+  // a11y-pattern --documented-by--> wcag criterion node.
+  const linkWcag = (patternKey, patternNodeId) => {
+    const crit = WCAG_FOR_PATTERN[patternKey];
+    if (!crit) return;
+    const wid = `pattern:wcag-${slug(crit)}`;
+    if (!nodeMap.has(wid)) nodeMap.set(wid, stubNode(wid, 'pattern', `WCAG ${crit}`, { criterion: crit }));
+    addEdge(patternNodeId, wid, 'documented-by', 0.8);
+  };
+
+  for (const root of rootList) {
+    for (const abs of walk(root)) {
+      let content;
+      try { content = fs.readFileSync(abs, 'utf8'); } catch { continue; }
+      const ext = path.extname(abs).toLowerCase();
+      const baseName = path.basename(abs, ext);
+      const compId = `component:${slug(baseName)}`;
+
+      // Detect each pattern family present in this file.
+      const aria = collect(ARIA_ATTR, content, (m) => m[1]);
+      const roles = collect(ROLE_ATTR, content, (m) => m[1]);
+      const kbd = (content.match(KEYBOARD) || []).length;
+      const focus = (content.match(FOCUS_STATE) || []).length;
+      const landmarks = collect(LANDMARK, content, (m) => m[1]);
+      const skip = (content.match(SKIP_LINK) || []).length;
+      const imgs = collect(IMG_TAG, content, (m) => m[0]);
+
+      const families = [];
+      if (aria.length) families.push(['aria-attributes', 'ARIA attributes', { attributes: [...new Set(aria)].slice(0, 12) }]);
+      if (roles.length) families.push(['role-semantics', 'ARIA role semantics', { roles: [...new Set(roles)].slice(0, 12) }]);
+      if (kbd) families.push(['keyboard-support', 'Keyboard navigation', {}]);
+      if (focus) families.push(['focus-visible', 'Focus-visible states', {}]);
+      if (landmarks.length) families.push(['semantic-landmarks', 'Semantic landmarks', { landmarks: [...new Set(landmarks)] }]);
+      if (skip) families.push(['skip-link', 'Skip link', {}]);
+      if (imgs.length) {
+        const withAlt = imgs.filter((t) => /\balt\s*=/.test(t)).length;
+        families.push(['image-alt', 'Image alt coverage', { images: imgs.length, with_alt: withAlt }]);
+      }
+
+      for (const [key, name, extra] of families) {
+        const pid = addPattern(key, name, extra);
+        // The file *references* the a11y pattern.
+        addEdge(compId, pid, 'referenced-by', 0.5);
+        // The pattern is *documented-by* the WCAG criterion.
+        linkWcag(key, pid);
+      }
+    }
+  }
+
+  return {
+    schema_version: SCHEMA_VERSION,
+    mapper: MAPPER,
+    generated_at: opts.generatedAt || '',
+    nodes: [...nodeMap.values()],
+    edges: [...edgeSet.values()],
+  };
+}
+
+export function main(argv = process.argv.slice(2)) {
+  const roots = argv.length ? argv : [process.cwd()];
+  const fragment = extract(roots, { generatedAt: new Date().toISOString() });
+  process.stdout.write(JSON.stringify(fragment, null, 2) + '\n');
+}
+
+const invokedDirectly =
+  process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href;
+if (invokedDirectly) main();

package/scripts/lib/design-context/extract-components.mjs

@@ -0,0 +1,243 @@
+#!/usr/bin/env node
+// scripts/lib/design-context/extract-components.mjs — Phase 52 (DesignContext graph), executor B.
+//
+// Deterministic, dependency-free component extractor. Regex-scans component
+// files (.tsx/.jsx/.vue/.svelte) for component definitions/exports, classifies
+// each as Atomic / Molecular / Organism via import + composition heuristics, and
+// emits a Fragment (schema_version 52.0) of `component` + `variant` + `layer`
+// nodes with `composes` / `extends` edges.
+//
+// Heuristics (mirrors agents/component-taxonomy-mapper.md semantics):
+//   - Atomic    : composes 0 other detected components
+//   - Molecular  : composes 1-4 other detected components
+//   - Organism  : composes 5+ OR is route/page-shaped (Page/Screen/Layout/View name)
+// A `variant` node is emitted when a `variant`/`size`/`intent` prop union or a
+// cva()/tv() variants block is detected; the variant `extends` its component.
+// A `layer` node (subtype Atomic/Molecular/Organism) is emitted per distinct
+// layer and the component `composes`... is captured component->component.
+//
+// Structural pass only: summary='' and complexity='moderate' are stubs the
+// LLM/mapper phase fills later (validator soft-warns). No network, no deps, no
+// top-level Date.now() (stamped in main()).
+//
+// Public API:
+//   extract(roots, opts?) -> Fragment   (pure)
+//   main()                              -> prints Fragment JSON to stdout
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+const MAPPER = 'component-taxonomy-mapper';
+const SCHEMA_VERSION = '52.0';
+
+const COMPONENT_EXT = new Set(['.tsx', '.jsx', '.vue', '.svelte']);
+const SKIP_DIRS = new Set([
+  'node_modules', '.git', 'dist', 'build', '.next', 'coverage',
+  '.design', '.planning', 'out', '.cache', '.turbo', '.svelte-kit',
+]);
+
+const ORGANISM_NAME = /(Page|Screen|Layout|View|Dashboard|Shell|Provider)$/;
+
+/** Recursively collect component files under `root`. */
+function walk(root) {
+  const out = [];
+  let st;
+  try { st = fs.statSync(root); } catch { return out; }
+  if (st.isFile()) {
+    if (COMPONENT_EXT.has(path.extname(root).toLowerCase())) out.push(root);
+    return out;
+  }
+  const stack = [root];
+  while (stack.length) {
+    const dir = stack.pop();
+    let entries;
+    try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch { continue; }
+    for (const e of entries) {
+      const full = path.join(dir, e.name);
+      if (e.isDirectory()) { if (!SKIP_DIRS.has(e.name)) stack.push(full); }
+      else if (e.isFile() && COMPONENT_EXT.has(path.extname(e.name).toLowerCase())) out.push(full);
+    }
+  }
+  return out;
+}
+
+function slug(s) {
+  return String(s).trim().replace(/[^A-Za-z0-9]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 60) || 'x';
+}
+
+// Canonical component id — lowercased so it MATCHES the file-basename-derived
+// `component:<basename>` ids produced by the token / a11y / visual-hierarchy
+// extractors. Component identity is case-insensitive across the graph so that a
+// `referenced-by` edge from a11y (which only knows the filename) recovers
+// against the `component` node defined here (which knows the export name).
+// Cross-fragment edge recovery in merge-fragments.mjs depends on this.
+function componentId(name) {
+  return `component:${slug(name).toLowerCase()}`;
+}
+
+function stubNode(id, type, name, extra) {
+  return { id, type, name, summary: '', tags: [], complexity: 'moderate', ...extra };
+}
+
+// ---------------------------------------------------------------------------
+// Component detection.
+// ---------------------------------------------------------------------------
+
+// React/TS component definitions: function decl, arrow const, class, default export.
+const DEF_FN = /(?:export\s+(?:default\s+)?)?function\s+([A-Z][A-Za-z0-9]*)\s*\(/g;
+const DEF_ARROW = /(?:export\s+)?const\s+([A-Z][A-Za-z0-9]*)\s*(?::\s*[A-Za-z0-9_.<>,\s]+)?=\s*(?:\([^)]*\)|[A-Za-z0-9_]+)\s*=>/g;
+const DEF_CLASS = /(?:export\s+(?:default\s+)?)?class\s+([A-Z][A-Za-z0-9]*)\s+extends\s+(?:React\.)?(?:Pure)?Component\b/g;
+const DEF_MEMO = /(?:export\s+)?const\s+([A-Z][A-Za-z0-9]*)\s*=\s*(?:React\.)?(?:memo|forwardRef)\s*\(/g;
+
+// JSX usage of a capitalized tag → a composed child component.
+const JSX_USE = /<([A-Z][A-Za-z0-9]*)[\s/>]/g;
+
+// Variant signals.
+const VARIANT_PROP = /\b(?:variant|intent|size|tone|appearance|kind)\??\s*:\s*([^;\n}]+)/g;
+const CVA_BLOCK = /\b(?:cva|tv|cssVariants)\s*\(/g;
+
+function collect(re, content, mapFn) {
+  const out = [];
+  re.lastIndex = 0;
+  let m;
+  while ((m = re.exec(content)) !== null) {
+    const v = mapFn(m);
+    if (v) out.push(v);
+    if (m.index === re.lastIndex) re.lastIndex++;
+  }
+  return out;
+}
+
+/** Detect component definitions in one file. Returns array of names. */
+function definedComponents(content, ext, baseName) {
+  const names = new Set();
+  if (ext === '.tsx' || ext === '.jsx') {
+    for (const n of collect(DEF_FN, content, (m) => m[1])) names.add(n);
+    for (const n of collect(DEF_ARROW, content, (m) => m[1])) names.add(n);
+    for (const n of collect(DEF_CLASS, content, (m) => m[1])) names.add(n);
+    for (const n of collect(DEF_MEMO, content, (m) => m[1])) names.add(n);
+  }
+  // Vue/Svelte (and React fallback): the file itself is a component named by
+  // its basename when nothing else was detected.
+  if (!names.size && /^[A-Z]/.test(baseName)) names.add(baseName);
+  else if (ext === '.vue' || ext === '.svelte') names.add(baseName);
+  return [...names];
+}
+
+/** Detect child components composed inside one file. */
+function composedChildren(content) {
+  const kids = new Set();
+  for (const n of collect(JSX_USE, content, (m) => m[1])) {
+    // Skip well-known intrinsic-ish wrappers that aren't design components.
+    if (n === 'Fragment' || n === 'Suspense' || n === 'StrictMode') continue;
+    kids.add(n);
+  }
+  return kids;
+}
+
+function classifyLayer(name, childCount) {
+  if (ORGANISM_NAME.test(name) || childCount >= 5) return 'Organism';
+  if (childCount >= 1) return 'Molecular';
+  return 'Atomic';
+}
+
+/**
+ * Pure extractor.
+ * @param {string[]|string} roots
+ * @param {{generatedAt?: string}} [opts]
+ * @returns {object} Fragment
+ */
+export function extract(roots, opts = {}) {
+  const rootList = (Array.isArray(roots) ? roots : [roots]).filter(Boolean);
+  const nodeMap = new Map();
+  const edgeSet = new Map();
+  const layerSeen = new Set();
+
+  // Pass 1: collect every defined component name (across files) so composes
+  // edges only point at components we actually saw defined somewhere.
+  const fileInfos = [];
+  const definedGlobal = new Set();
+  for (const root of rootList) {
+    for (const abs of walk(root)) {
+      let content;
+      try { content = fs.readFileSync(abs, 'utf8'); } catch { continue; }
+      const ext = path.extname(abs).toLowerCase();
+      const baseName = path.basename(abs, ext);
+      const defs = definedComponents(content, ext, baseName);
+      const kids = composedChildren(content);
+      const hasCva = CVA_BLOCK.test(content) || VARIANT_PROP.test(content);
+      // reset lastIndex side effects of .test on global regexes
+      CVA_BLOCK.lastIndex = 0; VARIANT_PROP.lastIndex = 0;
+      defs.forEach((d) => definedGlobal.add(d));
+      fileInfos.push({ defs, kids, hasCva });
+    }
+  }
+
+  // Pass 2: build nodes + edges.
+  for (const { defs, kids, hasCva } of fileInfos) {
+    for (const name of defs) {
+      const id = componentId(name);
+      // Children that are themselves defined components (drop self + unknown).
+      const realKids = [...kids].filter((k) => k !== name && definedGlobal.has(k));
+      const layer = classifyLayer(name, realKids.length);
+
+      if (!nodeMap.has(id)) {
+        nodeMap.set(id, stubNode(id, 'component', name, { layer }));
+      } else {
+        // Prefer the more-specific (higher) layer if seen twice.
+        const order = { Atomic: 0, Molecular: 1, Organism: 2 };
+        const prev = nodeMap.get(id);
+        if (order[layer] > order[prev.layer]) prev.layer = layer;
+      }
+
+      // layer node (one per distinct layer) + component depends-on-layer is
+      // implicit via the `layer` field; we emit the layer node so the graph has
+      // a navigable taxonomy anchor.
+      const layerId = `layer:${layer}`;
+      if (!layerSeen.has(layerId)) {
+        layerSeen.add(layerId);
+        nodeMap.set(layerId, stubNode(layerId, 'layer', `${layer} layer`, { subtype: layer }));
+      }
+
+      // composes edges: component -> child component.
+      for (const k of realKids) {
+        const childId = componentId(k);
+        const key = `${id}--composes-->${childId}`;
+        if (!edgeSet.has(key)) {
+          edgeSet.set(key, { source: id, target: childId, type: 'composes', direction: 'forward', weight: 0.6 });
+        }
+      }
+
+      // variant node + extends edge.
+      if (hasCva) {
+        const variantId = `variant:${slug(name).toLowerCase()}`;
+        if (!nodeMap.has(variantId)) {
+          nodeMap.set(variantId, stubNode(variantId, 'variant', `${name} (variants)`, {}));
+        }
+        const vkey = `${variantId}--extends-->${id}`;
+        if (!edgeSet.has(vkey)) {
+          edgeSet.set(vkey, { source: variantId, target: id, type: 'extends', direction: 'forward', weight: 0.7 });
+        }
+      }
+    }
+  }
+
+  return {
+    schema_version: SCHEMA_VERSION,
+    mapper: MAPPER,
+    generated_at: opts.generatedAt || '',
+    nodes: [...nodeMap.values()],
+    edges: [...edgeSet.values()],
+  };
+}
+
+export function main(argv = process.argv.slice(2)) {
+  const roots = argv.length ? argv : [process.cwd()];
+  const fragment = extract(roots, { generatedAt: new Date().toISOString() });
+  process.stdout.write(JSON.stringify(fragment, null, 2) + '\n');
+}
+
+const invokedDirectly =
+  process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href;
+if (invokedDirectly) main();