npm - @starklab/stark-mcp - Versions diffs - 0.2.0 → 0.3.0 - Mend

@starklab/stark-mcp 0.2.0 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (26) hide show

package/README.md +42 -4
package/package.json +12 -1
package/src/adopt/a11yPass.js +397 -0
package/src/adopt/adoptGate.js +471 -0
package/src/adopt/adoptScanReport.js +9 -0
package/src/adopt/componentPropApi.js +200 -0
package/src/adopt/findingSnippet.js +386 -0
package/src/adopt/foreignDiscoveryResolver.js +20 -3
package/src/adopt/foreignScoringResolver.js +163 -22
package/src/adopt/moduleGraph.js +44 -2
package/src/adopt/prCheckReport.js +274 -0
package/src/adopt/propApiResolver.js +2 -2
package/src/adopt/referenceResolver.js +2 -2
package/src/adopt/scanRollup.js +192 -0
package/src/adopt/tailwindResolver.js +6 -1
package/src/adopt/targetDiscovery.js +31 -3
package/src/adopt/tokenAliasResolver.js +45 -2
package/src/adopt/usageRulesResolver.js +299 -14
package/src/adopt/vecnaMaterializer.js +45 -5
package/src/adopt/vecnaVerifier.js +20 -9
package/src/adopt/wrapperResolver.js +3 -3
package/src/cli.js +343 -8
package/src/data.js +105 -11
package/src/server.js +69 -14
package/src/whisperer.d.ts +106 -0
package/src/whisperer.js +814 -0

package/src/adopt/tokenAliasResolver.js CHANGED Viewed

@@ -259,10 +259,39 @@ export function resolveTerminal(propGraph, propName, selector, inventory, layers
   });
 }
+/**
+ * Four states, not three, and the split between the last two is the point:
+ * a cycle and a depth-limit are *proven* from the CSS alone — the whole
+ * chain is in the graph and it doesn't terminate — whereas an undefined
+ * terminal only means "no definition among the files this scan happened to
+ * read." Those are not the same claim, and only the first is a defect.
+ *
+ * Measured live against openstatusHQ/openstatus's apps/dashboard, where
+ * treating them as one produced a 100% false-positive rate on real code:
+ * every one of the 165 Tailwind class usages resolved to `broken`, and so
+ * did all 5 of the `var(--radius)` usages in its globals.css. Two distinct
+ * causes, neither a defect:
+ *   - `--radius` is defined in packages/ui/src/globals.css, reached through
+ *     `@import "@openstatus/ui/globals"` — outside the scanned target root,
+ *     and behind a bare package specifier this scan never follows.
+ *   - `--font-mono` / `--font-cal` / `--font-commit-mono` (164 of the 165)
+ *     ARE defined in the scanned file, but alias next/font-injected
+ *     variables (`--font-geist-mono`, …, declared via `variable:` in
+ *     layout.tsx and applied as a class on <html>) that no CSS file can
+ *     ever contain.
+ * Both shapes are ordinary in a Next.js monorepo, so "not found in CSS"
+ * cannot be reported as breakage. `unresolved` is surfaced as an info
+ * finding instead — still visible, never a gate.
+ *
+ * Note the RN counterpart in rnTokenAliasResolver.js keeps the three-state
+ * mapping deliberately: it resolves JS object keys, where the whole graph
+ * IS the scanned source and an undefined terminal really is provable.
+ */
 export function classifyTerminalState(kind) {
   if (kind === 'stk') return 'conformant';
   if (kind === 'raw') return 'drift';
-  return 'broken'; // undefined | cycle | depth-limit
+  if (kind === 'undefined') return 'unresolved';
+  return 'broken'; // cycle | depth-limit
 }
 function classifyProperties(propGraph, inventory, layers) {
@@ -322,6 +351,17 @@ function classifyProperties(propGraph, inventory, layers) {
           line: s.line,
         });
       }
