baldart 4.76.1 → 4.78.0

package/framework/.claude/skills/design-system-init/scripts/extract-ts.mjs

@@ -0,0 +1,302 @@
+#!/usr/bin/env node
+// TS-aware component-manifest extraction (since v4.77.0).
+//
+// OPTIONAL companion to the zero-dep regex extractor (extract-manifest.mjs). It
+// resolves TypeScript type aliases / unions / intersections / Omit / Pick in a
+// component's prop type — the cases the pure-regex path cannot see
+// (`type Variant = 'a'|'b'; variant: Variant` captures the alias NAME, not its
+// members). The fix is SYNTACTIC: it parses the file with `ts.createSourceFile`
+// (no Program / TypeChecker / tsconfig — fast, in-file, deterministic) and walks
+// the AST. Opaque / imported types (`ComponentPropsWithoutRef<'button'>`,
+// `HTMLAttributes`) stay EMPTY — we never dump DOM attributes.
+//
+// Reliability contract (the whole reason this is a separate, probed module):
+//   - `typescript` is the CONSUMER's dependency, not BALDART's. It is resolved
+//     from `process.cwd()` (the repo root the extractor runs against), NOT from
+//     this script's location inside `.framework/` where it is absent.
+//   - When typescript is unavailable (Codex / greenfield / non-TS stack) OR the
+//     file fails to parse/traverse, `extractPropsTs` returns `null` and the
+//     caller falls back to the regex path for THAT file — zero regression.
+//   - `computeVariantProp` / `pureStringLiteralUnion` / `literalMembers` carry NO
+//     typescript dependency and are SHARED with the regex path, so the
+//     variant-axis ranking rule is byte-identical on both paths (determinism).
+//
+// This module imports NOTHING from extract-manifest.mjs (one-way, no cycle).
+// Schema: framework/agents/component-manifest-schema.md.
+
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+
+// --- typescript probe: resolve from the CONSUMER root (process.cwd()), not from
+// this script's location inside .framework/ (where typescript is not installed). ---
+let ts = null;
+try {
+  ts = require(require.resolve('typescript', { paths: [process.cwd()] }));
+} catch (_) {
+  ts = null;
+}
+
+/** True when the consumer has `typescript` resolvable; else the TS path no-ops. */
+export const TS_AVAILABLE = !!ts;
+
+// === Shared, typescript-FREE helpers (used by BOTH the TS and regex paths) ===
+
+/** Variant-axis ranking: which prop name wins when several are literal unions. */
+const RANK = ['variant', 'tone', 'intent', 'kind', 'appearance', 'state', 'status', 'color', 'severity'];
+
+/** A type text that is a pure union (or single) of string literals: `'a' | 'b'`. */
+export function pureStringLiteralUnion(typeText) {
+  if (!typeText) return false;
+  const parts = String(typeText).split('|').map((s) => s.trim()).filter(Boolean);
+  if (!parts.length) return false;
+  return parts.every((p) => /^'[^']*'$/.test(p) || /^"[^"]*"$/.test(p));
+}
+
+/** The string-literal members of a union type text, in source order. */
+export function literalMembers(typeText) {
+  if (!typeText) return [];
+  return [...String(typeText).matchAll(/'([^']*)'|"([^"]*)"/g)].map((m) => (m[1] !== undefined ? m[1] : m[2]));
+}
+
+/**
+ * The variant-axis prop name for a props map. A candidate is any prop whose
+ * resolved type is a pure string-literal union; the winner is the first by RANK,
+ * else the sole candidate, else '' (no resolvable axis). This is the single rule
+ * shared by the TS and regex paths — never fork it.
+ */
+export function computeVariantProp(props) {
+  if (!props || typeof props !== 'object') return '';
+  const candidates = Object.keys(props).filter((k) => pureStringLiteralUnion(props[k] && props[k].type));
+  if (!candidates.length) return '';
+  for (const r of RANK) if (candidates.includes(r)) return r;
+  return candidates.length === 1 ? candidates[0] : '';
+}
+
+// === TS path (no-ops entirely when typescript is unavailable) ===
+
+const MAX_DEPTH = 8; // alias-recursion cap (with `seen`, prevents pathological/cyclic blowups)
+
+/** Map of top-level type aliases + interfaces declared IN this file (by name). */
+function buildDeclMap(sf) {
+  const map = new Map();
+  for (const st of sf.statements) {
+    if ((ts.isTypeAliasDeclaration(st) || ts.isInterfaceDeclaration(st)) && st.name) {
+      map.set(st.name.text, st);
+    }
+  }
+  return map;
+}
+
+function paramTypeOfFunction(fn) {
+  return (fn.parameters && fn.parameters[0] && fn.parameters[0].type) || null;
+}
+
+/** React.FC<P> / FC<P> / FunctionComponent<P> → the first type argument (P). */
+function propsFromComponentTypeAnnotation(typeNode) {
+  if (!ts.isTypeReferenceNode(typeNode) || !typeNode.typeArguments || !typeNode.typeArguments.length) return null;
+  const tn = typeNode.typeName;
+  const simple = ts.isQualifiedName(tn) ? tn.right.text : tn.text;
+  if (simple === 'FC' || simple === 'FunctionComponent') return typeNode.typeArguments[0];
+  return null;
+}
+
+/** Locate the exported component `name` and return the TypeNode of its props. */
+function findComponentParamType(sf, name) {
+  let fallback = null;
+  for (const st of sf.statements) {
+    // function Name(props: T) / export [default] function Name(props: T)
+    if (ts.isFunctionDeclaration(st)) {
+      const isDefault = st.modifiers && st.modifiers.some((m) => m.kind === ts.SyntaxKind.DefaultKeyword);
+      if ((st.name && st.name.text === name) || (!st.name && isDefault)) {
+        const t = paramTypeOfFunction(st);
+        if (t) return t;
+      }
+      continue;
+    }
+    // export default Name; (anonymous arrow assigned to const handled below)
+    if (ts.isVariableStatement(st)) {
+      for (const decl of st.declarationList.declarations) {
+        if (!decl.name || !ts.isIdentifier(decl.name) || decl.name.text !== name) continue;
+        // const Name: React.FC<P> = ...
+        if (decl.type) {
+          const t = propsFromComponentTypeAnnotation(decl.type);
+          if (t) return t;
+        }
+        const init = decl.initializer;
+        if (!init) continue;
+        // forwardRef<Ref, Props>(...) / memo<Props>(...)
+        if (ts.isCallExpression(init)) {
+          const callee = init.expression;
+          const calleeName = ts.isPropertyAccessExpression(callee)
+            ? callee.name.text
+            : (ts.isIdentifier(callee) ? callee.text : '');
+          if (init.typeArguments && init.typeArguments.length) {
+            if (calleeName === 'forwardRef' && init.typeArguments[1]) return init.typeArguments[1];
+            if (calleeName === 'memo' && init.typeArguments[0]) return init.typeArguments[0];
+          }
+          // unwrap the first function argument (forwardRef/memo wrapping a component fn)
+          const fn = init.arguments && init.arguments[0];
+          if (fn && (ts.isArrowFunction(fn) || ts.isFunctionExpression(fn))) {
+            const t = paramTypeOfFunction(fn);
+            if (t) return t;
+          }
+        }
+        if (ts.isArrowFunction(init) || ts.isFunctionExpression(init)) {
+          const t = paramTypeOfFunction(init);
+          if (t) return t;
+        }
+      }
+    }
+  }
+  return fallback;
+}
+
+/**
+ * If a prop's type is (via single-file type aliases) a PURE string-literal union,
+ * return its expanded text (`'a' | 'b'`); else null. This is what makes
+ * `variant: Variant` (where `type Variant = 'a'|'b'`) resolve to the members — the
+ * core alias-resolution the regex path cannot do. Interfaces can't be a literal
+ * union, so only type-alias references are followed.
+ */
+function unionLiteralText(node, ctx, seen) {
+  const { declMap } = ctx;
+  if (!node) return null;
+  if (ts.isParenthesizedTypeNode(node)) return unionLiteralText(node.type, ctx, seen);
+  if (ts.isLiteralTypeNode(node) && node.literal && ts.isStringLiteral(node.literal)) return `'${node.literal.text}'`;
+  if (ts.isUnionTypeNode(node)) {
+    const parts = node.types.map((t) => unionLiteralText(t, ctx, seen));
+    return parts.every((p) => p !== null) ? parts.join(' | ') : null;
+  }
+  if (ts.isTypeReferenceNode(node)) {
+    const tn = node.typeName;
+    const simple = ts.isQualifiedName(tn) ? tn.right.text : tn.text;
+    if (declMap.has(simple) && !seen.has(simple)) {
+      const decl = declMap.get(simple);
+      if (ts.isTypeAliasDeclaration(decl)) {
+        const next = new Set(seen); next.add(simple);
+        return unionLiteralText(decl.type, ctx, next);
+      }
+    }
+  }
+  return null;
+}
+
+/** PropertySignature members of a TypeLiteral / InterfaceDeclaration body. */
+function membersOf(node, ctx) {
+  const { sf } = ctx;
+  const out = {};
+  const members = node.members || [];
+  for (const m of members) {
+    if (!ts.isPropertySignature(m) || !m.name) continue;
+    const pname = (ts.isIdentifier(m.name) || ts.isStringLiteral(m.name)) ? m.name.text : m.name.getText(sf);
+    // Resolve aliased literal unions to their members; else keep the raw type text.
+    const resolved = m.type ? unionLiteralText(m.type, ctx, new Set()) : null;
+    const type = resolved || (m.type ? m.type.getText(sf).replace(/\s+/g, ' ').trim() : 'any');
+    out[pname] = { type, required: !m.questionToken };
+  }
+  return out;
+}
+
+/** String-literal keys named by an Omit/Pick second argument (`'a'` or `'a'|'b'`). */
+function extractKeyLiterals(node) {
+  if (!node) return [];
+  if (ts.isLiteralTypeNode(node) && node.literal && ts.isStringLiteral(node.literal)) return [node.literal.text];
+  if (ts.isUnionTypeNode(node)) return node.types.flatMap((t) => extractKeyLiterals(t));
+  return [];
+}
+
+/** Resolve a TypeNode to `{ [prop]: { type, required } }` — syntactic, in-file only. */
+function resolveType(node, ctx, depth, seen) {
+  const { declMap } = ctx;
+  if (!node || depth > MAX_DEPTH) return {};
+  if (ts.isParenthesizedTypeNode(node)) return resolveType(node.type, ctx, depth + 1, seen);
+
+  if (ts.isInterfaceDeclaration(node)) {
+    const out = {};
+    // `extends` heritage first (own members override below).
+    for (const hc of node.heritageClauses || []) {
+      for (const et of hc.types || []) {
+        const exprName = et.expression && et.expression.text;
+        if (exprName && declMap.has(exprName) && !seen.has(exprName)) {
+          const next = new Set(seen); next.add(exprName);
+          Object.assign(out, resolveType(declMap.get(exprName), ctx, depth + 1, next));
+        }
+      }
+    }
+    Object.assign(out, membersOf(node, ctx));
+    return out;
+  }
+
+  if (ts.isTypeLiteralNode(node)) return membersOf(node, ctx);
+
+  if (ts.isIntersectionTypeNode(node)) {
+    const out = {};
+    for (const t of node.types) {
+      const m = resolveType(t, ctx, depth + 1, seen);
+      for (const k of Object.keys(m)) {
+        out[k] = out[k] ? { type: out[k].type, required: out[k].required || m[k].required } : m[k];
+      }
+    }
+    return out;
+  }
+
+  if (ts.isUnionTypeNode(node)) {
+    const arms = node.types.map((t) => resolveType(t, ctx, depth + 1, seen)).filter((m) => Object.keys(m).length);
+    if (!arms.length) return {};
+    const out = {};
+    for (const k of new Set(arms.flatMap((m) => Object.keys(m)))) {
+      const present = arms.filter((m) => m[k]);
+      const inAll = present.length === arms.length;
+      const requiredInAll = inAll && present.every((m) => m[k].required);
+      out[k] = { type: present[0][k].type, required: requiredInAll };
+    }
+    return out;
+  }
+
+  if (ts.isTypeReferenceNode(node)) {
+    const tn = node.typeName;
+    const simple = ts.isQualifiedName(tn) ? tn.right.text : tn.text;
+    if ((simple === 'Omit' || simple === 'Pick') && node.typeArguments && node.typeArguments.length >= 2) {
+      const base = resolveType(node.typeArguments[0], ctx, depth + 1, seen);
+      const keys = new Set(extractKeyLiterals(node.typeArguments[1]));
+      const out = {};
+      for (const k of Object.keys(base)) {
+        const inSet = keys.has(k);
+        if (simple === 'Omit' ? !inSet : inSet) out[k] = base[k];
+      }
+      return out;
+    }
+    if (declMap.has(simple) && !seen.has(simple)) {
+      const next = new Set(seen); next.add(simple);
+      const decl = declMap.get(simple);
+      const target = ts.isInterfaceDeclaration(decl) ? decl : decl.type;
+      return resolveType(target, ctx, depth + 1, next);
+    }
+    return {}; // opaque / imported — never enumerate (no DOM-attr dump)
+  }
+
+  return {};
+}
+
+/**
+ * TS-aware extraction for ONE component. Returns `{ props, variantProp, variants }`
+ * on success, or `null` to signal the caller to use the regex path for this file
+ * (typescript unavailable, no resolvable param type, or any parse/traversal error).
+ */
+export function extractPropsTs(src, name, fileName) {
+  if (!ts) return null;
+  try {
+    const kind = /\.tsx$/.test(fileName || '') ? ts.ScriptKind.TSX : ts.ScriptKind.TS;
+    const sf = ts.createSourceFile(fileName || 'component.tsx', src, ts.ScriptTarget.Latest, true, kind);
+    const typeNode = findComponentParamType(sf, name);
+    if (!typeNode) return null; // untyped param → let regex try the `${name}Props` convention
+    const props = resolveType(typeNode, { sf, declMap: buildDeclMap(sf) }, 0, new Set());
+    if (!props || typeof props !== 'object') return null;
+    const variantProp = computeVariantProp(props);
+    const variants = variantProp ? literalMembers(props[variantProp].type) : [];
+    return { props, variantProp, variants };
+  } catch (_) {
+    return null;
+  }
+}

