@starklab/stark-mcp 0.1.0

package/src/adopt/targetDiscovery.js

@@ -0,0 +1,237 @@
+import { existsSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+
+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/**'];
+
+function readJson(file) {
+  try {
+    return JSON.parse(readFileSync(file, 'utf-8'));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * `dominion.config.json#targets` is the asymmetric-override surface
+ * (ADOPTION_APP_PLAN.md §3e): force-include is unrestricted (a team wants
+ * adoption tracked from day zero even before it depends on stk*);
+ * force-exclude requires a recorded reason, shown beside the excluded count
+ * — "the gaming direction" the plan calls out explicitly. Reuses the same
+ * config file wrapperResolver.js already reads for declared wrappers.
+ */
+function readTargetOverrides(root) {
+  const configPath = path.join(root, 'dominion.config.json');
+  const raw = existsSync(configPath) ? readJson(configPath) : null;
+  const targets = raw?.targets && typeof raw.targets === 'object' ? raw.targets : {};
+  const forceInclude = Array.isArray(targets.forceInclude) ? targets.forceInclude : [];
+  const forceExclude = targets.forceExclude && typeof targets.forceExclude === 'object' ? targets.forceExclude : {};
+  return { forceInclude, forceExclude };
+}
+
+/**
+ * Resolves the workspace glob patterns a repo declares: npm/yarn's
+ * package.json#workspaces first (array form, or the yarn {packages:[...]}
+ * form), falling back to pnpm-workspace.yaml's `packages:` list. The
+ * pnpm-workspace.yaml parser is a hand-rolled flat-list reader, not a YAML
+ * parser — this package has no YAML dependency and the only shape pnpm
+ * actually emits for this key is a flat list of quoted globs, so a full
+ * parser would be unneeded weight.
+ */
+function resolveWorkspaceGlobs(root) {
+  const pkgPath = path.join(root, 'package.json');
+  const pkg = existsSync(pkgPath) ? readJson(pkgPath) : null;
+  if (pkg?.workspaces) {
+    const globs = Array.isArray(pkg.workspaces) ? pkg.workspaces : pkg.workspaces.packages;
+    if (Array.isArray(globs) && globs.length) return { source: 'package.json#workspaces', globs };
+  }
+
+  const pnpmPath = path.join(root, 'pnpm-workspace.yaml');
+  if (existsSync(pnpmPath)) {
+    const lines = readFileSync(pnpmPath, 'utf-8').split('\n');
+    const globs = [];
+    let inPackages = false;
+    for (const line of lines) {
+      if (/^packages:\s*$/.test(line)) {
+        inPackages = true;
+        continue;
+      }
+      if (inPackages) {
+        const m = line.match(/^\s+-\s*['"]?([^'"]+)['"]?\s*$/);
+        if (m) {
+          globs.push(m[1]);
+          continue;
+        }
+        if (line.trim() === '') continue;
+        inPackages = false; // dedented to a new top-level key — packages: list ended
+      }
+    }
+    if (globs.length) return { source: 'pnpm-workspace.yaml', globs };
+  }
+
+  return { source: null, globs: [] };
+}
+
+function monorepoToolingSignals(root) {
+  return {
+    turbo: existsSync(path.join(root, 'turbo.json')),
+    nx: existsSync(path.join(root, 'nx.json')),
+  };
+}
+
+/**
+ * Expands workspace globs to every directory containing its own
+ * package.json. When no manifest declares any globs at all, falls back to
+ * scanning the whole repo for package.json files — "never ask someone to
+ * type 20 paths" (ADOPTION_APP_PLAN.md §3e). A repo with no nested
+ * package.json anywhere is itself the one and only target.
+ */
+function expandTargetDirs(root, globs) {
+  if (globs.length === 0) {
+    const found = fg.sync(['**/package.json'], { cwd: root, ignore: DEFAULT_IGNORE, absolute: true });
+    const dirs = found.map((f) => path.dirname(f)).filter((d) => d !== root);
+    return dirs.length ? dirs : [root];
+  }
+  const patterns = globs.map((g) => `${g.replace(/\/$/, '')}/package.json`);
+  const found = fg.sync(patterns, { cwd: root, ignore: DEFAULT_IGNORE, absolute: true });
+  return found.map((f) => path.dirname(f));
+}
+
+function depNames(pkg) {
+  return new Set([
+    ...Object.keys(pkg?.dependencies || {}),
+    ...Object.keys(pkg?.devDependencies || {}),
+    ...Object.keys(pkg?.peerDependencies || {}),
+  ]);
+}
+
+function hasDirectStkDep(pkg) {
+  for (const name of depNames(pkg)) {
+    if (name.startsWith(STK_PREFIX)) return true;
+  }
+  return false;
+}
+
+function hasUiFrameworkDep(pkg) {
+  const deps = depNames(pkg);
+  return UI_FRAMEWORK_DEPS.some((d) => deps.has(d));
+}
+
+/**
+ * Discovers every workspace target in a repo and classifies each in/out of
+ * scope by direct-or-transitive dependency on @starklab/stk*
+ * (ADOPTION_APP_PLAN.md §3e — "a workspace with no dependency, direct or
+ * transitive, on stk* is out of scope, not 0%"). "Transitive" here means
+ * transitive through the workspace's own internal dependency graph (one
+ * target depending on another target that itself depends on stk*) — the
+ * exact shape this repo has (apps/storybook-native → packages/stk-react-
+ * native → packages/stk). There is no node_modules resolution step, so a
+ * transitive dependency reached only through a *non-workspace* npm package
+ * is not detected; that's an acceptable gap since a non-workspace package
+ * 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
+ * must never read as zeros inside a score, because they're the most
+ * valuable rows to bring into scope next.
+ */
+export function discoverTargets(root) {
+  const { source, globs } = resolveWorkspaceGlobs(root);
+  const monorepoTooling = monorepoToolingSignals(root);
+  const { forceInclude, forceExclude } = readTargetOverrides(root);
+
+  const dirs = expandTargetDirs(root, globs);
+
+  const rawTargets = dirs.map((dir) => {
+    const pkgPath = path.join(dir, 'package.json');
+    const pkg = existsSync(pkgPath) ? readJson(pkgPath) : null;
+    return {
+      dir,
+      relDir: path.relative(root, dir) || '.',
+      name: pkg?.name || path.basename(dir),
+      pkg,
+    };
+  });
+
+  const byPackageName = new Map(rawTargets.filter((t) => t.pkg?.name).map((t) => [t.pkg.name, t]));
+
+  function transitivelyDependsOnStk(target, visited) {
+    if (visited.has(target.relDir)) return false;
+    visited.add(target.relDir);
+    if (!target.pkg) return false;
+    if (hasDirectStkDep(target.pkg)) return true;
+    for (const dep of depNames(target.pkg)) {
+      const sibling = byPackageName.get(dep);
+      if (sibling && transitivelyDependsOnStk(sibling, visited)) return true;
+    }
+    return false;
+  }
+
+  const targets = rawTargets.map((t) => {
+    const relPath = t.relDir;
+    const isForceIncluded = forceInclude.includes(relPath);
+    const forceExcludeReason = forceExclude[relPath];
+    const dependsOnStk = transitivelyDependsOnStk(t, new Set());
+    const rendersUi = t.pkg ? hasUiFrameworkDep(t.pkg) : false;
+
+    let inScope;
+    let scopeReason;
+    if (forceExcludeReason) {
+      inScope = false;
+      scopeReason = `force-excluded: ${forceExcludeReason}`;
+    } else if (isForceIncluded) {
+      inScope = true;
+      scopeReason = 'force-included';
+    } else if (dependsOnStk) {
+      inScope = true;
+      scopeReason = 'depends on @starklab/stk*, directly or via a workspace sibling';
+    } else {
+      inScope = false;
+      scopeReason = 'no @starklab/stk* dependency, direct or transitive';
+    }
+
+    return {
+      name: t.name,
+      dir: relPath,
+      packageName: t.pkg?.name || null,
+      inScope,
+      scopeReason,
+      rendersUi,
+      forceIncluded: isForceIncluded,
+      forceExcluded: Boolean(forceExcludeReason),
+    };
+  });
+
+  const inScope = targets.filter((t) => t.inScope);
+  const excluded = targets.filter((t) => !t.inScope);
+  const opportunities = excluded.filter((t) => t.rendersUi);
+
+  return {
+    root,
+    manifestSource: source,
+    monorepoTooling,
+    targets,
+    inScope,
+    excluded,
+    opportunities,
+  };
+}
+
+/**
+ * Builds the `Map<packageName, absoluteDir>` resolveWrappers()'s
+ * `workspacePackages` option expects, from a discovery result — every
+ * target with a real package.json#name, in or out of scope alike (a
+ * cross-workspace wrapper chain can legitimately pass through an
+ * out-of-scope package on its way to a DS component).
+ */
+export function workspacePackageMap(discovery) {
+  const map = new Map();
+  for (const t of discovery.targets) {
+    if (t.packageName) map.set(t.packageName, path.join(discovery.root, t.dir));
+  }
+  return map;
+}

package/src/adopt/targetDiscovery.test.js

@@ -0,0 +1,227 @@
+import { mkdtempSync, rmSync, mkdirSync, writeFileSync } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+import { describe, it, expect, afterEach } from 'vitest';
+
+import { discoverTargets, workspacePackageMap } from './targetDiscovery.js';
+
+let tmpDirs = [];
+
+afterEach(() => {
+  for (const dir of tmpDirs) rmSync(dir, { recursive: true, force: true });
+  tmpDirs = [];
+});
+
+function fixture(files) {
+  const root = mkdtempSync(path.join(os.tmpdir(), 'stark-adopt-targets-'));
+  tmpDirs.push(root);
+  for (const [rel, content] of Object.entries(files)) {
+    const full = path.join(root, rel);
+    mkdirSync(path.dirname(full), { recursive: true });
+    writeFileSync(full, content);
+  }
+  return root;
+}
+
+function target(discovery, dir) {
+  const found = discovery.targets.find((t) => t.dir === dir);
+  if (!found) throw new Error(`No target "${dir}". Found: ${discovery.targets.map((t) => t.dir).join(', ')}`);
+  return found;
+}
+
+describe('discoverTargets — manifest source resolution', () => {
+  it('reads npm/yarn array-form package.json#workspaces', () => {
+    const root = fixture({
+      'package.json': JSON.stringify({ name: 'root', workspaces: ['packages/*'] }),
+      'packages/a/package.json': JSON.stringify({ name: 'a' }),
+      'packages/b/package.json': JSON.stringify({ name: 'b' }),
+    });
+    const d = discoverTargets(root);
+    expect(d.manifestSource).toBe('package.json#workspaces');
+    expect(d.targets.map((t) => t.dir).sort()).toEqual(['packages/a', 'packages/b']);
+  });
+
+  it('reads yarn object-form package.json#workspaces.packages', () => {
+    const root = fixture({
+      'package.json': JSON.stringify({ name: 'root', workspaces: { packages: ['apps/*'] } }),
+      'apps/one/package.json': JSON.stringify({ name: 'one' }),
+    });
+    const d = discoverTargets(root);
+    expect(d.manifestSource).toBe('package.json#workspaces');
+    expect(d.targets.map((t) => t.dir)).toEqual(['apps/one']);
+  });
+
+  it('falls back to pnpm-workspace.yaml when package.json has no workspaces field', () => {
+    const root = fixture({
+      'package.json': JSON.stringify({ name: 'root' }),
+      'pnpm-workspace.yaml': "packages:\n  - 'packages/*'\n  - 'apps/*'\n",
+      'packages/x/package.json': JSON.stringify({ name: 'x' }),
+      'apps/y/package.json': JSON.stringify({ name: 'y' }),
+    });
+    const d = discoverTargets(root);
+    expect(d.manifestSource).toBe('pnpm-workspace.yaml');
+    expect(d.targets.map((t) => t.dir).sort()).toEqual(['apps/y', 'packages/x']);
+  });
+
+  it('falls back to a whole-repo scan when no manifest declares globs', () => {
+    const root = fixture({
+      'package.json': JSON.stringify({ name: 'root' }),
+      'nested/thing/package.json': JSON.stringify({ name: 'thing' }),
+    });
+    const d = discoverTargets(root);
+    expect(d.manifestSource).toBeNull();
+    expect(d.targets.map((t) => t.dir)).toEqual(['nested/thing']);
+  });
+
+  it('treats the root itself as the sole target when nothing nested exists either', () => {
+    const root = fixture({
+      'package.json': JSON.stringify({ name: 'root' }),
+    });
+    const d = discoverTargets(root);
+    expect(d.targets.map((t) => t.dir)).toEqual(['.']);
+  });
+
+  it('records turbo.json/nx.json presence as informational monorepoTooling flags', () => {
+    const root = fixture({
+      'package.json': JSON.stringify({ name: 'root', workspaces: ['packages/*'] }),
+      'turbo.json': '{}',
+      'packages/a/package.json': JSON.stringify({ name: 'a' }),
+    });
+    const d = discoverTargets(root);
+    expect(d.monorepoTooling).toEqual({ turbo: true, nx: false });
+  });
+});
+
+describe('discoverTargets — scope classification', () => {
+  it('marks a direct @starklab/stk* dependent in scope', () => {
+    const root = fixture({
+      'package.json': JSON.stringify({ name: 'root', workspaces: ['packages/*'] }),
+      'packages/consumer/package.json': JSON.stringify({
+        name: 'consumer',
+        dependencies: { '@starklab/stk-components': '^1.0.0' },
+      }),
+    });
+    const d = discoverTargets(root);
+    const t = target(d, 'packages/consumer');
+    expect(t.inScope).toBe(true);
+    expect(t.scopeReason).toMatch(/depends on @starklab\/stk\*/);
+  });
+
+  it('marks a target with no stk* dependency, direct or transitive, out of scope — not 0%', () => {
+    const root = fixture({
+      'package.json': JSON.stringify({ name: 'root', workspaces: ['packages/*'] }),
+      'packages/unrelated/package.json': JSON.stringify({ name: 'unrelated', dependencies: { lodash: '^4.0.0' } }),
+    });
+    const d = discoverTargets(root);
+    const t = target(d, 'packages/unrelated');
+    expect(t.inScope).toBe(false);
+    expect(t.scopeReason).toBe('no @starklab/stk* dependency, direct or transitive');
+    expect(d.excluded.map((x) => x.dir)).toContain('packages/unrelated');
+  });
+
+  it('marks a transitive dependent (via a workspace sibling) in scope', () => {
+    const root = fixture({
+      'package.json': JSON.stringify({ name: 'root', workspaces: ['packages/*'] }),
+      'packages/core/package.json': JSON.stringify({
+        name: 'core',
+        dependencies: { '@starklab/stk': '^1.0.0' },
+      }),
+      'packages/app/package.json': JSON.stringify({ name: 'app', dependencies: { core: '1.0.0' } }),
+    });
+    const d = discoverTargets(root);
+    const t = target(d, 'packages/app');
+    expect(t.inScope).toBe(true);
+    expect(t.scopeReason).toMatch(/via a workspace sibling/);
+  });
+
+  it('flags an excluded target with a UI framework dependency as an opportunity', () => {
+    const root = fixture({
+      'package.json': JSON.stringify({ name: 'root', workspaces: ['packages/*'] }),
+      'packages/ui-no-stk/package.json': JSON.stringify({ name: 'ui-no-stk', dependencies: { react: '^18.0.0' } }),
+    });
+    const d = discoverTargets(root);
+    const t = target(d, 'packages/ui-no-stk');
+    expect(t.inScope).toBe(false);
+    expect(t.rendersUi).toBe(true);
+    expect(d.opportunities.map((x) => x.dir)).toContain('packages/ui-no-stk');
+  });
+
+  it('does not list an excluded, non-UI target as an opportunity', () => {
+    const root = fixture({
+      'package.json': JSON.stringify({ name: 'root', workspaces: ['packages/*'] }),
+      'packages/plain/package.json': JSON.stringify({ name: 'plain', dependencies: { lodash: '^4.0.0' } }),
+    });
+    const d = discoverTargets(root);
+    expect(d.opportunities.map((x) => x.dir)).not.toContain('packages/plain');
+  });
+});
+
+describe('discoverTargets — dominion.config.json overrides', () => {
+  it('force-includes a target with no stk* dependency, unrestricted', () => {
+    const root = fixture({
+      'package.json': JSON.stringify({ name: 'root', workspaces: ['packages/*'] }),
+      'packages/early/package.json': JSON.stringify({ name: 'early', dependencies: { lodash: '^4.0.0' } }),
+      'dominion.config.json': JSON.stringify({ targets: { forceInclude: ['packages/early'] } }),
+    });
+    const d = discoverTargets(root);
+    const t = target(d, 'packages/early');
+    expect(t.inScope).toBe(true);
+    expect(t.forceIncluded).toBe(true);
+    expect(t.scopeReason).toBe('force-included');
+  });
+
+  it('force-excludes a target that would otherwise be in scope, and requires a reason', () => {
+    const root = fixture({
+      'package.json': JSON.stringify({ name: 'root', workspaces: ['packages/*'] }),
+      'packages/gaming/package.json': JSON.stringify({
+        name: 'gaming',
+        dependencies: { '@starklab/stk-components': '^1.0.0' },
+      }),
+      'dominion.config.json': JSON.stringify({
+        targets: { forceExclude: { 'packages/gaming': 'prototype, not tracked yet' } },
+      }),
+    });
+    const d = discoverTargets(root);
+    const t = target(d, 'packages/gaming');
+    expect(t.inScope).toBe(false);
+    expect(t.forceExcluded).toBe(true);
+    expect(t.scopeReason).toBe('force-excluded: prototype, not tracked yet');
+  });
+
+  it('gives force-exclude priority over force-include when both name the same target', () => {
+    const root = fixture({
+      'package.json': JSON.stringify({ name: 'root', workspaces: ['packages/*'] }),
+      'packages/contested/package.json': JSON.stringify({ name: 'contested' }),
+      'dominion.config.json': JSON.stringify({
+        targets: {
+          forceInclude: ['packages/contested'],
+          forceExclude: { 'packages/contested': 'explicitly out' },
+        },
+      }),
+    });
+    const d = discoverTargets(root);
+    const t = target(d, 'packages/contested');
+    expect(t.inScope).toBe(false);
+    expect(t.scopeReason).toBe('force-excluded: explicitly out');
+  });
+});
+
+describe('workspacePackageMap', () => {
+  it('maps every target with a package.json#name to its absolute dir, in and out of scope alike', () => {
+    const root = fixture({
+      'package.json': JSON.stringify({ name: 'root', workspaces: ['packages/*'] }),
+      'packages/consumer/package.json': JSON.stringify({
+        name: 'consumer',
+        dependencies: { '@starklab/stk-components': '^1.0.0' },
+      }),
+      'packages/unrelated/package.json': JSON.stringify({ name: 'unrelated' }),
+    });
+    const d = discoverTargets(root);
+    const map = workspacePackageMap(d);
+    expect(map.get('consumer')).toBe(path.join(root, 'packages/consumer'));
+    // Out-of-scope targets are still mapped — a cross-workspace wrapper
+    // chain can legitimately pass through one on its way to a DS component.
+    expect(map.get('unrelated')).toBe(path.join(root, 'packages/unrelated'));
+  });
+});