@motujs/cli 0.0.0-stage → 0.1.0

package/src/lib/contracts.mjs

@@ -0,0 +1,244 @@
+// The generated half of an island's declaration.
+//
+// An island file used to open with twenty lines transcribing its own component: the props, the
+// callback props as events, the host modules it imports. All three are FACTS about code that already
+// exists a few directories away, and a fact is not something to review — it is something to derive.
+// What was left after removing them is what a person actually decided: the tag, the component, and
+// where an event's name differs from the callback's.
+//
+// So `motu sync` writes them here, once, for every island, and the island file reads its own
+// entry back through the generated `island()` helper. The map is `as const`, so `EventsOf` still sees
+// literal event names and `RegionWiringOk` still fails the build on a mistyped wire — the guarantees
+// are unchanged, the transcription is gone.
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, relative, resolve, sep } from 'node:path';
+import { readComponentContract } from './component-props.mjs';
+import { listIslands } from './islands.mjs';
+import { readEffectEntries, writeEffectEntry } from './effects.mjs';
+
+export const CONTRACTS_FILE = 'contracts.generated.ts';
+
+/** The `events` override an island file passes to `island()`: callback prop -> the region's word. */
+function eventOverrides(text) {
+  const at = text.indexOf('events:');
+  if (at === -1) return {};
+  const open = text.indexOf('{', at);
+  if (open === -1) return {};
+  let depth = 0;
+  for (let i = open; i < text.length; i++) {
+    if (text[i] === '{') depth++;
+    else if (text[i] === '}' && --depth === 0) {
+      const body = text.slice(open + 1, i);
+      return Object.fromEntries([...body.matchAll(/(\w+)\s*:\s*'([^']+)'/g)].map((m) => [m[1], m[2]]));
+    }
+  }
+  return {};
+}
+
+/** The component an island file mounts: `{ name, from }`, read off its own import. */
+function componentImport(text) {
+  const name =
+    text.match(/\bcomponent\s*:\s*([A-Za-z_$][\w$]*)/)?.[1] ??
+    text.match(/\bisland\(\s*'[^']+'\s*,\s*([A-Za-z_$][\w$]*)/)?.[1];
+  if (!name) return null;
+  for (const m of text.matchAll(/import\s+(?:type\s+)?\{([^}]*)\}\s*from\s*'([^']+)';/g)) {
+    for (const entry of m[1].split(',')) {
+      const [exported, alias] = entry.split(/\s+as\s+/).map((n) => n.trim());
+      if ((alias ?? exported) === name) return { name: exported, from: m[2] };
+    }
+  }
+  return null;
+}
+
+/** What one island declares about itself, read from its file and its component. */
+const islandCache = new Map();
+
+export function islandContract(island, util) {
+  const cached = islandCache.get(island.element);
+  if (cached) return cached;
+  const result = islandContractUncached(island, util);
+  islandCache.set(island.element, result);
+  return result;
+}
+
+function islandContractUncached(island, { islandComponentPath, islandComponentExport, names }) {
+  const text = readFileSync(island.element, 'utf8');
+  const component = componentImport(text);
+  const tag = (text.match(/\btag:\s*'([^']+)'/) ?? text.match(/\bisland\(\s*'([^']+)'/))?.[1] ?? `x-${island.kebab}`;
+  const { pascal } = names(island.kebab);
+  const contract = readComponentContract(islandComponentPath(island.kebab, pascal), islandComponentExport(island.kebab, pascal));
+  const overrides = eventOverrides(text);
+  const output = {};
+  for (const o of contract?.output ?? []) output[o.prop] = overrides[o.prop] ?? o.event;
+  // An override for a callback the component does not have is a wire that can never fire; keep it out
+  // of the generated map so `RegionWiringOk` reports it instead of blessing it.
+  return {
+    tag,
+    kebab: island.kebab,
+    input: contract?.input ?? [],
+    output,
+    effects: contract?.effects ?? [],
+    read: !!contract,
+    component,
+    // WHERE THE SPECIFIER WAS AUTHORED. `component.from` is copied verbatim off the island's own
+    // import, and the island file is not where it lands: a `folder` island sits one directory
+    // deeper than `contracts.generated.ts`, so a RELATIVE specifier written there resolves one
+    // level too high once it is re-emitted here. Keeping the authoring directory is what lets
+    // `renderContracts` rebase it. Alias and bare specifiers are depth-independent and are why this
+    // went unseen — every consumer that used `@/…` was already correct.
+    elementDir: dirname(island.element),
+  };
+}
+
+/** Every island's contract, as it will be generated. */
+export function projectContracts(islandsDir, util) {
+  return listIslands(islandsDir).map((i) => islandContract(i, util));
+}
+
+/** Render `contracts.generated.ts`. */
+/**
+ * The specifier as `contracts.generated.ts` must spell it.
+ *
+ * Relative specifiers are re-anchored from the island file's directory onto the generated file's;
+ * anything else (an alias like `@/…`, a bare package name) is depth-independent and passes through.
+ */
+function specifierFrom(component, elementDir, outDir) {
+  const spec = component.from;
+  if (!spec.startsWith('.') || !elementDir || !outDir) return spec;
+  const rebased = relative(outDir, resolve(elementDir, spec)).split(sep).join('/');
+  return rebased.startsWith('.') ? rebased : `./${rebased}`;
+}
+
+export function renderContracts(contracts, outDir) {
+  const entry = (c) => {
+    const input = c.input.map((p) => `'${p}'`).join(', ');
+    const output = Object.entries(c.output).map(([prop, ev]) => `${prop}: '${ev}'`).join(', ');
+    // Written back in the AUTHORED form, so the generated file reads like a hand-written one and a
+    // person diffing it sees the same vocabulary they would type.
+    const effects = c.effects.map((a) => writeEffectEntry(a)).join(', ');
+    return [
+      `  '${c.tag}': {`,
+      `    input: [${input}],`,
+      `    output: { ${output} },`,
+      `    effects: [${effects}],`,
+      '  },',
+    ].join('\n');
+  };
+  const withComponent = contracts.filter((c) => c.component);
+  const local = (c) => `C_${c.kebab.replace(/-/g, '_')}`;
+  const imports = withComponent
+    .map(
+      (c) =>
+        `import type { ${c.component.name} as ${local(c)} } from '${specifierFrom(c.component, c.elementDir, outDir)}';`,
+    )
+    .join('\n');
+  const assertions = withComponent
+    .map(
+      (c) =>
+        `const _${c.kebab.replace(/-/g, '_')}: ContractFitsComponent<typeof ${local(c)}, '${c.tag}'> = true;\n` +
+        `void _${c.kebab.replace(/-/g, '_')};`,
+    )
+    .join('\n');
+  return `// GENERATED by \`motu sync\` — do not edit by hand.
+//
+// Each island's boundary, READ from the component it mounts: the props it takes, the callback props it
+// calls (as event names), and everything it reaches that is not a prop. Editing the component changes this file;
+// editing this file changes nothing.
+//
+// The one part that is a decision — an event whose region name differs from the callback's — is
+// declared in the island file, as \`island(tag, Component, { events: { onProgress: 'week-progress' } })\`,
+// and baked in here so the compiler still sees literal event names.
+import { islandElement } from '@motujs/react';
+${imports}
+
+export const CONTRACTS = {
+${contracts.map(entry).join('\n')}
+} as const;
+
+type Tag = keyof typeof CONTRACTS;
+
+type PropsOf<C> = C extends (props: infer P, ...rest: never[]) => unknown ? NonNullable<P> : never;
+
+/**
+ * The generated contract names only props the component actually has — as a BUILD error.
+ *
+ * Reading the contract from the component removes the chance of transcribing it wrong, but not the
+ * chance of the file going stale: rename a prop and this map still names the old one until the next
+ * sync. The assertions below are what makes that a compile failure instead of an island that mounts
+ * with a prop nobody fills. Type-only, so nothing here reaches a bundle.
+ */
+type ContractFitsComponent<C, T extends Tag> = [
+  Exclude<
+    (typeof CONTRACTS)[T]['input'][number] | keyof (typeof CONTRACTS)[T]['output'],
+    keyof PropsOf<C>
+  >,
+] extends [never]
+  ? true
+  : ['contract is stale — run \`motu sync\`; the component has no such prop:', Exclude<
+      (typeof CONTRACTS)[T]['input'][number] | keyof (typeof CONTRACTS)[T]['output'],
+      keyof PropsOf<C>
+    >];
+
+${assertions}
+
+/**
+ * Declare an island: its tag, the component it mounts, and nothing that can be derived.
+ *
+ * \`options.events\` is read by \`motu sync\` (it is what produced the output names above) and
+ * applied here too, so the island is correct even before the next sync.
+ */
+export function island<T extends Tag>(
+  tag: T,
+  component: Parameters<typeof islandElement>[0]['component'],
+  options?: Record<string, unknown> & { events?: Record<string, string> },
+): ReturnType<typeof islandElement> & { options: { contract: (typeof CONTRACTS)[T] } } {
+  const { events, ...rest } = options ?? {};
+  const base = CONTRACTS[tag];
+  const spec = { tag, component, options: { ...rest, contract: { ...base, output: { ...base.output, ...(events ?? {}) } } } };
+  return islandElement(spec as never) as never;
+}
+`;
+}
+
+/** Write the contracts file. Returns { path, count, changed }. */
+export function syncContracts(islandsDir, util) {
+  const out = resolve(islandsDir, CONTRACTS_FILE);
+  const next = renderContracts(projectContracts(islandsDir, util), islandsDir);
+  const changed = !existsSync(out) || readFileSync(out, 'utf8') !== next;
+  if (changed) writeFileSync(out, next);
+  return { path: out, count: listIslands(islandsDir).length, changed };
+}
+
+/** Is the committed file what the components say it should be? (`motu check`'s drift gate.) */
+export function contractsDrift(islandsDir, util) {
+  const out = resolve(islandsDir, CONTRACTS_FILE);
+  if (!existsSync(out)) return { missing: true, drifted: false };
+  const next = renderContracts(projectContracts(islandsDir, util), islandsDir);
+  return { missing: false, drifted: readFileSync(out, 'utf8') !== next };
+}
+
+/**
+ * The generated contracts as data, read from the file rather than recomputed.
+ *
+ * Eject needs the event names an island declares, and after the short form there is nowhere else to
+ * read them: the island file names its component and nothing more. Parsing the generated file keeps
+ * eject working off exactly what the build compiled.
+ */
+export function readGeneratedContracts(islandsDir) {
+  const file = resolve(islandsDir, CONTRACTS_FILE);
+  if (!existsSync(file)) return {};
+  const text = readFileSync(file, 'utf8');
+  const start = text.indexOf('export const CONTRACTS');
+  if (start === -1) return {};
+  const out = {};
+  const re = /'([^']+)':\s*\{\s*input:\s*\[([^\]]*)\],\s*output:\s*\{([^}]*)\},\s*effects:\s*\[([\s\S]*?)\],\n/g;
+  for (const m of text.slice(start).matchAll(re)) {
+    const list = (body) => [...body.matchAll(/'([^']+)'/g)].map((x) => x[1]);
+    out[m[1]] = {
+      input: list(m[2]),
+      output: Object.fromEntries([...m[3].matchAll(/(\w+):\s*'([^']+)'/g)].map((x) => [x[1], x[2]])),
+      effects: readEffectEntries(m[4]),
+    };
+  }
+  return out;
+}

