@starklab/stark-mcp 0.2.0 → 0.3.0

package/src/adopt/moduleGraph.js

@@ -128,9 +128,20 @@ export function buildModuleGraph(root, { ignore = [] } = {}) {
       } else if (node.type === 'ExportNamedDeclaration') {
         if (node.source) {
           for (const spec of node.specifiers) {
-            const localName = spec.local.name;
             const exportedName = spec.exported.type === 'Identifier' ? spec.exported.name : spec.exported.value;
-            reexports.set(exportedName, { source: node.source.value, imported: localName });
+            // `export * as ns from './m'` parses as an ExportNamedDeclaration
+            // whose specifier is an ExportNamespaceSpecifier — which carries
+            // only `exported`, no `local`. Reading spec.local.name threw
+            // TypeError here and, because buildModuleGraph is shared, took
+            // down every scan of the whole repo: one such line in
+            // openstatusHQ/openstatus (packages/db/src/index.ts:1) crashed
+            // `scan-foreign` across all 45 of its workspace packages.
+            if (spec.type === 'ExportNamespaceSpecifier') {
+              reexports.set(exportedName, { source: node.source.value, imported: '*' });
+              continue;
+            }
+            if (!spec.local) continue;
+            reexports.set(exportedName, { source: node.source.value, imported: spec.local.name });
           }
         } else if (node.specifiers?.length) {
           // export { X, Y as Z }; — forwarding a local binding. Only meaningful
@@ -155,6 +166,37 @@ export function buildModuleGraph(root, { ignore = [] } = {}) {
   return { root, files, graph };
 }
 
+/**
+ * The package a bare specifier belongs to, with any subpath removed:
+ * `@starklab/stk-components/Button` and `@starklab/stk-components` both
+ * answer `@starklab/stk-components`, and `lodash/merge` answers `lodash`.
+ *
+ * Every resolver that asks "did this import come from the design system?"
+ * compares an origin's `pkg` against packageNameForPlatform()'s bare name,
+ * but `resolveOrigin` reports the specifier as written — so a subpath import
+ * matched nothing and the file was silently skipped. That is not a rare
+ * style: this repo writes 124 of them, and every one of apps/portfolio's
+ * imports is one, which is why a scan of it reported 0/69 components adopted
+ * for a site that renders Button on nearly every page.
+ *
+ * installedPackageScoringResolver.js already met this on the foreign side —
+ * see componentNameFromOrigin(), and the 0/149 coverage its header records —
+ * so this is that fix generalized, not a new idea. It deliberately only
+ * normalizes the package half: the imported *name* still has to be a real
+ * named export, because Stark's subpaths export named symbols and inferring
+ * a component from the subpath would be a guess where the repo has a fact.
+ *
+ * Relative specifiers are not package imports and answer null, so a caller
+ * can hand this any source string without pre-checking.
+ */
+export function packageOfSpecifier(source) {
+  if (typeof source !== 'string' || !source || source.startsWith('.') || source.startsWith('/')) {
+    return null;
+  }
+  const parts = source.split('/');
+  return source.startsWith('@') ? parts.slice(0, 2).join('/') : parts[0];
+}
+
 /**
  * Resolves `name` back to its ultimate origin, following relative-import and
  * re-export hops within the target repo only (never into node_modules).

package/src/adopt/prCheckReport.js

@@ -0,0 +1,274 @@
+import { normalizeSeverity } from './adoptGate.js';
+import { scrubForeignScanPaths } from './foreignScanReport.js';
+
+/**
+ * The reporting half of `stark-cli adopt --pr-check`: turns a `runAdopt`
+ * result into the payload Dominion's POST /api/pr-check accepts, and sends it.
+ *
+ * This is the third sibling of adoptScanReport.js and foreignScanReport.js and
+ * inherits their first governing constraint verbatim — **it must never break
+ * the consumer's CI**: every failure path returns `{ reported: false, reason }`,
+ * nothing throws, and the caller never touches `process.exitCode`. The route
+ * on the other end decides whether the *pull request* goes red; a reporter
+ * fault must not.
+ *
+ * It inherits their second constraint too, and for a sharper reason than
+ * privacy. Those two scrub the absolute scan root out of a whole document
+ * before sending it; this one sends a list of `{ rule, location, severity }`
+ * rows rather than the document, but it scrubs the same way and with the same
+ * function, because `location` is half of the identity the route matches on.
+ *
+ * That was the bug this file shipped with. A resolver reports `file` as an
+ * absolute path — `/home/runner/work/Starklab/Starklab/packages/...` on CI,
+ * `/Users/<someone>/...` on a laptop — and the header here claimed it was
+ * already target-relative, so nothing scrubbed it. The full-scan half did
+ * scrub, storing `<root>/src/Avatar/Avatar.jsx`, so the two halves compared
+ * two spellings of the same file and agreed on nothing: on a 222-finding
+ * scan the check reported 222 new and 222 fixed, every push, forever. Equal
+ * counts are the signature — one set of findings counted twice under two
+ * identities.
+ *
+ * So the scrub is not tidiness here, it is the wire's correctness, and it is
+ * `scrubForeignScanPaths` rather than a local `startsWith(root)` for the same
+ * reason the fingerprint is `findingFingerprint`: the two halves agree because
+ * they run the same code, not because two implementations were written to
+ * match. `root` is therefore required by `reportPrCheck` — without it the
+ * locations are unscrubbed and the check is confidently wrong, which is worse
+ * than the honest `{ reported: false }` a missing field produces.
+ *
+ * ## Why this is a translation and not a forward
+ *
+ * The route wants one shape. `runAdopt` produces several, because each resolver
+ * grew its own:
+ *
+ *   tokenAliases / tailwind / propApi / rnTokenAliases / rnTailwind
+ *       { rule, severity, file, line, property | component + prop, … }
+ *       — the common shape, and the only one Dominion stores
+ *   usageRules
+ *       { severity: 'Info', finding, violated, owner, fix, file }
+ *       — no `rule`, no `line`, and a capitalized severity
+ *   a11y
+ *       { rule, file: <a page URL>, selector, severity }
+ *       — `file` is a URL standing in for a path (a11yPass.js says so)
+ *
+ * Two of those cannot be forwarded as-is, and the failure would not be loud:
+ * the route builds a GitHub annotation by splitting `location` on `:` and
+ * prefixing the target dir, so an a11y finding would post an annotation on the
+ * path `<dir>/http` and a capitalized `Info` would miss the severity map. The
+ * second is harmless (it falls through to `notice`); the first is a wrong
+ * annotation on a file that does not exist, which is worse than no annotation.
+ *
+ * ## Why the subject fields travel, and why `violated` does not
+ *
+ * The route answers one question — is this finding *new on this commit* — by
+ * matching what we send against what the last full scan stored. A finding it
+ * cannot match reads as new every time, so agreeing with the store is not a
+ * detail here, it is the whole value of the check.
+ *
+ * Two consequences, and both are why this file changed after the wire first
+ * ran against production:
+ *
+ *   The store's identity is `rule:file[:line]:subject`, where the subject is
+ *   the custom property, or `Component.prop`, that separates two findings of
+ *   one rule on one line. So `property`, `component` and `prop` are forwarded
+ *   verbatim — not because the route reads them, but because it rebuilds that
+ *   subject from them (apps/dominion/lib/prCheckDiff.ts).
+ *
+ *   `usageRules` is not a section Dominion stores at all, so its findings can
+ *   never match anything and would be reported as new on every pull request
+ *   forever. They are counted as unsendable rather than sent — an honest gap
+ *   beats permanent noise. Bringing them back is a change to what the scan
+ *   ingests, not to what this reporter sends.
+ *
+ * ## Why the walk is generic
+ *
+ * `collectPrCheckFindings` recurses for any array under a `findings` key rather
+ * than reading a fixed list of resolver names. A hard-coded list is a thing to
+ * forget: the next resolver that reports findings would be silently absent from
+ * every pull request check, and nothing would say so. The generic walk means a
+ * new resolver is included the day it lands, and the shape rules below decide
+ * whether its findings can be placed in a file — the only question that matters
+ * here.
+ *
+ * ## What is dropped, and why nothing is dropped silently
+ *
+ * A finding reaches the route only if it can name a rule and a source location.
+ * Everything else is counted into `skipped` and reported to stderr by the CLI,
+ * because a finding that quietly does not travel is the exact failure this file
+ * exists to prevent:
+ *
+ *   noRule      — no `rule`. That is every `usageRules` finding (it names a
+ *                 `violated` pattern instead) and nothing else. The rule name
+ *                 is half the stored identity, so a finding without one could
+ *                 never be recognised again and never resolve as "fixed".
+ *   noFile      — the resolver reported a property or a component but no file
+ *                 (several token findings are like this). There is no line to
+ *                 annotate.
+ *   notInFile   — `file` contains a `:`. That is either a URL (every a11y
+ *                 finding) or an absolute Windows-style path, and both break
+ *                 the route's `location.split(':')`. One rule covers both; it
+ *                 is the reason a11y needs no special case. The test runs
+ *                 after the scrub, so a Windows root that became `<root>` is
+ *                 no longer caught by it — which is correct: it is a path the
+ *                 route can now split.
+ *
+ * Duplicates are folded before sending: two findings with the same rule and
+ * location are one fingerprint to the route, and sending both would post the
+ * same annotation twice.
+ */
+
+/** A location the route can split back into a file and a line. */
+function locationFor(finding) {
+  const file = typeof finding.file === 'string' ? finding.file.trim() : '';
+  if (!file) return { ok: false, why: 'noFile' };
+  if (file.includes(':')) return { ok: false, why: 'notInFile' };
+  const line = Number(finding.line);
+  return { ok: true, location: Number.isInteger(line) && line > 0 ? `${file}:${line}` : file };
+}
+
+/** The rule name the fingerprint is built on. */
+function ruleFor(finding) {
+  return typeof finding.rule === 'string' && finding.rule.trim() ? finding.rule.trim() : null;
+}
+
+/**
+ * The fields the route needs to rebuild the stored subject, and nothing else —
+ * a payload key the route does not read is a key it could one day read wrong.
+ */
+function subjectFor(finding) {
+  const subject = {};
+  for (const key of ['property', 'component', 'prop']) {
+    const value = finding[key];
+    if (typeof value === 'string' && value.trim()) subject[key] = value.trim();
+  }
+  return subject;
+}
+
+/**
+ * Walks a `runAdopt` result and returns every finding the route can place,
+ * plus a count of the ones it cannot.
+ *
+ * Exported for its own tests and because the CLI prints the skip counts.
+ */
+export function collectPrCheckFindings(result) {
+  const findings = [];
+  const seen = new Set();
+  const skipped = { noRule: 0, noFile: 0, notInFile: 0 };
+
+  const visit = (value, key) => {
+    if (Array.isArray(value)) {
+      if (key === 'findings') {
+        for (const f of value) {
+          if (!f || typeof f !== 'object') continue;
+
+          const rule = ruleFor(f);
+          if (!rule) {
+            skipped.noRule += 1;
+            continue;
+          }
+
+          const where = locationFor(f);
+          if (!where.ok) {
+            skipped[where.why] += 1;
+            continue;
+          }
+
+          // The route's own severity map is lowercase; `Info` is a live
+          // spelling. An unrecognized one becomes `info` rather than being
+          // dropped — a finding with an odd severity is still a finding, and
+          // `info` is the bucket that cannot fail a check on its own.
+          const severity = normalizeSeverity(f.severity) ?? 'info';
+
+          const subject = subjectFor(f);
+
+          // The subject is part of what makes two findings different, so it is
+          // part of what makes two of them the same: without it, two hardcoded
+          // properties in one declaration block fold into one annotation.
+          const fingerprint = JSON.stringify([rule, where.location, subject]);
+          if (seen.has(fingerprint)) continue;
+          seen.add(fingerprint);
+
+          findings.push({ rule, location: where.location, severity, ...subject });
+        }
+        return;
+      }
+      for (const child of value) visit(child, key);
+      return;
+    }
+    if (value && typeof value === 'object') {
+      for (const [childKey, child] of Object.entries(value)) visit(child, childKey);
+    }
+  };
+
+  visit(result, null);
+  return { findings, skipped };
+}
+
+/**
+ * Builds the request body POST /api/pr-check expects.
+ *
+ * `root` is the directory the scan ran against, and the scrub that uses it is
+ * what makes a location here the same string the full scan stored — see this
+ * file's header for what happens when it is missing.
+ */
+export function buildPrCheckReport(result, { targetDir, commitSha, root }) {
+  const { findings, skipped } = collectPrCheckFindings(scrubForeignScanPaths(result, root));
+  return { body: { targetDir, commitSha, findings }, skipped };
+}
+
+/**
+ * POSTs the findings and resolves to an outcome record. Never throws, never
+ * rejects — see this file's header.
+ *
+ * `fetchImpl` exists for tests; production always uses global fetch.
+ */
+export async function reportPrCheck(result, {
+  url,
+  token,
+  root,
+  targetDir,
+  commitSha,
+  timeoutMs = 15000,
+  fetchImpl = globalThis.fetch,
+} = {}) {
+  const missing = Object.entries({ url, token, root, targetDir, commitSha })
+    .filter(([, v]) => !v)
+    .map(([k]) => k);
+  if (missing.length > 0) {
+    return { reported: false, reason: `Missing required reporting field(s): ${missing.join(', ')}.` };
+  }
+
+  const { body, skipped } = buildPrCheckReport(result, { targetDir, commitSha, root });
+
+  let response;
+  try {
+    response = await fetchImpl(url, {
+      method: 'POST',
+      headers: {
+        'content-type': 'application/json',
+        authorization: `Bearer ${token}`,
+      },
+      body: JSON.stringify(body),
+      signal: AbortSignal.timeout(timeoutMs),
+    });
+  } catch (err) {
+    // Network down, DNS failure, TLS error, timeout. The scan itself already
+    // succeeded and has already been printed.
+    return { reported: false, reason: `Could not reach ${url}: ${err.message}`, skipped };
+  }
+
+  const text = await response.text().catch(() => '');
+  let parsed = null;
+  try {
+    parsed = text ? JSON.parse(text) : null;
+  } catch {
+    // A proxy or error page rather than the API. Surfaced as-is below.
+  }
+
+  if (!response.ok) {
+    const detail = parsed?.error ?? (text ? text.slice(0, 200) : '(empty response)');
+    return { reported: false, status: response.status, reason: `${url} returned ${response.status}: ${detail}`, skipped };
+  }
+
+  return { reported: true, status: response.status, response: parsed, sent: body.findings.length, skipped };
+}

package/src/adopt/propApiResolver.js

@@ -3,7 +3,7 @@ import path from 'node:path';
 import traverseModule from '@babel/traverse';
 
 import { loadCatalog, packageNameForPlatform } from './catalog.js';
-import { buildModuleGraph, resolveOrigin } from './moduleGraph.js';
+import { buildModuleGraph, packageOfSpecifier, resolveOrigin } from './moduleGraph.js';
 import { getComponentProps } from '../data.js';
 
 const traverse = traverseModule.default ?? traverseModule;
@@ -228,7 +228,7 @@ export function resolvePropApi(root, { platform = 'web', ignore = [] } = {}) {
     const localToComponent = new Map();
     for (const localName of entry.imports.keys()) {
       const origin = resolveOrigin(moduleGraph, file, localName);
-      if (origin?.pkg === pkgName && byName.has(origin.name)) {
+      if (packageOfSpecifier(origin?.pkg) === pkgName && byName.has(origin.name)) {
         localToComponent.set(localName, origin.name);
       }
     }

package/src/adopt/referenceResolver.js

@@ -3,7 +3,7 @@ import path from 'node:path';
 import traverseModule from '@babel/traverse';
 
 import { loadCatalog, packageNameForPlatform } from './catalog.js';
-import { buildModuleGraph, resolveOrigin } from './moduleGraph.js';
+import { buildModuleGraph, packageOfSpecifier, resolveOrigin } from './moduleGraph.js';
 
 const traverse = traverseModule.default ?? traverseModule;
 
@@ -106,7 +106,7 @@ export function resolveReferences(root, { platform = 'web', ignore = [] } = {})
     const localToComponent = new Map();
     for (const localName of entry.imports.keys()) {
       const origin = resolveOrigin(moduleGraph, file, localName);
-      if (origin?.pkg === pkgName && byName.has(origin.name)) {
+      if (packageOfSpecifier(origin?.pkg) === pkgName && byName.has(origin.name)) {
         localToComponent.set(localName, origin.name);
       }
     }

package/src/adopt/scanRollup.js

@@ -0,0 +1,192 @@
+/**
+ * The rollup: bounded, deterministic per-`(component, prop, value)` and
+ * per-`(component, file)` counts, folded out of the enumerations that
+ * adoptScanReport.js's `DROPPED_KEYS` throws away before reporting.
+ *
+ * ## Why this exists
+ *
+ * `DROPPED_KEYS` is right about the enumerations and wrong about the
+ * aggregate. `checks` (one row per validated JSX attribute) and `sites` (one
+ * row per component reference) genuinely are most of the payload on a real
+ * repo, and they genuinely are re-derivable by re-scanning — so dropping them
+ * is correct. But the consequence was that nothing below the three-number
+ * `report` summaries ever reached Dominion, and a question like "which
+ * `variant` values does this org actually use, across repos?" had no data to
+ * answer from even though the scanner had computed it and thrown it away.
+ *
+ * The asymmetry that makes this worth doing before customers rather than
+ * after: a new *query* over grain that is already stored is free and works on
+ * the whole history; a new *rollup* costs a migration but is recovered by
+ * re-scanning; teaching the scanner to compute something it never computed is
+ * **not retroactive at all** — there is no backfill of a repo's past, and a
+ * six-month trend cannot be fabricated later.
+ *
+ * ## What it is not
+ *
+ * It is derived, never authoritative. Every number here is a fold of rows the
+ * same scan produced, so it can always be rebuilt by re-scanning the same
+ * commit, and it never carries a fact no resolver established. It is computed
+ * in `runAdopt` — i.e. *before* `stripAdoptDetail` runs — precisely because
+ * its inputs do not survive that strip.
+ *
+ * ## Limits, which are the resolvers' limits and must not be overstated
+ *
+ * `props` is not a census of prop usage. `evaluateCallSite` emits a check row
+ * only for `enum` props and for `required` props, so a string or boolean the
+ * mapping file does not track leaves no trace here either; and `required` is
+ * not authored into any real mapping file yet, so that rule contributes
+ * nothing against real data today. "Prop usage" currently means *enum-value
+ * usage*, which is less than the phrase suggests.
+ *
+ * `props` is null — not empty — on the native platform, because
+ * `resolvePropApi` does not run there at all (`prop-mapping/` has no `rn/`
+ * subdirectory). Null means "not measured"; an empty row list means "measured,
+ * found nothing". Collapsing the two is the failure mode the resolvers'
+ * `unresolvedReason` machinery exists to prevent, so it is not done here.
+ */
+
+export const ROLLUP_SCHEMA_VERSION = 1;
+
+/**
+ * Per-section row cap. The rollup exists to be bounded — an unbounded fold is
+ * the enumeration again with extra steps — so it truncates rather than growing
+ * with the repo, and says so when it does.
+ *
+ * Cardinality in practice is lopsided: `props` is bounded by the catalog's own
+ * enum surface (components × enum props × declared values) plus whatever
+ * invalid values a repo invents, so it lands in the hundreds. `files` is
+ * bounded by files × components-per-file, and is the one that can actually
+ * reach the cap on a large monorepo.
+ */
+export const MAX_ROLLUP_ROWS = 5000;
+
+/** Invalid enum values come from the consumer's source and are arbitrary text. */
+const MAX_VALUE_LENGTH = 80;
+
+/**
+ * Deliberately not a printable character. Component names, prop names, file
+ * paths and arbitrary invalid enum values all share this key space; any
+ * printable separator that one of them could itself contain would let two
+ * different tuples collapse into the same group.
+ */
+const KEY_SEP = '\u0000';
+
+const KINDS = ['jsx', 'createElement', 'hoc', 'indirect', 'reexport'];
+
+/**
+ * `reexport` is deliberately excluded, matching KIND_CONFIDENCE's
+ * 'not-a-usage' and lib/adoptionScan.ts's `usageCount`: forwarding a binding
+ * through `export { Button }` is not a render.
+ */
+const USAGE_KINDS = new Set(['jsx', 'createElement', 'hoc', 'indirect']);
+
+function normalizeValue(value) {
+  if (value === undefined || value === null) return null;
+  const text = String(value);
+  return text.length > MAX_VALUE_LENGTH ? `${text.slice(0, MAX_VALUE_LENGTH)}…` : text;
+}
+
+/**
+ * Sorts by weight descending, then by the row's own key ascending, and caps.
+ *
+ * The tie-break on the key is what makes this reproducible: two scans of the
+ * same commit must produce identical rollups, and Map iteration order follows
+ * insertion, which follows file-walk order. `distinct` is reported before the
+ * cap, so a truncated rollup reads as truncated instead of as a small repo.
+ */
+function finalize(rows, weightOf, keyOf, sources) {
+  const distinct = rows.length;
+  rows.sort((a, b) => {
+    const byWeight = weightOf(b) - weightOf(a);
+    if (byWeight !== 0) return byWeight;
+    const ka = keyOf(a);
+    const kb = keyOf(b);
+    return ka < kb ? -1 : ka > kb ? 1 : 0;
+  });
+  return {
+    rows: distinct > MAX_ROLLUP_ROWS ? rows.slice(0, MAX_ROLLUP_ROWS) : rows,
+    distinct,
+    truncated: distinct > MAX_ROLLUP_ROWS,
+    sources,
+  };
+}
+
+/** Folds propApiResolver's `checks` into (component, prop, rule, classification, value) counts. */
+export function rollupProps(propApi) {
+  if (!propApi || !Array.isArray(propApi.checks)) return null;
+
+  const keyFor = (row) =>
+    [row.component, row.prop, row.rule, row.classification, row.value ?? ''].join(KEY_SEP);
+
+  const groups = new Map();
+  for (const check of propApi.checks) {
+    const row = {
+      component: check.component,
+      prop: check.prop,
+      rule: check.rule,
+      classification: check.classification,
+      value: normalizeValue(check.value),
+      count: 1,
+    };
+    const key = keyFor(row);
+    const existing = groups.get(key);
+    if (existing) existing.count += 1;
+    else groups.set(key, row);
+  }
+
+  return finalize([...groups.values()], (r) => r.count, keyFor, propApi.checks.length);
+}
+
+/**
+ * Folds referenceResolver's per-component `sites` into (component, file)
+ * counts, keeping the five reference kinds apart.
+ *
+ * The kind split is carried rather than summed because the kinds are not
+ * interchangeable evidence: a `jsx` reference is `certain`, an `indirect` one
+ * is `needs-review` (KIND_CONFIDENCE). Folding them into one number would make
+ * a file of ambiguous references indistinguishable from a file of confirmed
+ * renders — the same conflation `zeroUsage` avoids upstream. `refs` is the
+ * usage subtotal, and exists so the common question does not have to re-derive
+ * which kinds count.
+ */
+export function rollupFiles(components) {
+  if (!Array.isArray(components)) return null;
+
+  const keyFor = (row) => [row.component, row.file].join(KEY_SEP);
+
+  const groups = new Map();
+  let sources = 0;
+  for (const component of components) {
+    if (!Array.isArray(component?.sites)) continue;
+    for (const site of component.sites) {
+      sources += 1;
+      const row = { component: component.name, file: site.file, refs: 0 };
+      const key = keyFor(row);
+      let group = groups.get(key);
+      if (!group) {
+        for (const kind of KINDS) row[kind] = 0;
+        group = row;
+        groups.set(key, group);
+      }
+      if (KINDS.includes(site.kind)) group[site.kind] += 1;
+      if (USAGE_KINDS.has(site.kind)) group.refs += 1;
+    }
+  }
+
+  return finalize([...groups.values()], (r) => r.refs, keyFor, sources);
+}
+
+/**
+ * Builds the whole rollup from a composed `runAdopt` result.
+ *
+ * Takes the composed result rather than the individual resolvers so there is
+ * exactly one place that knows which resolver each section folds, and so a
+ * resolver that did not run stays null instead of silently becoming zero.
+ */
+export function buildScanRollup(result) {
+  return {
+    schema: ROLLUP_SCHEMA_VERSION,
+    props: rollupProps(result?.propApi),
+    files: rollupFiles(result?.components),
+  };
+}

package/src/adopt/tailwindResolver.js

@@ -313,6 +313,9 @@ function classifyThemeProperties(propGraph, themeEntryNames, inventory, layers)
     if (state === 'broken') {
       findings.push({ rule: 'broken-alias', severity: 'critical', property: name, reason: terminal.kind });
     }
+    if (state === 'unresolved') {
+      findings.push({ rule: 'unresolved-alias', severity: 'info', property: name, reason: 'terminal-not-in-scanned-css' });
+    }
     if (terminal.rawFallbackPresent) {
       findings.push({ rule: 'raw-fallback', severity: 'info', property: name });
     }
@@ -373,7 +376,9 @@ function classifyClassNameUsage(cls, propGraph, themeEntryNames, inventory, laye
         : { classification: 'broken', reason: 'undefined-stk-token' };
     }
     const bySelector = propGraph.get(name);
-    if (!bySelector) return { classification: 'broken', reason: 'undefined-property' };
+    // 'unresolved', not 'broken' — the definition may be @import'ed from a
+    // sibling package or injected at runtime; see classifyTerminalState.
+    if (!bySelector) return { classification: 'unresolved', reason: 'undefined-property' };
     const bound = bySelector.has(':root') ? ':root' : [...bySelector.keys()][0];
     const terminal = resolveTerminal(propGraph, name, bound, inventory, layers, new Set(), 0);
     const state = classifyTerminalState(terminal.kind);

package/src/adopt/targetDiscovery.js

@@ -6,6 +6,7 @@ import fg from 'fast-glob';
 const STK_PREFIX = '@starklab/stk';
 const UI_FRAMEWORK_DEPS = ['react', 'react-dom', 'react-native', 'expo', 'preact', 'vue', 'svelte'];
 const DEFAULT_IGNORE = ['**/node_modules/**', '**/dist/**', '**/build/**', '**/.next/**', '**/coverage/**'];
+const UI_SOURCE_GLOBS = ['**/*.tsx', '**/*.jsx', '**/*.vue', '**/*.svelte'];
 
 function readJson(file) {
   try {
@@ -120,6 +121,32 @@ function hasUiFrameworkDep(pkg) {
   return UI_FRAMEWORK_DEPS.some((d) => deps.has(d));
 }
 
+/**
+ * Second half of the `rendersUi` signal, and the reason it isn't a
+ * package.json read alone: a declared React dependency is evidence of
+ * *linking against* a UI framework, not of *containing* UI. Measured live
+ * against openstatusHQ/openstatus (45 workspace targets, none Stark-
+ * dependent): the dependency check alone produced 9 opportunity rows, of
+ * which 2 held no markup at all — `packages/api` (71 source files, zero
+ * JSX; it depends on react only to render @openstatus/emails templates
+ * server-side) and `packages/notifications/email` (5 files, zero JSX,
+ * react-dom for the same reason). Both are backend packages, i.e. exactly
+ * the rows an opportunity list must not carry, since its stated job is
+ * naming what to bring into scope next. A markup-file glob removes both
+ * and keeps all 7 true positives; no target in that repo has JSX without
+ * also declaring the framework, so requiring both signals cost no recall.
+ *
+ * A file listing, not a parse — the AST oracle used to establish those
+ * numbers agrees with the extension for every one of the 45 targets, and
+ * TypeScript will not compile JSX out of a .ts file anyway.
+ */
+function hasUiSourceFiles(dir) {
+  return (
+    fg.sync(UI_SOURCE_GLOBS, { cwd: dir, ignore: DEFAULT_IGNORE, onlyFiles: true, suppressErrors: true })
+      .length > 0
+  );
+}
+
 /**
  * Discovers every workspace target in a repo and classifies each in/out of
  * scope by direct-or-transitive dependency on @starklab/stk*
@@ -134,8 +161,9 @@ function hasUiFrameworkDep(pkg) {
  * can't be a scan target of its own anyway.
  *
  * A second, independent signal — `rendersUi` — flags whether an excluded
- * target still has a UI framework dependency (React/RN/etc.) despite having
- * no stk* dependency. These are the "opportunity list": excluded rows that
+ * target still contains UI code (a React/RN/etc. dependency *and* at least
+ * one markup source file — see hasUiSourceFiles) despite having no stk*
+ * dependency. These are the "opportunity list": excluded rows that
  * must never read as zeros inside a score, because they're the most
  * valuable rows to bring into scope next.
  */
@@ -176,7 +204,7 @@ export function discoverTargets(root) {
     const isForceIncluded = forceInclude.includes(relPath);
     const forceExcludeReason = forceExclude[relPath];
     const dependsOnStk = transitivelyDependsOnStk(t, new Set());
-    const rendersUi = t.pkg ? hasUiFrameworkDep(t.pkg) : false;
+    const rendersUi = t.pkg ? hasUiFrameworkDep(t.pkg) && hasUiSourceFiles(t.dir) : false;
 
     let inScope;
     let scopeReason;