@motujs/cli 0.0.0-stage → 0.1.0

package/src/lib/screens.mjs

@@ -0,0 +1,266 @@
+// `motu check — screens` (EXPERIMENTAL): do the declared screens hold together, and does every
+// navigation a region asks for go somewhere?
+//
+// A screen is arrangement — a route, the app's own layout, a region per slot (`@motujs/react`
+// `screens.ts`). What can be checked without a browser:
+//
+//   screens-declared  the routes are unique and every slot names a region this project has
+//   screen-coverage   a region on no screen is reachable only on its own (a warning: legitimate for a
+//                     region the app embeds elsewhere, worth knowing about everywhere else)
+//   nav-targets       every `host.navigate(...)` in an archipelago resolves to a declared screen — a
+//                     button to an address nothing serves fails here, before anything runs.
+//                     KNOW THE LIMIT: a target that MATCHES the wrong route passes. The demo's
+//                     "+ New member" once navigated to `/member/edit`, which `/member/:memberId`
+//                     serves — so the router opened a profile for a member called "edit", and this
+//                     check would have accepted it too. Matching a route is not meaning the route.
+//
+// READ, NOT EVALUATED: the screens module imports React components and evidence, which plain node
+// cannot load — the same reason the region checks parse evidence. So a target built in a way this
+// does not follow is reported as UNREAD rather than passed: a check that looked at nothing has not
+// passed.
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { SyntaxKind } from 'ts-morph';
+import { paths } from './util.mjs';
+import { sourceFileAt } from './ts-project.mjs';
+
+/** Where a project declares its screens: `src/screens/screens.ts`, beside `src/archipelagos/`. */
+export function screensFile() {
+  return resolve(dirname(paths.archipelagosDir), 'screens', 'screens.ts');
+}
+
+/** `/member/:id` -> a whole-path matcher, as `compileScreenPath` in @motujs/react builds it. */
+export function compilePath(path) {
+  const source = path
+    .replace(/\/+$/, '')
+    .split('/')
+    .map((part) => (/^:[A-Za-z_]\w*$/.test(part) ? '[^/]+' : part.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')))
+    .join('/');
+  return new RegExp(`^${source}/?$`);
+}
+
+/** Does any screen serve this target? `prefix` targets end where an id would be appended. */
+export function served(screens, target) {
+  const probe = target.kind === 'prefix' ? `${target.value}x-param` : target.value;
+  return screens.some((s) => compilePath(s.path).test(probe));
+}
+
+const str = (node) =>
+  node && (node.getKind() === SyntaxKind.StringLiteral || node.getKind() === SyntaxKind.NoSubstitutionTemplateLiteral)
+    ? node.getLiteralText()
+    : null;
+
+/**
+ * Every path a navigate argument can produce, or `{ unread }` when it is built some other way.
+ *
+ * Followed: a literal; `'/prefix/' + anything` (and a template starting with a literal); either side
+ * of `?:` and `??`; `encodeURIComponent`-style calls inside a prefix; and `MAP[key]` where MAP is an
+ * object literal const in the same file — every one of its values is a target.
+ */
+export function targetsOf(expr, sf) {
+  if (!expr) return [{ unread: '(no argument)' }];
+  const k = expr.getKind();
+  const literal = str(expr);
+  if (literal !== null) return [{ kind: 'exact', value: literal }];
+  if (k === SyntaxKind.ParenthesizedExpression) return targetsOf(expr.getExpression(), sf);
+  if (k === SyntaxKind.ConditionalExpression) return [...targetsOf(expr.getWhenTrue(), sf), ...targetsOf(expr.getWhenFalse(), sf)];
+  if (k === SyntaxKind.BinaryExpression) {
+    const op = expr.getOperatorToken().getText();
+    if (op === '??' || op === '||') return [...targetsOf(expr.getLeft(), sf), ...targetsOf(expr.getRight(), sf)];
+    if (op === '+') {
+      // The leftmost operand of a `+` chain is the prefix.
+      let left = expr;
+      while (left.getKind() === SyntaxKind.BinaryExpression && left.getOperatorToken().getText() === '+') left = left.getLeft();
+      const prefix = str(left);
+      if (prefix !== null) return [{ kind: 'prefix', value: prefix }];
+    }
+  }
+  if (k === SyntaxKind.TemplateExpression) {
+    const head = expr.getHead().getLiteralText();
+    if (head) return [{ kind: 'prefix', value: head }];
+  }
+  if (k === SyntaxKind.ElementAccessExpression) {
+    const name = expr.getExpression().getText();
+    const decl = sf.getVariableDeclaration(name);
+    const init = decl?.getInitializer();
+    if (init?.getKind() === SyntaxKind.ObjectLiteralExpression) {
+      const out = [];
+      for (const prop of init.getProperties()) {
+        const v = prop.getInitializer?.();
+        out.push(...(str(v) !== null ? [{ kind: 'exact', value: str(v) }] : [{ unread: prop.getText() }]));
+      }
+      return out;
+    }
+  }
+  return [{ unread: expr.getText() }];
+}
+
+/** Each declared screen: its id, its path, and the identifiers its slots name. */
+function readScreens(sf) {
+  const out = [];
+  for (const call of sf.getDescendantsOfKind(SyntaxKind.CallExpression)) {
+    if (call.getExpression().getText() !== 'screen') continue;
+    const spec = call.getArguments()[0];
+    if (spec?.getKind() !== SyntaxKind.ObjectLiteralExpression) continue;
+    const id = str(spec.getProperty('id')?.getInitializer?.());
+    const path = str(spec.getProperty('path')?.getInitializer?.());
+    const slots = spec.getProperty('slots')?.getInitializer?.();
+    const regions = [];
+    if (slots?.getKind() === SyntaxKind.ObjectLiteralExpression) {
+      for (const p of slots.getProperties()) {
+        const v = p.getInitializer?.();
+        if (!v) continue;
+        if (v.getKind() === SyntaxKind.CallExpression && v.getExpression().getText() === 'notARegion') continue;
+        regions.push(v.getText());
+      }
+    }
+    if (id && path) out.push({ id, path, regions, line: call.getStartLineNumber() });
+    else out.push({ unread: true, line: call.getStartLineNumber(), text: (spec.getProperty('id')?.getText?.() ?? spec.getText()).slice(0, 60) });
+  }
+  return out;
+}
+
+/** Identifier (as a screens file names it) -> region id, from the archipelago files' own exports. */
+function regionIdsByName(screensSf) {
+  const byName = new Map();
+  const dir = paths.archipelagosDir;
+  if (!existsSync(dir)) return byName;
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    if (!entry.isDirectory()) continue;
+    const file = resolve(dir, entry.name, `${entry.name}.archipelago.ts`);
+    if (!existsSync(file)) continue;
+    const text = readFileSync(file, 'utf8');
+    const id = /\bid:\s*['"]([^'"]+)['"]/.exec(text)?.[1] ?? entry.name;
+    for (const m of text.matchAll(/export\s+(?:const|function)\s+(\w+)/g)) byName.set(m[1], id);
+  }
+  // One level of local aliasing in the screens file: `const members = membersArchipelago();`.
+  for (const decl of screensSf.getVariableDeclarations()) {
+    const init = decl.getInitializer();
+    if (!init) continue;
+    const callee = init.getKind() === SyntaxKind.CallExpression ? init.getExpression().getText() : init.getText();
+    if (byName.has(callee)) byName.set(decl.getName(), byName.get(callee));
+  }
+  return byName;
+}
+
+/** Findings for the screens section, or null when the project declares no screens. */
+/**
+ * The screens this project declares, as `motu lagoon states` lists them: `{ screens, unread }`, or
+ * null when there is no screens module. `unread` counts the `screen(...)` calls whose id or path is
+ * not a string literal — said by the caller, never dropped.
+ */
+export function declaredScreens() {
+  const file = screensFile();
+  if (!existsSync(file)) return null;
+  const all = readScreens(sourceFileAt(file, { allowJs: true, jsx: 4 }));
+  return { screens: all.filter((s) => !s.unread), unread: all.filter((s) => s.unread).length };
+}
+
+export function screenFindings() {
+  const file = screensFile();
+  if (!existsSync(file)) return null;
+  const findings = [];
+  const add = (level, check, msg) => findings.push({ level, check, msg });
+  const sf = sourceFileAt(file, { allowJs: true, jsx: 4 });
+  const all = readScreens(sf);
+  // A screen() whose id or path is not a plain string literal — a template, a helper's parameter — is
+  // a screen this check did not see. Said, never dropped: it once reported "8 screen(s)" over 21, and
+  // then called a route served by one of the unseen thirteen unserved.
+  const unreadScreens = all.filter((s) => s.unread);
+  const screens = all.filter((s) => !s.unread);
+  if (unreadScreens.length)
+    add(
+      'warn',
+      'screens-declared',
+      `${unreadScreens.length} screen(...) call(s) NOT read — write \`id\` and \`path\` as string literals: ` +
+        unreadScreens.map((s) => `${paths.rel(file)}:${s.line}`).join(', '),
+    );
+  if (!screens.length) {
+    add('error', 'screens-declared', `${paths.rel(file)} declares no screen(...) — nothing was examined, so nothing is proved`);
+    return { findings, screens };
+  }
+
+  // Unique routes: two screens on one path means the second can never open.
+  const seen = new Map();
+  for (const s of screens) {
+    const prior = seen.get(s.path);
+    if (prior) add('error', 'screens-declared', `screens "${prior}" and "${s.id}" both declare ${s.path} — the second can never open`);
+    seen.set(s.path, s.id);
+  }
+
+  // Every slot names a region this project has.
+  const byName = regionIdsByName(sf);
+  const regionIds = new Set(
+    existsSync(paths.archipelagosDir)
+      ? readdirSync(paths.archipelagosDir, { withFileTypes: true }).filter((e) => e.isDirectory()).map((e) => e.name)
+      : [],
+  );
+  const onScreen = new Set();
+  for (const s of screens) {
+    for (const name of s.regions) {
+      const id = byName.get(name);
+      if (!id) add('error', 'screens-declared', `screen "${s.id}" fills a slot with \`${name}\`, which is no archipelago this project exports`);
+      else onScreen.add(id);
+    }
+  }
+  if (!findings.some((f) => f.level === 'error' && f.check === 'screens-declared'))
+    add('ok', 'screens-declared', `${screens.length} screen(s), unique routes, every slot a known region · ${onScreen.size} region(s) placed`);
+
+  // A region REFERENCED by a placed region's root (`slots: { x: { region: 'equipage' } }`) is on the
+  // screen too — inside its parent. Followed to a fixed point, so a reference of a reference counts.
+  for (let grew = true; grew; ) {
+    grew = false;
+    for (const id of [...onScreen]) {
+      const archFile = paths.archipelagoFile(id);
+      if (!existsSync(archFile)) continue;
+      for (const m of readFileSync(archFile, 'utf8').matchAll(/\bregion:\s*['"]([\w-]+)['"]/g)) {
+        if (regionIds.has(m[1]) && !onScreen.has(m[1])) {
+          onScreen.add(m[1]);
+          grew = true;
+        }
+      }
+    }
+  }
+  const loose = [...regionIds].filter((id) => !onScreen.has(id)).sort();
+  if (loose.length)
+    add('warn', 'screen-coverage', `region(s) on no screen: ${loose.join(', ')} — reachable in the lagoon only on their own`);
+
+  // Every navigation a region asks for resolves to a screen.
+  let examined = 0;
+  const unread = [];
+  for (const id of regionIds) {
+    const archFile = paths.archipelagoFile(id);
+    if (!existsSync(archFile)) continue;
+    const asf = sourceFileAt(archFile, { allowJs: true, jsx: 4 });
+    for (const call of asf.getDescendantsOfKind(SyntaxKind.CallExpression)) {
+      if (!/\.navigate$/.test(call.getExpression().getText())) continue;
+      for (const t of targetsOf(call.getArguments()[0], asf)) {
+        examined++;
+        if (t.unread) {
+          unread.push(`${id}:${call.getStartLineNumber()} \`${t.unread}\``);
+          continue;
+        }
+        if (!served(screens, t)) {
+          add(
+            'error',
+            'nav-targets',
+            `${id} navigates to ${t.kind === 'prefix' ? `${t.value}…` : t.value} (${paths.rel(archFile)}:${call.getStartLineNumber()}) — no declared screen serves it, so this control leads nowhere`,
+          );
+        }
+      }
+    }
+  }
+  if (unread.length)
+    add('warn', 'nav-targets', `${unread.length} navigation target(s) built in a way this check does not follow, so NOT checked: ${unread.join(', ')}`);
+  if (!findings.some((f) => f.check === 'nav-targets' && f.level === 'error'))
+    add(
+      examined ? 'ok' : 'warn',
+      'nav-targets',
+      !examined
+        ? 'no region navigates anywhere — nothing was examined'
+        : unread.length
+          ? `the ${examined - unread.length} target(s) it could read resolve to a screen · ${unread.length} not checked (above)`
+          : `every navigation target resolves to a screen · ${examined} target(s) checked`,
+    );
+  return { findings, screens };
+}

package/src/lib/snapshots.mjs

@@ -0,0 +1,85 @@
+// Visual baselines — the gate for the one thing nothing else in motu looks at: what the island LOOKS
+// like.
+//
+// Everything else here proves structure: props match the component, keys have one owner, the region
+// mounts, the wiring resolves. None of it notices that a card lost its padding, that a heading now
+// wraps on a phone, or that editing the header moved the panel underneath it. An agent cannot see, and
+// a human reviewing a diff of TSX cannot either — so the harness has to.
+//
+// Baselines live beside the island's evidence, one per scenario × viewport, and are committed. A change
+// to them is a change to the UI, and it shows up in review as an image, which is exactly where a
+// reviewer can judge it.
+import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync } from 'node:fs';
+import { basename, resolve } from 'node:path';
+
+/** Where an island's baselines live: `<islands>/<kebab>.snapshots/`. */
+export function snapshotDir(islandsDir, kebab) {
+  return resolve(islandsDir, `${kebab}.snapshots`);
+}
+
+/** `<scenario>@<viewport>.png`, with anything filesystem-hostile flattened out of the scenario name. */
+export function snapshotName(scenario, viewport) {
+  const slug = String(scenario)
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-|-$/g, '');
+  return `${slug || 'default'}@${viewport}.png`;
+}
+
+/**
+ * Compare a fresh capture against its baseline.
+ *
+ * Returns `{ status, diffPixels, ratio }` where status is 'new' (no baseline yet), 'match',
+ * 'changed', or 'resized'. A size change is reported separately because pixel comparison is
+ * meaningless across dimensions, and because it is nearly always a layout change worth looking at.
+ */
+export async function compareSnapshot(baselinePath, actual) {
+  if (!existsSync(baselinePath)) return { status: 'new', diffPixels: 0, ratio: 0 };
+  return compareBuffers(readFileSync(baselinePath), actual);
+}
+
+/**
+ * The same comparison against BYTES rather than a path — what `--remote` needs, where the accepted
+ * baseline arrives over http and never touches the repository.
+ */
+export async function compareBuffers(baselineBytes, actual) {
+  const { PNG } = await import('pngjs');
+  const { default: pixelmatch } = await import('pixelmatch');
+  const before = PNG.sync.read(baselineBytes);
+  const after = PNG.sync.read(actual);
+  if (before.width !== after.width || before.height !== after.height) {
+    return { status: 'resized', diffPixels: 0, ratio: 1, from: [before.width, before.height], to: [after.width, after.height] };
+  }
+  const diff = new PNG({ width: before.width, height: before.height });
+  // A small threshold absorbs antialiasing differences without hiding a real change: anything a human
+  // would notice moves far more than a handful of pixels.
+  const diffPixels = pixelmatch(before.data, after.data, diff.data, before.width, before.height, { threshold: 0.12 });
+  const ratio = diffPixels / (before.width * before.height);
+  return { status: ratio > 0.001 ? 'changed' : 'match', diffPixels, ratio, diff: PNG.sync.write(diff) };
+}
+
+/** Write a baseline (and drop any stale `.actual`/`.diff` beside it). */
+export function writeBaseline(dir, file, png) {
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(resolve(dir, file), png);
+  for (const suffix of ['.actual.png', '.diff.png']) {
+    const stale = resolve(dir, file.replace(/\.png$/, suffix));
+    if (existsSync(stale)) rmSync(stale);
+  }
+}
+
+/** Write what was actually rendered + the diff, so a failure is inspectable rather than described. */
+export function writeFailureArtifacts(dir, file, actual, diff) {
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(resolve(dir, file.replace(/\.png$/, '.actual.png')), actual);
+  if (diff) writeFileSync(resolve(dir, file.replace(/\.png$/, '.diff.png')), diff);
+}
+
+/** Baselines with no scenario behind them any more — evidence was renamed or deleted. */
+export function orphanBaselines(dir, expected) {
+  if (!existsSync(dir)) return [];
+  const keep = new Set(expected);
+  return readdirSync(dir)
+    .filter((f) => f.endsWith('.png') && !f.endsWith('.actual.png') && !f.endsWith('.diff.png'))
+    .filter((f) => !keep.has(basename(f)));
+}

package/src/lib/stubs.mjs

@@ -0,0 +1,114 @@
+// The seam where the lagoon's isolation can become a lie.
+//
+// A host stub stands in for a real module so an island can render with no backend. Nothing checked
+// that it still stands in for all of it: in acme, two exports went missing from stubs and only
+// surfaced because the lagoon BUILD happened to import them — a bundler error, by luck. An export
+// nothing imports at build time would have gone unnoticed, and the lagoon would have been quietly
+// green about a module it no longer mirrors.
+//
+// What is checked here is what the ISLANDS actually reach for: every named import of an aliased
+// specifier, found by walking the import graph from each island's component. Demanding that a stub
+// mirror a module's whole surface would be noise — the real missions service exports twenty things and
+// the islands use four.
+import { existsSync, readFileSync, statSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { paths, resolveModuleSpecifier } from './util.mjs';
+import { listIslands, elementExportName } from './islands.mjs';
+
+/** The lagoon's alias table: app specifier -> stub file (absolute). */
+export function lagoonAliases() {
+  const file = resolve(paths.lagoonDir, 'lagoon.config.json');
+  if (!existsSync(file)) return [];
+  const alias = JSON.parse(readFileSync(file, 'utf8')).alias ?? {};
+  return Object.entries(alias).map(([specifier, target]) => ({
+    specifier,
+    stub: resolve(paths.lagoonDir, target),
+  }));
+}
+
+/** Named exports a module declares, by source text — enough for a name-level comparison. */
+function exportedNames(file) {
+  if (!existsSync(file)) return null;
+  const code = readFileSync(file, 'utf8')
+    .replace(/\/\*[\s\S]*?\*\//g, ' ')
+    .replace(/\/\/[^\n]*/g, ' ');
+  const names = new Set();
+  for (const m of code.matchAll(/export\s+(?:async\s+)?(?:function|const|let|var|class)\s+([A-Za-z_$][\w$]*)/g)) {
+    names.add(m[1]);
+  }
+  // `export { a, b as c }` — the exported NAME is what an importer writes, so take the alias when there
+  // is one.
+  for (const block of code.matchAll(/export\s*\{([^}]*)\}/g)) {
+    for (const entry of block[1].split(',')) {
+      const [, exported] = entry.trim().match(/(?:(\w+)\s+as\s+)?(\w+)/) ?? [];
+      if (exported) names.add(exported);
+    }
+  }
+  return names;
+}
+
+/** Type-only imports never reach the runtime, so a stub owes them nothing. */
+const TYPE_IMPORT = /^\s*import\s+type\b/;
+
+/**
+ * Every named import of `specifier` made by code an island can reach.
+ *
+ * Walks from each island's component through relative and aliased imports, staying inside the host's
+ * own sources. That set is what the lagoon bundles, which is the only set a stub has to satisfy.
+ */
+export function islandReachableImports(specifiers) {
+  const wanted = new Set(specifiers);
+  const found = new Map(specifiers.map((s) => [s, new Set()]));
+  const seen = new Set();
+  const queue = [];
+
+  for (const island of listIslands(paths.islandsDir)) {
+    const elementFile = island.element;
+    if (existsSync(elementFile)) queue.push(elementFile);
+    void elementExportName;
+  }
+
+  while (queue.length) {
+    const file = queue.shift();
+    // A specifier can resolve to a directory (an index import); there is nothing to read there.
+    if (seen.has(file) || !existsSync(file) || statSync(file).isDirectory()) continue;
+    seen.add(file);
+    const text = readFileSync(file, 'utf8');
+    for (const m of text.matchAll(/import\s+([^'"]*?)from\s*['"]([^'"]+)['"]/g)) {
+      const clause = m[1];
+      const spec = m[2];
+      if (wanted.has(spec) && !TYPE_IMPORT.test(m[0])) {
+        for (const named of clause.matchAll(/\{([^}]*)\}/g)) {
+          for (const entry of named[1].split(',')) {
+            const name = entry.trim().split(/\s+as\s+/)[0].trim().replace(/^type\s+/, '');
+            if (name && !entry.trim().startsWith('type ')) found.get(spec).add(name);
+          }
+        }
+      }
+      // Keep walking the app's own code; node_modules and motu's packages are not the host's to stub.
+      const next = resolveModuleSpecifier(spec, dirname(file));
+      if (next && !next.includes('node_modules')) queue.push(next);
+    }
+  }
+  return found;
+}
+
+/**
+ * Compare each stub against the real module, over what the islands import.
+ *
+ * Returns [{ specifier, stub, missing, unresolved }] — `missing` is the finding that matters: an
+ * island reaches for it, the stub does not have it.
+ */
+export function stubParity() {
+  const aliases = lagoonAliases();
+  if (!aliases.length) return [];
+  const used = islandReachableImports(aliases.map((a) => a.specifier));
+  return aliases.map(({ specifier, stub }) => {
+    const stubExports = exportedNames(stub);
+    const real = resolveModuleSpecifier(specifier, paths.lagoonDir);
+    const needed = [...(used.get(specifier) ?? [])];
+    if (!stubExports) return { specifier, stub, unresolved: 'stub file not found', missing: [], needed };
+    const missing = needed.filter((name) => !stubExports.has(name));
+    return { specifier, stub, real, missing, needed, unresolved: null };
+  });
+}

package/src/lib/ts-project.mjs

@@ -0,0 +1,42 @@
+// One ts-morph program per process, instead of one per question.
+//
+// Every static check used to build its own Project and re-parse the file it was about to read: the
+// component for the props check, the same component for the contract, the island file for coupling,
+// the island file again for the mount-point rules. Parsing is the expensive part of a static verify —
+// a sweep of fifteen islands spent most of its wall clock re-reading files it had already read.
+//
+// The projects here are keyed by compiler options and cached for the life of the command, so a file is
+// parsed once no matter how many checks ask about it. They are READ-ONLY: anything that rewrites
+// source (create, eject, integrate) keeps its own Project, because a shared one would carry another
+// command's edits.
+import { Project } from 'ts-morph';
+
+const projects = new Map();
+
+/** A shared, read-only Project for these compiler options. */
+export function sharedProject(compilerOptions = { allowJs: true }) {
+  const key = JSON.stringify(compilerOptions);
+  let project = projects.get(key);
+  if (!project) {
+    project = new Project({
+      skipAddingFilesFromTsConfig: true,
+      skipFileDependencyResolution: true,
+      compilerOptions,
+    });
+    projects.set(key, project);
+  }
+  return project;
+}
+
+/**
+ * The source file at `path`, parsed at most once.
+ *
+ * `refreshFromFileSystemSync` is deliberate rather than paranoid: a long-running command (the lagoon's
+ * watch mode) can ask about a file that changed since it was first read.
+ */
+export function sourceFileAt(path, compilerOptions) {
+  const project = sharedProject(compilerOptions);
+  const existing = project.getSourceFile(path);
+  if (existing) return existing;
+  return project.addSourceFileAtPath(path);
+}