package/src/lib/data-flow.mjs

@@ -0,0 +1,47 @@
+// The `data-flow` judgement, shared by both lanes (the browser in playwright-lagoon.mjs and the
+// browser-free `--fast` harness in runtime-harness.mjs) so they cannot disagree about one island.
+//
+// DISTINCT INPUTS MUST PRODUCE DISTINCT OUTPUT, and a scenario that renders NOTHING cannot be compared
+// — unless it says so. `blank: 'why'` on a scenario declares that rendering nothing IS its answer (a
+// banner silent when nothing is wrong, a palette closed). Declared, the empty render is a value like
+// any other in the comparison — and it is ASSERTED: a blank scenario that renders something fails,
+// so the declaration cannot go stale quietly. Undeclared, an empty render is still an error.
+//
+// This exists because two of motu's own checks disagreed: `data-flow` refused every empty scenario
+// while `input-coverage` asked for exactly those states, and Peps (13 islands) and motu's host-app
+// (2) were red on scenarios their authors had pinned on purpose. Deleting them was the only way out,
+// and it threw away the state the input-coverage check had asked for.
+
+/** The scenario's declared reason for rendering nothing, or null. An empty reason is no declaration. */
+export const blankReason = (scenario) =>
+  typeof scenario?.blank === 'string' && scenario.blank.trim() !== '' ? scenario.blank.trim() : null;
+
+/**
+ * @param {string[]} outputs  the normalised render of each scenario, in order
+ * @param {object[]} scenarios
+ */
+export function judgeRenders(outputs, scenarios) {
+  const name = (i) => scenarios[i]?.name ?? `#${i + 1}`;
+  const empty = []; // rendered nothing and did not say it would
+  const blankButRendered = []; // said it would render nothing, and rendered something
+  outputs.forEach((o, i) => {
+    const isEmpty = !o.trim().length;
+    const declared = blankReason(scenarios[i]) !== null;
+    if (isEmpty && !declared) empty.push(name(i));
+    if (!isEmpty && declared) blankButRendered.push(name(i));
+  });
+  const distinctOutputs = new Set(outputs).size;
+  // Declared-blank scenarios all promise the SAME render — nothing — so several of them are one
+  // expected value, not duplicate evidence. Counted once when asking "did any two scenarios collide?".
+  const blanks = scenarios.filter((s, i) => blankReason(s) !== null && !outputs[i]?.trim()).length;
+  const comparedCount = outputs.length - Math.max(0, blanks - 1);
+  const differentiates = empty.length === 0 && blankButRendered.length === 0 && distinctOutputs > 1;
+  return { differentiates, empty, blankButRendered, distinctOutputs, comparedCount };
+}
+
+/**
+ * Every input a scenario hands the island — its `seed` and what arrives `afterMount` — for the checks
+ * that ask about inputs rather than about WHEN they land (seed transport, input coverage, the keys a
+ * reset must forget). The later value wins, as it does on screen.
+ */
+export const scenarioInputs = (scenario) => ({ ...(scenario?.seed ?? {}), ...(scenario?.afterMount ?? {}) });