package/framework/.claude/skills/design-system-init/scripts/render-manifest.mjs

@@ -45,13 +45,27 @@ function parseHead(md) {
   if (!name) return null;
   const source = scalar('source');
 
-  // variants: [a, b, c]  (the enumerated literal union of the `variant` prop)
+  // variants — the enumerated literal union of the variant-axis prop. The
+  // serializer emits a BLOCK list for non-empty arrays (`variants:\n  - a`) and
+  // flow `[]` when empty, so accept BOTH block and flow `[a, b]` here.
   let variants = [];
-  const vr = head.match(/^variants:\s*\[(.*?)\]/m);
-  if (vr && vr[1].trim()) {
-    variants = vr[1].split(',').map((s) => s.trim().replace(/^["']|["']$/g, '')).filter(Boolean);
+  const vFlow = head.match(/^variants:\s*\[(.*?)\]/m);
+  if (vFlow && vFlow[1].trim()) {
+    variants = vFlow[1].split(',').map((s) => s.trim().replace(/^["']|["']$/g, '')).filter(Boolean);
+  } else {
+    const vBlock = head.match(/^variants:\s*\n((?:[ \t]+-[ \t]*.+\n?)+)/m);
+    if (vBlock) {
+      variants = vBlock[1].split('\n')
+        .map((l) => { const m2 = l.match(/^\s*-\s*(.+?)\s*$/); return m2 ? m2[1].replace(/^["']|["']$/g, '') : null; })
+        .filter(Boolean);
+    }
   }
 
+  // variant_prop: which prop is the variant axis (since v4.77.0). Legacy HEADs
+  // (pre-v4.77.0) lack it → default to 'variant' when variants are present, so
+  // existing registries keep the same axis/rendering.
+  const variant_prop = scalar('variant_prop') || (variants.length ? 'variant' : '');
+
   // props block: each line `  <name>: { type: "...", required: ..., default: ... }`
   const props = {};
   const pm = head.match(/^props:\s*\n([\s\S]*?)(?=^\S|\n# ===|\Z)/m);
@@ -68,7 +82,7 @@ function parseHead(md) {
       props[pname] = { type: strip(typeM && typeM[1]) || '', default: strip(defM && defM[1]) };
     }
   }
-  return { name, source, variants, props };
+  return { name, source, variant_prop, variants, props };
 }
 
 // Enumerable iff the prop type is a literal union of string/number/boolean
@@ -89,7 +103,10 @@ function enumMembers(type) {
 
 function entriesFor(spec, full) {
   const { name, variants, props } = spec;
-  const others = Object.keys(props).filter((p) => p !== 'variant');
+  // The variant axis is the prop named by `variant_prop` (default 'variant' for
+  // legacy HEADs) — NOT hardcoded, so a Chip whose axis is `tone` mounts `tone`.
+  const axis = spec.variant_prop || (variants.length ? 'variant' : '');
+  const others = Object.keys(props).filter((p) => p !== axis);
   const baseFixture = {};
   for (const p of others) if (props[p].default !== undefined && props[p].default !== null) baseFixture[p] = props[p].default;
 
@@ -97,8 +114,8 @@ function entriesFor(spec, full) {
   const variantValues = variants.length ? variants : ['default'];
   let entries = variantValues.map((v) => ({
     id: `${name}--${v}`,
-    props: { ...(variants.length ? { variant: v } : {}), ...baseFixture },
-    axis: 'variant',
+    props: { ...(variants.length && axis ? { [axis]: v } : {}), ...baseFixture },
+    axis: axis || 'variant',
   }));
 
   if (full) {
@@ -150,7 +167,7 @@ function main() {
       spec = parseHead(fs.readFileSync(path.join(dir, file), 'utf8'));
     } catch (_) { spec = null; }
     if (!spec) { skipped.push(file); continue; }
-    components.push({ name: spec.name, source: spec.source || null, variants: spec.variants, entries: entriesFor(spec, full) });
+    components.push({ name: spec.name, source: spec.source || null, variant_prop: spec.variant_prop || null, variants: spec.variants, entries: entriesFor(spec, full) });
   }
 
   emit({

package/framework/.claude/skills/design-system-init/scripts/serialize-spec.mjs

@@ -16,8 +16,9 @@
 // Usage:
 //   node serialize-spec.mjs --bundle bundle.json --out-dir <dir> [--index <path>] [--brand <name>]
 //   bundle.json = { brand?, components: [ { name, source, source_sha, status,
-//     category, props:{}, variants:[], composes:[], purpose, token_bindings:[],
-//     a11y, related:[], must_rules:[], last_verified, owner, prose } ] }
+//     category, props:{}, variant_prop, variants:[], composes:[], purpose,
+//     token_bindings:[], a11y, related:[], must_rules:[], last_verified, owner,
+//     prose } ] }
 // Exits non-zero if any emitted HEAD fails to re-parse (when js-yaml is present).
 
 import fs from 'node:fs';
@@ -72,6 +73,7 @@ export function emitHead(c) {
   L.push(`status: ${scalar(c.status || 'stable')}`);
   L.push(`category: ${scalar(c.category || 'primitive')}`);
   L.push(propsBlock(c.props));
+  L.push(`variant_prop: ${scalar(c.variant_prop ?? '')}`);
   L.push(list('variants', c.variants));
   L.push(list('composes', c.composes));
   L.push('# AGENTIC (curated by doc-reviewer — preserved across regeneration):');

package/framework/.claude/skills/ds-edit/SKILL.md

@@ -110,7 +110,8 @@ Each step is a delegation. Read the cited SSOT; do not paraphrase it.
    describe the required source change as a TODO and require the user to apply it.
 3. **Re-extract the deterministic HEAD.**
    `node .framework/framework/.claude/skills/design-system-init/scripts/extract-one.mjs --source <path.tsx> --json`
-   → the updated `props` / `variants` / `composes` / `source_sha` from the new source.
+   → the updated `props` / `variant_prop` / `variants` / `composes` / `source_sha`
+   from the new source (TS-aware: resolves type aliases / unions / `Omit` / `Pick`).
 4. **Re-verify the agentic fields.** DELEGATE `doc-reviewer` to update ONLY what the
    change affects (`must_rules` / `a11y` / `token_bindings` / `purpose`) and keep the
    rest. Existing values are preserved by the serializer; never blank a field you

package/framework/.claude/skills/ds-new/SKILL.md

@@ -102,8 +102,8 @@ Each step is a delegation. Read the cited SSOT; do not paraphrase it.
    path. The skill itself NEVER writes component source.
 3. **Extract the deterministic HEAD.**
    `node .framework/framework/.claude/skills/design-system-init/scripts/extract-one.mjs --source <path.tsx> --json`
-   → `name`/`source`/`source_sha`/`props`/`variants`/`composes` (zero-dep,
-   Codex-portable, no subagent).
+   → `name`/`source`/`source_sha`/`props`/`variant_prop`/`variants`/`composes`
+   (TS-aware when typescript resolves, else zero-dep regex; Codex-portable, no subagent).
 4. **Enrich the agentic fields AS DATA.** DELEGATE `doc-reviewer` (Task tool) to
    produce `purpose` / `token_bindings` (picked from the REAL ids in
    `${paths.design_tokens}`) / `a11y` / `related` / `must_rules` as JSON values —