+      if (s.state === 'unresolved') {
+        findings.push({
+          rule: 'unresolved-alias',
+          severity: 'info',
+          property: propName,
+          selector: s.selector,
+          reason: 'terminal-not-in-scanned-css',
+          file: s.file,
+          line: s.line,
+        });
+      }
       if (s.terminal.rawFallbackPresent) {
         // Works today, silently becomes a hardcoded value the day the
         // aliased property is renamed — a latent-risk signal, never Critical.
@@ -423,7 +463,10 @@ function collectUsages(cssFiles, propGraph, inventory, layers) {
             const bySelector = propGraph.get(ref.name);
             if (!bySelector) {
-              usages.push({ ...site, classification: 'broken', reason: 'undefined-property' });
+              // Not 'broken' — see classifyTerminalState: the definition may
+              // live in an @import'ed sibling package or be injected at
+              // runtime (next/font, inline style={{'--x': …}}).
+              usages.push({ ...site, classification: 'unresolved', reason: 'undefined-property' });
               continue;
             }

package/src/adopt/usageRulesResolver.js CHANGED Viewed

@@ -5,7 +5,7 @@ import traverseModule from '@babel/traverse';
 import { checkComponentRules } from '@starklab/stk/conformance/index.js';
 import { packageNameForPlatform } from './catalog.js';
-import { buildModuleGraph, resolveOrigin } from './moduleGraph.js';
+import { buildModuleGraph, packageOfSpecifier, resolveOrigin } from './moduleGraph.js';
 const traverse = traverseModule.default ?? traverseModule;
@@ -16,6 +16,20 @@ const traverse = traverseModule.default ?? traverseModule;
 // at anything else.
 const RULE_TYPES = new Set(['Toolbar', 'Button', 'DropdownMenu']);
+// Components that put their content on a layer of their own — a dialog, a
+// sliding panel, a menu. "One clear CTA per view" is a rule about a *view*,
+// and an open Modal is a different view from the page behind it: its own
+// confirm button is that layer's CTA, not a second page-level one competing
+// with the page's. So the rule is evaluated per layer, not per file.
+//
+// The trigger slot is the deliberate exception — `<Popover.Trigger>`, a
+// `trigger`/`anchor` prop — because that control sits in the page and opens
+// the layer; it is not on it.
+const OVERLAY_TYPES = new Set([
+  'Modal', 'SidePanel', 'BottomSheet', 'PushPanel', 'NonModal',
+  'Popover', 'DropdownMenu', 'Toast',
+]);
 /**
  * Evaluates a JSX attribute value as a (possibly nested) literal — recurses
  * into object/array expressions so `logo={{ src: '/x.svg' }}` and
@@ -118,7 +132,28 @@ export function extractUsageNode({ type, attributes }) {
  * 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.
+ *
+ * Two details are read off DropdownMenu.jsx's own sub-component list rather
+ * than assumed, and both were live false-positive sources found by gating a
+ * real repo (apps/dominion) instead of a fixture:
+ *
+ *  - **Four sub-components carry a menu entry, not one.** `Item` is the plain
+ *    one, but `ItemRadio`/`ItemCheckbox` are entries in a RadioGroup/Group,
+ *    and `SubTrigger` is the entry that opens a submenu. Matching only `Item`
+ *    read a fully-populated radio menu as empty and fired the Critical
+ *    "no resolvable menu entries" rule against valid code. The container
+ *    sub-components (`Content`, `RadioGroup`, `Group`, `Sub`, `SubContent`)
+ *    keep falling through to the recursion below, which is how the entries
+ *    inside them are reached; `Separator` falls through too and contributes
+ *    nothing, which is correct — it is not an entry.
+ *  - **`Trigger` is skipped outright.** It holds the anchor control, never a
+ *    menu entry, and its subtree is ordinary application JSX — so an
+ *    expression child in there (a `{count}` in a button label) would set
+ *    `dynamic` and silently drop the whole menu from a rule that had nothing
+ *    to do with the trigger.
  */
+const DROPDOWN_ENTRY_SUBCOMPONENTS = new Set(['Item', 'ItemRadio', 'ItemCheckbox', 'SubTrigger']);
 function scanDropdownItemsInChildren(children, localName) {
   let dynamic = false;
   const items = [];
@@ -143,10 +178,12 @@ function scanDropdownItemsInChildren(children, localName) {
         break;
       case 'JSXElement': {
         const name = child.openingElement.name;
-        const isItem = name.type === 'JSXMemberExpression'
+        const subComponent = name.type === 'JSXMemberExpression'
           && name.object.type === 'JSXIdentifier' && name.object.name === localName
-          && name.property.name === 'Item';
-        if (isItem) {
+          ? name.property.name
+          : null;
+        if (subComponent === 'Trigger') break; // the anchor, never an entry
+        if (subComponent && DROPDOWN_ENTRY_SUBCOMPONENTS.has(subComponent)) {
           const attrs = child.openingElement.attributes;
           const isSeparator = attrs.some(a => a.type === 'JSXAttribute' && a.name.name === 'separator');
           if (!isSeparator) {
@@ -171,6 +208,204 @@ function scanDropdownItemsInChildren(children, localName) {
   return { dynamic, items };
 }
+/**
+ * The overlay layer a JSX node is rendered on, or `''` for the page itself.
+ * Walks outward to the nearest enclosing OVERLAY_TYPES element, skipping any
+ * whose trigger slot the node sits in (see OVERLAY_TYPES). The layer's own
+ * source offset makes the key, so two sibling Modals in one file are two
+ * layers, not one.
+ */
+export function overlaySectionOf(elPath, localToOverlay) {
+  let cur = elPath.parentPath;
+  let viaTrigger = false;
+  while (cur) {
+    const n = cur.node;
+    if (n.type === 'JSXAttribute') {
+      if (n.name?.name === 'trigger' || n.name?.name === 'anchor') viaTrigger = true;
+    } else if (n.type === 'JSXElement') {
+      const nm = n.openingElement.name;
+      if (nm.type === 'JSXMemberExpression' && nm.property?.name === 'Trigger') {
+        viaTrigger = true;
+      } else if (nm.type === 'JSXIdentifier' && localToOverlay.has(nm.name)) {
+        if (!viaTrigger) return `${localToOverlay.get(nm.name)}@${n.start}`;
+        viaTrigger = false; // that trigger belonged to this overlay — keep going outward
+      }
+    }
+    cur = cur.parentPath;
+  }
+  return '';
+}
+/** A stable key for a discriminant expression (`phase`, `props.mode`, `this.x`). */
+function discriminantKey(node) {
+  switch (node?.type) {
+    case 'Identifier':   return node.name;
+    case 'ThisExpression': return 'this';
+    case 'MemberExpression': {
+      if (node.computed) return null;
+      const obj = discriminantKey(node.object);
+      return obj && node.property?.name ? `${obj}.${node.property.name}` : null;
+    }
+    default: return null;
+  }
+}
+function literalOf(node) {
+  switch (node?.type) {
+    case 'StringLiteral':
+    case 'NumericLiteral':
+    case 'BooleanLiteral': return node.value;
+    case 'NullLiteral':    return null;
+    default:               return undefined;
+  }
+}
+/**
+ * Turns a rendering test into constraints on named discriminants. Only the
+ * shapes it can prove are returned; anything else yields `[]`, which reads as
+ * "unconstrained" — the same behaviour this resolver had before scenarios
+ * existed, so an unrecognised test can never make it miss a violation it used
+ * to report.
+ */
+export function constraintsFrom(test, positive) {
+  switch (test?.type) {
+    case 'BinaryExpression': {
+      const key = discriminantKey(test.left);
+      const value = literalOf(test.right);
+      if (!key || value === undefined) return [];
+      const eq = test.operator === '===' || test.operator === '==';
+      const ne = test.operator === '!==' || test.operator === '!=';
+      if (!eq && !ne) return [];
+      const allow = eq === positive;
+      return [allow ? { key, allow: new Set([value]) } : { key, deny: new Set([value]) }];
+    }
+    case 'LogicalExpression': {
+      if (!positive) return []; // De Morgan on a negated compound — not worth proving
+      if (test.operator === '&&') {
+        return [...constraintsFrom(test.left, true), ...constraintsFrom(test.right, true)];
+      }
+      if (test.operator === '||') {
+        // `phase === 'input' || phase === 'error'` — one discriminant, a set of
+        // values. Mergeable only when both sides constrain the same key with
+        // `allow`; anything else is a disjunction this can't narrow.
+        const l = constraintsFrom(test.left, true);
+        const r = constraintsFrom(test.right, true);
+        if (l.length === 1 && r.length === 1 && l[0].key === r[0].key && l[0].allow && r[0].allow) {
+          return [{ key: l[0].key, allow: new Set([...l[0].allow, ...r[0].allow]) }];
+        }
+      }
+      return [];
+    }
+    case 'UnaryExpression':
+      return test.operator === '!' ? constraintsFrom(test.argument, !positive) : [];
+    default: {
+      // A bare truthiness test: `{open && <X/>}`, `cond ? <A/> : <B/>`.
+      const key = discriminantKey(test);
+      return key ? [{ key, allow: new Set([positive]) }] : [];
+    }
+  }
+}
+/**
+ * Every constraint on the path from a JSX node up to the module root — the
+ * conditions that must hold for it to be rendered at all.
+ */
+export function guardOf(elPath) {
+  const constraints = [];
+  let cur = elPath;
+  let parent = cur.parentPath;
+  while (parent) {
+    const p = parent.node;
+    const c = cur.node;
+    if (p.type === 'ConditionalExpression') {
+      if (c === p.consequent) constraints.push(...constraintsFrom(p.test, true));
+      else if (c === p.alternate) constraints.push(...constraintsFrom(p.test, false));
+    } else if (p.type === 'LogicalExpression' && p.operator === '&&' && c === p.right) {
+      constraints.push(...constraintsFrom(p.left, true));
+    }
+    cur = parent;
+    parent = parent.parentPath;
+  }
+  return constraints;
+}
+// A discriminant value standing for "none of the literals this file tests
+// for" — the scenario where every `phase === '…'` branch is closed.
+const OTHER = Symbol('other');
+// Above this many scenarios the file is evaluated flat instead, exactly as
+// before scenarios existed. A view with that many independent discriminants
+// is not a state machine this can reason about, and enumerating it would cost
+// more than the precision is worth.
+const SCENARIO_CAP = 64;
+function nodeMatchesScenario(constraints, scenario) {
+  for (const c of constraints) {
+    const value = scenario.get(c.key);
+    if (c.allow && !c.allow.has(value)) return false;
+    if (c.deny && c.deny.has(value)) return false;
+  }
+  return true;
+}
+/**
+ * Enumerates the mutually-exclusive rendering states of one layer: the
+ * cartesian product of the values each discriminant is tested against, plus
+ * OTHER. Returns `null` past SCENARIO_CAP, meaning "evaluate flat".
+ */
+export function scenariosFor(entries) {
+  const values = new Map();
+  for (const e of entries) {
+    for (const c of e.constraints) {
+      if (!values.has(c.key)) values.set(c.key, new Set([OTHER]));
+      if (c.allow) for (const v of c.allow) values.get(c.key).add(v);
+      if (c.deny) for (const v of c.deny) values.get(c.key).add(v);
+    }
+  }
+  if (values.size === 0) return [new Map()];
+  let count = 1;
+  for (const set of values.values()) count *= set.size;
+  if (count > SCENARIO_CAP) return null;
+  let scenarios = [new Map()];
+  for (const [key, set] of values) {
+    const next = [];
+    for (const base of scenarios) {
+      for (const v of set) {
+        const m = new Map(base);
+        m.set(key, v);
+        next.push(m);
+      }
+    }
+    scenarios = next;
+  }
+  return scenarios;
+}
+/**
+ * Collapses primary Buttons that carry the same accessible name down to one.
+ * Two `variant="primary"` Buttons both reading "Invite teammate" are one CTA
+ * rendered twice — the responsive full-label/icon-only pair a component
+ * library without a responsive `iconOnly` forces an app to write, where CSS,
+ * not the JSX, decides which one is visible. The rule counts *competing*
+ * CTAs, so a repeat of the same one is not a second CTA. An unnamed Button is
+ * never collapsed: two of those are not provably the same control.
+ */
+export function collapseDuplicateCtas(nodes) {
+  const seen = new Set();
+  return nodes.filter((n) => {
+    if (n.type !== 'Button' || (n.variant ?? 'primary') !== 'primary') return true;
+    const name = typeof n.label === 'string' && n.label ? n.label
+      : typeof n['aria-label'] === 'string' && n['aria-label'] ? n['aria-label']
+      : null;
+    if (name === null) return true;
+    if (seen.has(name)) return false;
+    seen.add(name);
+    return true;
+  });
+}
 /**
  * Runs the Vecna conformance gate's component-usage rules
  * (`packages/stk/conformance/index.js`'s `checkComponentRules` — Toolbar
@@ -184,6 +419,22 @@ function scanDropdownItemsInChildren(children, localName) {
  * and it's what keeps "at most one Toolbar" / "at most one primary Button"
  * meaningful instead of comparing unrelated screens against each other.
  *
+ * A file is one page but not one *view*, though, and the difference is what
+ * these rules actually count. Three splits keep the comparison to controls
+ * that are on screen together — each one only narrowing what the resolver
+ * claims, never widening it:
+ *
+ *  - **Overlay layers** (`overlaySectionOf`) — a Modal's confirm button is
+ *    that dialog's CTA, not a rival to the page's.
+ *  - **Mutually-exclusive rendering states** (`guardOf`, `scenariosFor`) — a
+ *    connect wizard's `{phase === 'install' && …}` / `{phase === 'select' &&
+ *    …}` branches are four screens in one file, each with its own single CTA.
+ *  - **The same CTA rendered twice** (`collapseDuplicateCtas`) — a responsive
+ *    full-label/icon-only pair, one of which CSS always hides.
+ *
+ * All three came out of gating a real repo (apps/dominion): every one of its
+ * primary-Button warnings was a view the file never actually renders at once.
+ *
  * 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
@@ -216,15 +467,16 @@ export function resolveUsageRules(root, { platform = 'web', ignore = [] } = {})
     }
     const localToType = new Map();
+    const localToOverlay = 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 (packageOfSpecifier(origin?.pkg) !== pkgName) continue;
+      if (RULE_TYPES.has(origin.name)) localToType.set(localName, origin.name);
+      if (OVERLAY_TYPES.has(origin.name)) localToOverlay.set(localName, origin.name);
     }
     if (localToType.size === 0) continue;
-    const nodes = [];
+    const entries = [];
     let droppedForUnresolvedVariant = 0;
     let droppedForUnresolvedDropdownChildren = 0;
@@ -247,19 +499,52 @@ export function resolveUsageRules(root, { platform = 'web', ignore = [] } = {})
           if (scan.items.length > 0) node.items = scan.items;
         }
-        nodes.push(node);
+        entries.push({
+          node,
+          section: overlaySectionOf(elPath, localToOverlay),
+          constraints: guardOf(elPath),
+        });
       },
     });
-    if (nodes.length === 0 && droppedForUnresolvedVariant === 0 && droppedForUnresolvedDropdownChildren === 0) continue;
+    if (entries.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 });
+    // One file is one page, but not one *view*: a page renders one branch of
+    // its state machine at a time, and an open overlay is a layer of its own.
+    // Evaluating every Button in the file against each other reports views
+    // that never coexist — the exact "violation it can't statically prove"
+    // this resolver refuses to invent elsewhere. So the nodes are split by
+    // overlay layer, then by mutually-exclusive rendering state, and the rules
+    // run once per combination. A finding that holds in several scenarios is
+    // still reported once.
+    if (entries.length > 0) {
+      const bySection = new Map();
+      for (const e of entries) {
+        if (!bySection.has(e.section)) bySection.set(e.section, []);
+        bySection.get(e.section).push(e);
+      }
+      const seenFindings = new Set();
+      for (const [section, sectionEntries] of bySection) {
+        const scenarios = scenariosFor(sectionEntries);
+        const views = scenarios === null
+          ? [sectionEntries.map(e => e.node)]
+          : scenarios.map(s => sectionEntries.filter(e => nodeMatchesScenario(e.constraints, s)).map(e => e.node));
+        for (const view of views) {
+          const nodes = collapseDuplicateCtas(view);
+          if (nodes.length === 0) continue;
+          const layout = { page: { sections: [{ id: section ? `${relFile}#${section}` : relFile, nodes }] } };
+          for (const f of checkComponentRules(layout)) {
+            const key = `${f.severity}|${f.violated}|${f.finding}`;
+            if (seenFindings.has(key)) continue;
+            seenFindings.add(key);
+            findings.push({ ...f, file: relFile });
+          }
+        }
       }
     }

package/src/adopt/vecnaMaterializer.js CHANGED Viewed

@@ -83,7 +83,24 @@ function emitNode(node, catalogMap, componentsUsed, skipped, nodePath, counter)
   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);
+    // A canvasOnly key is consumed by LayoutCanvas to compose something
+    // (DataTable's pagination keys build a footer element) and is never
+    // forwarded as a prop. Emitting it would put an attribute on the call site
+    // that no real call site can carry — which is the whole failure mode this
+    // materializer exists to avoid.
+    if (propDef.canvasOnly) {
+      skipped.push({ path: `${nodePath}.${propDef.name}`, kind: 'canvas-only', reason: 'schema-declared canvasOnly key — composed by LayoutCanvas, never passed as a prop' });
+      continue;
+    }
+    // The layout key and the React prop are allowed to be spelled
+    // differently (BadgeStatus's "variant" is the component's `color`).
+    // `reactProp` is the declared rename, checked against the real component
+    // signature by packages/stk/scripts/validate-prop-api.js — emit that, or
+    // the resolvers verify an attribute the component never accepts.
+    const emitName = propDef.reactProp ?? propDef.name;
+    const serialized = serializePropValue(emitName, propDef, value);
     if (serialized === null) {
       skipped.push({ path: `${nodePath}.${propDef.name}`, kind: 'unrepresentable', reason: `unrepresentable prop value for type "${propDef.type}"` });
       continue;
@@ -91,10 +108,18 @@ function emitNode(node, catalogMap, componentsUsed, skipped, nodePath, counter)
     attrParts.push(serialized);
   }
+  // A canvasOnly slot is composed into the component's children by
+  // LayoutCanvas through a compound sub-component (Popover's trigger/content
+  // become <Popover.Trigger>/<Popover.Content>), so the component never
+  // receives a prop of that name. Emit those nodes as JSX children instead of
+  // as an attribute — that keeps the call site faithful *and* keeps the nested
+  // nodes in the file, so the resolvers still verify them.
+  const childParts = [];
   const slotDefs = entry.schema.slots ?? [];
   for (const slotDef of slotDefs) {
     const slotValue = node[slotDef.name];
     if (slotValue === undefined) continue;
+    const sink = slotDef.canvasOnly ? childParts : null;
     if (slotDef.array) {
       if (!Array.isArray(slotValue)) {
@@ -106,16 +131,21 @@ function emitNode(node, catalogMap, componentsUsed, skipped, nodePath, counter)
         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('')}</>}`);
-      }
+      if (children.length === 0) continue;
+      if (sink) sink.push(...children);
+      else 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}}`);
+      if (!jsx) continue;
+      if (sink) sink.push(jsx);
+      else attrParts.push(`${slotDef.name}={${jsx}}`);
     }
   }
   const openTag = attrParts.length > 0 ? `<${entry.name} ${attrParts.join(' ')}` : `<${entry.name}`;
+  if (childParts.length > 0) {
+    return `${openTag}>${childParts.join('')}</${entry.name}>`;
+  }
   return `${openTag} />`;
 }
@@ -130,6 +160,16 @@ function emitNode(node, catalogMap, componentsUsed, skipped, nodePath, counter)
  * (unmapped nodeType, malformed prop/slot shape) is recorded in
  * `skippedNodes` with a reason, never guessed or defaulted.
  *
+ * The layout schema is not the component's signature, and the two are allowed
+ * to diverge in three declared ways — `reactProp` (a rename), `canvasOnly` on a
+ * prop (LayoutCanvas composes it, nothing is forwarded), and `canvasOnly` on a
+ * slot (composed into children through a compound sub-component). All three are
+ * honoured here, and enforced against the real signatures by
+ * packages/stk/scripts/validate-prop-api.js. Ignoring them is not a cosmetic
+ * bug: emitting the layout key verbatim produced `<BadgeStatus variant=...>`
+ * for a component whose prop is `color`, and the resolvers then verified an
+ * attribute no real call site can carry.
+ *
  * The output filename must never contain ".stories." — moduleGraph.js's
  * DEFAULT_IGNORE excludes that glob, which would make every resolver
  * silently skip the file.

package/src/adopt/vecnaVerifier.js CHANGED Viewed

@@ -32,15 +32,26 @@ import { resolvePropApi } from './propApiResolver.js';
  *     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."
+ *     NOTE — two of propApiResolver's four rules are themselves vacuous by
+ *     construction here, both for the same reason: vecnaMaterializer.js only
+ *     ever emits props declared in a component's layoutSchema.
+ *       · style-escape-hatch checks for STYLE_ESCAPE_ATTRS (className/style)
+ *         on a call site; no layoutSchema declares either, so it can never
+ *         fire against Vecna output.
+ *       · deprecated-prop-passed fires on a propMap entry marked
+ *         `deprecated`. Measured: the only three in the system are Button's
+ *         `disabled`/`loading`/`active` (button.mapping.json), all superseded
+ *         by `state`, and none of the three appears in Button's layoutSchema
+ *         (label, variant, size, fullWidth, radius). So a Vecna layout has no
+ *         way to author one, and the rule is 0-reachable here — not by
+ *         accident, but because the layout schema deliberately offers only the
+ *         current API.
+ *     The other two are real and both verified live: invalid-enum-value
+ *     (an out-of-range enum), and required-prop-missing (Toast's `title` is
+ *     the one propMap entry marked `required` system-wide, and it *is* in
+ *     Toast's layoutSchema, so a layout that omits it fires the rule). Same
+ *     honesty as the wrappers/tokenAliases bullets above — propApi as a whole
+ *     is not vacuous, but count 2 live rules, not 4, when citing coverage.
  *
  * This mirrors R3 point 1's own finding (only 1 of 6 conformance checks
  * generalizes to arbitrary scanned JSX) one level deeper — see

package/src/adopt/wrapperResolver.js CHANGED Viewed

@@ -4,7 +4,7 @@ import path from 'node:path';
 import traverseModule from '@babel/traverse';
 import { loadCatalog, packageNameForPlatform } from './catalog.js';
-import { buildModuleGraph, resolveOriginDeep, EXTENSIONS } from './moduleGraph.js';
+import { buildModuleGraph, packageOfSpecifier, resolveOriginDeep, EXTENSIONS } from './moduleGraph.js';
 import { classifyReference, KIND_CONFIDENCE } from './referenceResolver.js';
 const traverse = traverseModule.default ?? traverseModule;
@@ -417,7 +417,7 @@ function resolveTagTerminal(file, tagInfo, moduleGraph, declsCache, catalogByNam
   const { source, imported } = binding;
   if (!source.startsWith('.') && !source.startsWith('/')) {
-    if (source === pkgName && catalogByName.has(imported)) {
+    if (packageOfSpecifier(source) === pkgName && catalogByName.has(imported)) {
       return { terminal: 'ds-component', component: imported };
     }
     const crossed = resolveWorkspacePackage(source, imported, workspace, catalogByName, pkgName, visited, depth);
@@ -453,7 +453,7 @@ function resolveImportedSymbol(resolvedFile, imported, moduleGraph, declsCache,
   const deep = resolveOriginDeep(moduleGraph, resolvedFile, imported, { viaExport: true });
   if (deep?.type === 'package') {
-    if (deep.pkg === pkgName && catalogByName.has(deep.name)) {
+    if (packageOfSpecifier(deep.pkg) === pkgName && catalogByName.has(deep.name)) {
       return { terminal: 'ds-component', component: deep.name };
     }
     const crossed = resolveWorkspacePackage(deep.pkg, deep.name, workspace, catalogByName, pkgName, visited, depth);