@starklab/stark-mcp 0.1.0 → 0.2.0

package/src/adopt/foreignSystemConfig.js

@@ -0,0 +1,356 @@
+/**
+ * Data-only registry of foreign design systems `stark-cli scan-foreign`
+ * knows how to detect. Phase 1 ships one entry — shadcn/ui, the only
+ * system that scored 4/4 in the B1 spike (ADOPTION_APP_PLAN.md §10
+ * decision #25) because its copy-paste distribution puts real component
+ * source (and therefore real prop types) inside the repo, with no
+ * node_modules boundary to cross. Structured so Phase 2's installed-
+ * package adapter (MUI, most likely) adds a second entry of a different
+ * shape rather than a new code path — the same reasoning catalog.json
+ * already gives Stark's own components, applied here to foreign ones.
+ */
+export const FOREIGN_SYSTEMS = {
+  shadcn: {
+    id: 'shadcn',
+    label: 'shadcn/ui',
+    distribution: 'copy-paste', // vs Phase 2's 'installed-package'
+    // Same display-only hint as every installed-package entry below (see the
+    // comment above `mui`). shadcn generates React DOM components wrapping
+    // Radix web primitives, so 'web' is the only honest value — it was
+    // omitted rather than deliberated, which made shadcn the one row
+    // listForeignSystems() emitted as `platform: undefined`.
+    platform: 'web',
+    packageDetect: {
+      // shadcn is never itself an npm dependency — components.json (written
+      // by `npx shadcn init`) is the primary signal; @radix-ui/* deps (what
+      // shadcn's generated components wrap) are corroborating evidence only.
+      configFiles: ['components.json'],
+      depFallback: [/^@radix-ui\//],
+    },
+    componentDir: { parentName: 'components', dirName: 'ui' },
+    tokenSource: { markerVars: ['--background', '--primary', '--radius'] },
+  },
+  // Phase 2's 'installed-package' shape — real component/prop types live in
+  // node_modules/<npmPackage>'s .d.ts, not in repo source (see
+  // installedPackageDiscoveryResolver.js). This registry entry is a
+  // convenience label only, never a gate: cli.js's scan-foreign accepts any
+  // raw npm package name too, registered here or not. "platform" is a
+  // hint for the tested-systems list/auto-detect output only — it never
+  // restricts which --platform value actually runs against the package.
+  //
+  // An entry declares its packages one of two ways, never both:
+  // `npmPackage: 'x'` for a system published as one entry package (every
+  // entry below but `atlaskit`), or `npmPackages: ['a', 'b']` for one
+  // distributed as many sibling packages with no umbrella barrel. Read them
+  // through systemPackages() rather than either field directly; that helper
+  // is what every consumer (auto-detect, the tested-systems list, cli.js's
+  // scan dispatch) normalises through.
+  //
+  // Having an umbrella is the thing to check before reaching for
+  // `npmPackages` — a system that has one should be registered by it. Adobe
+  // React Spectrum looked like the multi-package case and is not: live
+  // probing on 2026-08-27 found `@adobe/react-spectrum` enumerating all 101
+  // components, so it would be registered single-string. What that probe did
+  // establish is that the two import styles are mutually blind — the
+  // umbrella scored 3/101 against umbrella-style imports and 0/101 against
+  // `@react-spectrum/button`-style ones, and the siblings scored the reverse.
+  // Listing an umbrella *and* its siblings together would therefore
+  // double-count the shared catalog (101 + 6 + 3 for 101 real components) and
+  // deflate the percentage, so `npmPackages` is for systems with no umbrella
+  // to choose, never a way to cover both import styles at once.
+  mui: {
+    id: 'mui',
+    label: 'MUI',
+    distribution: 'installed-package',
+    npmPackage: '@mui/material',
+    platform: 'web',
+  },
+  // The following twelve entries were live-verified against real npm installs
+  // 2026-08-25 (ADOPTION_APP_PLAN.md §10 decision #25, "broader 12-system
+  // sweep") — five needed real adapter fixes (Radix, Mantine, NativeBase,
+  // Chakra UI v3, @atlaskit/button), the rest came back clean. Restyle is
+  // registered despite its `used: 0` coverage gap — since root-caused as
+  // KNOWN_DISTRIBUTION_PATTERNS #7 (runtime-factory-synthesized), a
+  // documented architectural non-goal rather than a bug — instead of being
+  // left out: the point of this list is "what's been tested," not "what's
+  // guaranteed clean."
+  chakra: {
+    id: 'chakra',
+    label: 'Chakra UI',
+    distribution: 'installed-package',
+    npmPackage: '@chakra-ui/react',
+    platform: 'web',
+  },
+  carbon: {
+    id: 'carbon',
+    label: 'Carbon Design System',
+    distribution: 'installed-package',
+    npmPackage: '@carbon/react',
+    platform: 'web',
+  },
+  antd: {
+    id: 'antd',
+    label: 'Ant Design',
+    distribution: 'installed-package',
+    npmPackage: 'antd',
+    platform: 'web',
+  },
+  // The one genuinely umbrella-less system registered here, and the reason
+  // `npmPackages` exists. Atlaskit publishes ~100 independent `@atlaskit/*`
+  // packages and no barrel over them: `@atlaskit/core` is a 404 and bare
+  // `atlaskit` is npm's 0.0.1-security placeholder (both checked 2026-08-27).
+  // Until then this entry named a single sibling and its label said so —
+  // "Atlassian (Atlaskit Button)" — which reported Atlaskit as a
+  // four-component system. Live-verified against a real four-package install
+  // the same day: the old single-sibling form said 1/4 used (25%), the list
+  // below says 3/13 (23.1%) across the four, which is the honest denominator.
+  //
+  // The list is a curated core rather than all ~100 — every name below was
+  // confirmed to resolve on npm before being added. Siblings a repo has not
+  // installed are not an error: they land in the scan's `unresolved` array
+  // and stay out of the coverage denominator, since a component that isn't
+  // installed is not one the repo declined to use.
+  atlaskit: {
+    id: 'atlaskit',
+    label: 'Atlassian Atlaskit',
+    distribution: 'installed-package',
+    npmPackages: [
+      '@atlaskit/button',
+      '@atlaskit/textfield',
+      '@atlaskit/checkbox',
+      '@atlaskit/radio',
+      '@atlaskit/select',
+      '@atlaskit/form',
+      '@atlaskit/toggle',
+      '@atlaskit/modal-dialog',
+      '@atlaskit/drawer',
+      '@atlaskit/banner',
+      '@atlaskit/flag',
+      '@atlaskit/tooltip',
+      '@atlaskit/lozenge',
+      '@atlaskit/badge',
+      '@atlaskit/tag',
+      '@atlaskit/avatar',
+      '@atlaskit/tabs',
+      '@atlaskit/menu',
+      '@atlaskit/dropdown-menu',
+      '@atlaskit/breadcrumbs',
+      '@atlaskit/spinner',
+      '@atlaskit/progress-bar',
+      '@atlaskit/calendar',
+      '@atlaskit/datetime-picker',
+      '@atlaskit/inline-edit',
+    ],
+    platform: 'web',
+  },
+  radix: {
+    id: 'radix',
+    label: 'Radix Primitives',
+    distribution: 'installed-package',
+    npmPackage: 'radix-ui',
+    platform: 'web',
+  },
+  mantine: {
+    id: 'mantine',
+    label: 'Mantine',
+    distribution: 'installed-package',
+    npmPackage: '@mantine/core',
+    platform: 'web',
+  },
+  fluentui: {
+    id: 'fluentui',
+    label: 'Fluent UI',
+    distribution: 'installed-package',
+    npmPackage: '@fluentui/react-components',
+    platform: 'web',
+  },
+  nativebase: {
+    id: 'nativebase',
+    label: 'NativeBase',
+    distribution: 'installed-package',
+    npmPackage: 'native-base',
+    platform: 'native',
+  },
+  tamagui: {
+    id: 'tamagui',
+    label: 'Tamagui',
+    distribution: 'installed-package',
+    npmPackage: 'tamagui',
+    platform: 'native',
+  },
+  rnPaper: {
+    id: 'rnPaper',
+    label: 'React Native Paper',
+    distribution: 'installed-package',
+    npmPackage: 'react-native-paper',
+    platform: 'native',
+  },
+  restyle: {
+    id: 'restyle',
+    label: 'Restyle (Shopify)',
+    distribution: 'installed-package',
+    npmPackage: '@shopify/restyle',
+    platform: 'native',
+  },
+  rnElements: {
+    id: 'rnElements',
+    label: 'React Native Elements',
+    distribution: 'installed-package',
+    npmPackage: 'react-native-elements',
+    platform: 'native',
+  },
+  // The following six were live-verified 2026-08-26 (ADOPTION_APP_PLAN.md
+  // §10 decision #25, Track C) — chosen for distribution-mechanic diversity
+  // rather than popularity, to find export shapes the popular-and-similar
+  // systems above could not surface. Five came back clean; primereact
+  // produced KNOWN_DISTRIBUTION_PATTERNS #8. Registered here after the fact:
+  // they were verified in that round but never added, so `scan-foreign`'s
+  // tested-systems list under-reported what had actually been tested.
+  reactAria: {
+    id: 'reactAria',
+    label: 'React Aria (Adobe)',
+    distribution: 'installed-package',
+    npmPackage: 'react-aria',
+    platform: 'web',
+  },
+  headlessui: {
+    id: 'headlessui',
+    label: 'Headless UI',
+    distribution: 'installed-package',
+    npmPackage: '@headlessui/react',
+    platform: 'web',
+  },
+  blueprint: {
+    id: 'blueprint',
+    label: 'Blueprint (Palantir)',
+    distribution: 'installed-package',
+    npmPackage: '@blueprintjs/core',
+    platform: 'web',
+  },
+  // Registered on the same "what's been tested" principle as Restyle above:
+  // primereact discovers 0 components because it has no root barrel at all
+  // (every component lives under a subpath like `primereact/button`), which
+  // is pattern #8 — the adapter now reports that honestly via
+  // unresolvedReason instead of a false `installed: false`.
+  primereact: {
+    id: 'primereact',
+    label: 'PrimeReact',
+    distribution: 'installed-package',
+    npmPackage: 'primereact',
+    platform: 'web',
+  },
+  gluestack: {
+    id: 'gluestack',
+    label: 'gluestack-ui',
+    distribution: 'installed-package',
+    npmPackage: '@gluestack-ui/themed',
+    platform: 'native',
+  },
+  uiKitten: {
+    id: 'uiKitten',
+    label: 'UI Kitten (Eva Design)',
+    distribution: 'installed-package',
+    npmPackage: '@ui-kitten/components',
+    platform: 'native',
+  },
+  // Live-verified 2026-08-27 while probing whether it needed `npmPackages`.
+  // It does not — see the umbrella discussion in the block comment above
+  // `mui`: `@adobe/react-spectrum` enumerates all 101 components on its own,
+  // so it is registered by the umbrella and nothing else. Adding its
+  // `@react-spectrum/*` siblings alongside would double-count the shared
+  // catalog rather than widen it.
+  //
+  // Known limitation, specific to this entry's shape rather than a bug:
+  // coverage sees one import style at a time. Against a fixture importing
+  // from the umbrella this scored 3/101; against the same components
+  // imported from `@react-spectrum/button`/`-textfield` it scored 0/101,
+  // while the siblings scored the reverse. Adobe's docs teach the umbrella
+  // import, so that is the style registered for — but a repo that mixes both
+  // under-reports, and nothing warns about it yet.
+  spectrum: {
+    id: 'spectrum',
+    label: 'React Spectrum (Adobe)',
+    distribution: 'installed-package',
+    npmPackage: '@adobe/react-spectrum',
+    platform: 'web',
+  },
+  // The two below were live-verified 2026-08-27 against real npm installs in
+  // a throwaway fixture repo (an App.jsx importing five components each),
+  // scanned with `scan-foreign … --platform=native`.
+  //
+  // react-native-ui-lib@9.1.2 came back clean: types at `src/index.d.ts`,
+  // 71 components discovered, all five fixture imports counted, no
+  // unresolved entries and no duplicates. Worth noting for the next system
+  // with the same shape: its barrel contains `export * from 'uilib-native'`,
+  // a wildcard re-export from a sibling package, and discovery follows it
+  // without help.
+  uiLib: {
+    id: 'uiLib',
+    label: 'React Native UI Lib (Wix)',
+    distribution: 'installed-package',
+    npmPackage: 'react-native-ui-lib',
+    platform: 'native',
+  },
+  // @ant-design/react-native@5.4.3: types at `lib/index.d.ts`, 41 components
+  // discovered, three of the five fixture imports counted. Registered with
+  // its gap known rather than omitted, same as Restyle and PrimeReact above.
+  // Four barrel exports (Checkbox, Collapse, Input, List) are missed because
+  // they are declared as `typeof Internal & { …statics }` intersections —
+  // pattern #9 in installedPackageDiscoveryResolver.js, root-caused by
+  // reading the package's own .d.ts rather than inferred. A fifth absent
+  // export, ActionSheet, is excluded *correctly*: it declares only imperative
+  // methods (showActionSheetWithOptions, close), not a component.
+  antdRn: {
+    id: 'antdRn',
+    label: 'Ant Design Mobile RN',
+    distribution: 'installed-package',
+    npmPackage: '@ant-design/react-native',
+    platform: 'native',
+  },
+};
+
+/**
+ * The npm packages an entry's types come from, normalised to an array so no
+ * consumer has to know which of the two declaration forms an entry used —
+ * `[]` for a copy-paste system, which has no npm package at all.
+ *
+ * Single-string `npmPackage` was the only form until 2026-08-27, which made
+ * a system with no umbrella package unregisterable rather than merely
+ * untested — and the `atlaskit` entry above is what that cost in practice:
+ * `@atlaskit/button` was named as "the" package, so a repo using twenty
+ * @atlaskit/* siblings was scored against one sibling's four components.
+ * Multi-package entries are scanned per package and aggregated — see
+ * installedSystemScan.js.
+ */
+export function systemPackages(system) {
+  if (Array.isArray(system.npmPackages)) return system.npmPackages;
+  return system.npmPackage ? [system.npmPackage] : [];
+}
+
+/** The tested-systems list surfaced by `scan-foreign` with no args and
+ * consulted by the auto-detector — a plain array so both consumers can
+ * map/filter without reaching into object-key iteration order.
+ * `npmPackage` stays the single primary package (first, for display and for
+ * the one-package case); `npmPackages` carries the full set. */
+export function listForeignSystems() {
+  return Object.values(FOREIGN_SYSTEMS).map((system) => {
+    const packages = systemPackages(system);
+    return {
+      id: system.id,
+      label: system.label,
+      distribution: system.distribution,
+      npmPackage: packages[0] ?? null,
+      npmPackages: packages,
+      platform: system.platform,
+    };
+  });
+}
+
+export function getForeignSystem(systemId) {
+  const system = FOREIGN_SYSTEMS[systemId];
+  if (!system) {
+    const known = Object.keys(FOREIGN_SYSTEMS).join(', ');
+    throw new Error(`Unknown foreign system "${systemId}" — known systems: ${known}`);
+  }
+  return system;
+}