@starklab/stark-mcp 0.1.0 → 0.2.0

package/src/adopt/moduleGraph.js

@@ -20,12 +20,36 @@ const DEFAULT_IGNORE = [
 
 export const EXTENSIONS = ['.tsx', '.ts', '.jsx', '.js', '.mjs', '.cjs'];
 
-export function resolveRelative(fromFile, specifier) {
-  const base = path.resolve(path.dirname(fromFile), specifier);
+/**
+ * RN's platform-split file convention — a bare `import Button from
+ * './Button'` resolves to one of these ahead of the plain `.tsx`/`.ts`/etc.
+ * sibling when `platform: 'native'` is threaded through, mirroring
+ * Metro/react-native's own module resolution priority (`.native.*` first,
+ * then the OS-specific suffix, then the platform-agnostic file last).
+ */
+const NATIVE_SUFFIXES = ['.native', '.ios', '.android'];
+const NATIVE_EXTENSIONS = NATIVE_SUFFIXES.flatMap((suffix) => EXTENSIONS.map((ext) => suffix + ext));
+
+/**
+ * Tries `base` itself, then each known extension appended, then each
+ * extension under an `index` file inside `base` as a directory. Shared by
+ * resolveRelative() (relative-specifier hops) and, via export, by any
+ * resolver that has already turned a non-relative specifier into a
+ * filesystem base path of its own (e.g. foreignScoringResolver.js
+ * resolving a tsconfig `paths` alias) and just needs the same fallback.
+ * Pass `{ platform: 'native' }` to prefer a `.native.*`/`.ios.*`/`.android.*`
+ * sibling over the plain extension, for a target repo whose own source uses
+ * RN platform-split files (installedPackageDiscoveryResolver.js's `platform:
+ * 'native'` case) — the installed package's own .d.ts resolution is
+ * unaffected, since a package's types entry is a single file regardless of
+ * platform.
+ */
+export function resolveCandidateFile(base, { platform = 'web' } = {}) {
+  const exts = platform === 'native' ? [...NATIVE_EXTENSIONS, ...EXTENSIONS] : EXTENSIONS;
   const candidates = [
     base,
-    ...EXTENSIONS.map((ext) => base + ext),
-    ...EXTENSIONS.map((ext) => path.join(base, 'index' + ext)),
+    ...exts.map((ext) => base + ext),
+    ...exts.map((ext) => path.join(base, 'index' + ext)),
   ];
   for (const candidate of candidates) {
     if (existsSync(candidate) && statSync(candidate).isFile()) return candidate;
@@ -33,6 +57,11 @@ export function resolveRelative(fromFile, specifier) {
   return null;
 }
 
+export function resolveRelative(fromFile, specifier, opts = {}) {
+  const base = path.resolve(path.dirname(fromFile), specifier);
+  return resolveCandidateFile(base, opts);
+}
+
 /**
  * Parses every source file under `root` once and extracts each file's import
  * bindings and re-export edges. This is the graph the reference resolver
@@ -145,7 +174,7 @@ export function buildModuleGraph(root, { ignore = [] } = {}) {
  *                     such binding)
  */
 export function resolveOrigin(moduleGraph, file, name, opts = {}) {
-  const { visited = new Set(), depth = 0, viaExport = false } = opts;
+  const { visited = new Set(), depth = 0, viaExport = false, platform = 'web' } = opts;
   const MAX_DEPTH = 20; // safety valve only — see ADOPTION_APP_PLAN.md §4 "5 is governance, 20 is safety"
   const key = `${file}#${viaExport ? 'export' : 'local'}#${name}`;
   if (visited.has(key)) return { cycle: [...visited, key] };
@@ -170,13 +199,14 @@ export function resolveOrigin(moduleGraph, file, name, opts = {}) {
     return null;
   }
 
-  const resolvedFile = resolveRelative(file, source);
+  const resolvedFile = resolveRelative(file, source, { platform });
   if (!resolvedFile || !moduleGraph.graph.has(resolvedFile)) return null;
 
   return resolveOrigin(moduleGraph, resolvedFile, imported, {
     visited: nextVisited,
     depth: depth + 1,
     viaExport: true,
+    platform,
   });
 }
 
@@ -196,7 +226,7 @@ export function resolveOrigin(moduleGraph, file, name, opts = {}) {
  *   null                           — dead end (missing file, namespace import, unparseable)
  */
 export function resolveOriginDeep(moduleGraph, file, name, opts = {}) {
-  const { visited = new Set(), depth = 0, viaExport = false } = opts;
+  const { visited = new Set(), depth = 0, viaExport = false, platform = 'web' } = opts;
   const MAX_DEPTH = 20; // safety valve only — see ADOPTION_APP_PLAN.md §4 "5 is governance, 20 is safety"
   const key = `${file}#${viaExport ? 'export' : 'local'}#${name}`;
   if (visited.has(key)) return { cycle: [...visited, key] };
@@ -221,12 +251,13 @@ export function resolveOriginDeep(moduleGraph, file, name, opts = {}) {
     return null;
   }
 
-  const resolvedFile = resolveRelative(file, source);
+  const resolvedFile = resolveRelative(file, source, { platform });
   if (!resolvedFile || !moduleGraph.graph.has(resolvedFile)) return null;
 
   return resolveOriginDeep(moduleGraph, resolvedFile, imported, {
     visited: nextVisited,
     depth: depth + 1,
     viaExport: true,
+    platform,
   });
 }

package/src/adopt/opportunityResolver.js

@@ -0,0 +1,255 @@
+import path from 'node:path';
+
+import traverseModule from '@babel/traverse';
+
+import { buildModuleGraph } from './moduleGraph.js';
+import { resolveJsxLiteral } from './usageRulesResolver.js';
+import {
+  getAttr,
+  domTagName as nativeTagName,
+  classNameMatches,
+  hasStaticClassNameContent,
+  styleTouchesKeys,
+  significantJsxChildren,
+} from './jsxOpportunityHelpers.js';
+import { OPPORTUNITY_SIGNATURES_NATIVE } from './opportunitySignaturesNative.js';
+
+const traverse = traverseModule.default ?? traverseModule;
+
+// ───────────────────────────── Button signature ─────────────────────────────
+
+const BUTTON_STYLE_KEY_RE = /^(background|border|padding)/i;
+
+/**
+ * A native <button> with onClick alone is common and often fine as-is (a
+ * bare form reset/submit, a test id target). Requiring visual styling too
+ * — the same "don't flag on one weak signal" discipline wrapperResolver.js
+ * uses for passthrough classification — narrows to the case that's actually
+ * worth flagging: someone re-implemented what Button already provides.
+ * "Styled" means style keys touching background/border/padding, OR any
+ * static class name at all (see hasStaticClassNameContent — a keyword
+ * regex like /btn|button/ was tried first and missed every real case in
+ * apps/portfolio's own hand-rolled buttons, none of which named their class
+ * that way).
+ */
+function matchButton(elPath) {
+  const opening = elPath.node.openingElement;
+  if (nativeTagName(opening.name) !== 'button') return null;
+  if (!getAttr(opening, 'onClick')) return null;
+  const styled = styleTouchesKeys(opening, BUTTON_STYLE_KEY_RE) || hasStaticClassNameContent(opening);
+  if (!styled) return null;
+  return { confidence: 'high', detail: 'native <button> with onClick and visual styling (style/className)' };
+}
+
+// ───────────────────────────── TextInput signature ─────────────────────────────
+
+const TEXT_INPUT_TYPES = new Set(['text', 'email', 'password', 'search', 'tel', 'url', 'number']);
+
+function isLabelTag(node) {
+  return node.type === 'JSXElement' && nativeTagName(node.openingElement.name) === 'label';
+}
+
+function pairedWithLabel(elPath) {
+  const parentNode = elPath.parentPath?.node;
+  if (parentNode?.type === 'JSXElement' && isLabelTag(parentNode)) return true; // <label>Name <input/></label>
+  if (parentNode?.type === 'JSXElement' || parentNode?.type === 'JSXFragment') {
+    return (parentNode.children || []).some((c) => c !== elPath.node && isLabelTag(c));
+  }
+  return false;
+}
+
+/**
+ * The <label> pairing is what distinguishes a real form field from an
+ * inline filter/search box glued into custom logic — an <input> with no
+ * label anywhere nearby is left alone rather than guessed as a TextInput
+ * candidate. A dynamic `type` expression is never guessed at; the input is
+ * simply skipped, same "don't guess" discipline every other adopt/ resolver
+ * follows for a non-literal attribute value.
+ */
+function matchTextInput(elPath) {
+  const opening = elPath.node.openingElement;
+  if (nativeTagName(opening.name) !== 'input') return null;
+
+  const typeAttr = getAttr(opening, 'type');
+  let type = 'text'; // HTML's own default when the attribute is omitted
+  if (typeAttr) {
+    const r = resolveJsxLiteral(typeAttr.value);
+    if (!r.resolved || typeof r.value !== 'string') return null;
+    type = r.value;
+  }
+  if (!TEXT_INPUT_TYPES.has(type)) return null;
+  if (!pairedWithLabel(elPath)) return null;
+  return { confidence: 'high', detail: `native <input type="${type}"> paired with a <label>` };
+}
+
+// ───────────────────────────── Toolbar signature ─────────────────────────────
+
+const TOOLBAR_CLASSNAME_RE = /\bflex\b|\brow\b/i;
+
+function isFlexRowContainer(opening) {
+  if (classNameMatches(opening, TOOLBAR_CLASSNAME_RE)) return true;
+  const attr = getAttr(opening, 'style');
+  if (!attr || attr.value?.type !== 'JSXExpressionContainer') return false;
+  const expr = attr.value.expression;
+  if (expr.type !== 'ObjectExpression') return false;
+  let display = null;
+  let direction = null;
+  for (const p of expr.properties) {
+    if (p.type !== 'ObjectProperty' || p.computed) continue;
+    const key = p.key.type === 'Identifier' ? p.key.name : p.key.type === 'StringLiteral' ? p.key.value : null;
+    if (key === 'display') { const r = resolveJsxLiteral(p.value); if (r.resolved) display = r.value; }
+    if (key === 'flexDirection') { const r = resolveJsxLiteral(p.value); if (r.resolved) direction = r.value; }
+  }
+  if (typeof display !== 'string' || !/flex/i.test(display)) return false;
+  return direction !== 'column' && direction !== 'column-reverse';
+}
+
+/**
+ * High confidence: an explicit `role="toolbar"` — a repo already telling
+ * assistive tech what this is, just not using the component that does the
+ * same thing with tokens. Medium confidence: no such declaration exists, so
+ * this falls back to a structural guess — a flex/row container whose ONLY
+ * significant children are native <button>s (never a mixed container that
+ * merely happens to hold two buttons among other content, which would fire
+ * constantly on things like a card footer or a data table row and isn't
+ * what this signature means to catch). Deliberately does not attempt to
+ * judge "top of a component tree" positioning — that needs whole-component
+ * structural analysis this per-element matcher doesn't have; a known,
+ * accepted source of over-eagerness on the medium tier, not a bug.
+ */
+function matchToolbar(elPath) {
+  const opening = elPath.node.openingElement;
+  const tag = nativeTagName(opening.name);
+  if (!tag) return null;
+
+  const roleAttr = getAttr(opening, 'role');
+  if (roleAttr) {
+    const r = resolveJsxLiteral(roleAttr.value);
+    if (r.resolved && r.value === 'toolbar') {
+      return { confidence: 'high', detail: `<${tag} role="toolbar">` };
+    }
+  }
+
+  if (!isFlexRowContainer(opening)) return null;
+  const sig = significantJsxChildren(elPath.node.children);
+  if (sig.length < 2) return null;
+  const allButtons = sig.every((c) => c.type === 'JSXElement' && nativeTagName(c.openingElement.name) === 'button');
+  if (!allButtons) return null;
+  return { confidence: 'medium', detail: `<${tag}> flex/row container with ${sig.length} sibling <button> children` };
+}
+
+// ───────────────────────────── assembly ─────────────────────────────
+
+/**
+ * Explicit and auditable, not inferred from layoutSchema/prop-mapping —
+ * those describe Stark's own API surface, not what generic hand-rolled HTML
+ * maps to it. Deliberately 3 starter components, not an attempt at the full
+ * catalog (ADOPTION_APP_PLAN.md R3 dimension 1's scoping plan) — expand only
+ * once a live run proves the false-positive rate low.
+ */
+const OPPORTUNITY_SIGNATURES = [
+  { component: 'Button', match: matchButton },
+  { component: 'TextInput', match: matchTextInput },
+  { component: 'Toolbar', match: matchToolbar },
+];
+
+/**
+ * Scans a repo for hand-rolled UI patterns that resemble a Stark catalog
+ * component, whether or not the repo has adopted Stark at all. This closes
+ * R3 dimension 1 (ADOPTION_APP_PLAN.md / project_usage_rules_adapter_r3):
+ * every other adopt/ resolver, checkComponentRules included, only has
+ * something to say about a repo that already imports @starklab/stk* — a
+ * 0%-adoption repo produces a scan with zero findings from any of them, not
+ * "here's what you're missing." This resolver is additive, not a
+ * replacement for those: it targets the population they can't see.
+ *
+ * Every existing resolver detects a *fact* with zero judgment calls; "this
+ * raw JSX could become a Button" is inherently a heuristic, so it runs
+ * under a different discipline than the rest of adopt/ — a small number of
+ * narrow, named, auditable structural signatures (OPPORTUNITY_SIGNATURES),
+ * never fuzzy/statistical scoring. Every finding carries `confidence`
+ * ('high'|'medium', a suggestion strength) separately from `severity`,
+ * which is always 'Info' — an opportunity is not a defect and must never
+ * read as a CI-gate failure, the same instinct behind vecnaVerifier.js's
+ * `vacuousByConstruction` labeling.
+ *
+ * Output is keyed "opportunities", deliberately the same word
+ * targetDiscovery.js's discoverTargets() already uses for a different,
+ * package-granularity idea (an out-of-scope workspace target that still
+ * renders UI). The two can appear side by side under `adopt --all-targets`:
+ * that one flags whole excluded packages worth bringing into scope; this
+ * one flags individual JSX patterns worth swapping for a catalog component,
+ * inside any package regardless of scope. Same word, two granularities —
+ * intentional, not a naming collision, since they never occupy the same key
+ * (targetDiscovery's lives at the top level; this resolver's is nested
+ * under "opportunities" inside each target's own adopt result).
+ *
+ * Web and native — 'web' uses OPPORTUNITY_SIGNATURES (DOM/JSX-shape
+ * assumptions: role="toolbar", style.display, native <input>/<button>);
+ * 'native' uses OPPORTUNITY_SIGNATURES_NATIVE (RN-shape assumptions:
+ * Pressable/TouchableOpacity + onPress + StyleSheet-object styling — see
+ * opportunitySignaturesNative.js). Any other platform value throws, same
+ * "never guess" discipline as every other resolver's unsupported-input case.
+ * JSX-only like every other resolver here: a repo whose markup lives in
+ * .astro/.vue/.svelte files produces zero opportunities, not a false "clean"
+ * signal — same unresolvedFiles/parseError reporting as usageRulesResolver.js,
+ * so a caller can see what wasn't actually scanned.
+ */
+export function resolveOpportunities(root, { platform = 'web', ignore = [] } = {}) {
+  const signatures = platform === 'web'
+    ? OPPORTUNITY_SIGNATURES
+    : platform === 'native'
+      ? OPPORTUNITY_SIGNATURES_NATIVE
+      : null;
+  if (!signatures) {
+    throw new Error(`resolveOpportunities only supports platform "web" or "native" (got "${platform}").`);
+  }
+
+  const moduleGraph = buildModuleGraph(root, { ignore });
+  const opportunities = [];
+  const unresolvedFiles = [];
+  let filesWithOpportunities = 0;
+
+  for (const file of moduleGraph.files) {
+    const entry = moduleGraph.graph.get(file);
+    if (!entry) continue;
+    if (entry.parseError) {
+      unresolvedFiles.push(path.relative(root, file));
+      continue;
+    }
+
+    const relFile = path.relative(root, file);
+    const fileFindings = [];
+
+    traverse(entry.ast, {
+      JSXElement(elPath) {
+        for (const sig of signatures) {
+          const result = sig.match(elPath);
+          if (!result) continue;
+          fileFindings.push({
+            component: sig.component,
+            confidence: result.confidence,
+            severity: 'Info',
+            detail: result.detail,
+            file: relFile,
+            line: elPath.node.loc?.start.line ?? null,
+          });
+        }
+      },
+    });
+
+    if (fileFindings.length > 0) {
+      filesWithOpportunities += 1;
+      opportunities.push(...fileFindings);
+    }
+  }
+
+  return {
+    platform,
+    root,
+    scannedFiles: moduleGraph.files.length,
+    filesWithOpportunities,
+    unresolvedFiles,
+    opportunities,
+  };
+}

package/src/adopt/opportunitySignaturesNative.js

@@ -0,0 +1,47 @@
+import {
+  getAttr,
+  componentTagName,
+  styleTouchesKeys,
+  styleReferencesStylesheetMember,
+} from './jsxOpportunityHelpers.js';
+
+// ───────────────────────────── Button signature (RN) ─────────────────────────────
+
+const BUTTON_STYLE_KEY_RE = /^(background|border|padding)/i;
+const BUTTON_TAGS = new Set(['Pressable', 'TouchableOpacity', 'TouchableHighlight', 'TouchableWithoutFeedback']);
+
+/**
+ * RN counterpart of opportunityResolver.js's matchButton: a hand-rolled
+ * pressable primitive (Pressable/TouchableOpacity/TouchableHighlight/
+ * TouchableWithoutFeedback) with an onPress handler, styled via either an
+ * inline style={{...}} touching background/border/padding keys or a
+ * StyleSheet-object reference (styles.foo / [styles.foo, cond && styles.bar])
+ * — RN's equivalent of a static className, since RN has no CSS classes.
+ * Same "onPress alone isn't enough" discipline as the web signature: a bare
+ * pressable with no visual styling is often fine as-is (a no-op test target,
+ * a transparent hit-area wrapper), so styling is required too.
+ */
+function matchButton(elPath) {
+  const opening = elPath.node.openingElement;
+  const tag = componentTagName(opening.name);
+  if (!tag || !BUTTON_TAGS.has(tag)) return null;
+  if (!getAttr(opening, 'onPress')) return null;
+  const styled = styleTouchesKeys(opening, BUTTON_STYLE_KEY_RE) || styleReferencesStylesheetMember(opening);
+  if (!styled) return null;
+  return { confidence: 'high', detail: `<${tag}> with onPress and visual styling (style/StyleSheet reference)` };
+}
+
+// ───────────────────────────── assembly ─────────────────────────────
+
+/**
+ * RN twin of opportunityResolver.js's OPPORTUNITY_SIGNATURES — a single
+ * starter signature (Button), per ADOPTION_APP_PLAN.md §10 decision #25
+ * Phase 2's "expand only after a live run proves the false-positive rate
+ * low" precedent, the same discipline the web table's own R3 dimension-1
+ * scoping already established. Lives in its own file (not inline in
+ * opportunityResolver.js) to avoid a circular import — see
+ * jsxOpportunityHelpers.js's header comment.
+ */
+export const OPPORTUNITY_SIGNATURES_NATIVE = [
+  { component: 'Button', match: matchButton },
+];