@starklab/stark-mcp 0.1.0 → 0.2.0

package/src/adopt/usageRulesResolver.js

@@ -0,0 +1,298 @@
+import path from 'node:path';
+
+import traverseModule from '@babel/traverse';
+
+import { checkComponentRules } from '@starklab/stk/conformance/index.js';
+
+import { packageNameForPlatform } from './catalog.js';
+import { buildModuleGraph, resolveOrigin } from './moduleGraph.js';
+
+const traverse = traverseModule.default ?? traverseModule;
+
+// The only catalog components checkComponentRules has rules for at all
+// (Toolbar count, Button primary-variant count, DropdownMenu empty-items).
+// Extracting every other component into a fake node would just widen the
+// AST walk for zero additional findings — checkComponentRules doesn't look
+// at anything else.
+const RULE_TYPES = new Set(['Toolbar', 'Button', 'DropdownMenu']);
+
+/**
+ * Evaluates a JSX attribute value as a (possibly nested) literal — recurses
+ * into object/array expressions so `logo={{ src: '/x.svg' }}` and
+ * `items={[{ label: 'A' }]}` resolve, not just scalars like
+ * propApiResolver.js's literalAttrValue handles. A dynamic expression
+ * (identifier, call, member access, ternary, template, spread, JSX child)
+ * is reported unresolved rather than guessed — this resolver never invents
+ * a violation it can't statically prove.
+ */
+export function resolveJsxLiteral(node) {
+  if (!node) return { resolved: false };
+  switch (node.type) {
+    case 'StringLiteral':
+    case 'NumericLiteral':
+    case 'BooleanLiteral':
+      return { resolved: true, value: node.value };
+    case 'NullLiteral':
+      return { resolved: true, value: null };
+    case 'JSXExpressionContainer':
+      return resolveJsxLiteral(node.expression);
+    case 'ArrayExpression': {
+      const values = [];
+      for (const el of node.elements) {
+        if (el === null) { values.push(null); continue; }
+        if (el.type === 'SpreadElement') return { resolved: false };
+        const r = resolveJsxLiteral(el);
+        if (!r.resolved) return { resolved: false };
+        values.push(r.value);
+      }
+      return { resolved: true, value: values };
+    }
+    case 'ObjectExpression': {
+      const obj = {};
+      for (const prop of node.properties) {
+        if (prop.type !== 'ObjectProperty' || prop.computed) return { resolved: false };
+        const key = prop.key.type === 'Identifier' ? prop.key.name
+          : prop.key.type === 'StringLiteral' ? prop.key.value
+          : null;
+        if (key === null) return { resolved: false };
+        const r = resolveJsxLiteral(prop.value);
+        if (!r.resolved) return { resolved: false };
+        obj[key] = r.value;
+      }
+      return { resolved: true, value: obj };
+    }
+    default:
+      // Includes JSXElement/JSXFragment (a component passed as a prop, e.g.
+      // accountMenu={<DropdownMenu .../>}) — out of scope, treated as
+      // unresolved like any other non-literal expression.
+      return { resolved: false };
+  }
+}
+
+/**
+ * Turns one JSX call site into the `{ type, ...props }` node shape
+ * checkComponentRules expects from an AI-generated layout tree, built
+ * instead from statically-resolvable JSX attributes. A prop that can't be
+ * resolved is omitted from the node rather than guessed at.
+ *
+ * That omission is safe for Toolbar (`logo`) and DropdownMenu (`items`) —
+ * an absent key just skips that sub-check, the same as a real layout node
+ * that never set it. It is NOT safe for Button's `variant`: checkComponentRules
+ * defaults a missing variant to "primary" (mirroring the real renderer), so
+ * silently dropping an unresolved `variant={cond ? 'primary' : 'ghost'}`
+ * would make it count as a bare default-primary button — a false positive
+ * this resolver has no evidence for. `unresolvedDynamic` flags that one case
+ * so the caller can drop the whole node from the primary-count rule instead
+ * of guessing either way.
+ */
+export function extractUsageNode({ type, attributes }) {
+  const node = { type };
+  let unresolvedDynamic = false;
+
+  for (const attr of attributes) {
+    if (attr.type === 'JSXSpreadAttribute') continue;
+    const name = attr.name.name;
+    if (attr.value === null) { node[name] = true; continue; } // boolean shorthand: <Button showLabel />
+    const r = resolveJsxLiteral(attr.value);
+    if (r.resolved) {
+      node[name] = r.value;
+    } else if (type === 'Button' && name === 'variant') {
+      unresolvedDynamic = true;
+    }
+  }
+
+  return { node, unresolvedDynamic };
+}
+
+/**
+ * DropdownMenu's real JSX API is compound/children-based
+ * (`<DropdownMenu><DropdownMenu.Trigger/><DropdownMenu.Content><DropdownMenu.Item
+ * label="Edit" /></DropdownMenu.Content></DropdownMenu>`), but
+ * checkComponentRules' `resolvedDropdownItems` only reads the `items` /
+ * `children.content` / `content` *props* — the shape Vecna's generated layout
+ * JSON uses. Without this scan, every hand-authored compound-API usage (e.g.
+ * LayoutCanvas.jsx's own renderer) would read as an empty menu: not because it
+ * is one, but because its items live in JSX children this resolver otherwise
+ * never looks at. Recurses through wrapping elements/fragments to find
+ * `<localName>.Item>` descendants and pull a static `label`; any other `{…}`
+ * expression in the subtree (a `.map()`, a conditional) means the real item
+ * list is dynamic, so this reports `dynamic: true` rather than guessing empty
+ * or non-empty.
+ */
+function scanDropdownItemsInChildren(children, localName) {
+  let dynamic = false;
+  const items = [];
+
+  for (const child of children ?? []) {
+    switch (child.type) {
+      case 'JSXText':
+      case 'JSXEmptyExpression':
+        break;
+      case 'JSXExpressionContainer':
+        if (child.expression.type !== 'JSXEmptyExpression') dynamic = true;
+        break;
+      case 'JSXSpreadChild':
+        dynamic = true;
+        break;
+      case 'JSXFragment':
+        {
+          const sub = scanDropdownItemsInChildren(child.children, localName);
+          if (sub.dynamic) dynamic = true;
+          items.push(...sub.items);
+        }
+        break;
+      case 'JSXElement': {
+        const name = child.openingElement.name;
+        const isItem = name.type === 'JSXMemberExpression'
+          && name.object.type === 'JSXIdentifier' && name.object.name === localName
+          && name.property.name === 'Item';
+        if (isItem) {
+          const attrs = child.openingElement.attributes;
+          const isSeparator = attrs.some(a => a.type === 'JSXAttribute' && a.name.name === 'separator');
+          if (!isSeparator) {
+            const labelAttr = attrs.find(a => a.type === 'JSXAttribute'
+              && ['label', 'title', 'text'].includes(a.name.name));
+            const r = labelAttr ? resolveJsxLiteral(labelAttr.value) : { resolved: false };
+            if (r.resolved && r.value) items.push({ label: r.value });
+            else dynamic = true; // an Item with no statically-provable label — don't guess its presence away
+          }
+        } else {
+          const sub = scanDropdownItemsInChildren(child.children, localName);
+          if (sub.dynamic) dynamic = true;
+          items.push(...sub.items);
+        }
+        break;
+      }
+      default:
+        break;
+    }
+  }
+
+  return { dynamic, items };
+}
+
+/**
+ * Runs the Vecna conformance gate's component-usage rules
+ * (`packages/stk/conformance/index.js`'s `checkComponentRules` — Toolbar
+ * count, Button primary-variant count, DropdownMenu empty-items) against a
+ * scanned consumer repo's own JSX, not just Vecna's AI-generated layout
+ * JSON. This is the adapter ADOPTION_APP_PLAN.md's R3/§10 decision #3 called
+ * for: the gate's input contract is a `layout.page.sections[]` node tree, so
+ * each scanned file's statically-resolvable Toolbar/Button/DropdownMenu
+ * usages are assembled into one such tree — treating one file as one "page",
+ * since that's the natural unit a consumer app's own routing already uses,
+ * and it's what keeps "at most one Toolbar" / "at most one primary Button"
+ * meaningful instead of comparing unrelated screens against each other.
+ *
+ * Only the three rule-bearing checks are reusable this way — checkGuardrails
+ * needs Vecna's own `intent`, checkStructure/checkCatalogRendererParity only
+ * make sense against Vecna's own renderer cases, and checkRendered needs a
+ * live DOM snapshot. Reusing all of those against arbitrary external code
+ * isn't what "wiring them together" can mean; checkComponentRules is the one
+ * genuinely platform-agnostic, structural piece.
+ *
+ * Web only — `packages/stk/conformance/`'s node-shape conventions
+ * (`logo.src`, `items[].label`) are the web renderer's own, and RN's
+ * Toolbar/Button/DropdownMenu equivalents don't share them.
+ */
+export function resolveUsageRules(root, { platform = 'web', ignore = [] } = {}) {
+  if (platform !== 'web') {
+    throw new Error(`resolveUsageRules only supports platform "web" (got "${platform}") — checkComponentRules' node shapes (logo.src, items[].label) are the web renderer's own.`);
+  }
+
+  const pkgName = packageNameForPlatform(platform);
+  const moduleGraph = buildModuleGraph(root, { ignore });
+
+  const findings = [];
+  const unresolvedFiles = [];
+  let filesWithUsage = 0;
+
+  for (const file of moduleGraph.files) {
+    const entry = moduleGraph.graph.get(file);
+    if (!entry) continue;
+    if (entry.parseError) {
+      unresolvedFiles.push(path.relative(root, file));
+      continue;
+    }
+
+    const localToType = new Map();
+    for (const localName of entry.imports.keys()) {
+      const origin = resolveOrigin(moduleGraph, file, localName);
+      if (origin?.pkg === pkgName && RULE_TYPES.has(origin.name)) {
+        localToType.set(localName, origin.name);
+      }
+    }
+    if (localToType.size === 0) continue;
+
+    const nodes = [];
+    let droppedForUnresolvedVariant = 0;
+    let droppedForUnresolvedDropdownChildren = 0;
+
+    traverse(entry.ast, {
+      JSXOpeningElement(elPath) {
+        const nameNode = elPath.node.name;
+        const localName = nameNode.type === 'JSXIdentifier' ? nameNode.name : null;
+        const type = localName ? localToType.get(localName) : null;
+        if (!type) return;
+        const { node, unresolvedDynamic } = extractUsageNode({ type, attributes: elPath.node.attributes });
+        if (unresolvedDynamic) { droppedForUnresolvedVariant += 1; return; }
+
+        if (type === 'DropdownMenu' && node.items === undefined
+          && node.content === undefined && node.children === undefined) {
+          const parent = elPath.parentPath.node;
+          const scan = parent.type === 'JSXElement'
+            ? scanDropdownItemsInChildren(parent.children, localName)
+            : { dynamic: false, items: [] };
+          if (scan.dynamic) { droppedForUnresolvedDropdownChildren += 1; return; }
+          if (scan.items.length > 0) node.items = scan.items;
+        }
+
+        nodes.push(node);
+      },
+    });
+
+    if (nodes.length === 0 && droppedForUnresolvedVariant === 0 && droppedForUnresolvedDropdownChildren === 0) continue;
+    filesWithUsage += 1;
+
+    const relFile = path.relative(root, file);
+
+    if (nodes.length > 0) {
+      const layout = { page: { sections: [{ id: relFile, nodes }] } };
+      for (const f of checkComponentRules(layout)) {
+        findings.push({ ...f, file: relFile });
+      }
+    }
+
+    if (droppedForUnresolvedVariant > 0) {
+      findings.push({
+        severity: 'Info',
+        finding: `${droppedForUnresolvedVariant} Button node(s) in ${relFile} have a dynamic \`variant\` (not a string literal) — excluded from the primary-button-count rule rather than guessed.`,
+        violated: 'usage pattern',
+        owner: 'vecna-layouts',
+        fix: 'No action needed unless this recurs across many files in the same view — a static variant lets the check be exact.',
+        file: relFile,
+      });
+    }
+
+    if (droppedForUnresolvedDropdownChildren > 0) {
+      findings.push({
+        severity: 'Info',
+        finding: `${droppedForUnresolvedDropdownChildren} DropdownMenu node(s) in ${relFile} build their items dynamically (a \`.map()\`, a conditional, or an unlabeled \`Item\`) — excluded from the empty-menu rule rather than guessed.`,
+        violated: 'usage pattern',
+        owner: 'vecna-layouts',
+        fix: 'No action needed unless the menu is actually empty at runtime — a static `DropdownMenu.Item` list or `items` prop lets the check be exact.',
+        file: relFile,
+      });
+    }
+  }
+
+  return {
+    platform,
+    package: pkgName,
+    root,
+    scannedFiles: moduleGraph.files.length,
+    filesWithUsage,
+    unresolvedFiles,
+    findings,
+  };
+}

