@radicool/throughline 0.12.1 → 0.14.0

package/scripts/build-docs-digest.mjs

@@ -0,0 +1,74 @@
+// docs:digest — aggregates every component doc record into two AI-facing
+// artifacts: index.json (machine map) and llms.txt (narrative index).
+// Zero dependencies.
+//
+// Usage: node build-docs-digest.mjs [--root <dir>]
+import { readdirSync, writeFileSync, existsSync, mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { parseArgs } from 'node:util';
+import { pathToFileURL } from 'node:url';
+import { loadRecord } from './lib/doc-record.mjs';
+
+const DOCS_DIR = join('design-system', 'docs');
+const COMPONENTS_DIR = join(DOCS_DIR, 'components');
+
+export function buildIndex(records) {
+  return {
+    generatedFrom: 'design-system/docs/components/*.doc.json',
+    components: records.map((r) => ({
+      name: r.name,
+      summary: r.summary ?? '',
+      description: r.description ?? '',
+      whenToUse: r.whenToUse ?? [],
+      whenNotToUse: r.whenNotToUse ?? [],
+      variants: r.variants ?? {},
+      states: r.states ?? {},
+      dos: r.dos ?? [],
+      donts: r.donts ?? [],
+      accessibility: r.accessibility ?? {},
+      tokensUsed: r.tokensUsed ?? [],
+      status: r.status ?? 'draft',
+    })),
+  };
+}
+
+export function buildLlmsTxt(records) {
+  const lines = ['# Design system — component usage guide', ''];
+  lines.push('Generated documentation for AI and human consumers. One section per component.', '');
+  for (const r of records) {
+    lines.push(`## ${r.name}`, '');
+    if (r.summary) lines.push(r.summary, '');
+    if (r.description) lines.push(r.description, '');
+    if ((r.whenToUse ?? []).length) lines.push('**When to use:** ' + r.whenToUse.join('; '));
+    if ((r.whenNotToUse ?? []).length) lines.push('**When not to use:** ' + r.whenNotToUse.join('; '));
+    if ((r.dos ?? []).length) lines.push('**Do:** ' + r.dos.join('; '));
+    if ((r.donts ?? []).length) lines.push("**Don't:** " + r.donts.join('; '));
+    if ((r.tokensUsed ?? []).length) lines.push('**Tokens:** ' + r.tokensUsed.join(', '));
+    lines.push('');
+  }
+  return lines.join('\n');
+}
+
+export function loadAllRecords(root) {
+  const dir = join(root, COMPONENTS_DIR);
+  if (!existsSync(dir)) return [];
+  return readdirSync(dir)
+    .filter((f) => f.endsWith('.doc.json'))
+    .sort()
+    .map((f) => loadRecord(join(dir, f)));
+}
+
+function main() {
+  const { values } = parseArgs({ options: { root: { type: 'string', default: '.' } } });
+  const root = values.root;
+  const records = loadAllRecords(root);
+  const outDir = join(root, DOCS_DIR);
+  if (!existsSync(outDir)) mkdirSync(outDir, { recursive: true });
+  writeFileSync(join(outDir, 'index.json'), JSON.stringify(buildIndex(records), null, 2) + '\n');
+  writeFileSync(join(outDir, 'llms.txt'), buildLlmsTxt(records));
+  console.log(`✓ docs:digest — ${records.length} component(s) → design-system/docs/{index.json,llms.txt}`);
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  main();
+}

package/scripts/docs-check.mjs

@@ -0,0 +1,103 @@
+// docs:check — the documentation drift gate. Compares each component's canonical
+// record and its rendered surfaces against the fingerprints recorded in
+// design-system.json, and reports drift. Zero dependencies.
+//
+// Drift classes: canonical-changed | stale | edited | missing-surface | edit-unverified
+// (edit-unverified = a surface the CLI cannot read, e.g. Figma — informational;
+//  it is checked live by the Figma-connected skill instead.
+//  missing-surface = a repo surface that declares a file which is now gone — failing;
+//  distinct from edit-unverified, which has no file to read in the first place.)
+//
+// Usage: node docs-check.mjs [--root <dir>]   (default root: cwd)
+import { readFileSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { parseArgs } from 'node:util';
+import { pathToFileURL } from 'node:url';
+import { loadRecord, canonicalFingerprint, fingerprint } from './lib/doc-record.mjs';
+
+// Surfaces whose rendered content the CLI can re-read from the repo.
+const REPO_SURFACES = new Set(['storybookMdx']);
+
+export function classifySurface({ currentCanonical, surface, currentRenderHash, fileMissing = false }) {
+  const flags = [];
+  if (surface.src !== currentCanonical) flags.push('stale');
+  if (fileMissing) {
+    flags.push('missing-surface');
+  } else if (currentRenderHash === null) {
+    flags.push('edit-unverified');
+  } else if (surface.render !== currentRenderHash) {
+    flags.push('edited');
+  }
+  return flags;
+}
+
+export function checkComponent({ name, meta, root }) {
+  const out = [];
+  const doc = meta && meta.doc;
+  if (!doc) return out;
+
+  const recordPath = join(root, doc.path);
+  if (!existsSync(recordPath)) {
+    out.push({ name, surface: 'canonical', flags: ['missing-record'] });
+    return out;
+  }
+  const currentCanonical = canonicalFingerprint(loadRecord(recordPath));
+  if (currentCanonical !== doc.fingerprint) {
+    out.push({ name, surface: 'canonical', flags: ['canonical-changed'] });
+  }
+
+  for (const [surfaceName, surface] of Object.entries(doc.surfaces || {})) {
+    let currentRenderHash = null;
+    let fileMissing = false;
+    if (REPO_SURFACES.has(surfaceName) && surface.file) {
+      const filePath = join(root, surface.file);
+      if (existsSync(filePath)) {
+        currentRenderHash = fingerprint(readFileSync(filePath, 'utf8'));
+      } else {
+        fileMissing = true;
+      }
+    }
+    const flags = classifySurface({ currentCanonical, surface, currentRenderHash, fileMissing });
+    if (flags.length) out.push({ name, surface: surfaceName, flags });
+  }
+  return out;
+}
+
+export function checkAll(manifest, root) {
+  const out = [];
+  const meta = (manifest && manifest.components && manifest.components.meta) || {};
+  for (const [name, m] of Object.entries(meta)) {
+    out.push(...checkComponent({ name, meta: m, root }));
+  }
+  return out;
+}
+
+const FAILING = new Set(['canonical-changed', 'stale', 'edited', 'missing-record', 'missing-surface']);
+
+function main() {
+  const { values } = parseArgs({ options: { root: { type: 'string', default: '.' } } });
+  const root = values.root;
+  const manifestPath = join(root, 'design-system.json');
+  if (!existsSync(manifestPath)) {
+    console.error(`docs:check — no design-system.json at ${root}`);
+    process.exit(1);
+  }
+  const manifest = JSON.parse(readFileSync(manifestPath, 'utf8'));
+  const results = checkAll(manifest, root);
+
+  const drift = results.filter((r) => r.flags.some((f) => FAILING.has(f)));
+  const info = results.filter((r) => !r.flags.some((f) => FAILING.has(f)));
+
+  for (const r of drift) console.error(`  ✗ ${r.name} · ${r.surface}: ${r.flags.join(', ')}`);
+  for (const r of info) console.log(`  ~ ${r.name} · ${r.surface}: ${r.flags.join(', ')} (check in a Figma session)`);
+
+  if (drift.length) {
+    console.error(`✗ docs:check — ${drift.length} drifted surface(s); reconcile with /document-component`);
+    process.exit(1);
+  }
+  console.log(`✓ docs:check — no drift${info.length ? ` (${info.length} Figma surface(s) unverified)` : ''}`);
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  main();
+}

package/scripts/lib/doc-record.mjs

@@ -0,0 +1,54 @@
+// Loads, validates, and fingerprints a component documentation record
+// (design-system/docs/components/<Name>.doc.json). Zero dependencies.
+import { readFileSync } from 'node:fs';
+import { createHash } from 'node:crypto';
+
+// Blocks that get PROJECTED to surfaces. `provenance` is authoring metadata and
+// is intentionally excluded from the fingerprint.
+// MAINTENANCE: keep this in sync with the record schema — any NEW projected field
+// (see references/component-doc-schema.md) must be added here, or it will be
+// silently excluded from the fingerprint and its drift will go undetected.
+const PROJECTED_KEYS = [
+  'name', 'summary', 'description', 'whenToUse', 'whenNotToUse',
+  'variants', 'states', 'dos', 'donts', 'accessibility', 'tokensUsed',
+  'status', 'updatedAt',
+];
+
+const REQUIRED_KEYS = ['name', 'summary', 'description'];
+
+export function stableStringify(value) {
+  if (Array.isArray(value)) {
+    return `[${value.map(stableStringify).join(',')}]`;
+  }
+  if (value && typeof value === 'object') {
+    const keys = Object.keys(value).sort();
+    return `{${keys.map((k) => `${JSON.stringify(k)}:${stableStringify(value[k])}`).join(',')}}`;
+  }
+  return JSON.stringify(value ?? null);
+}
+
+export function fingerprint(text) {
+  return createHash('sha256').update(text, 'utf8').digest('hex').slice(0, 16);
+}
+
+export function canonicalFingerprint(record) {
+  const projected = {};
+  for (const k of PROJECTED_KEYS) {
+    if (record[k] !== undefined) projected[k] = record[k];
+  }
+  return fingerprint(stableStringify(projected));
+}
+
+export function validateRecord(record) {
+  const problems = [];
+  for (const k of REQUIRED_KEYS) {
+    if (typeof record[k] !== 'string' || record[k].trim() === '') {
+      problems.push(`missing or empty required field "${k}"`);
+    }
+  }
+  return problems;
+}
+
+export function loadRecord(path) {
+  return JSON.parse(readFileSync(path, 'utf8'));
+}