@motujs/cli 0.0.0-stage → 0.1.1

package/src/lib/bundlability.mjs

@@ -0,0 +1,123 @@
+// CAN THIS ISLAND BE BUNDLED FOR A BROWSER, and if not, which module stopped it?
+//
+// Two callers, one answer. `motu island verify` asks it to REPORT (`rsc-boundary`), and the lagoon
+// build asks it to DECIDE — because an island whose import graph cannot be bundled does not merely
+// fail its own preview, it fails the whole build.
+//
+// WHY THE SECOND CALLER EXISTS. Measured on a cold adoption of Formbricks: a SAML button statically
+// imports a Next server action, which reaches `node:async_hooks` five hops down. The lagoon builds
+// every archipelago as ONE chunk, so that single island took the entire gallery with it — rollup died
+// 11,000 modules deep, no island in the project was previewable, and the agent that hit it ended with
+// a fully green `motu check --runtime` and not one openable URL. Green checks and nothing to look at
+// is the worst possible state for a tool whose promise is "every declared state has an address".
+//
+// The island's own verdict does not change: it still fails `rsc-boundary`, and its own preview is
+// still broken. What changes is the BLAST RADIUS.
+import { existsSync, readFileSync, statSync } from 'node:fs';
+import { blankComments, names, paths, resolveAppImport, HOST, islandComponentPath } from './util.mjs';
+import { listIslands } from './islands.mjs';
+
+/** Adapters that ship a verify contribution, by the specifier an island imports / by host. */
+const ADAPTER_VERIFY = { '@motujs/adapter-next': '@motujs/adapter-next/verify' };
+const HOST_ADAPTER_VERIFY = { next: '@motujs/adapter-next/verify' };
+
+/**
+ * Every APPLICATION file an island's component can reach, breadth-first from the component.
+ *
+ * A host boundary is a property of the BUNDLE, not of one file. Judging it from the island's own
+ * source alone is how `rsc-boundary` printed `✓` over a component that could not be built.
+ *
+ * Bounded on purpose — package specifiers are not followed, and the file count is capped so a check
+ * that runs per island stays cheap. The cap being HIT is reported, because a check that quietly
+ * examined part of a graph is the bug this closes.
+ */
+export function reachableAppSources(entry, { aliased = [], limit = 400 } = {}) {
+  const isAliased = (spec) => aliased.some((a) => spec === a || spec.startsWith(a + '/'));
+  const seen = new Set();
+  const out = [];
+  const queue = [entry];
+  let truncated = false;
+  while (queue.length) {
+    const file = queue.shift();
+    const found = ['', '.tsx', '.ts', '/index.tsx', '/index.ts']
+      .map((e) => file + e)
+      .find((c) => existsSync(c) && statSync(c).isFile());
+    if (!found || seen.has(found)) continue;
+    seen.add(found);
+    if (out.length >= limit) {
+      truncated = true;
+      break;
+    }
+    let src;
+    try {
+      src = readFileSync(found, 'utf8');
+    } catch {
+      continue;
+    }
+    if (found !== entry) out.push({ file: paths.rel(found), source: src });
+    for (const m of blankComments(src).matchAll(/(?:from|import)\s*\(?\s*['"]([^'"]+)['"]/g)) {
+      if (isAliased(m[1])) continue;
+      const next = resolveAppImport(found, m[1]);
+      if (next) queue.push(next);
+    }
+  }
+  if (truncated) out.push({ file: '(truncated)', source: '', truncated: true });
+  return out;
+}
+
+/** The adapter verify module for one island, or null when no adapter judges this host. */
+function adapterFor(elementPath) {
+  if (!existsSync(elementPath)) return null;
+  const text = readFileSync(elementPath, 'utf8');
+  const pkgs = [...text.matchAll(/from\s+['"](@motujs\/adapter-[\w-]+)['"]/g)].map((m) => m[1]);
+  return pkgs.map((p) => ADAPTER_VERIFY[p]).find(Boolean) ?? HOST_ADAPTER_VERIFY[HOST] ?? null;
+}
+
+/**
+ * Islands that CANNOT be bundled, as `{ kebab, tag, element, componentPath, reason }`.
+ *
+ * Only an ERROR-level `rsc-boundary` finding counts. A warning is a note about how something renders;
+ * this list decides whether a module is put into the build at all, so it takes only the level that
+ * means "this cannot work", and errs toward including an island when it cannot tell.
+ */
+export async function unbundlableIslands({ aliased = [] } = {}) {
+  const out = [];
+  for (const island of listIslands(paths.islandsDir)) {
+    const specifier = adapterFor(island.element);
+    if (!specifier) continue;
+    // `islandComponentPath(kebab, PASCAL)` — the pascal name, which is what every other caller passes.
+    // Handing it the EXPORTED name instead returned nothing, so the detector found no islands at all
+    // and excluded nothing, silently. Caught only because the build then behaved identically with the
+    // feature on and off.
+    const { pascal } = names(island.kebab);
+    const componentPath = islandComponentPath(island.kebab, pascal);
+    if (!componentPath || !existsSync(componentPath)) continue;
+    let mod;
+    try {
+      mod = await import(specifier);
+    } catch {
+      continue; // no adapter available: not our place to exclude anything
+    }
+    let findings = [];
+    try {
+      findings = mod.checkCoupling({
+        source: readFileSync(componentPath, 'utf8'),
+        elementSource: readFileSync(island.element, 'utf8'),
+        graph: reachableAppSources(componentPath, { aliased }),
+      });
+    } catch {
+      continue;
+    }
+    const fatal = findings.filter((f) => f.level === 'error' && f.check === 'rsc-boundary');
+    if (!fatal.length) continue;
+    const tag = readFileSync(island.element, 'utf8').match(/tag:\s*['"]([^'"]+)['"]/)?.[1];
+    out.push({
+      kebab: island.kebab,
+      tag: tag ?? null,
+      element: island.element,
+      componentPath,
+      reason: fatal[0].msg,
+    });
+  }
+  return out;
+}

package/src/lib/changed.mjs

@@ -0,0 +1,157 @@
+// Which islands and regions did this branch actually touch?
+//
+// The per-island cost of `--runtime` is roughly constant, so a project pays it once per island: at
+// sixteen islands a full run is a hundred seconds, and an agent that changed one file pays for the
+// other fifteen. That is the difference between a check an agent runs and one it learns to skip.
+//
+// THE RULE THIS FOLLOWS: narrowing must never be silent. A change this cannot attribute to an island
+// or a region — the shared module, the lagoon frame, the config, the framework itself — widens the run
+// back to everything and says why. A check that quietly examined less than you think is the failure
+// this whole report exists to avoid, and "fast because it skipped your change" is the worst version.
+import { execFileSync } from 'node:child_process';
+import { relative, resolve, sep } from 'node:path';
+import { islandComponentPath, names, paths, REPO_ROOT } from './util.mjs';
+import { listIslands } from './islands.mjs';
+import { readRegions } from './eject.mjs';
+
+/** Files this working tree has touched, relative to `base` (default: everything not yet committed). */
+function changedFiles(base) {
+  const git = (args) => execFileSync('git', args, { cwd: REPO_ROOT, encoding: 'utf8' }).trim();
+  const out = new Set();
+  try {
+    // Uncommitted work, staged and not, plus untracked files: what an agent has in front of it.
+    for (const f of git(['diff', '--name-only', 'HEAD']).split('\n')) if (f) out.add(f);
+    for (const f of git(['ls-files', '--others', '--exclude-standard']).split('\n')) if (f) out.add(f);
+    // And, when asked, everything since a branch point.
+    if (base) for (const f of git(['diff', '--name-only', `${base}...HEAD`]).split('\n')) if (f) out.add(f);
+  } catch {
+    return null; // not a git repo, or git unavailable — cannot scope, so do not pretend to
+  }
+  return [...out].map((f) => resolve(gitRoot(), f));
+}
+
+function gitRoot() {
+  try {
+    return execFileSync('git', ['rev-parse', '--show-toplevel'], { cwd: REPO_ROOT, encoding: 'utf8' }).trim();
+  } catch {
+    return REPO_ROOT;
+  }
+}
+
+const under = (dir, file) => {
+  const rel = relative(dir, file);
+  return rel && !rel.startsWith('..') && !rel.startsWith(sep) ? rel : null;
+};
+
+/**
+ * Split the touched files into the islands and regions they belong to.
+ *
+ * Returns `{ scoped: false, reason }` when something changed that cannot be attributed — the caller
+ * then runs everything, which is the safe direction to be wrong in.
+ */
+/**
+ * Files that cannot change what an island renders, whatever else they change.
+ *
+ * NARROWING MUST NEVER BE SILENT — that rule is why anything unattributable widens the run, and it is
+ * right. But it made the most common edit in an agent's tree the most expensive: `.claude/
+ * settings.local.json` changes every time a permission is granted, belongs to no island, and forced a
+ * hundred-second sweep to prove something about a file the lagoon never loads. Editor and CI
+ * configuration is not a silent narrowing; it is a file that provably cannot reach a render.
+ *
+ * Deliberately short, and deliberately NOT including lockfiles: a dependency version absolutely can
+ * change what renders. If a pattern here is ever wrong, the run gets narrower than the truth, so the
+ * bar for adding one is "there is no path from this file to a rendered pixel".
+ */
+const CANNOT_AFFECT_A_RENDER = [
+  /(^|\/)\.claude\//,
+  /(^|\/)\.vscode\//,
+  /(^|\/)\.idea\//,
+  /(^|\/)\.github\//,
+  /\.md$/,
+];
+
+export function changedScope(base) {
+  const files = changedFiles(base);
+  if (!files) return { scoped: false, reason: 'not a git repository, so nothing can be attributed' };
+  if (!files.length) return { scoped: true, islands: [], regions: [], files: 0 };
+
+  const islands = new Set();
+  const regions = new Set();
+  const unattributed = [];
+
+  // AN ISLAND'S COMPONENT MAY NOT LIVE UNDER motu AT ALL. On a React host the island wraps a component
+  // the application already owns — acme's `src/ui` is empty and every component sits in the app — so
+  // mapping by directory alone would attribute the most common edit to nothing and widen every run
+  // back to the whole project. Follow each island to the file it actually mounts.
+  const byComponent = new Map();
+  for (const i of listIslands(paths.islandsDir)) {
+    try {
+      const componentPath = islandComponentPath(i.kebab, names(i.kebab).pascal);
+      if (componentPath) byComponent.set(componentPath, i.kebab);
+    } catch {
+      // An island whose component cannot be resolved is one this cannot scope; leave it to widen.
+    }
+  }
+
+  for (const file of files) {
+    if (CANNOT_AFFECT_A_RENDER.some((re) => re.test(file))) continue;
+    const inIslands = under(paths.islandsDir, file);
+    const inUi = under(paths.uiRoot, file);
+    const inRegions = under(paths.archipelagosDir, file);
+
+    if (inRegions) {
+      const id = inRegions.split(sep)[0];
+      if (id && !id.endsWith('.ts')) regions.add(id);
+      else unattributed.push(file); // the registry itself, or a loose file — affects every region
+      continue;
+    }
+    if (inIslands) {
+      // `<kebab>.island.ts`, `<kebab>.evidence.ts` or `<kebab>/…`; the generated registry is nobody's.
+      const head = inIslands.split(sep)[0];
+      const kebab = head.replace(/\.(island|evidence)\.tsx?$/, '').replace(/\.tsx?$/, '');
+      if (head.startsWith('registry.') || head.startsWith('contracts.')) continue; // generated
+      if (kebab) islands.add(kebab);
+      else unattributed.push(file);
+      continue;
+    }
+    if (inUi) {
+      const dir = inUi.split(sep)[0];
+      if (dir) islands.add(dir);
+      else unattributed.push(file);
+      continue;
+    }
+    const owner = byComponent.get(file);
+    if (owner) {
+      islands.add(owner);
+      continue;
+    }
+    // THE LAGOON'S PER-REGION MODULE belongs to that region and to no other: `regions/<id>.tsx` holds
+    // one region's seed and one region's arrangement. The map that wires them all together
+    // (`lagoon.tsx`) is a different file and still widens, as it should.
+    const inLagoonRegions = under(resolve(paths.lagoonDir, 'src/regions'), file);
+    if (inLagoonRegions && !inLagoonRegions.includes(sep)) {
+      regions.add(inLagoonRegions.replace(/\.tsx?$/, ''));
+      continue;
+    }
+    unattributed.push(file);
+  }
+
+  if (unattributed.length) {
+    return {
+      scoped: false,
+      reason:
+        `${unattributed.length} changed file(s) belong to no single island or region ` +
+        `(e.g. ${relative(gitRoot(), unattributed[0])})`,
+    };
+  }
+  // A CHANGED ISLAND BELONGS TO SPECIFIC REGIONS, not to all of them. Running every region because one
+  // island moved cost more than running every island: a region check is ~20s, an island ~3s.
+  for (const region of readRegions(paths.archipelagosDir)) {
+    const tags = new Set((region.islands ?? []).map((i) => i.element));
+    for (const kebab of islands) {
+      if (tags.has(names(kebab).tag)) regions.add(region.id);
+    }
+  }
+
+  return { scoped: true, islands: [...islands], regions: [...regions], files: files.length };
+}

package/src/lib/component-props.mjs

@@ -0,0 +1,145 @@
+// What a component already tells us about its own boundary.
+//
+// Every island file starts as the same transcription job: list the props, map the `on*` ones to event
+// names, note which host capabilities the component reaches for. All three are facts about the
+// component, sitting in its source — so scaffolding should read them, not ask a human (or an agent) to
+// copy them and get one wrong. What is left for a person to decide is the part that is actually a
+// decision: which region keys those props bind to, and what the events are called.
+import { existsSync, readFileSync } from 'node:fs';
+import { SyntaxKind } from 'ts-morph';
+import { sourceFileAt } from './ts-project.mjs';
+import { lagoonAliases } from './util.mjs';
+
+/**
+ * Everything an island reaches without being handed it — declared as `contract.effects`.
+ *
+ * CANDIDATES ONLY. These patterns are a heuristic for "looks like a host capability"; what makes one
+ * ACTUALLY an effect is that the lagoon has to stand it in (`lagoonAliases()`), and the derivation
+ * below intersects with that whenever a lagoon config exists. Keeping the patterns as the fallback
+ * means a project with no lagoon still gets a sensible contract.
+ */
+const AMBIENT = [/^@\/lib\/contexts\//, /^@\/hooks\//, /^@\/lib\/services\//, /^@\/contexts\//, /^@\/services\//];
+
+/** `onWeekProgress` -> `week-progress`. The author renames it if the region has a better word. */
+/** React's callback convention, and the ONLY test either side of the contract may use. */
+const CALLBACK = /^on[A-Z]/;
+
+export function eventNameFor(prop) {
+  return prop
+    .replace(/^on/, '')
+    .replace(/([a-z0-9])([A-Z])/g, '$1-$2')
+    .replace(/^-/, '')
+    .toLowerCase();
+}
+
+/**
+ * Read a component's boundary: input props, callback props (with a proposed event name), and the host
+ * modules it imports.
+ *
+ * Returns null when the component cannot be found or its props cannot be resolved from the file alone
+ * — scaffolding then falls back to an empty contract rather than inventing one.
+ */
+const contractCache = new Map();
+
+/**
+ * Does the component invoke this callback from an EFFECT — i.e. from rendering itself, rather than
+ * from something a user does?
+ *
+ * The distinction decides what a runtime check may expect. An output fired inside `useEffect` MUST
+ * fire when the island simply renders, so a region that renders and never sees it has a component
+ * that stopped emitting. An output fired from a click handler need not fire at all during a
+ * render-only pass, and demanding it would flag every well-behaved island in the project.
+ *
+ * CONSERVATIVE BY DESIGN: it answers "provably effect-driven", and anything it cannot prove is
+ * reported as not effect-driven, so the runtime check stays silent rather than guessing. An indirect
+ * call — the callback handed to a helper that invokes it later — reads as handler-driven here, which
+ * costs a missed finding and never a false one.
+ */
+function calledFromEffect(fn, prop) {
+  const EFFECT_HOOKS = new Set(['useEffect', 'useLayoutEffect', 'useInsertionEffect']);
+  let found = false;
+  fn.forEachDescendant((node) => {
+    if (found) return;
+    if (node.getKindName?.() !== 'CallExpression') return;
+    const expr = node.getExpression?.();
+    // `onProgress(...)` or `props.onProgress(...)` — the two spellings a destructured or bagged prop takes.
+    const callee = expr?.getText?.() ?? '';
+    if (callee !== prop && !callee.endsWith(`.${prop}`)) return;
+    for (let a = node.getParent?.(); a; a = a.getParent?.()) {
+      if (a.getKindName?.() !== 'CallExpression') continue;
+      const hook = a.getExpression?.()?.getText?.() ?? '';
+      if (EFFECT_HOOKS.has(hook.split('.').pop() ?? '')) {
+        found = true;
+        return;
+      }
+    }
+  });
+  return found;
+}
+
+export function readComponentContract(file, exportName) {
+  if (!existsSync(file)) return null;
+  // Reading a component means parsing it and resolving its props type, which is the expensive part of
+  // a static verify. A sweep asks for the same file several times (props-match, effects, the generated
+  // contract), so the answer is remembered for the life of the process.
+  const cacheKey = `${file}::${exportName ?? ''}`;
+  if (contractCache.has(cacheKey)) return contractCache.get(cacheKey);
+  const result = readComponentContractUncached(file, exportName);
+  contractCache.set(cacheKey, result);
+  return result;
+}
+
+function readComponentContractUncached(file, exportName) {
+  const sf = sourceFileAt(file, { allowJs: true, jsx: 4 });
+
+  const fn =
+    (exportName && (sf.getFunction(exportName) ?? sf.getVariableDeclaration(exportName)?.getInitializerIfKind(SyntaxKind.ArrowFunction))) ??
+    sf.getFunctions().find((f) => f.isExported() && /^[A-Z]/.test(f.getName() ?? '')) ??
+    null;
+  if (!fn) return null;
+
+  let names = [];
+  const param = fn.getParameters()[0];
+  if (param) {
+    try {
+      names = param
+        .getType()
+        .getProperties()
+        .map((p) => p.getName());
+    } catch {
+      names = [];
+    }
+  }
+
+  // A TYPE import is not a capability: it erases, the island never calls it, and declaring it as
+  // declaring it would ask the lagoon to stand in for a module nothing reaches at runtime.
+  //
+  // Intersected with what the lagoon actually stands down, so this agrees with the `effects` check by
+  // construction rather than by coincidence — see `lagoonAliases()` for the split this closed.
+  const stoodDown = lagoonAliases();
+  const effects = [...new Set(
+    readFileSync(file, 'utf8')
+      .split('\n')
+      .filter((l) => !/^\s*import\s+type\b/.test(l))
+      .map((l) => l.match(/from\s*['"]([^'"]+)['"]/)?.[1])
+      .filter((spec) => spec && AMBIENT.some((re) => re.test(spec)))
+      .filter((spec) => stoodDown === null || stoodDown.includes(spec)),
+  )].sort();
+
+  return {
+    component: fn.getName?.() ?? exportName ?? null,
+    // `fit` is motu's own injected prop, never part of an island's declared boundary.
+    // ONE RULE FOR BOTH SIDES, and it is React's own: a callback is `on` FOLLOWED BY A CAPITAL.
+    //
+    // These two filters used to disagree — inputs excluded anything starting with `on`, outputs
+    // required `/^on[A-Z]/` — so a prop whose name merely begins with those two letters
+    // (`onboardingState`) was neither. It vanished from the contract silently: not an input, not an
+    // event, and `props-match` then reported it as a callback nobody had mapped. A prop that decides
+    // which of four cards a page renders, dropped because of two letters.
+    input: names.filter((n) => !CALLBACK.test(n) && n !== 'fit'),
+    output: names
+      .filter((n) => CALLBACK.test(n))
+      .map((n) => ({ prop: n, event: eventNameFor(n), effectDriven: calledFromEffect(fn, n) })),
+    effects,
+  };
+}