@starklab/stark-mcp 0.1.0 → 0.2.0

package/src/adopt/foreignScanReport.js

@@ -0,0 +1,210 @@
+import os from 'node:os';
+import { realpathSync } from 'node:fs';
+
+/**
+ * The reporting half of `scan-foreign --report` (ADOPTION_APP_PLAN.md §10
+ * decision #25): turns a scan result into the payload Dominion's
+ * POST /api/foreign-scan accepts, and sends it.
+ *
+ * Two properties matter more than anything else here, and both are about
+ * what this must NOT do:
+ *
+ *  1. **It must never break the consumer's CI.** This runs inside somebody
+ *     else's pipeline, appended to a command whose actual job is printing a
+ *     scan to stdout. A tracker being down, a rotated token, a typo'd URL —
+ *     none of that is a reason to fail their build. Every failure path here
+ *     returns `{ reported: false, reason }`; nothing throws, and the caller
+ *     never touches `process.exitCode`.
+ *  2. **It must not leak the customer's filesystem layout.** The scan is run
+ *     against real absolute paths and several output fields embed them
+ *     verbatim. Reporting is the moment those paths would leave the
+ *     customer's machine and get persisted in someone's database, so the
+ *     scrub belongs here rather than in the resolvers — stdout keeps the real
+ *     paths, which is what a human debugging a local scan actually wants.
+ */
+
+/**
+ * Fields confirmed to carry an absolute path, by inspecting real scan output
+ * from three live fixtures rather than reasoning about the code:
+ *
+ *   discovery.root / propSchema.root / scoring.root   (and per-package copies)
+ *   root                                              (multi-package top level)
+ *   discovery.unresolvedReason                        — the path sits inside prose
+ *   propSchema.sampled[].typeName                     — `import("/abs/path").Foo`
+ *   propSchema.sampled[].props[].type                 — same
+ *
+ * Everything else — `typesEntryFile`, `evidence[].file`, `components[].file`,
+ * `duplicates[].file` — is already repo-relative.
+ *
+ * That spread is why this is a deep walk over every string rather than a
+ * list of known keys: two of the five are free prose and generated type
+ * strings, where a path can appear anywhere in the value and a key-by-key
+ * scrub would quietly miss it the first time a message is reworded.
+ */
+function replacements(root) {
+  const home = os.homedir();
+  let realRoot = null;
+  try {
+    realRoot = realpathSync(root);
+  } catch {
+    // A root that no longer resolves is not a reporting failure — the scan
+    // already ran against it. Fall through with the literal path only.
+  }
+
+  // Longest first: on macOS `realpathSync('/tmp/x')` is `/private/tmp/x`, so
+  // both spellings are live at once and replacing the shorter one first
+  // would leave the `/private` prefix stranded in the output.
+  return [
+    ...new Set([realRoot, root].filter(Boolean)),
+    home,
+  ]
+    .filter(Boolean)
+    .sort((a, b) => b.length - a.length)
+    .map((from) => ({ from, to: from === home ? '<home>' : '<root>' }));
+}
+
+// Anything still absolute after the known prefixes are gone — a hoisted
+// node_modules above the scan root in a monorepo, a global npm cache. Kept
+// deliberately narrow (user-home-shaped paths only) so it can't chew through
+// legitimate content like a URL or a package name.
+const RESIDUAL_ABSOLUTE = /(?:\/(?:Users|home)\/[^/\s"')]+|[A-Za-z]:\\Users\\[^\\\s"')]+)(?:[/\\][^\s"')]*)?/g;
+
+// Absorbs a path prefix left stranded immediately in front of a placeholder.
+// This happens when the payload carries a spelling of the root that isn't in
+// the substitution list — macOS resolves /tmp/x to /private/tmp/x, so if the
+// root can no longer be realpath'd (it was deleted, or the scan is being
+// re-reported later) only one spelling is replaced and "/private<root>" is
+// what's left. A half-replaced path is worse than either whole outcome: it
+// still leaks, and it no longer looks like a path to anything downstream.
+const STRANDED_PREFIX = /(?:\/|[A-Za-z]:\\)[^\s"')]*?(?=<root>|<home>)/g;
+
+function scrubString(value, subs) {
+  let out = value;
+  for (const { from, to } of subs) {
+    if (out.includes(from)) out = out.split(from).join(to);
+  }
+  return out.replace(STRANDED_PREFIX, '').replace(RESIDUAL_ABSOLUTE, '<path>');
+}
+
+/**
+ * Deep-copies `value`, rewriting every absolute path found in any string.
+ * Object keys are walked but never rewritten: no key in any scan output shape
+ * is a path (verified against all three shapes), and rewriting keys would
+ * risk collapsing two distinct entries into one.
+ */
+export function scrubForeignScanPaths(value, root) {
+  const subs = replacements(root);
+
+  const walk = (node) => {
+    if (typeof node === 'string') return scrubString(node, subs);
+    if (Array.isArray(node)) return node.map(walk);
+    if (node && typeof node === 'object') {
+      const out = {};
+      for (const [key, child] of Object.entries(node)) out[key] = walk(child);
+      return out;
+    }
+    return node;
+  };
+
+  return walk(value);
+}
+
+/**
+ * Drops `propSchema` from what gets reported — top level for a single-package
+ * scan, per entry for a multi-package one.
+ *
+ * This is a deliberate reduction, not an oversight. Dominion's ingestion
+ * reads discovery, coverage and totals; it never reads a prop schema, and the
+ * catalog is re-derivable by re-scanning. Keeping it would ship a great deal
+ * of JSON nobody consumes: on a real @mui/material scan the reported payload
+ * goes from 2.18 MB to 10.6 KB. It also happens to be where most of the
+ * absolute paths live, so dropping it shrinks the leak surface at the same
+ * time — but the scrub above stands on its own and does not depend on this.
+ *
+ * stdout is untouched either way. `--report` changes what is sent, never what
+ * the command prints.
+ */
+export function stripPropSchema(result) {
+  const { propSchema, ...rest } = result;
+  if (Array.isArray(rest.packages)) {
+    rest.packages = rest.packages.map((entry) => {
+      const { propSchema: _dropped, ...keep } = entry;
+      return keep;
+    });
+  }
+  return rest;
+}
+
+/**
+ * Builds the request body POST /api/foreign-scan expects. `label` is passed
+ * separately because a single-package result has nowhere to carry it — only
+ * the caller knows which registry entry it resolved.
+ */
+export function buildForeignScanReport(result, { root, targetDir, commitSha, scannerVersion, label = null }) {
+  return {
+    targetDir,
+    commitSha,
+    scannerVersion,
+    ...(label ? { label } : {}),
+    result: scrubForeignScanPaths(stripPropSchema(result), root),
+  };
+}
+
+/**
+ * POSTs the scan and resolves to an outcome record. Never throws, never
+ * rejects — see property (1) in this file's header.
+ *
+ * `fetchImpl` exists for tests; production always uses global fetch.
+ */
+export async function reportForeignScan(result, {
+  url,
+  token,
+  root,
+  targetDir,
+  commitSha,
+  scannerVersion,
+  label = null,
+  timeoutMs = 15000,
+  fetchImpl = globalThis.fetch,
+} = {}) {
+  const missing = Object.entries({ url, token, targetDir, commitSha, scannerVersion })
+    .filter(([, v]) => !v)
+    .map(([k]) => k);
+  if (missing.length > 0) {
+    return { reported: false, reason: `Missing required reporting field(s): ${missing.join(', ')}.` };
+  }
+
+  const body = buildForeignScanReport(result, { root, targetDir, commitSha, scannerVersion, label });
+
+  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}` };
+  }
+
+  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}` };
+  }
+
+  return { reported: true, status: response.status, response: parsed };
+}

