@starklab/stark-mcp 0.2.0 → 0.3.0

package/src/adopt/adoptGate.js

@@ -0,0 +1,471 @@
+/**
+ * Turns a `runAdopt()` result over a customer repo into a PASS/FAIL verdict
+ * with concrete evidence — the missing half of "scan a client repo → gate →
+ * verdict" (ADOPTION_APP_PLAN.md §6).
+ *
+ * Before this, the two halves existed and never met. `stark-cli adopt` runs
+ * eight resolvers over real customer code and prints numbers; `verifyVecna-
+ * Layout` produces a judgment but only over one Vecna-generated LayoutConfig
+ * it materializes itself. Nothing ever judged a scanned repo, so a customer
+ * CI run could report 41 critical findings and still exit 0.
+ *
+ * Design rules, all inherited from the resolvers rather than invented here:
+ *
+ *  1. **Absence of evidence is never a violation** (§9). A resolver that did
+ *     not run on this platform is `not-applicable`; a resolver that ran with
+ *     nothing in its domain (no CSS files, no catalog JSX, Tailwind absent) is
+ *     `no-evidence`. Neither can fail the gate, and both are reported rather
+ *     than collapsed into a passing check — "PASS" over an empty denominator
+ *     is a weaker claim than "PASS" over a full one, and the caller has to be
+ *     able to tell them apart. Same denominator honesty as vecnaVerifier's
+ *     `coverage.gaps`.
+ *
+ *  2. **The gate reads findings, it does not re-derive them.** Every verdict
+ *     traces to a finding object a resolver already produced, carried through
+ *     verbatim as evidence. No second, parallel implementation of any check.
+ *     The one exception is the explicitly-labelled `policy: true` finding from
+ *     `minComponentsUsed`, which is a caller's CI policy and not something a
+ *     resolver could know.
+ *
+ *  3. **Low adoption is not a failure.** A repo that uses three catalog
+ *     components correctly passes; that is a *score*, which Dominion computes
+ *     from the same scan (apps/dominion/lib/adoptionScan.ts), not a
+ *     conformance verdict. The reference check therefore has no failing state
+ *     unless the caller opts in with `minComponentsUsed`.
+ *
+ * Two severity vocabularies reach this function and both are live: the adopt
+ * resolvers emit lowercase `critical|warning|info`, while `usageRules`
+ * forwards the conformance engine's own capitalized `Critical|Warning|Info`
+ * (packages/stk/conformance/index.js `SEVERITY`). Normalizing here rather
+ * than changing either producer keeps the gate the only place that has to
+ * know, and `unknownSeverities` surfaces any third spelling instead of
+ * silently bucketing it.
+ *
+ * Not gated: `opportunities` (hand-rolled markup a catalog component could
+ * replace) is a roadmap signal about code that never claimed to use Stark —
+ * failing CI on it would punish a repo for the parts it has not adopted yet,
+ * which is rule 3 again.
+ */
+
+const SEVERITY_RANK = { info: 0, warning: 1, critical: 2 };
+
+export const GATE_SEVERITIES = Object.keys(SEVERITY_RANK);
+
+/** Lowercases the two live spellings into one. An unrecognized severity is
+ *  counted as `info` — the non-blocking bucket — and recorded in the check's
+ *  `unknownSeverities` so it shows up as a gap to close rather than as a
+ *  finding that quietly stopped mattering. */
+export function normalizeSeverity(value) {
+  const s = String(value ?? '').toLowerCase();
+  return s in SEVERITY_RANK ? s : null;
+}
+
+function blocks(severity, failOn) {
+  return SEVERITY_RANK[severity] >= SEVERITY_RANK[failOn];
+}
+
+/**
+ * Builds one check from a resolver's `findings` array.
+ *
+ * `evidence` is every blocking finding, capped at `maxEvidence` with
+ * `evidenceTotal` alongside so a truncated list can never be mistaken for the
+ * whole set. Findings are carried through verbatim (spread) — the gate adds a
+ * normalized `severity` and nothing else, so every field a resolver chose to
+ * report (rule, component, prop, value, allowed, selector, file, line) reaches
+ * the verdict without this module having to know the shape of any of them.
+ */
+function fromFindings({ id, dimension, title, findings, measured, failOn, maxEvidence }) {
+  const counts = { critical: 0, warning: 0, info: 0 };
+  const unknownSeverities = [];
+  const blocking = [];
+
+  for (const f of findings) {
+    const severity = normalizeSeverity(f.severity);
+    if (severity === null) {
+      unknownSeverities.push(f.severity ?? null);
+      counts.info += 1;
+      continue;
+    }
+    counts[severity] += 1;
+    if (blocks(severity, failOn)) blocking.push({ ...f, severity });
+  }
+
+  const check = {
+    id,
+    dimension,
+    title,
+    status: blocking.length > 0 ? 'fail' : 'pass',
+    measured,
+    findings: counts,
+    evidenceTotal: blocking.length,
+    evidence: blocking.slice(0, maxEvidence),
+  };
+  if (unknownSeverities.length > 0) check.unknownSeverities = [...new Set(unknownSeverities)];
+  return check;
+}
+
+function skipped({ id, dimension, title, status, reason }) {
+  return {
+    id,
+    dimension,
+    title,
+    status,
+    reason,
+    measured: null,
+    findings: { critical: 0, warning: 0, info: 0 },
+    evidenceTotal: 0,
+    evidence: [],
+  };
+}
+
+/** A resolver whose headline `report` is the `{total, direct, aliased,
+ *  unresolved, conformancePct}` shape — all four token resolvers share it
+ *  exactly (tokenAliasResolver, tailwindResolver, rnTokenAliasResolver,
+ *  rnTailwindResolver), which is why one builder covers them. */
+function tokenCheck({ id, title, result, notApplicableReason, failOn, maxEvidence }) {
+  const shared = { id, dimension: 'tokens', title };
+  if (!result) return skipped({ ...shared, status: 'not-applicable', reason: notApplicableReason });
+  if (result.detected === false) {
+    return skipped({ ...shared, status: 'not-applicable', reason: result.reason ?? 'Not detected in this repo.' });
+  }
+  if (!result.report || result.report.total === 0) {
+    return skipped({
+      ...shared,
+      status: 'no-evidence',
+      reason: 'The resolver ran but found no token usage to classify — nothing to gate, not a clean result.',
+    });
+  }
+  // A repo that declares custom properties but resolves *none* of them to a
+  // Stark token is not a Stark consumer, and "not a consumer" is a scope
+  // question, not 400 conformance violations. The resolver's own numbers stay
+  // honest either way (408 total, 0 aliased is a true measurement); it is the
+  // verdict that would be wrong, and low adoption is a score, never a failure
+  // — ADOPTION_APP_PLAN.md §9, the same rule component-references already
+  // honours by reporting no-evidence when nothing in the catalog is imported.
+  //
+  // Found by gating a real external repo rather than a fixture
+  // (~/Projects/Admin.Users, a Vite + shadcn/Radix app with zero Stark): every
+  // custom property terminates in a raw literal by definition when there is no
+  // design system behind them, so `drift-behind-alias` fired 454 times — on
+  // Tailwind's own engine internals (`--tw-translate-x`) and on shadcn's theme
+  // tokens (`--color-background`). Neither is a Stark token that drifted.
+  //
+  // The boundary is strictly zero: one aliased token makes the repo a consumer,
+  // and its remaining drift is then a real finding worth failing on.
+  const starkTokens = (result.report.direct ?? 0) + (result.report.aliased ?? 0);
+  if (starkTokens === 0) {
+    return skipped({
+      ...shared,
+      status: 'no-evidence',
+      reason:
+        `Not one of the ${result.report.total} declared properties resolves to a Stark token — ` +
+        'this repo does not consume the design system here, so there is nothing to conform.',
+    });
+  }
+  return fromFindings({
+    ...shared,
+    findings: result.findings ?? [],
+    measured: result.report,
+    failOn,
+    maxEvidence,
+  });
+}
+
+/**
+ * @param {object} adopt        A `runAdopt()` result (the JSON `stark-cli adopt` prints).
+ * @param {object} [options]
+ * @param {'critical'|'warning'|'info'} [options.failOn='critical']
+ *        Lowest severity that fails the gate. `critical` is the default
+ *        because it is the only severity every resolver reserves for a real
+ *        contract break; `warning` is a legitimate stricter setting, `info`
+ *        would fail on findings whose own text says no action is needed.
+ * @param {number} [options.maxEvidence=5]  Findings quoted per check.
+ * @param {number|null} [options.minComponentsUsed=null]
+ *        Opt-in CI policy: fail when fewer than N catalog components are
+ *        actually referenced. Off by default — see rule 3 above.
+ */
+export function gateAdoptResult(adopt, { failOn = 'critical', maxEvidence = 5, minComponentsUsed = null } = {}) {
+  if (!adopt || typeof adopt !== 'object') {
+    throw new Error('gateAdoptResult expects a runAdopt() result object.');
+  }
+  if (!(failOn in SEVERITY_RANK)) {
+    throw new Error(`failOn must be one of: ${GATE_SEVERITIES.join(', ')} (got "${failOn}").`);
+  }
+
+  const platform = adopt.platform ?? 'web';
+  const checks = [];
+
+  // 1. References — the "which catalog components does this repo actually
+  //    use" evidence. `components` always lists the whole catalog including
+  //    zero-usage entries (referenceResolver's own contract), so the used
+  //    count is the catalog minus zeroUsage, never `components.length`.
+  const components = adopt.components ?? [];
+  const used = components.filter((c) => !(adopt.zeroUsage ?? []).includes(c.name));
+  const usageCount = (c) => c.counts.jsx + c.counts.createElement + c.counts.hoc + c.counts.indirect;
+  const totalUsages = used.reduce((n, c) => n + usageCount(c), 0);
+  const referenceMeasured = {
+    catalogComponents: components.length,
+    componentsUsed: used.length,
+    usages: totalUsages,
+    scannedFiles: adopt.scannedFiles ?? 0,
+    unresolvedFiles: (adopt.unresolvedFiles ?? []).length,
+  };
+
+  if (used.length === 0) {
+    checks.push(
+      skipped({
+        id: 'component-references',
+        dimension: 'references',
+        title: 'Catalog component references',
+        status: 'no-evidence',
+        reason:
+          'No catalog component is referenced anywhere in the scanned files — there is nothing to conform, so this is a scope question, not a violation.',
+      })
+    );
+    // A repo with zero adoption still fails an explicit floor, which is the
+    // one thing that floor exists to catch.
+    if (minComponentsUsed !== null && used.length < minComponentsUsed) {
+      checks[checks.length - 1] = policyFloor(referenceMeasured, minComponentsUsed, used.length, maxEvidence);
+    }
+  } else if (minComponentsUsed !== null && used.length < minComponentsUsed) {
+    checks.push(policyFloor(referenceMeasured, minComponentsUsed, used.length, maxEvidence));
+  } else {
+    checks.push({
+      id: 'component-references',
+      dimension: 'references',
+      title: 'Catalog component references',
+      status: 'pass',
+      measured: referenceMeasured,
+      findings: { critical: 0, warning: 0, info: 0 },
+      evidenceTotal: used.length,
+      // Evidence for a passing reference check is the usage itself: which
+      // components, how often, and one real call site each — so a PASS is
+      // readable as "here is what it found", not as an empty assertion.
+      evidence: [...used]
+        .sort((a, b) => usageCount(b) - usageCount(a) || a.name.localeCompare(b.name))
+        .slice(0, maxEvidence)
+        .map((c) => ({
+          component: c.name,
+          usages: usageCount(c),
+          counts: c.counts,
+          site: c.sites?.[0] ? { file: c.sites[0].file, line: c.sites[0].line, kind: c.sites[0].kind } : null,
+        })),
+    });
+  }
+
+  // 2. Prop API — the one dimension that is about how components are *called*.
+  if (!adopt.propApi) {
+    checks.push(
+      skipped({
+        id: 'prop-api',
+        dimension: 'prop-api',
+        title: 'Component prop API',
+        status: 'not-applicable',
+        reason:
+          'Web-only: prop-mapping/ has no rn/ subdirectory, so there is no artifact to validate a React Native prop against.',
+      })
+    );
+  } else if ((adopt.propApi.report?.total ?? 0) === 0) {
+    checks.push(
+      skipped({
+        id: 'prop-api',
+        dimension: 'prop-api',
+        title: 'Component prop API',
+        status: 'no-evidence',
+        reason: 'No catalog call site carried a prop this resolver tracks — no props were checked.',
+      })
+    );
+  } else {
+    checks.push(
+      fromFindings({
+        id: 'prop-api',
+        dimension: 'prop-api',
+        title: 'Component prop API',
+        findings: adopt.propApi.findings ?? [],
+        measured: adopt.propApi.report,
+        failOn,
+        maxEvidence,
+      })
+    );
+  }
+
+  // 3–4. Tokens, web.
+  checks.push(
+    tokenCheck({
+      id: 'token-aliases',
+      title: 'CSS custom-property token aliases',
+      result: adopt.tokenAliases,
+      notApplicableReason: 'Web-only: CSS custom properties have no React Native equivalent.',
+      failOn,
+      maxEvidence,
+    })
+  );
+  checks.push(
+    tokenCheck({
+      id: 'tailwind-tokens',
+      title: 'Tailwind theme tokens',
+      result: adopt.tailwind,
+      notApplicableReason: 'Web-only.',
+      failOn,
+      maxEvidence,
+    })
+  );
+
+  // 5–6. Tokens, React Native.
+  checks.push(
+    tokenCheck({
+      id: 'rn-token-aliases',
+      title: 'React Native token aliases',
+      result: adopt.rnTokenAliases,
+      notApplicableReason: 'React Native only.',
+      failOn,
+      maxEvidence,
+    })
+  );
+  checks.push(
+    tokenCheck({
+      id: 'rn-tailwind-tokens',
+      title: 'NativeWind theme tokens',
+      result: adopt.rnTailwind,
+      notApplicableReason: 'React Native only.',
+      failOn,
+      maxEvidence,
+    })
+  );
+
+  // 7. Usage rules — the conformance engine's three rule-bearing checks, run
+  //    over the customer's own JSX via the R3 adapter. Capitalized severities.
+  if (!adopt.usageRules) {
+    checks.push(
+      skipped({
+        id: 'usage-rules',
+        dimension: 'usage-rules',
+        title: 'Composition usage rules',
+        status: 'not-applicable',
+        reason: 'Web-only.',
+      })
+    );
+  } else if ((adopt.usageRules.filesWithUsage ?? 0) === 0) {
+    checks.push(
+      skipped({
+        id: 'usage-rules',
+        dimension: 'usage-rules',
+        title: 'Composition usage rules',
+        status: 'no-evidence',
+        reason: 'No scanned file contained a statically-resolvable Toolbar/Button/DropdownMenu composition to check.',
+      })
+    );
+  } else {
+    checks.push(
+      fromFindings({
+        id: 'usage-rules',
+        dimension: 'usage-rules',
+        title: 'Composition usage rules',
+        findings: adopt.usageRules.findings ?? [],
+        measured: {
+          scannedFiles: adopt.usageRules.scannedFiles ?? 0,
+          filesWithUsage: adopt.usageRules.filesWithUsage ?? 0,
+          unresolvedFiles: (adopt.usageRules.unresolvedFiles ?? []).length,
+        },
+        failOn,
+        maxEvidence,
+      })
+    );
+  }
+
+  // 8. Wrappers. wrapperResolver reports no `findings` array — its two
+  //    problem shapes are `contradictions` (a dominion.config.json declaration
+  //    the auto-detected terminal disagrees with) and `unresolvedDeclarations`
+  //    (a declaration naming something that isn't a catalog component). Both
+  //    are config defects rather than code violations, so both are Warning at
+  //    most: the customer's shipped UI is unaffected either way, only the
+  //    attribution of it is. Given a repo with no config at all, this is
+  //    no-evidence rather than a clean pass.
+  const wrapperFindings = [
+    ...(adopt.contradictions ?? []).map((c) => ({
+      rule: 'wrapper-declaration-contradicted',
+      severity: 'warning',
+      ...c,
+    })),
+    ...(adopt.unresolvedDeclarations ?? []).map((d) => ({
+      rule: 'wrapper-declaration-unresolved',
+      severity: 'warning',
+      ...d,
+    })),
+  ];
+  if (!adopt.dominionConfigFound && wrapperFindings.length === 0) {
+    checks.push(
+      skipped({
+        id: 'wrapper-declarations',
+        dimension: 'wrappers',
+        title: 'Declared wrapper components',
+        status: 'no-evidence',
+        reason: 'No dominion.config.json wrapper declarations in this repo — nothing was declared, so nothing can contradict.',
+      })
+    );
+  } else {
+    checks.push(
+      fromFindings({
+        id: 'wrapper-declarations',
+        dimension: 'wrappers',
+        title: 'Declared wrapper components',
+        findings: wrapperFindings,
+        measured: {
+          wrappers: (adopt.wrappers ?? []).length,
+          provenance: adopt.provenanceTriple ?? null,
+          dominionConfigFound: Boolean(adopt.dominionConfigFound),
+        },
+        failOn,
+        maxEvidence,
+      })
+    );
+  }
+
+  const summary = {
+    checks: checks.length,
+    passed: checks.filter((c) => c.status === 'pass').length,
+    failed: checks.filter((c) => c.status === 'fail').length,
+    notApplicable: checks.filter((c) => c.status === 'not-applicable').length,
+    noEvidence: checks.filter((c) => c.status === 'no-evidence').length,
+    findings: checks.reduce(
+      (acc, c) => ({
+        critical: acc.critical + c.findings.critical,
+        warning: acc.warning + c.findings.warning,
+        info: acc.info + c.findings.info,
+      }),
+      { critical: 0, warning: 0, info: 0 }
+    ),
+  };
+
+  return {
+    verdict: summary.failed > 0 ? 'FAIL' : 'PASS',
+    failOn,
+    platform,
+    package: adopt.package ?? null,
+    root: adopt.root ?? null,
+    summary,
+    checks,
+  };
+}
+
+/** The one finding this module authors rather than forwards — flagged
+ *  `policy: true` so a reader can tell a CI floor from a resolver's own
+ *  judgment about the code. */
+function policyFloor(measured, minComponentsUsed, actual, maxEvidence) {
+  const finding = {
+    rule: 'below-minimum-component-usage',
+    severity: 'critical',
+    policy: true,
+    required: minComponentsUsed,
+    actual,
+  };
+  return fromFindings({
+    id: 'component-references',
+    dimension: 'references',
+    title: 'Catalog component references',
+    findings: [finding],
+    measured,
+    failOn: 'critical',
+    maxEvidence,
+  });
+}