package/src/lib/declared-sources.mjs

@@ -0,0 +1,101 @@
+// `sources` from an archipelago, read ONCE and by a parser.
+//
+// WHY THIS FILE EXISTS. Two commands read the same declaration, and each had grown its own regex over
+// it: `verify` handled both forms, `integrate check` handled only `{ module, produces }` and silently
+// skipped `week: weekSource`. So moving a region to the STRONGER declaration — the source imported by
+// reference, which the type system checks — quietly turned off the check that says the page installs
+// it. The better declaration got less checking, and nothing said so.
+//
+// That is what two hand-rolled readers of one shape always end up doing. `integration.mjs` had
+// already reached this conclusion for the host's JSX ("PARSED, NOT MATCHED … ts-morph is already how
+// every other host-source question here is answered; this was the last regex standing in the middle
+// of it") — it was not the last: the archipelago side was still matched, in both files.
+//
+// The scars are worth keeping in view. `verify.mjs` blanks comments before matching, because an
+// apostrophe in prose opens a string as far as a regex is concerned and "the week's missions" turned
+// into a key named ` missions, so it comes...`. `\n  \},` as a block terminator means the declaration
+// must be indented exactly two spaces. Neither is a property of the language; both are properties of
+// reading it with the wrong tool.
+import { SyntaxKind } from 'ts-morph';
+import { sourceFileAt } from './ts-project.mjs';
+
+/** Strip the quotes ts-morph keeps on a string literal's text. */
+const unquoted = (node) => (node?.getText?.() ?? '').replace(/^['"`]|['"`]$/g, '');
+
+/**
+ * Where an identifier came from — the import that brought it in.
+ *
+ * A source declared by reference names its module exactly once, in the import, which is the fact the
+ * regex was reconstructing with a RegExp built from the identifier's own name.
+ */
+function moduleOfIdentifier(sourceFile, name) {
+  for (const decl of sourceFile.getImportDeclarations()) {
+    const named = decl.getNamedImports().some((i) => (i.getAliasNode() ?? i.getNameNode()).getText() === name);
+    const dflt = decl.getDefaultImport()?.getText() === name;
+    if (named || dflt) return decl.getModuleSpecifierValue();
+  }
+  return null;
+}
+
+/**
+ * Every declared source of one archipelago file.
+ *
+ * Returns `{ [name]: { module, produces, byReference, reachesText } }` — both declaration forms, in
+ * one shape, so a caller cannot handle one and forget the other. `reachesText` is the raw initializer
+ * of `reaches` (or null), because its entries are a mix of strings and objects that each caller
+ * already knows how to read.
+ *
+ * An unparseable file yields `{}` rather than throwing: this answers "what does the region declare",
+ * and a file the host's own build accepts but ts-morph does not is not a question about sources.
+ */
+export function declaredSourcesOf(archipelagoFile) {
+  let sf;
+  try {
+    sf = sourceFileAt(archipelagoFile, { allowJs: true });
+  } catch {
+    return {};
+  }
+
+  // The `sources:` property of the archipelago's config object. Found by NAME rather than by walking
+  // the call expression, because the config is written as `archipelago<…>()({ … } as const, { … })`
+  // and the shape of that wrapper is not this function's business.
+  const prop = sf
+    .getDescendantsOfKind(SyntaxKind.PropertyAssignment)
+    .find((p) => (p.getNameNode?.()?.getText?.() ?? '').replace(/['"]/g, '') === 'sources');
+  const obj = prop?.getInitializerIfKind?.(SyntaxKind.ObjectLiteralExpression);
+  if (!obj) return {};
+
+  const out = {};
+  for (const entry of obj.getProperties()) {
+    if (!entry.getNameNode) continue;
+    const name = (entry.getNameNode().getText() ?? '').replace(/['"]/g, '');
+    const init = entry.getInitializer?.();
+    if (!init) continue;
+
+    // `week: weekSource` — the source object itself. What it produces lives in the source file and is
+    // checked by the compiler there, so there is nothing to read here but the module.
+    if (init.getKind() === SyntaxKind.Identifier) {
+      const module = moduleOfIdentifier(sf, init.getText());
+      if (module) out[name] = { module, produces: [], byReference: true, reachesText: null };
+      continue;
+    }
+
+    // `revenue: { module: '…', produces: [...] }` — a claim about somebody else's code.
+    if (init.getKind() === SyntaxKind.ObjectLiteralExpression) {
+      const moduleProp = init.getProperty?.('module');
+      const module = unquoted(moduleProp?.getInitializer?.());
+      if (!module) continue;
+      const producesInit = init.getProperty?.('produces')?.getInitializer?.();
+      const produces = (producesInit?.getElements?.() ?? []).map((el) => unquoted(el));
+      const reaches = init.getProperty?.('reaches')?.getInitializer?.();
+      out[name] = {
+        module,
+        produces,
+        byReference: false,
+        // The INNER text of the array, which is what the existing effect readers take.
+        reachesText: reaches?.getText?.()?.replace(/^\[|\]$/g, '') ?? null,
+      };
+    }
+  }
+  return out;
+}

package/src/lib/dock-inject.mjs

@@ -0,0 +1,47 @@
+// THE DOCK, INJECTED — one definition, three consumers.
+//
+// `motu lagoon serve` serves a built artifact, the Vite DEV server serves a module graph, and the
+// motu host frames a published one. All three must draw the SAME dock: a copy per consumer is two
+// chromes that drift, and the dev loop and every runtime check run through this one, so a divergence
+// here is a divergence between what a person sees while working and what the checks assert on.
+//
+// It lived in `lagoon.mjs` and was therefore reachable only from `lagoon serve` — which is why
+// `motu lagoon dev` had no dock at all while the documentation said it did.
+import { motuDockCss, motuDockJs } from '@motujs/chrome/dock';
+
+/** Append the dock to a page's HTML. It takes over only a lagoon it can drive; see the script below. */
+export function injectDock(page) {
+  return `${page}
+<style>${motuDockCss()}</style>
+<script>
+${motuDockJs()}
+(function () {
+  var tries = 0;
+  var take = function () {
+    if (tries++ > 60) return;
+    if (!window.__motuLagoonControl) return setTimeout(take, 200);
+    // The artifact still ships its own while both exist. Hidden, not removed: it owns that element.
+    // THE TWO DOCKS SHARE AN ID, and here they share a document as well — so the rule that hides the
+    // artifact's would hide the replacement with it. In the host that never came up: the artifact is
+    // in a frame and the new dock is in the shell. Mark ours, and hush only what is not ours.
+    var mounted = document.createElement('div');
+    mounted.setAttribute('data-motu-chrome', '');
+    document.body.appendChild(mounted);
+    motuMountDock({ mount: mounted, lagoonWindow: function () { return window; } });
+    var ours = mounted.querySelector('#tide');
+    if (ours) ours.setAttribute('data-hosted', '');
+    var hush = document.createElement('style');
+    hush.textContent = '#tide:not([data-hosted]){display:none!important}' +
+      // THE FLOATING TOOLBAR TOO. It used to be adopted by the in-page dock; with that gone it falls
+      // back to floating over the application, and its chips are already in the rig out here.
+      '#motu-toolbar{display:none!important}';
+    document.head.appendChild(hush);
+    // The served page is the lagoon itself, so the dock stands on this document and this document
+    // keeps the strip — the same reserve the host's shell makes around a framed one.
+    document.documentElement.dataset.motuDock =
+      window.matchMedia('(max-width: 760px)').matches ? 'bottom' : 'right';
+  };
+  take();
+})();
+</script>`;
+}

package/src/lib/effects.mjs

@@ -0,0 +1,97 @@
+// `contract.effects` / `reaches`, between the form people WRITE and the form checks COMPARE.
+//
+// Authored as objects — `{ table: 'shots', operation: 'select' }` — so a misspelled kind is a build
+// error rather than an entry nothing recognises. Compared as a canonical STRING, because that is what
+// the runtime records: the fake fetch tags every request at the moment it is made and has no view of
+// anyone's declaration. Normalising the declaration to the observation, rather than the other way
+// round, is what keeps `@motujs/runtime` free of this vocabulary entirely.
+//
+// The canonical forms, which are exactly `reachEntry()` in `postgrest-fetch.ts`:
+//
+//   '@/lib/x'              a host module — the bare form, unchanged
+//   'scope:search'
+//   'table:shots(select)'  and 'table:shots' when no operation is named
+//   'rpc:accept_shots'
+//   'fn:notify'
+//   'route:GET /api/x'     and 'route:/api/x' when no method is named
+
+/** The kinds that are NOT a host module. A bare entry has no prefix, which is what makes it a module. */
+const KINDS = /^(scope|table|rpc|fn|route):/;
+
+/** True for a canonical entry that names something other than a host module. */
+export const isKinded = (canonical) => KINDS.test(String(canonical));
+
+/** True for a canonical entry the runtime can observe — the data kinds, as opposed to scope/module. */
+export const isDataKind = (canonical) => /^(table|rpc|fn|route):/.test(String(canonical));
+
+/**
+ * One authored entry as its canonical string, or null when it is not a shape we know.
+ *
+ * `null` rather than a throw: this runs over source text the user is mid-edit in, and a check that
+ * crashes on a half-written declaration is worse than one that ignores it — the TYPE is what rejects a
+ * bad entry, and it does so at the line where it was written.
+ */
+export function canonicalEffect(entry) {
+  if (typeof entry === 'string') return entry;
+  if (!entry || typeof entry !== 'object') return null;
+  if (entry.scope) return `scope:${entry.scope}`;
+  if (entry.rpc) return `rpc:${entry.rpc}`;
+  if (entry.fn) return `fn:${entry.fn}`;
+  if (entry.table) return entry.operation ? `table:${entry.table}(${entry.operation})` : `table:${entry.table}`;
+  if (entry.route) return entry.method ? `route:${entry.method} ${entry.route}` : `route:${entry.route}`;
+  return null;
+}
+
+/**
+ * Does a DECLARED entry account for an OBSERVED one?
+ *
+ * Equal, or the declaration is the same thing with its qualifier left off — `{ table: 'shots' }` covers
+ * every operation on that table, `{ route: '/api/x' }` every method on that route. Naming a dependency
+ * without pinning how it is used is a legitimate declaration, and the qualifier sits in a different
+ * place for each kind (a suffix for a table, a prefix for a route), which is why this is a function
+ * rather than a string comparison.
+ */
+export function coversEffect(declared, observed) {
+  if (declared === observed) return true;
+  const d = String(declared);
+  const o = String(observed);
+  if (d.startsWith('table:') && o.startsWith('table:')) return o.replace(/\(.*\)$/, '') === d;
+  if (d.startsWith('route:') && o.startsWith('route:')) return o.replace(/^route:\S+ /, 'route:') === d;
+  return false;
+}
+
+/**
+ * The entries in an `effects: [...]` / `reaches: [...]` array, read from SOURCE TEXT.
+ *
+ * A tolerant reader rather than a parser: the array holds literals only — quoted strings and flat
+ * object literals of quoted values — because that is all the type admits. It is used on the island
+ * file, on a source module, and on the generated contracts, so the one implementation keeps those
+ * three from disagreeing about what a declaration says.
+ */
+export function readEffectEntries(arrayBody) {
+  if (!arrayBody) return [];
+  const out = [];
+  for (const [, obj] of arrayBody.matchAll(/\{([^}]*)\}/g)) {
+    const fields = {};
+    for (const [, k, v] of obj.matchAll(/(\w+)\s*:\s*['"]([^'"]*)['"]/g)) fields[k] = v;
+    const canonical = canonicalEffect(fields);
+    if (canonical) out.push(canonical);
+  }
+  // Bare strings are whatever is quoted OUTSIDE an object literal — the module entries.
+  for (const [, str] of arrayBody.replace(/\{[^}]*\}/g, '').matchAll(/['"]([^'"]+)['"]/g)) out.push(str);
+  return out;
+}
+
+/** Serialise a canonical entry back to the AUTHORED form, for anything that generates a declaration. */
+export function writeEffectEntry(canonical) {
+  const s = String(canonical);
+  if (!isKinded(s)) return `'${s}'`;
+  const [, kind, rest] = s.match(/^(\w+):(.*)$/);
+  if (kind === 'scope' || kind === 'rpc' || kind === 'fn') return `{ ${kind}: '${rest}' }`;
+  if (kind === 'table') {
+    const m = rest.match(/^(.*)\((.*)\)$/);
+    return m ? `{ table: '${m[1]}', operation: '${m[2]}' }` : `{ table: '${rest}' }`;
+  }
+  const m = rest.match(/^(\S+) (.*)$/);
+  return m ? `{ route: '${m[2]}', method: '${m[1]}' }` : `{ route: '${rest}' }`;
+}