package/src/adopt/vecnaMaterializer.js

@@ -0,0 +1,165 @@
+import { mkdirSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+
+import { buildCatalogFromDir } from '@starklab/stk/conformance/catalog.js';
+import { mappingDir } from '../data.js';
+
+// The 5 layout primitives (logo/heading/text/divider/spacer) are hardcoded
+// as plain HTML in LayoutCanvas.jsx and Vecna's own system prompt — they
+// have no prop-mapping/*.mapping.json, so buildCatalogFromDir() never
+// returns them. Every other nodeType is expected to resolve to a real
+// catalog component; these five are the one *known* class of intentional
+// skip, not evidence of an incomplete catalog.
+const KNOWN_PRIMITIVE_TYPES = new Set(['logo', 'heading', 'text', 'divider', 'spacer']);
+
+function buildCatalogMap() {
+  const entries = buildCatalogFromDir(mappingDir(), { platform: 'web' });
+  return new Map(entries.map((e) => [e.schema.nodeType, e]));
+}
+
+function serializePropValue(name, def, value) {
+  if (def.type === 'boolean') {
+    return value ? name : `${name}={false}`;
+  }
+  if (def.type === 'string' || def.type === 'enum') {
+    return `${name}=${JSON.stringify(String(value))}`;
+  }
+  if (def.type === 'stringArray') {
+    if (!Array.isArray(value)) return null;
+    return `${name}={${JSON.stringify(value)}}`;
+  }
+  return null;
+}
+
+/**
+ * Emits one node as a JSX element string, recursing into its slots.
+ * Never guesses: a nodeType absent from the catalog, a prop of unknown
+ * type, or a slot value of the wrong shape is skipped with a logged
+ * reason instead of being fabricated — same discipline as
+ * usageRulesResolver.js's resolveJsxLiteral/extractUsageNode.
+ */
+function emitNode(node, catalogMap, componentsUsed, skipped, nodePath, counter) {
+  if (!node || typeof node !== 'object') {
+    skipped.push({ path: nodePath, kind: 'malformed', reason: 'missing or malformed node' });
+    return null;
+  }
+
+  // A slot value with no `type` is not a broken node — several slots are
+  // declared in layoutSchema as *literal payload shapes* rather than nested
+  // catalog nodes, and carry no `type` by design: Toolbar's `logo` is
+  // documented as a flat `{ src, alt }`, DropdownMenu's `items[]` entries are
+  // `{ label }` / `{ separator }` descriptors, and the lowercase `accepts`
+  // values (heading, image, spacer, text) mark the same thing. These carry no
+  // component props, so there is genuinely nothing for propApi to verify —
+  // they are correctly excluded, but must not be reported as malformed, or
+  // the coverage number reads as a defect count instead of a denominator.
+  if (!node.type) {
+    skipped.push({
+      path: nodePath,
+      kind: 'literal',
+      reason: 'schema-declared literal slot payload (no "type" field, e.g. {src,alt} or {label}) — not a catalog node, no props to verify',
+    });
+    return null;
+  }
+
+  const entry = catalogMap.get(node.type);
+  if (!entry) {
+    const isPrimitive = KNOWN_PRIMITIVE_TYPES.has(node.type);
+    skipped.push({
+      path: nodePath,
+      nodeType: node.type,
+      kind: isPrimitive ? 'primitive' : 'unmapped',
+      reason: isPrimitive
+        ? 'layout primitive (hardcoded HTML in LayoutCanvas, no prop-mapping file — not a catalog component)'
+        : 'no catalog entry for this nodeType (unmapped or missing layoutSchema)',
+    });
+    return null;
+  }
+
+  componentsUsed.add(entry.name);
+  counter.emitted++;  // node count, not distinct-name count — this is the coverage denominator
+
+  const attrParts = [];
+  for (const propDef of entry.schema.props ?? []) {
+    const value = node[propDef.name];
+    if (value === undefined) continue; // optional/absent — nothing to emit, never defaulted
+    const serialized = serializePropValue(propDef.name, propDef, value);
+    if (serialized === null) {
+      skipped.push({ path: `${nodePath}.${propDef.name}`, kind: 'unrepresentable', reason: `unrepresentable prop value for type "${propDef.type}"` });
+      continue;
+    }
+    attrParts.push(serialized);
+  }
+
+  const slotDefs = entry.schema.slots ?? [];
+  for (const slotDef of slotDefs) {
+    const slotValue = node[slotDef.name];
+    if (slotValue === undefined) continue;
+
+    if (slotDef.array) {
+      if (!Array.isArray(slotValue)) {
+        skipped.push({ path: `${nodePath}.${slotDef.name}`, kind: 'malformed', reason: 'expected array slot value, got non-array' });
+        continue;
+      }
+      const children = [];
+      slotValue.forEach((child, i) => {
+        const jsx = emitNode(child, catalogMap, componentsUsed, skipped, `${nodePath}.${slotDef.name}[${i}]`, counter);
+        if (jsx) children.push(jsx);
+      });
+      if (children.length > 0) {
+        attrParts.push(`${slotDef.name}={<>${children.join('')}</>}`);
+      }
+    } else {
+      const jsx = emitNode(slotValue, catalogMap, componentsUsed, skipped, `${nodePath}.${slotDef.name}`, counter);
+      if (jsx) attrParts.push(`${slotDef.name}={${jsx}}`);
+    }
+  }
+
+  const openTag = attrParts.length > 0 ? `<${entry.name} ${attrParts.join(' ')}` : `<${entry.name}`;
+  return `${openTag} />`;
+}
+
+/**
+ * Compiles a Vecna LayoutConfig into a real, syntactically valid .jsx file
+ * with real `import { X } from '@starklab/stk-components'` statements and
+ * real JSX element trees — so the actual adopt/ resolvers (which require a
+ * scannable file on disk, not a JSON tree) can run against Vecna's own
+ * generated output unmodified. See ADOPTION_APP_PLAN.md R3 point 3.
+ *
+ * Only mechanically representable content is emitted. Anything else
+ * (unmapped nodeType, malformed prop/slot shape) is recorded in
+ * `skippedNodes` with a reason, never guessed or defaulted.
+ *
+ * The output filename must never contain ".stories." — moduleGraph.js's
+ * DEFAULT_IGNORE excludes that glob, which would make every resolver
+ * silently skip the file.
+ */
+export function materializeLayout(layoutConfig, { outDir, slug = 'layout' } = {}) {
+  const catalogMap = buildCatalogMap();
+  const componentsUsed = new Set();
+  const counter = { emitted: 0 };
+  const skippedNodes = [];
+
+  const sections = layoutConfig?.page?.sections ?? [];
+  const elements = [];
+  sections.forEach((section, si) => {
+    const nodes = section?.nodes ?? [];
+    nodes.forEach((node, ni) => {
+      const jsx = emitNode(node, catalogMap, componentsUsed, skippedNodes, `page.sections[${si}](${section?.id ?? si}).nodes[${ni}]`, counter);
+      if (jsx) elements.push(jsx);
+    });
+  });
+
+  const componentNames = [...componentsUsed].sort();
+  const importLine = componentNames.length > 0
+    ? `import { ${componentNames.join(', ')} } from '@starklab/stk-components';\n\n`
+    : '';
+
+  const source = `${importLine}export default function MaterializedLayout() {\n  return (\n    <>\n      ${elements.join('\n      ')}\n    </>\n  );\n}\n`;
+
+  mkdirSync(outDir, { recursive: true });
+  const filePath = path.join(outDir, `${slug}.materialized.jsx`);
+  writeFileSync(filePath, source, 'utf-8');
+
+  return { filePath, componentsUsed: componentNames, nodesEmitted: counter.emitted, skippedNodes };
+}

package/src/adopt/vecnaVerifier.js

@@ -0,0 +1,127 @@
+import path from 'node:path';
+
+import { materializeLayout } from './vecnaMaterializer.js';
+import { resolveWrappers } from './wrapperResolver.js';
+import { resolveTokenAliases } from './tokenAliasResolver.js';
+import { resolvePropApi } from './propApiResolver.js';
+
+/**
+ * Runs the real client-side adopt/ resolvers against one Vecna-generated
+ * LayoutConfig, via a materialized real .jsx file (see vecnaMaterializer.js).
+ * This is the reverse direction of R3 (ADOPTION_APP_PLAN.md): stark-cli adopt
+ * checks real client code against the catalog; this checks Vecna's own
+ * output against the same catalog, using the same resolver code, not a
+ * second parallel reimplementation of the checks.
+ *
+ * IMPORTANT — of the three resolvers run here, only propApi is structurally
+ * capable of producing real findings against materialized output:
+ *   - wrapperResolver detects a *consumer's own local wrapper component*
+ *     that renders a catalog component internally (e.g. a local MyButton
+ *     wrapping <Button/>). Vecna's materialized output only ever contains
+ *     direct catalog JSX — it never generates a wrapper component — so this
+ *     always returns real-but-empty results. Included for parity with
+ *     stark-cli adopt's own resolver set, not because it can find anything
+ *     here; this is by construction, not a materializer gap.
+ *   - tokenAliasResolver scans every .css file for a `--custom-prop:
+ *     var(--stk-*)` alias graph. Vecna never emits CSS files or alias indirection — it
+ *     only ever references `var(--stk-*)` tokens as one-hop literal prop/
+ *     style string values — so this resolver finds zero files to scan and
+ *     always returns empty. Same "vacuous by construction" caveat as above.
+ *   - propApiResolver validates literal JSX call-site props (invalid enum
+ *     values, missing required props, deprecated props, className/style
+ *     escape hatches) against prop-mapping/*.mapping.json. A materialized
+ *     layout *is* a set of call-site JSX props, so this is the one check
+ *     whose domain actually matches — this is where real findings live.
+ *     NOTE — one of propApiResolver's four rules is itself vacuous by
+ *     construction here: style-escape-hatch checks for STYLE_ESCAPE_ATTRS
+ *     (className/style) on a call site, but vecnaMaterializer.js only ever
+ *     emits props declared in a component's layoutSchema — className/style
+ *     are never among them, so this rule can never fire against Vecna
+ *     output. The other three (invalid-enum-value, required-prop-missing,
+ *     deprecated-prop-passed) are real. Same honesty as the wrappers/
+ *     tokenAliases bullets above — propApi as a whole is not vacuous, but
+ *     don't count this rule as live coverage when citing "N rules checked."
+ *
+ * This mirrors R3 point 1's own finding (only 1 of 6 conformance checks
+ * generalizes to arbitrary scanned JSX) one level deeper — see
+ * feedback_dont_conflate_architecture_fix_with_full_resolution. Do not
+ * describe this as "runs the same 4 resolvers as adopt" without this
+ * caveat; moduleGraph is shared internal plumbing, not an independent
+ * check, so only 1 of the 3 externally-visible resolvers here is load-
+ * bearing for this specific input shape.
+ */
+export function verifyVecnaLayout(layoutConfig, { outDir, slug = 'layout' } = {}) {
+  const dir = path.resolve(outDir ?? path.join(process.cwd(), '.vecna-verify'));
+  const { filePath, componentsUsed, nodesEmitted, skippedNodes } = materializeLayout(layoutConfig, { outDir: dir, slug });
+
+  // Each resolver is isolated: a crash inside one must never take down the
+  // others. This matters most for the two vacuous ones — their results are
+  // never read by the caller, but they still *execute*, so without isolation
+  // a bug in a resolver whose output is declared meaningless can still kill
+  // the gate. That was live: resolveWrappers() was called with
+  // `workspacePackages: {}`, but resolveWrappers documents that option as an
+  // optional `Map<packageName, absoluteDir>` and does `workspacePackages ||
+  // new Map()` — `{}` is truthy, so it survived the default and threw
+  // `workspace?.packages?.has is not a function` from resolveWorkspacePackage
+  // as soon as a wrapper chain reached a terminal tag. Omitting the option
+  // fixes that call site; the isolation below is what stops the next one.
+  // Same per-item failure-isolation discipline as scan-foreign's.
+  const run = (name, fn) => {
+    try {
+      return { result: fn(), failed: false, error: null };
+    } catch (err) {
+      return { result: null, failed: true, error: `${name} threw: ${err.message}` };
+    }
+  };
+
+  const wrappers = run('resolveWrappers', () => resolveWrappers(dir, { platform: 'web', ignore: [] }));
+  const tokenAliases = run('resolveTokenAliases', () => resolveTokenAliases(dir, { platform: 'web', ignore: [] }));
+  const propApi = run('resolvePropApi', () => resolvePropApi(dir, { platform: 'web', ignore: [] }));
+
+  // Coverage denominator. `verified` counts nodes that actually became JSX and
+  // were therefore seen by propApi; `unverifiable` counts the skips that are
+  // correct by construction (layout primitives, literal slot payloads), and
+  // `gaps` counts the ones that are genuine blind spots (malformed input, an
+  // unmapped nodeType, a prop shape the materializer can't represent). A gate
+  // that reports "clean" without this is reporting the absence of findings in
+  // an unstated denominator — gaps > 0 means "clean" is a weaker claim.
+  const byKind = {};
+  for (const s of skippedNodes) byKind[s.kind ?? 'unknown'] = (byKind[s.kind ?? 'unknown'] ?? 0) + 1;
+  const unverifiable = (byKind.primitive ?? 0) + (byKind.literal ?? 0);
+  const coverage = {
+    verified: nodesEmitted,
+    skipped: skippedNodes.length,
+    unverifiable,
+    gaps: skippedNodes.length - unverifiable,
+    byKind,
+  };
+
+  return {
+    materialized: { filePath, componentsUsed, nodesEmitted, skippedNodes, coverage },
+    resolvers: {
+      wrappers: {
+        vacuousByConstruction: true,
+        reason: 'Vecna output has no local wrapper components — only direct catalog JSX.',
+        failed: wrappers.failed,
+        error: wrappers.error,
+        result: wrappers.result,
+      },
+      tokenAliases: {
+        vacuousByConstruction: true,
+        reason: 'Vecna output has no CSS files or custom-property alias chains.',
+        failed: tokenAliases.failed,
+        error: tokenAliases.error,
+        result: tokenAliases.result,
+      },
+      propApi: {
+        vacuousByConstruction: false,
+        reason: 'Materialized call-site JSX props are exactly what this resolver validates. ' +
+          'One exception: style-escape-hatch is vacuous by construction here — the materializer ' +
+          'never emits className/style, so only 3 of the 4 rules can produce real findings.',
+        failed: propApi.failed,
+        error: propApi.error,
+        result: propApi.result,
+      },
+    },
+  };
+}