package/src/adopt/foreignScoringResolver.js

@@ -0,0 +1,192 @@
+import { existsSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+
+import { getForeignSystem } from './foreignSystemConfig.js';
+import { buildModuleGraph, resolveCandidateFile, resolveRelative } from './moduleGraph.js';
+import { resolveOpportunities } from './opportunityResolver.js';
+
+// Strips // and block comments from JSONC source, string-literal-aware — a
+// naive regex stripper is NOT safe here: a first attempt matched the block-
+// comment opener inside the path pattern "@/*" itself and ate everything up
+// to the next closer, which it found inside the unrelated glob for .ts
+// files in tsconfig.json's own "include" array, corrupting the whole file.
+// Caught live against shadcn-ui/taxonomy's real tsconfig.json, which
+// contains both.
+function stripJsonComments(src) {
+  let out = '';
+  let inString = false;
+  let stringChar = '';
+  for (let i = 0; i < src.length; i++) {
+    const c = src[i];
+    if (inString) {
+      out += c;
+      if (c === '\\') {
+        out += src[++i] ?? '';
+      } else if (c === stringChar) {
+        inString = false;
+      }
+      continue;
+    }
+    if (c === '"' || c === "'") {
+      inString = true;
+      stringChar = c;
+      out += c;
+      continue;
+    }
+    if (c === '/' && src[i + 1] === '/') {
+      while (i < src.length && src[i] !== '\n') i++;
+      out += '\n';
+      continue;
+    }
+    if (c === '/' && src[i + 1] === '*') {
+      i += 2;
+      while (i < src.length && !(src[i] === '*' && src[i + 1] === '/')) i++;
+      i++;
+      continue;
+    }
+    out += c;
+  }
+  return out;
+}
+
+/**
+ * Reads compilerOptions.paths/baseUrl from the target's own tsconfig.json
+ * (falling back to jsconfig.json). A live run against shadcn-ui/taxonomy
+ * caught the reason this exists: every real Next.js + shadcn consumer
+ * imports its own components via the `@/*` alias (`create-next-app`'s and
+ * shadcn's own CLI's default), never a relative path — without this,
+ * scoreCoverage() only ever sees the 0-import case. Trailing commas are
+ * also stripped tolerantly since real tsconfig.json is JSONC, not strict
+ * JSON; a config that still fails to parse just yields no aliases, same as
+ * a repo with no path aliases at all.
+ */
+function loadPathAliases(root) {
+  for (const name of ['tsconfig.json', 'jsconfig.json']) {
+    const file = path.join(root, name);
+    if (!existsSync(file)) continue;
+    try {
+      const raw = stripJsonComments(readFileSync(file, 'utf-8')).replace(/,(\s*[}\]])/g, '$1');
+      const json = JSON.parse(raw);
+      const paths = json.compilerOptions?.paths;
+      if (!paths) continue;
+      return { baseUrl: json.compilerOptions?.baseUrl || '.', paths };
+    } catch {
+      continue;
+    }
+  }
+  return null;
+}
+
+/** Resolves a bare specifier (e.g. "@/components/ui/button") against tsconfig paths, if any match. */
+function resolveAliasedImport(root, aliases, specifier) {
+  if (!aliases) return null;
+  const base = path.resolve(root, aliases.baseUrl);
+  for (const [pattern, targets] of Object.entries(aliases.paths)) {
+    if (pattern.endsWith('/*')) {
+      const prefix = pattern.slice(0, -2);
+      if (specifier !== prefix && !specifier.startsWith(`${prefix}/`)) continue;
+      const suffix = specifier.slice(prefix.length).replace(/^\//, '');
+      for (const target of targets) {
+        const resolved = resolveCandidateFile(path.resolve(base, target.replace(/\*$/, ''), suffix));
+        if (resolved) return resolved;
+      }
+    } else if (pattern === specifier) {
+      for (const target of targets) {
+        const resolved = resolveCandidateFile(path.resolve(base, target));
+        if (resolved) return resolved;
+      }
+    }
+  }
+  return null;
+}
+
+/**
+ * Coverage — which of the components resolveForeignDiscovery found are
+ * actually imported anywhere else in the repo, vs. the full inventory the
+ * componentDir holds. shadcn components are local files, never bare
+ * package specifiers, so the origin?.pkg === pkgName filter every other
+ * resolver uses (usageRulesResolver.js, propApiResolver.js) doesn't apply
+ * here — instead this walks every file's relative imports through
+ * moduleGraph.js's own resolveRelative() and checks whether the resolved
+ * absolute path lands on a discovered component file. A local-file import
+ * edge stands in for "used" — no JSX-usage confirmation beyond that, which
+ * is exactly the "structural, not opinionated" scope Layer 3 commits to.
+ */
+function scoreCoverage(root, ignore, components) {
+  const moduleGraph = buildModuleGraph(root, { ignore });
+  const aliases = loadPathAliases(root);
+  const absComponentFiles = components.map((c) => path.resolve(root, c.file));
+  const absSet = new Set(absComponentFiles);
+  const usageCounts = new Map(absComponentFiles.map((f) => [f, 0]));
+
+  for (const file of moduleGraph.files) {
+    const entry = moduleGraph.graph.get(file);
+    if (!entry || entry.parseError) continue;
+    for (const { source } of entry.imports.values()) {
+      const resolved =
+        source.startsWith('.') || source.startsWith('/')
+          ? resolveRelative(file, source)
+          : resolveAliasedImport(root, aliases, source);
+      if (resolved && resolved !== file && absSet.has(resolved)) {
+        usageCounts.set(resolved, usageCounts.get(resolved) + 1);
+      }
+    }
+  }
+
+  const perComponent = components.map((c) => ({
+    component: c.name,
+    file: c.file,
+    usageCount: usageCounts.get(path.resolve(root, c.file)) ?? 0,
+  }));
+  const used = perComponent.filter((c) => c.usageCount > 0).length;
+  const available = perComponent.length;
+
+  return {
+    used,
+    available,
+    pct: available > 0 ? Math.round((used / available) * 1000) / 10 : null,
+    perComponent,
+  };
+}
+
+/**
+ * Duplication — reuses opportunityResolver.js's own resolveOpportunities()
+ * wholesale rather than hand-rolling a second near-identical matcher: a
+ * shadcn Button is itself a native <button> styled via a static className
+ * (Tailwind utility classes), the exact shape opportunityResolver.js's
+ * Button signature already detects. Findings inside the system's own
+ * componentDir are excluded — that's the catalog's own definition, not a
+ * duplicate of it. Phase 1 ships this one signature only, mirroring
+ * R3 dimension 1's "start narrow, expand only after a live run proves the
+ * false-positive rate low" precedent.
+ */
+function findDuplicates(root, ignore, system) {
+  const { opportunities } = resolveOpportunities(root, { platform: 'web', ignore });
+  const { parentName, dirName } = system.componentDir;
+  const uiDirFragment = `${parentName}${path.sep}${dirName}${path.sep}`;
+  return opportunities
+    .filter((o) => o.component === 'Button')
+    .filter((o) => !o.file.includes(uiDirFragment));
+}
+
+/**
+ * Layer 3 of "Version B" (ADOPTION_APP_PLAN.md §10 decision #25) —
+ * deliberately structural-only: catalog coverage and hand-rolled
+ * duplication, no opinionated conformance rules (Stark has no house
+ * opinion about a design system it doesn't own). No CI-gate severity for
+ * the same reason opportunityResolver.js's findings are always "Info" —
+ * this reports a fact, not a defect.
+ */
+export function scoreForeignAdoption(root, systemId, discovery, { ignore = [] } = {}) {
+  const system = getForeignSystem(systemId);
+  const coverage = scoreCoverage(root, ignore, discovery.components);
+  const duplicates = findDuplicates(root, ignore, system);
+
+  return {
+    system: systemId,
+    root,
+    coverage: { used: coverage.used, available: coverage.available, pct: coverage.pct },
+    coverageDetail: coverage.perComponent,
+    duplicates,
+  };
+}