package/src/adopt/adoptScanReport.js

@@ -37,6 +37,15 @@ import { scrubForeignScanPaths } from './foreignScanReport.js';
  * `findings` is deliberately NOT in this list. A finding is a defect the
  * tracker exists to surface, and the counts alone can't reconstruct one.
  *
+ * Neither is `rollup`, and that is the point of it: scanRollup.js folds
+ * `checks` and `sites` into bounded per-(component, prop, value) and
+ * per-(component, file) counts *before* this strip runs, so the aggregate
+ * survives while the enumeration does not. Everything above stays true — the
+ * ingest still never reads the enumeration — but "re-derivable by re-scanning"
+ * is a weaker guarantee than it sounds for a customer's *past* commits, which
+ * nobody re-scans, so the shape that a question might later need is kept and
+ * the rows behind it are not.
+ *
  * stdout is untouched either way — `--report` changes what is sent, never what
  * the command prints.
  */

package/src/adopt/componentPropApi.js

@@ -0,0 +1,200 @@
+import { existsSync, readFileSync, statSync } from 'node:fs';
+import path from 'node:path';
+
+import { parse } from '@babel/parser';
+
+import { stkRoot } from '../data.js';
+
+/**
+ * The component prop API — what props the real React components actually
+ * accept, read from their own source.
+ *
+ * Everything else in this repo that claims to describe a component's props is
+ * hand-written: prop-mapping's `propMap` describes the Figma sync contract,
+ * and `layoutSchema` describes the AI layout-JSON contract. Neither is the
+ * component's signature, and both were free to drift from it — silently. That
+ * drift is what made the Vecna Gate assert against a fiction: it materialized
+ * `<BadgeStatus variant="…">` from a layoutSchema whose `variant` the real
+ * component has never accepted (it is `color`), and the propApi resolver then
+ * found nothing wrong with it because `variant` matched no rule either.
+ *
+ * This module closes that by parsing the destructured parameter of each
+ * component's own declaration, which is the only place the truth lives.
+ *
+ * Two halves, mirroring catalog.js:
+ *   - extractComponentProps() runs in the monorepo, where the component
+ *     sources exist, and is what the build-time generator calls.
+ *   - loadComponentPropApi() reads the generated artifact that ships inside
+ *     @starklab/stk, which is all a published install has — stark-mcp
+ *     deliberately does not depend on @starklab/stk-components (see
+ *     catalog.js for the same reasoning).
+ */
+
+const PACKAGE_NAME = {
+  web: '@starklab/stk-components',
+  native: '@starklab/stk-react-native',
+};
+
+const ARTIFACT = 'component-props.json';
+
+/** Wrappers that keep the props object as their inner function's first param. */
+const TRANSPARENT_CALLS = new Set(['forwardRef', 'memo']);
+
+function resolveModule(srcDir, spec) {
+  const base = path.resolve(srcDir, spec);
+  const candidates = [base, `${base}.jsx`, `${base}.js`, path.join(base, 'index.jsx'), path.join(base, 'index.js')];
+  for (const c of candidates) {
+    if (existsSync(c) && statSync(c).isFile()) return c;
+  }
+  return null;
+}
+
+/**
+ * Reads the same flat re-export barrel catalog.js reads, but keeps the module
+ * specifier and the local name too — the local name is what the declaration is
+ * called inside its own file, which is not always the exported name
+ * (`export { Foo as Bar }`).
+ */
+function readBarrelBindings(file) {
+  const src = readFileSync(file, 'utf-8');
+  const bindings = new Map();
+  for (const line of src.split('\n')) {
+    const bare = line.trim();
+    if (!bare || bare.startsWith('//') || bare.startsWith('*') || bare.startsWith('/*')) continue;
+    const m = bare.match(/^export\s*\{([^}]+)\}\s*from\s*['"]([^'"]+)['"];?$/);
+    if (!m) continue;
+    for (const part of m[1].split(',')) {
+      const segs = part.trim().split(/\s+as\s+/);
+      const local = segs[0]?.trim();
+      const exported = (segs[1] ?? segs[0])?.trim();
+      if (exported && local) bindings.set(exported, { source: m[2], local });
+    }
+  }
+  return bindings;
+}
+
+/** Unwraps forwardRef(…)/memo(…) — including React.forwardRef(…) — down to the function. */
+function unwrapComponent(node) {
+  let current = node;
+  while (current && current.type === 'CallExpression') {
+    const callee = current.callee;
+    const name =
+      callee.type === 'Identifier'
+        ? callee.name
+        : callee.type === 'MemberExpression' && callee.property.type === 'Identifier'
+          ? callee.property.name
+          : null;
+    if (!TRANSPARENT_CALLS.has(name)) return null;
+    current = current.arguments[0] ?? null;
+  }
+  if (!current) return null;
+  const fn = ['FunctionDeclaration', 'FunctionExpression', 'ArrowFunctionExpression'];
+  return fn.includes(current.type) ? current : null;
+}
+
+function findDeclaration(ast, localName) {
+  for (const node of ast.program.body) {
+    const decl = node.type === 'ExportNamedDeclaration' ? node.declaration : node;
+    if (!decl) continue;
+    if (decl.type === 'FunctionDeclaration' && decl.id?.name === localName) return decl;
+    if (decl.type === 'VariableDeclaration') {
+      for (const d of decl.declarations) {
+        if (d.id.type === 'Identifier' && d.id.name === localName) return d.init;
+      }
+    }
+  }
+  return null;
+}
+
+function propsFromPattern(pattern, code) {
+  if (!pattern || pattern.type !== 'ObjectPattern') return null;
+  const props = [];
+  for (const p of pattern.properties) {
+    if (p.type === 'RestElement') {
+      props.push({ name: p.argument.type === 'Identifier' ? p.argument.name : 'rest', rest: true });
+      continue;
+    }
+    if (p.type !== 'ObjectProperty') continue;
+    const name = p.key.type === 'Identifier' ? p.key.name : String(p.key.value);
+    if (p.value.type === 'AssignmentPattern') {
+      props.push({ name, hasDefault: true, defaultSource: code.slice(p.value.right.start, p.value.right.end) });
+    } else {
+      props.push({ name, hasDefault: false });
+    }
+  }
+  return props;
+}
+
+/**
+ * Parses every component the barrel exports and returns its accepted props.
+ *
+ * Exports that are not prop-object components — hooks, primarily — come back
+ * under `skipped` rather than being silently dropped, so a component that
+ * stops parsing (a refactor to positional params, say) is visible instead of
+ * quietly vanishing from the validator's denominator.
+ */
+export function extractComponentProps(srcDir) {
+  const barrel = path.join(srcDir, 'index.js');
+  const bindings = readBarrelBindings(barrel);
+  const components = {};
+  const skipped = [];
+
+  for (const [exported, { source, local }] of bindings) {
+    const file = resolveModule(srcDir, source);
+    if (!file) {
+      skipped.push({ name: exported, reason: `module not found: ${source}` });
+      continue;
+    }
+    const code = readFileSync(file, 'utf-8');
+    let ast;
+    try {
+      ast = parse(code, { sourceType: 'module', plugins: ['jsx'] });
+    } catch (e) {
+      skipped.push({ name: exported, reason: `parse error: ${e.message}` });
+      continue;
+    }
+    const decl = findDeclaration(ast, local);
+    if (!decl) {
+      skipped.push({ name: exported, reason: `no declaration for "${local}" in ${source}` });
+      continue;
+    }
+    const fn = unwrapComponent(decl);
+    if (!fn) {
+      skipped.push({ name: exported, reason: 'not a function component' });
+      continue;
+    }
+    const props = propsFromPattern(fn.params[0], code);
+    if (!props) {
+      skipped.push({ name: exported, reason: 'first parameter is not a destructured props object' });
+      continue;
+    }
+    components[exported] = { source, props };
+  }
+
+  return { components, skipped };
+}
+
+/**
+ * Reads the generated artifact for one platform. Returns null when it is
+ * absent — the resolvers treat a missing prop API as "no ground truth
+ * available" and fall back to their prior behaviour rather than failing, the
+ * same posture every other adopt resolver takes toward missing inputs.
+ */
+export function loadComponentPropApi(platform = 'web', root = stkRoot()) {
+  if (!PACKAGE_NAME[platform]) {
+    throw new Error(
+      `Unsupported platform "${platform}". Available: ${Object.keys(PACKAGE_NAME).join(', ')}.`
+    );
+  }
+  const file = path.join(root, ARTIFACT);
+  if (!existsSync(file)) return null;
+  let parsed;
+  try {
+    parsed = JSON.parse(readFileSync(file, 'utf-8'));
+  } catch {
+    return null;
+  }
+  return parsed.platforms?.[platform] ?? null;
+}
+
+export { PACKAGE_NAME as PROP_API_PACKAGE_NAME, ARTIFACT as PROP_API_ARTIFACT };