@starklab/stark-mcp 0.1.0 → 0.2.0

package/src/cli.js

@@ -1,5 +1,7 @@
 #!/usr/bin/env node
 import path from 'node:path';
+import { readFileSync } from 'node:fs';
+import { execFileSync } from 'node:child_process';
 
 import {
   listComponents,
@@ -13,9 +15,20 @@ import { resolveWrappers } from './adopt/wrapperResolver.js';
 import { resolveTokenAliases } from './adopt/tokenAliasResolver.js';
 import { resolveTailwindTokens } from './adopt/tailwindResolver.js';
 import { resolvePropApi } from './adopt/propApiResolver.js';
+import { resolveUsageRules } from './adopt/usageRulesResolver.js';
+import { resolveOpportunities } from './adopt/opportunityResolver.js';
 import { resolveRnTokenAliases } from './adopt/rnTokenAliasResolver.js';
 import { resolveRnTailwindTokens } from './adopt/rnTailwindResolver.js';
 import { discoverTargets, workspacePackageMap } from './adopt/targetDiscovery.js';
+import { verifyVecnaLayout } from './adopt/vecnaVerifier.js';
+import { resolveForeignDiscovery } from './adopt/foreignDiscoveryResolver.js';
+import { resolvePropSchema } from './adopt/foreignPropSchemaResolver.js';
+import { scoreForeignAdoption } from './adopt/foreignScoringResolver.js';
+import { FOREIGN_SYSTEMS, listForeignSystems, systemPackages } from './adopt/foreignSystemConfig.js';
+import { detectForeignSystems } from './adopt/installedSystemAutoDetector.js';
+import { scanInstalledSystem } from './adopt/installedSystemScan.js';
+import { reportForeignScan } from './adopt/foreignScanReport.js';
+import { reportAdoptScan } from './adopt/adoptScanReport.js';
 
 function print(value) {
   console.log(JSON.stringify(value, null, 2));
@@ -26,6 +39,43 @@ function fail(message) {
   process.exitCode = 1;
 }
 
+/** How a foreign system is identified in scan-foreign's human-readable
+ * lists: its package name, or — for a system with no umbrella package, whose
+ * name would otherwise be one arbitrary sibling of forty — the count. */
+function packageSummary(system) {
+  if (system.npmPackages && system.npmPackages.length > 1) {
+    return `${system.npmPackages.length} packages, e.g. ${system.npmPackages[0]}`;
+  }
+  return system.npmPackage ?? system.distribution;
+}
+
+// Reported to the tracker alongside every scan, so a coverage number can
+// always be traced back to the code that produced it.
+const SCANNER_VERSION = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf-8')).version;
+
+/** The commit a reported scan describes. CI almost always already knows the
+ * SHA it checked out, so those variables are preferred over shelling out;
+ * `git rev-parse` covers a local run. A tree with neither reports nothing
+ * rather than inventing a placeholder — a coverage row keyed to a fake commit
+ * is worse than one that was never written. */
+function resolveCommitSha(root) {
+  const fromEnv =
+    process.env.GITHUB_SHA ||
+    process.env.VERCEL_GIT_COMMIT_SHA ||
+    process.env.CI_COMMIT_SHA ||
+    process.env.BUILDKITE_COMMIT;
+  if (fromEnv) return fromEnv;
+  try {
+    return execFileSync('git', ['rev-parse', 'HEAD'], {
+      cwd: root,
+      encoding: 'utf-8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+    }).trim();
+  } catch {
+    return undefined;
+  }
+}
+
 function hasFlag(args, name) {
   return args.includes(`--${name}`);
 }
@@ -49,6 +99,20 @@ function runAdopt(root, platform, ignore, workspacePackages) {
   // prop-mapping/ is flat, with no rn/ subdirectory — there is no artifact
   // to validate an RN prop against, so metric 6 only runs on web.
   const propApi = platform === 'web' ? resolvePropApi(root, { platform, ignore }) : null;
+  // Runs the Vecna conformance gate's own component-usage rules
+  // (checkComponentRules — Toolbar count, Button primary-variant count,
+  // DropdownMenu empty-items) against this repo's real JSX, closing the R3
+  // gap: the scanner and the gate used to have zero references to each
+  // other in either direction (ADOPTION_APP_PLAN.md §10 decision #3). Web
+  // only — see usageRulesResolver.js's header for why.
+  const usageRules = platform === 'web' ? resolveUsageRules(root, { platform, ignore }) : null;
+  // Scans for hand-rolled UI patterns resembling a catalog component,
+  // regardless of whether this repo has adopted Stark at all — closes R3
+  // dimension 1: every other resolver above only has something to say once
+  // a @starklab/stk* import is already in scope. DOM/JSX-shape signatures
+  // (role="toolbar", native <input>/<button>) — web only, see
+  // opportunityResolver.js's header for why.
+  const opportunities = platform === 'web' ? resolveOpportunities(root, { platform, ignore }) : null;
   // The RN JS-object token indirection resolver is the inverse: it only
   // makes sense for the native platform (see rnTokenAliasResolver.js).
   const rnTokenAliases = platform === 'native' ? resolveRnTokenAliases(root, { platform, ignore }) : null;
@@ -65,6 +129,8 @@ function runAdopt(root, platform, ignore, workspacePackages) {
     tokenAliases,
     tailwind,
     propApi,
+    usageRules,
+    opportunities,
     rnTokenAliases,
     rnTailwind,
   };
@@ -79,7 +145,12 @@ Usage:
   stark-cli manifest
   stark-cli eject <Component> [--platform=web|native] [--out=<dir>] [--force]
   stark-cli adopt [path] [--platform=web|native] [--ignore=<glob>,<glob>,...] [--all-targets]
+                                                         [--report=<url> --target-dir=<dir> [--commit=<sha>]]
   stark-cli targets [path]
+  stark-cli verify-vecna <path-to-layout.json> [--out=<dir>]
+  stark-cli scan-foreign <system-id-or-npm-package|auto> [path] [--platform=web|native] [--allow-network] [--ignore=<glob>,<glob>,...]
+                                                         [--report=<url> --target-dir=<dir> [--commit=<sha>]]
+  stark-cli scan-foreign                                 List the tested systems (pass one's id, or any raw npm package name)
 
 Options:
   --platform=<web|native>   Target platform for "props", "eject", and "adopt" (default: web)
@@ -176,6 +247,28 @@ missing feature; population is a separate, later pass. Not run for
 --platform=native (prop-mapping/ has no RN equivalent) — metric 6 is a
 visible "n/a" there, never an implicit zero.
 
+Also on the web platform, "adopt" scans for hand-rolled UI patterns that
+resemble a catalog component, whether or not the repo has adopted Stark at
+all — reported under "opportunities". Every other check above only has
+something to say about JSX that already imports @starklab/stk-components;
+a 0%-adoption repo produces zero findings from all of them, not "here's
+what you're missing." This closes that gap with a small, fixed set of
+named structural signatures, never fuzzy/statistical scoring: a native
+<button> with both an onClick handler and visual styling (style touching
+background/border/padding, or a className matching /btn|button/) suggests
+Button; a native <input type="text"|"email"|...> paired with a <label>
+suggests TextInput; an element with role="toolbar", or a flex/row container
+whose only significant children are 2+ native <button>s, suggests Toolbar.
+Each finding carries "confidence" ("high"|"medium", a suggestion strength)
+separate from "severity", which is always "Info" — an opportunity is not a
+defect and must never read as a CI-gate failure. Output is deliberately
+keyed "opportunities", the same word "targets"/"adopt --all-targets" use
+for a different, package-granularity idea (a whole excluded workspace
+target that still renders UI) — the two can appear side by side under
+"--all-targets" but never occupy the same key: that one is top-level, this
+one is nested per-target under its own "opportunities". Not run for
+--platform=native (the signatures are DOM/JSX-shape assumptions).
+
 On the native platform, "adopt" instead resolves the consumer's own JS-
 object token indirection — RN has no CSS custom properties, so the
 indirection is a local const or object property instead of var(), e.g.
@@ -253,10 +346,152 @@ without this, a shared internal UI package would score near-0% in every
 consuming target and 100% in the one that defines it, the same inverted-
 result problem catalog left-joining exists to prevent, recurring one level
 up at package granularity.
+
+"adopt --report=<url>" additionally POSTs the scan to a stark.dominion
+tracker (its /api/adoption-scan endpoint), the Stark-adoption counterpart
+of "scan-foreign --report" and the way a repo-connected target's real
+adoption score gets into the dashboard. It takes the same
+"--target-dir=<dir>" (required), "--commit=<sha>", STARK_DOMINION_TOKEN /
+"--token=<secret>" and never-fail-the-build behaviour documented under
+"scan-foreign" below, and the same path scrubbing. What is sent is a
+reduced projection: every per-site enumeration ("sites", "usages",
+"properties", "checks") is dropped, since the tracker reads counts and the
+three-number reports, never the enumeration behind them. Findings are kept.
+"--report" is not supported together with "--all-targets" — a reported scan
+belongs to exactly one tracker target, so run one "adopt <dir>
+--report --target-dir=<dir>" per target instead of reporting a whole
+discovery sweep under a single dir.
+
+"verify-vecna <path-to-layout.json>" is the reverse direction of "adopt":
+instead of scanning a consumer's real code for catalog usage, it checks one
+of Vecna's own generated LayoutConfig JSON files against the same catalog.
+The JSON is compiled into a real .jsx file with a real import statement
+from '@starklab/stk-components' (see adopt/vecnaMaterializer.js), written
+under --out (default ./.vecna-verify), then the real wrapperResolver/
+tokenAliasResolver/propApiResolver run against it unmodified — not a
+second, narrower reimplementation of the checks.
+
+Of those three, only "propApi" can produce real findings here: it validates
+literal call-site JSX props (invalid enum values, missing required props,
+deprecated props, className/style escape hatches) against
+prop-mapping/*.mapping.json, which is exactly what a materialized layout is.
+"wrappers" and "tokenAliases" are included for parity with "adopt"'s own
+resolver set, but always report empty by construction — Vecna's output
+never contains a local wrapper component (wrappers' whole domain) or a CSS
+custom-property alias chain (tokenAliases' whole domain). This is marked
+explicitly per-resolver as "vacuousByConstruction" in the output rather than
+silently reported as "0 findings," so it never reads as broader coverage
+than it has.
+
+A layout node whose type isn't in the catalog (the 5 hardcoded layout
+primitives — logo/heading/text/divider/spacer — or any future node type
+added without a matching prop-mapping layoutSchema) is skipped and listed
+under "materialized.skippedNodes" with a reason, never guessed.
+
+"scan-foreign <system-id-or-npm-package> [path]" is EXPERIMENTAL —
+ADOPTION_APP_PLAN.md §10 decision #25, "Version B": it answers a different
+question than "adopt": not "how much of @starklab/stk does this repo use,"
+but "what does this repo's OWN (non-Stark) design system look like, and how
+consistently does the repo itself use it." No opinionated conformance rules
+and no CI-gate severity — Stark has no house opinion about a design system
+it doesn't own; this reports facts, not defects. Two distribution modes,
+dispatched by the first argument:
+
+Phase 1 — "copy-paste" distribution (currently shadcn/ui only, <system> =
+"shadcn"): the component source ships directly in the consumer's repo (e.g.
+via "npx shadcn init"), so there's no node_modules boundary to cross.
+Discovery detects the package (components.json / @radix-ui/* deps), enumerates
+components by parsing every .tsx/.jsx directly under a components/ui
+directory, and detects the token source (CSS custom properties matching
+--background/--primary/--radius). Prop schema is extracted from each
+component's own "NameProps" interface/type, parsed straight from its file.
+Structural scoring covers catalog coverage (which discovered components are
+actually imported elsewhere in the repo) plus hand-rolled-duplicate detection
+for native <button> markup outside the catalog's own directory.
+
+Phase 2 — "installed-package" distribution (any React/React Native design
+system published to npm and already installed in the target repo — MUI,
+Chakra, Carbon, or any other; pass a registered id like "mui" for a friendly
+label, or any raw npm package name like "@mui/material" directly — the
+registry is a convenience, never a gate): real component/prop types live in
+node_modules/<package>'s own .d.ts, so discovery and prop-schema extraction
+both use the TypeScript compiler API (checker.getExportsOfModule,
+checker.getPropertiesOfType) against the package's resolved types entry
+instead of parsing local .tsx source — this also resolves generic prop
+aliases like ComponentProps<'div'> that a Babel-AST walk (Phase 1's approach)
+cannot. Component enumeration covers the package's FULL exported catalog,
+not just the components the target repo happens to import. Structural
+scoring covers catalog coverage (bare-import usage, resolveOrigin-based) plus
+hand-rolled-duplicate detection — reusing the same opportunity signatures
+"adopt" uses, web (native <button>-shaped) or native (Pressable/
+TouchableOpacity + onPress + StyleSheet-shaped) per --platform. Reads only
+already-installed node_modules by default: no "npm install" is ever run
+(that would execute install-time lifecycle scripts — real code execution
+from scanning a repo). If the package isn't installed, pass --allow-network
+to fetch its published package.json + .d.ts read-only from a CDN
+(cdn.jsdelivr.net — static file GETs only, still never installed or
+executed); without that flag, an uninstalled package reports
+"unresolvedReason" rather than fetching anything. --platform (default
+"web") selects RN vs DOM component-file conventions and duplicate-detection
+signatures; --ignore works the same as "adopt"'s.
+
+A system does not have to be one package. Some ship as many sibling
+packages with no umbrella barrel — Atlaskit's ~100 @atlaskit/* packages are
+the whole system, with no @atlaskit/core to name — so a registered entry may
+declare several, and a raw argument may be a comma-separated list
+("@atlaskit/button,@atlaskit/textfield"). Each package is discovered and scored
+separately and the results are aggregated: output then carries
+"multiPackage": true, a "packages" array, and "totals" (coverage summed,
+never averaged across packages), with repo-wide facts — "root",
+"platform", "duplicates" — hoisted out of the per-package entries. A
+one-package scan's output shape is unchanged.
+
+Known gap for Phase 2 (not built): JS-theme-object token detection
+(MUI/Chakra createTheme()/extendTheme() call-site parsing) — token source is
+not reported for installed-package systems in this pass.
+
+Two ways to skip typing a package name: "stark-cli scan-foreign" with no
+system argument prints the tested-systems list (id, label, npm package,
+platform) instead of running a scan — pick one's id, or fall through to any
+raw npm package name for a system that isn't listed ("Other" is just
+passing the package name directly, never a separate mode). "stark-cli
+scan-foreign auto [path]" instead reads [path]'s (default ".") own
+package.json dependency graph and matches it against that same tested list
+— if it's a registered dependency already, there's no reason to make the
+caller re-type what the repo itself already declares. Zero matches fails
+with the tested list (nothing registered is installed — pass a system id or
+raw package name explicitly); more than one match fails and lists what
+matched (a repo can depend on more than one design system; "auto" only
+resolves the unambiguous case) rather than guessing which one you meant.
+
+"--report=<url>" additionally POSTs the scan to a stark.dominion tracker
+(its /api/foreign-scan endpoint), which is how a foreign coverage number
+gets from a consumer's CI into the dashboard — the scan has to run where
+node_modules exists, so it runs there and pushes, rather than the tracker
+pulling. "--target-dir=<dir>" names the tracker target the scan belongs to
+and is required with it. The bearer secret is read from
+STARK_DOMINION_TOKEN, or from "--token=<secret>" — prefer the environment
+variable, since a flag is visible in the process list and in most CI logs.
+The commit comes from GITHUB_SHA / VERCEL_GIT_COMMIT_SHA / CI_COMMIT_SHA /
+BUILDKITE_COMMIT, then "git rev-parse HEAD", and can be set explicitly with
+"--commit=<sha>".
+
+Reporting never fails the build and never changes what is printed. An
+unreachable tracker, a rotated token or a missing target is written to
+stderr as a skipped-report line; stdout is the same JSON document either
+way and the exit code is the scan's own. What gets sent is a reduced
+projection of that document, not a copy of it: prop schemas are dropped
+(the tracker does not read them, and re-scanning re-derives them — on a
+real @mui/material scan this is 2.18 MB down to 10.6 KB), and every
+absolute path is rewritten to "<root>"/"<home>" before the payload leaves
+the machine. Paths are scrubbed only on the reported copy — stdout keeps
+the real ones, which is what is actually useful when debugging a local
+scan.
 `;
 
 const [, , command, ...rest] = process.argv;
 
+async function main() {
 switch (command) {
   case 'list':
     print(listComponents());
@@ -321,7 +556,19 @@ switch (command) {
     const ignoreArg = flagValue(rest, 'ignore', '');
     const ignore = ignoreArg ? ignoreArg.split(',').map(s => s.trim()).filter(Boolean) : [];
 
+    const reportUrl = flagValue(rest, 'report', undefined);
+
     if (hasFlag(rest, 'all-targets')) {
+      if (reportUrl) {
+        // Refused rather than silently ignored. A reported scan is keyed to
+        // one tracker target (targets.dir + the per-target bearer secret), and
+        // an --all-targets sweep produces one result per discovered directory
+        // — there is no single dir the aggregate honestly belongs to. Filing
+        // it under whatever --target-dir happened to be passed would attribute
+        // every target's numbers to one of them.
+        fail('--report cannot be combined with --all-targets. Run "stark-cli adopt <dir> --report=<url> --target-dir=<dir>" once per target.');
+        break;
+      }
       try {
         const discovery = discoverTargets(root);
         const workspacePackages = workspacePackageMap(discovery);
@@ -344,11 +591,37 @@ switch (command) {
       break;
     }
 
+    let adoptResult = null;
     try {
-      print(runAdopt(root, platform, ignore));
+      adoptResult = runAdopt(root, platform, ignore);
+      print(adoptResult);
     } catch (err) {
+      adoptResult = null;
       fail(err.message);
     }
+
+    // Same placement and the same reasoning as scan-foreign's reporting block
+    // below: outside the scan's try/catch, so a fault in the reporting path
+    // can never reach fail() and turn a successful scan into a non-zero exit.
+    // Outcome goes to stderr only; stdout stays a clean JSON document whether
+    // or not a tracker is configured.
+    if (adoptResult && reportUrl) {
+      const token = flagValue(rest, 'token', process.env.STARK_DOMINION_TOKEN);
+      const outcome = await reportAdoptScan(adoptResult, {
+        url: reportUrl,
+        token,
+        root,
+        targetDir: flagValue(rest, 'target-dir', undefined),
+        commitSha: flagValue(rest, 'commit', resolveCommitSha(root)),
+        scannerVersion: SCANNER_VERSION,
+      }).catch((err) => ({ reported: false, reason: err.message }));
+
+      if (outcome.reported) {
+        console.error(`Reported to ${reportUrl} (adoption scan #${outcome.response?.id ?? '?'}).`);
+      } else {
+        console.error(`Scan complete; reporting was skipped: ${outcome.reason}`);
+      }
+    }
     break;
   }
 
@@ -364,6 +637,136 @@ switch (command) {
     break;
   }
 
+  case 'verify-vecna': {
+    const [maybePath] = rest;
+    if (!maybePath || maybePath.startsWith('--')) {
+      fail('Usage: stark-cli verify-vecna <path-to-layout.json> [--out=<dir>]');
+      break;
+    }
+    const layoutPath = path.resolve(process.cwd(), maybePath);
+    const outDir = flagValue(rest, 'out', undefined);
+    const slug = path.basename(layoutPath).replace(/\.layout\.json$|\.json$/, '');
+    try {
+      const layoutConfig = JSON.parse(readFileSync(layoutPath, 'utf-8'));
+      print(verifyVecnaLayout(layoutConfig, { outDir, slug }));
+    } catch (err) {
+      fail(err.message);
+    }
+    break;
+  }
+
+  case 'scan-foreign': {
+    const [systemArg, maybePath] = rest;
+    if (!systemArg) {
+      print({
+        hint: 'Pass a system id below, any raw npm package name for one not listed, or "auto" to detect from [path]\'s package.json.',
+        systems: listForeignSystems(),
+      });
+      break;
+    }
+    const target = maybePath && !maybePath.startsWith('--') ? maybePath : '.';
+    const root = path.resolve(process.cwd(), target);
+    const ignoreArg = flagValue(rest, 'ignore', '');
+    const ignore = ignoreArg ? ignoreArg.split(',').map(s => s.trim()).filter(Boolean) : [];
+    const platform = flagValue(rest, 'platform', 'web');
+    const allowNetwork = hasFlag(rest, 'allow-network');
+
+    // "auto" resolves to a real registered system id up front, then falls
+    // straight into the same dispatch below — it never becomes a third
+    // code path of its own. Ambiguous (>1) and no-match cases fail with
+    // the candidates/tested list rather than guessing, same "never guess
+    // among ambiguous candidates" discipline as the rest of adopt/.
+    let resolvedSystemArg = systemArg;
+    if (systemArg === 'auto') {
+      const detected = detectForeignSystems(root, { ignore });
+      if (detected.length === 0) {
+        fail(
+          `No tested system's dependency was found in ${root}'s package.json — pass a system id or raw npm package name explicitly. Tested systems:\n` +
+            listForeignSystems().map((s) => `  ${s.id} — ${s.label} (${packageSummary(s)})`).join('\n')
+        );
+        break;
+      }
+      if (detected.length > 1) {
+        fail(
+          `More than one tested system's dependency was found in ${root}'s package.json — pass one explicitly:\n` +
+            detected.map((d) => `  ${d.id} — ${d.label} (${packageSummary(d)})`).join('\n')
+        );
+        break;
+      }
+      resolvedSystemArg = detected[0].id;
+      console.error(`Auto-detected "${detected[0].label}" (${packageSummary(detected[0])}) from ${root}'s package.json dependencies.`);
+    }
+
+    // A registered system id (e.g. "shadcn", "mui") dispatches on its own
+    // "distribution" shape; anything else is treated as a raw npm package
+    // name, defaulting to the "installed-package" path — this is what makes
+    // "whatever design system" real rather than a curated list (see
+    // foreignSystemConfig.js's header comment).
+    const registered = FOREIGN_SYSTEMS[resolvedSystemArg];
+
+    const reportUrl = flagValue(rest, 'report', undefined);
+
+    let result = null;
+    try {
+      if (registered && registered.distribution === 'copy-paste') {
+        const discovery = resolveForeignDiscovery(root, resolvedSystemArg, { ignore });
+        const propSchema = resolvePropSchema(root, resolvedSystemArg, discovery.components);
+        const scoring = scoreForeignAdoption(root, resolvedSystemArg, discovery, { ignore });
+        result = { discovery, propSchema, scoring };
+      } else {
+        // A registered system contributes its declared package(s); an
+        // unregistered argument is a raw package name, or a comma-separated
+        // list of them — the same multi-package shape the registry can now
+        // express, kept available to systems nobody has registered, since
+        // this command's whole premise is "whatever design system," not a
+        // curated list. Commas are safe as the separator: npm names can't
+        // contain one.
+        const packages = registered
+          ? systemPackages(registered)
+          : resolvedSystemArg.split(',').map((s) => s.trim()).filter(Boolean);
+        result = await scanInstalledSystem(root, packages, {
+          platform,
+          ignore,
+          allowNetwork,
+          system: registered?.id ?? null,
+          label: registered?.label ?? null,
+        });
+      }
+      print(result);
+    } catch (err) {
+      fail(err.message);
+    }
+
+    // Reporting sits outside the scan's own try/catch on purpose. A scan that
+    // failed has already reported that failure and left `result` null, so
+    // nothing is sent; and a fault in the reporting path can never reach
+    // `fail()` and turn a successful scan into a non-zero exit. Its outcome
+    // goes to stderr only, so stdout stays a clean JSON document whether or
+    // not a tracker is configured. See foreignScanReport.js's header for why
+    // never breaking the consumer's CI is the governing constraint.
+    if (result && reportUrl) {
+      // The token is read from the environment by default: a secret passed as
+      // a flag is visible in the process list and in most CI logs.
+      const token = flagValue(rest, 'token', process.env.STARK_DOMINION_TOKEN);
+      const outcome = await reportForeignScan(result, {
+        url: reportUrl,
+        token,
+        root,
+        targetDir: flagValue(rest, 'target-dir', undefined),
+        commitSha: flagValue(rest, 'commit', resolveCommitSha(root)),
+        scannerVersion: SCANNER_VERSION,
+        label: registered?.label ?? null,
+      }).catch((err) => ({ reported: false, reason: err.message }));
+
+      if (outcome.reported) {
+        console.error(`Reported to ${reportUrl} (foreign scan #${outcome.response?.id ?? '?'}).`);
+      } else {
+        console.error(`Scan complete; reporting was skipped: ${outcome.reason}`);
+      }
+    }
+    break;
+  }
+
   case undefined:
   case '--help':
   case '-h':
@@ -374,3 +777,6 @@ switch (command) {
   default:
     fail(`Unknown command "${command}".\n\n${HELP}`);
 }
+}
+
+main();

package/src/adopt/__fixtures__/dominion-fixture-app/src/pages/Home.jsx

@@ -1,21 +0,0 @@
-import React from 'react';
-import { Button } from '@starklab/stk-components';
-import { AppButton } from '../wrappers/AppButton';
-import { BrandButton } from '../wrappers/BrandButton';
-import { FeatureCard } from '../wrappers/FeatureCard';
-
-export function Home() {
-  return (
-    <div className="dark:bg-primary">
-      <AppButton>Save</AppButton>
-      <BrandButton>Buy now</BrandButton>
-      <BrandButton>Learn more</BrandButton>
-      <BrandButton>Get started</BrandButton>
-      {/* Direct (non-wrapper) catalog call site — invalid enum value plus a
-          className passthrough, exercising resolvePropApi's two checkable
-          rules against the real button.mapping.json data. */}
-      <Button variant="primry" className="cta-override">Go</Button>
-      <FeatureCard content={<p>Feature</p>} />
-    </div>
-  );
-}

package/src/adopt/__fixtures__/dominion-fixture-app/src/pages/Menu.jsx

@@ -1,13 +0,0 @@
-import React from 'react';
-import { DropdownMenu } from '@starklab/stk-components';
-
-// Compound Foo.Bar usage — <DropdownMenu.SubTrigger/> is a JSXMemberExpression
-// and must attribute back to the DropdownMenu catalog entry, not go unmatched
-// as a component literally named "DropdownMenu.SubTrigger".
-export function Menu() {
-  return (
-    <DropdownMenu>
-      <DropdownMenu.SubTrigger>Open</DropdownMenu.SubTrigger>
-    </DropdownMenu>
-  );
-}

package/src/adopt/__fixtures__/dominion-fixture-app/src/pages/Profile.jsx

@@ -1,11 +0,0 @@
-import React from 'react';
-import { BrandButton } from '../wrappers/BrandButton';
-
-export function Profile() {
-  return (
-    <div>
-      <BrandButton>Edit</BrandButton>
-      <BrandButton>Delete</BrandButton>
-    </div>
-  );
-}

package/src/adopt/__fixtures__/dominion-fixture-app/src/theme.css

@@ -1,34 +0,0 @@
-:root {
-  /* nested aliases — app-base -> app-mid -> app-top -> app-deep, terminal
-     depth 4 (deeper than tokenAliasResolver's WARN_DEPTH of 3), exercising
-     both transitive resolution and the deep-alias-chain finding */
-  --app-base: var(--stk-surface-brand-1-strong);
-  --app-mid: var(--app-base);
-  --app-top: var(--app-mid);
-  --app-deep: var(--app-top);
-
-  /* raw fallback — resolves conformant, still flagged info-level since the
-     fallback silently becomes load-bearing the day
-     --stk-surface-brand-1-strong is renamed */
-  --app-cta: var(--stk-surface-brand-1-strong, #1956dd);
-
-  /* primitive alias — layer violation: a consumer property pointing straight
-     at a base/primitive token instead of a semantic one */
-  --app-gap: var(--stk-spacing-md);
-
-  /* scoped-override target — conformant at :root */
-  --app-accent: var(--stk-surface-brand-1-strong);
-}
-
-/* scoped override — same property, different selector, resolving to a raw
-   hex under .theme-promo: :root and .theme-promo disagree, so the property
-   overall is partial-conformance rather than collapsed to one scope */
-.theme-promo {
-  --app-accent: #1956dd;
-}
-
-/* Tailwind v4 theme entry — Home.jsx's className="dark:bg-primary" resolves
-   through this back to a Stark token */
-@theme {
-  --color-primary: var(--stk-surface-brand-1-strong);
-}

package/src/adopt/__fixtures__/dominion-fixture-app/src/wrappers/AppButton.jsx

@@ -1,8 +0,0 @@
-import React from 'react';
-import { Button } from '@starklab/stk-components';
-
-// Transparent wrapper — spreads props through unmodified, no hardcoded or
-// style-only attributes.
-export function AppButton(props) {
-  return <Button {...props} />;
-}

package/src/adopt/__fixtures__/dominion-fixture-app/src/wrappers/BrandButton.jsx

@@ -1,9 +0,0 @@
-import React from 'react';
-import { Button } from '@starklab/stk-components';
-
-// Divergent wrapper — a hardcoded className makes this a styling override,
-// not a faithful passthrough. Used from several call sites (see
-// pages/Home.jsx and pages/Profile.jsx) to exercise high fanout.
-export function BrandButton(props) {
-  return <Button className="brand-button" {...props} />;
-}

package/src/adopt/__fixtures__/dominion-fixture-app/src/wrappers/CardBase.jsx

@@ -1,9 +0,0 @@
-import React from 'react';
-import { Card } from '@starklab/stk-components';
-
-// First hop of a two-level wrapper chain (see FeatureCard.jsx) — transparent
-// passthrough. Only consumed internally by FeatureCard, so its own external
-// fanout should be zero (the chain edge itself is excluded from fanout).
-export function CardBase(props) {
-  return <Card {...props} />;
-}

package/src/adopt/__fixtures__/dominion-fixture-app/src/wrappers/FeatureCard.jsx

@@ -1,7 +0,0 @@
-import React from 'react';
-import { CardBase } from './CardBase';
-
-// Second hop of the chain — resolves through CardBase down to Card.
-export function FeatureCard(props) {
-  return <CardBase {...props} />;
-}

package/src/adopt/__fixtures__/dominion-fixture-app/src/wrappers/SectionCard.jsx

@@ -1,12 +0,0 @@
-import React from 'react';
-import { Card } from '@starklab/stk-components';
-
-// An "as"-polymorphic call site. ADOPTION_APP_PLAN.md §4 "Polymorphism" calls
-// for a declared `polymorphicProp` field in prop-mapping/schema.json as
-// future work — no dedicated `as`-detection exists in wrapperResolver.js yet,
-// so a hardcoded `as` attribute is classified through the ordinary
-// hardcodedProps -> "constraining" path, same as any other literal prop.
-// This fixture documents that current (pre-declaration) behavior.
-export function SectionCard(props) {
-  return <Card as="section" {...props} />;
-}