@starci/hfs 5.0.8 → 5.1.0

package/codemod/main.mjs

@@ -7,11 +7,13 @@ import { migrateSectionFrame, sectionFrameMarkdown } from './section-frame.mjs';
 import { migrateSmallRenames, smallRenamesMarkdown } from './small-renames.mjs';
 import { migrateSpacingRoles, spacingRolesMarkdown } from './spacing-roles.mjs';
 import { migrateSurfaceCardKinds, surfaceCardKindsMarkdown } from './surface-card-kinds.mjs';
+import { explicitSurfaceMarkdown, migrateExplicitSurface } from './explicit-surface.mjs';
+import { directiveFirstMarkdown, migrateDirectiveFirst } from './directive-first.mjs';
 import { migrateThemeTokens, themeTokensMarkdown } from './theme-tokens.mjs';
 import { migrateTierBinding, tierBindingMarkdown } from './tier-binding.mjs';
 /** The codemods `starci app codemod` runs, by name. */
-export const CODEMODS = Object.freeze(['button-intent', 'spacing-roles', 'theme-tokens', 'small-renames', 'page-navigation', 'section-frame', 'surface-card-kinds', 'tier-binding', 'loading-states']);
-/** The arguments of `starci app codemod spacing-roles`, `theme-tokens`, `small-renames`, `page-navigation`, `section-frame`, `surface-card-kinds`, `tier-binding` and `loading-states`: --execute, --json, --format and --out; any other is refused. */
+export const CODEMODS = Object.freeze(['button-intent', 'spacing-roles', 'theme-tokens', 'small-renames', 'page-navigation', 'section-frame', 'surface-card-kinds', 'tier-binding', 'loading-states', 'explicit-surface', 'directive-first']);
+/** The arguments of every report-style `starci app codemod`: --execute, --json, --format and --out; any other is refused. */
 export function spacingRolesArguments(argv) {
     const options = { write: false, format: 'markdown' };
     const args = argv.values();
@@ -44,6 +46,10 @@ export function spacingRolesArguments(argv) {
 }
 /** One of the report-style codemods run at an app root: its report object and the Markdown of it. */
 function runCodemod(name, root, write) {
+    if (name === 'directive-first') {
+        const report = migrateDirectiveFirst({ root, write });
+        return { report, markdown: directiveFirstMarkdown(report) };
+    }
     if (name === 'theme-tokens') {
         const report = migrateThemeTokens({ root, write });
         return { report, markdown: themeTokensMarkdown(report) };
@@ -75,6 +81,30 @@ function runCodemod(name, root, write) {
     const report = migrateSpacingRoles({ root, write });
     return { report, markdown: spacingRolesMarkdown(report) };
 }
+/** The report written where the options say (`--out`) and to stdout; the exit code is 1 when a case is left for a person. */
+function emit(options, result, io) {
+    const output = options.format === 'json' ? `${JSON.stringify(result.report, null, 2)}\n` : result.markdown;
+    if (options.out) {
+        const target = path.resolve(io.cwd, options.out);
+        fs.mkdirSync(path.dirname(target), { recursive: true });
+        fs.writeFileSync(target, output);
+    }
+    io.stdout(output);
+    return result.report.findings.length ? 1 : 0;
+}
+/** The arguments of a report-style codemod: spacingRolesArguments, and a report file that is JSON or Markdown. */
+function reportArguments(argv) {
+    const options = spacingRolesArguments(argv);
+    if (options.out && !/\.(?:json|md)$/i.test(options.out))
+        throw new Error('--out needs a .json or .md report file');
+    return options;
+}
+/** `starci app codemod explicit-surface`: it reads the app's types through the compiler and formats with its Prettier, both asynchronous. */
+async function explicitSurfaceMain(argv, io) {
+    const options = reportArguments(argv);
+    const report = await migrateExplicitSurface({ root: path.resolve(io.cwd), write: options.write });
+    return emit(options, { report, markdown: explicitSurfaceMarkdown(report) }, io);
+}
 /**
  * CLI boundary of `starci app codemod <name>`. Dry run by default; --execute writes only the safe rewrites. A codemod
  * that leaves a case for a person exits 1 with the complete report.
@@ -83,19 +113,10 @@ export function codemodMain(argv, io) {
     const [name, ...rest] = argv;
     if (name === 'button-intent')
         return buttonIntentMain(argv, io);
-    if (name !== 'spacing-roles' && name !== 'theme-tokens' && name !== 'small-renames' && name !== 'page-navigation' && name !== 'section-frame' && name !== 'surface-card-kinds' && name !== 'tier-binding' && name !== 'loading-states')
+    if (name === 'explicit-surface')
+        return explicitSurfaceMain(rest, io);
+    if (name === undefined || !CODEMODS.includes(name))
         throw new Error(`starci app codemod takes ${CODEMODS.join(' or ')}`);
-    const options = spacingRolesArguments(rest);
-    if (options.out && !/\.(?:json|md)$/i.test(options.out))
-        throw new Error('--out needs a .json or .md report file');
-    const root = path.resolve(io.cwd);
-    const { report, markdown } = runCodemod(name, root, options.write);
-    const output = options.format === 'json' ? `${JSON.stringify(report, null, 2)}\n` : markdown;
-    if (options.out) {
-        const target = path.resolve(io.cwd, options.out);
-        fs.mkdirSync(path.dirname(target), { recursive: true });
-        fs.writeFileSync(target, output);
-    }
-    io.stdout(output);
-    return report.findings.length ? 1 : 0;
+    const options = reportArguments(rest);
+    return emit(options, runCodemod(name, path.resolve(io.cwd), options.write), io);
 }

package/codemod/source-tree.d.mts

@@ -0,0 +1,8 @@
+/** Folders no codemod enters: installed packages, build output and caches. */
+export declare const GENERATED: Set<string>;
+/** The folders of an app a codemod reads source from: the `be` and `fe` sides, else `src` of a single-side app, as absolute paths. */
+export declare function sideFolders(root: string): string[];
+/** Every file under `directory` whose name matches `pattern`, sorted, without descending into generated folders. */
+export declare function filesUnder(directory: string, pattern: RegExp): string[];
+/** The posix path of `target` relative to `root`, the way a report names a file. */
+export declare const relativePosix: (root: string, target: string) => string;

package/codemod/source-tree.mjs

@@ -0,0 +1,23 @@
+import fs from 'node:fs';
+import path from 'node:path';
+/** Folders no codemod enters: installed packages, build output and caches. */
+export const GENERATED = new Set(['node_modules', '.next', '.turbo', 'dist', 'build', 'out', 'coverage', '.git', 'storybook-static']);
+/** The folders of an app a codemod reads source from: the `be` and `fe` sides, else `src` of a single-side app, as absolute paths. */
+export function sideFolders(root) {
+    const isFolder = (folder) => fs.statSync(folder, { throwIfNoEntry: false })?.isDirectory() === true;
+    const sides = ['be', 'fe'].map(name => path.join(root, name)).filter(isFolder);
+    if (sides.length)
+        return sides;
+    return ['src'].map(name => path.join(root, name)).filter(isFolder);
+}
+/** Every file under `directory` whose name matches `pattern`, sorted, without descending into generated folders. */
+export function filesUnder(directory, pattern) {
+    return fs.readdirSync(directory, { withFileTypes: true }).flatMap(entry => {
+        const target = path.join(directory, entry.name);
+        if (entry.isDirectory())
+            return GENERATED.has(entry.name) ? [] : filesUnder(target, pattern);
+        return entry.isFile() && pattern.test(entry.name) ? [target] : [];
+    }).sort();
+}
+/** The posix path of `target` relative to `root`, the way a report names a file. */
+export const relativePosix = (root, target) => path.relative(root, target).split(path.sep).join('/');

package/lint/eslint-list.cjs

@@ -1,4 +1,12 @@
 "use strict";
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 // eslint-list.cts - ESLint over a list of files in ONE process, through the app's own install (the Node API of the ESLint the side's folder resolves).
 //
@@ -7,9 +15,28 @@ Object.defineProperty(exports, "__esModule", { value: true });
 // argument ({ files, fix }), lints it once from its working directory (the side folder) and prints the results as the `--format json` of the CLI
 // does (the list of result objects), so the launcher validates them the same way. Its exit code is the CLI's: 0 clean of errors, 1 at least one
 // error, 2 the run could not complete (the message is on stderr). It stays CommonJS like bound-sys.cts, which may be preloaded in front of it.
+//
+// The project graph the canon's graph rules read is built in this process, once per side. When the job names the canons (`graph.canons`, the entry file
+// of each installed canon) and a file (`graph.out`), the runner asks each canon for the snapshot of the graph it built (`projectGraphSnapshot`) after
+// the lint and writes `{ snapshots }` there, so the cache keeps the graph findings without building the graph a second time in the CLI. A canon that
+// cannot answer leaves its snapshot out; the report and the exit code are never affected.
 const fs = require('node:fs');
 const path = require('node:path');
 const { createRequire } = require('node:module');
+const { pathToFileURL } = require('node:url');
+/** Writes the snapshot of the graph each named canon built in this process; a canon that cannot answer is left out. */
+async function handOutGraph(handoff, repoRoot) {
+    const snapshots = {};
+    for (const { name, entry } of handoff.canons) {
+        try {
+            const canon = await import(__rewriteRelativeImportExtension(pathToFileURL(entry).href));
+            if (typeof canon.projectGraphSnapshot === 'function')
+                snapshots[name] = canon.projectGraphSnapshot({ repoRoot });
+        }
+        catch { /* the cache builds this canon's graph itself */ }
+    }
+    fs.writeFileSync(handoff.out, JSON.stringify({ snapshots }));
+}
 async function main() {
     const job = JSON.parse(fs.readFileSync(String(process.argv[2]), 'utf8'));
     const cwd = process.cwd();
@@ -17,6 +44,8 @@ async function main() {
     const results = await new ESLint({ cwd, fix: job.fix }).lintFiles(job.files);
     if (job.fix)
         await ESLint.outputFixes(results);
+    if (job.graph !== undefined)
+        await handOutGraph(job.graph, cwd);
     process.stdout.write(JSON.stringify(results));
     return results.some((result) => result.errorCount > 0 || result.fatalErrorCount > 0) ? 1 : 0;
 }

package/lint/run.d.mts

@@ -1,11 +1,17 @@
 import { type HeavyNodeRun } from '../runtime/scripts/api/node/run-node.mjs';
-import { type CanonDeclarations, type LintSideStats } from '../cache/lint-family.mjs';
+import { type CanonDeclarations, type GraphSnapshot, type LintSideStats } from '../cache/lint-family.mjs';
 import type { CheckSession } from '../cache/types.mjs';
 type Dynamic = any;
-/** What a linter run answers: its json results, or why it could not complete (both when the run was partial). */
+/**
+ * The project-graph findings of one canon, as its `projectGraphSnapshot` answers them: by side-relative posix path.
+ * The ESLint child builds this graph for the canon's graph rules, so it hands the snapshot out instead of the cache building the same graph again.
+ */
+export type GraphSnapshotParts = Readonly<Record<string, GraphSnapshot>>;
+/** What a linter run answers: its json results, or why it could not complete (both when the run was partial), and the graph snapshots its child handed out, by canon name. */
 export interface LinterRun {
     results?: Dynamic[];
     error?: string;
+    graph?: GraphSnapshotParts;
 }
 /**
  * What a linter run is asked for. `list` is the files an ESLint run lints (cwd-relative, posix) when they are named one by one: they go to the child
@@ -20,6 +26,12 @@ export interface LinterSpec {
     bound?: string | null;
     list?: readonly string[] | undefined;
     files?: number | undefined;
+    graph?: readonly GraphCanon[] | undefined;
+}
+/** An installed canon whose graph snapshot the ESLint child hands out: its package name and the entry file the child imports. */
+export interface GraphCanon {
+    name: string;
+    entry: string;
 }
 /** The seam that runs a linter through the app's own install from cwd. */
 export type LinterRunner = (spec: LinterSpec) => Promise<LinterRun>;
@@ -43,7 +55,7 @@ type RepoDeclaration = Dynamic;
 export declare const ESLINT_HEAP_ENV = "STARCI_ESLINT_HEAP_MB";
 export declare function eslintHeapArgs(env?: NodeJS.ProcessEnv): string[];
 /** A linter's json results through the app's own install, run from `cwd` (a side folder): `{ results }` or `{ error }`. The child runs while the caller goes on. */
-export declare function runLinter({ cwd, pkg, bin, args, bound, list, files }: LinterSpec, execute?: HeavyNodeRun): Promise<LinterRun>;
+export declare function runLinter({ cwd, pkg, bin, args, bound, list, files, graph }: LinterSpec, execute?: HeavyNodeRun): Promise<LinterRun>;
 /**
  * The lint scope a flat config declares: `ignored(file)` for its global ignores (a block holding only `ignores` and `name`), which prune
  * the walk, and `source(file)` for a file some block's `files` select while that block's own `ignores` do not (standard flat-config
@@ -66,7 +78,7 @@ export declare function installedLintConfig({ repoRoot, cwd, side }: {
     side: string;
 }): Promise<Dynamic[]>;
 /** Execute each side's installed ESLint config once, whole or over a named list; the cached and the cacheless run share scope, coverage and tool-failure judgment. */
-export declare function eslintRepository({ repoRoot, app, opts, changed, existing, run, scopes }: {
+export declare function eslintRepository({ repoRoot, app, opts, changed, existing, run, scopes, handOutGraph }: {
     repoRoot: string;
     app?: RepoDeclaration;
     opts?: {
@@ -77,6 +89,7 @@ export declare function eslintRepository({ repoRoot, app, opts, changed, existin
     existing?: readonly string[];
     run?: LinterRunner | undefined;
     scopes?: Readonly<Record<string, readonly string[]>> | undefined;
+    handOutGraph?: boolean | undefined;
 }): Promise<{
     findings: LintFinding[];
     errors: string[];
@@ -87,6 +100,7 @@ export declare function eslintRepository({ repoRoot, app, opts, changed, existin
             skipped?: string;
         }>;
     };
+    graphs: Record<string, GraphSnapshotParts>;
 }>;
 /** What the cache reads of the canons a side lints with: the ESLint canon (which publishes the project-graph rules) and the grammar family of the fe side. */
 export declare function canonDeclarations({ repoRoot, cwd, side }: {
@@ -101,7 +115,7 @@ export declare function canonDeclarations({ repoRoot, cwd, side }: {
 export declare function gitBaseToken(repoRoot: string): string;
 /** What the cached linters answer: the ESLint answer in the shape of eslintRepository's, the stylelint results, and each side's counts. */
 export interface CachedLinters {
-    eslint: Awaited<ReturnType<typeof eslintRepository>>;
+    eslint: Omit<Awaited<ReturnType<typeof eslintRepository>>, 'graphs'>;
     stylelint: {
         results: Dynamic[];
         errors: string[];

package/lint/run.mjs

@@ -45,8 +45,23 @@ export function eslintHeapArgs(env = process.env) {
 }
 /** The ESLint list runner (eslint-list.cts, built beside this file). */
 const LIST_RUNNER = fileURLToPath(new URL('./eslint-list.cjs', import.meta.url));
+/** The snapshots an ESLint child wrote, by canon name; undefined when it wrote none or a file that is not a snapshot list (the cache then builds the graph itself). */
+function readGraphSnapshots(file) {
+    try {
+        const written = JSON.parse(fs.readFileSync(file, 'utf8'));
+        const snapshots = written?.snapshots;
+        if (snapshots === null || typeof snapshots !== 'object' || Array.isArray(snapshots))
+            return undefined;
+        const sound = Object.values(snapshots).every((snapshot) => snapshot !== null && typeof snapshot === 'object' && snapshot.byFile !== null && typeof snapshot.byFile === 'object' && !Array.isArray(snapshot.byFile)
+            && Object.values(snapshot.byFile).every((findings) => Array.isArray(findings)));
+        return sound ? snapshots : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
 /** A linter's json results through the app's own install, run from `cwd` (a side folder): `{ results }` or `{ error }`. The child runs while the caller goes on. */
-export async function runLinter({ cwd, pkg, bin, args, bound = null, list, files }, execute) {
+export async function runLinter({ cwd, pkg, bin, args, bound = null, list, files, graph }, execute) {
     let entry;
     try {
         const manifest = createRequire(path.join(cwd, 'package.json')).resolve(`${pkg}/package.json`);
@@ -57,18 +72,22 @@ export async function runLinter({ cwd, pkg, bin, args, bound = null, list, files
         return { error: `${pkg} is not installed for ${cwd}` };
     }
     const heap = pkg === 'eslint' ? eslintHeapArgs() : [];
-    // A named list is written to a file the runner reads: ESLint lints all of it in one process, and no command line holds a path.
-    const listed = pkg === 'eslint' && list !== undefined ? makeTempDir('starci-eslint-') : null;
+    // A named list, or a run that hands its project graph out, goes through the list runner: the job is a file it reads (ESLint lints all of it in one
+    // process, no command line holds a path), the whole side is the list `.`, and the graph snapshots come back in a file beside the job.
+    const listed = pkg === 'eslint' && (list !== undefined || graph !== undefined) ? makeTempDir('starci-eslint-') : null;
     let childArgs = [entry, ...args];
-    if (listed !== null && list !== undefined) {
+    const snapshotFile = listed === null || graph === undefined ? null : path.join(listed, 'graph.json');
+    if (listed !== null) {
         const job = path.join(listed, 'job.json');
-        fs.writeFileSync(job, JSON.stringify({ files: list, fix: args.includes('--fix') }));
+        fs.writeFileSync(job, JSON.stringify({ files: list ?? ['.'], fix: args.includes('--fix'), ...(snapshotFile === null || graph === undefined ? {} : { graph: { out: snapshotFile, canons: graph } }) }));
         childArgs = [LIST_RUNNER, job];
     }
     const count = list?.length ?? files;
     let run;
+    let handed;
     try {
         run = completedNode(await runHeavyNode(execute, { kind: 'eslint', label: `app check ${pkg} ${path.basename(cwd)}`, args: [...heap, ...(bound ? linterBoundArgs() : []), ...childArgs], cwd, maxBuffer: 64 * 1024 * 1024, ...(count === undefined || pkg !== 'eslint' ? {} : { files: count }), ...(bound ? { env: { ...process.env, [BOUND_ENV]: bound } } : {}) }), pkg);
+        handed = snapshotFile === null ? undefined : readGraphSnapshots(snapshotFile);
     }
     finally {
         if (listed !== null)
@@ -87,7 +106,7 @@ export async function runLinter({ cwd, pkg, bin, args, bound = null, list, files
         return { error: `${pkg} produced a report that is not a result list` };
     const completed = !run.error && !run.signal && [0, 1].includes(run.status)
         && (run.status === 0 || results.some((result) => result?.messages?.length || result?.warnings?.length));
-    return { results, ...(completed ? {} : { error: `${pkg} could not complete in ${path.basename(cwd)}/ (exit ${run.status}, signal ${run.signal ?? 'none'}): ${String(run.error?.message || run.stderr || run.stdout || '').trim().split('\n')[0]}` }) };
+    return { results, ...(handed === undefined || !completed ? {} : { graph: handed }), ...(completed ? {} : { error: `${pkg} could not complete in ${path.basename(cwd)}/ (exit ${run.status}, signal ${run.signal ?? 'none'}): ${String(run.error?.message || run.stderr || run.stdout || '').trim().split('\n')[0]}` }) };
 }
 const eslintFindings = (results, appRoot) => results.flatMap((result) => (result.messages ?? []).map((message) => ({
     engine: 'eslint', rule: message.ruleId ?? 'eslint-error', code: CODE_PREFIX.exec(message.message ?? '')?.[1] ?? null, severity: message.severity === 1 ? 'warning' : 'error',
@@ -268,8 +287,18 @@ const spawnFailure = (error) => {
         throw error;
     return { error: `could not start eslint: ${String(error?.message ?? error)}` };
 };
+/** The installed canon of `side`, which publishes the project-graph rules, as the child imports it; undefined when it cannot be resolved (the cache then builds the graph itself). */
+function graphCanonsOf(repoRoot, cwd, side) {
+    const name = `@starci/eslint-canon-${side}`;
+    try {
+        return [{ name, entry: ownCanonEntry({ repoRoot, cwd }, name) }];
+    }
+    catch {
+        return undefined;
+    }
+}
 /** Starts the ESLint child of every side that has work and returns one record per side: skipped, a scope error, or the running child. */
-async function launchEslint({ app, repoRoot, opts, changed, existing, run = runLinter, scopes = {} }) {
+async function launchEslint({ app, repoRoot, opts, changed, existing, run = runLinter, scopes = {}, handOutGraph = false }) {
     const launches = [];
     for (const side of app ? SIDES.filter((candidate) => opts.side === undefined || opts.side === candidate) : []) {
         const sources = onSide(existing, side).filter((file) => /\.(?:[cm]?[jt]sx?)$/.test(file));
@@ -289,20 +318,22 @@ async function launchEslint({ app, repoRoot, opts, changed, existing, run = runL
             continue;
         }
         const head = ['--format', 'json', ...(opts.fix ? ['--fix'] : [])];
+        // the child that builds the canon's project graph for its rules hands the snapshot out when the caller keeps the graph findings (the cache)
+        const graph = handOutGraph ? graphCanonsOf(repoRoot, cwd, side) : undefined;
         // The files of a diff go to ONE child through a file (a diff of hundreds of long paths outgrows the Windows command line, and each extra
         // child would build the whole TypeScript program again); the whole side is a single directory argument.
-        const launch = Promise.resolve().then(() => run(changed ? { cwd, pkg: 'eslint', bin: 'eslint', args: head, list: sources, bound: repoRoot } : { cwd, pkg: 'eslint', bin: 'eslint', args: [...head, '.'], files: expected.length, bound: repoRoot }));
+        const launch = Promise.resolve().then(() => run(changed ? { cwd, pkg: 'eslint', bin: 'eslint', args: head, list: sources, bound: repoRoot, ...(graph === undefined ? {} : { graph }) } : { cwd, pkg: 'eslint', bin: 'eslint', args: [...head, '.'], files: expected.length, bound: repoRoot, ...(graph === undefined ? {} : { graph }) }));
         launches.push({ side, cwd, expected, run: launch.catch(spawnFailure) });
     }
     return launches;
 }
 /** Execute each side's installed ESLint config once, whole or over a named list; the cached and the cacheless run share scope, coverage and tool-failure judgment. */
-export async function eslintRepository({ repoRoot, app = readRepoDeclaration(loadSlotManifest(), repoRoot), opts = {}, changed = null, existing = [], run, scopes }) {
-    const findings = [], errors = [], raw = [];
+export async function eslintRepository({ repoRoot, app = readRepoDeclaration(loadSlotManifest(), repoRoot), opts = {}, changed = null, existing = [], run, scopes, handOutGraph }) {
+    const findings = [], errors = [], raw = [], graphs = {};
     const engine = { sides: {} };
     if (!app.sides)
         throw new Error('ESLint runs at the app root, the folder of hfs.json');
-    const launches = await launchEslint({ app, repoRoot, opts, changed, existing, run, ...(scopes === undefined ? {} : { scopes }) });
+    const launches = await launchEslint({ app, repoRoot, opts, changed, existing, run, ...(scopes === undefined ? {} : { scopes }), ...(handOutGraph === true ? { handOutGraph } : {}) });
     const settled = await Promise.allSettled(launches.map(launch => launch.run ?? null));
     const rejected = settled.filter((run) => run.status === 'rejected');
     const failed = rejected.find(run => isHostHeld(run.reason)) ?? rejected[0];
@@ -335,8 +366,10 @@ export async function eslintRepository({ repoRoot, app = readRepoDeclaration(loa
             findings.push(...eslintFindings(linted.results, repoRoot));
         }
         engine.sides[side] = { files: linted.results?.length ?? 0 };
+        if (linted.graph !== undefined)
+            graphs[side] = linted.graph;
     });
-    return { findings, errors, raw, engine };
+    return { findings, errors, raw, engine, graphs };
 }
 // ------------------------------------------------------------------------------------------------ the cached lint
 /** A `crossFileInputs` export that has the shape the cache reads, or null (an installed canon without it, or with a broken one, is linted whole). */
@@ -441,8 +474,8 @@ export async function cachedLinters({ repoRoot, app, side: only, run, session })
             canons, styleCanon: styled ? await styleDeclaration({ repoRoot, cwd }) : null, typescript: () => loadAppTypeScript(cwd), extraKey: '', gitToken, full, write: true,
             eslint: async (files) => {
                 const listed = files === null ? null : files.map((file) => `${side}/${file}`);
-                const sub = await eslintRepository({ repoRoot, app, opts: { side }, changed: listed, existing: listed ?? [], run, scopes: { [side]: scope } });
-                return { results: sub.raw, errors: sub.errors };
+                const sub = await eslintRepository({ repoRoot, app, opts: { side }, changed: listed, existing: listed ?? [], run, scopes: { [side]: scope }, handOutGraph: true });
+                return { results: sub.raw, errors: sub.errors, ...(sub.graphs[side] === undefined ? {} : { graph: sub.graphs[side] }) };
             },
             stylelint: styled ? async (files) => {
                 const linted = await (run ?? runLinter)({ cwd, pkg: 'stylelint', bin: 'stylelint', args: [...(files ?? [STYLE_GLOB]), '--formatter', 'json'] });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@starci/hfs",
-  "version": "5.0.8",
+  "version": "5.1.0",
   "description": "The StarCi app command implementation for scaffolding, linting, checking and synchronizing one product repository.",
   "type": "module",
   "license": "MIT",

package/runtime/knowledge/hfs/canon-pins.yaml

@@ -31,35 +31,35 @@ pins:
     source: packages/event-stream/package.json
     why: 'the one server-sent-events client of every front end (fe-stack event-stream, owner:event-stream-package): the transport client layer (modules/api/sse/clients) creates one instance for the app with the bearer token source and the stream operations follow on it; it carries Last-Event-ID resume, the capped doubling backoff, the heartbeat timeout, the single 401 renewal and the useSWRSubscription adapter, so no app keeps a hand-written reader.'
   '@starci/grammar':
-    version: 0.21.12
+    version: 0.21.13
     group: starci
     install: registry
     side: fe
     source: packages/grammar/package.json
     why: 'the grammar front ends read: the brand layer sets `--font-sans` and `--font-mono` and the grammar reads them; it carries the Input tel kind, the copyable and read-only Input, the IconButton disclosure props and count badge, ChatBubble, FillViewport, Textarea mentions and Enter-to-send, the leading PrimaryRailLayout rail, the plate-less Image, ListRow, the soft Alert, Progress steps, the floating primary IconButton, FlowGraph, the STATE-8 loading views and the bordered selectable TagGroup chips. The runtime source version wins for a @starci package.'
   '@starci/eslint-canon-be':
-    version: 3.11.19
+    version: 3.12.0
     group: starci
     install: registry
     side: be
     source: packages/eslint-canon-be/package.json
     why: 'the back-end ESLint canon: `loadHfs(import.meta.url)` of be/eslint.config.mjs finds the app-root hfs.json (kind app) and gives every linted file the view of the be side, and the project graph is built per side; its bundled runtime copies (slots, canon-pins, failure codes, the architecture machine) put .starcistacks and .sops.yaml at the app root; `starciBeConfig({ hfs: loadHfs(import.meta.url) })` is the typed factory and the BE-CONVENTION laws are its rules.'
   '@starci/eslint-canon-fe':
-    version: 9.9.12
+    version: 9.10.0
     group: starci
     install: registry
     side: fe
     source: packages/eslint-canon-fe/package.json
     why: 'the front-end ESLint canon: `loadHfs(import.meta.url)` of fe/eslint.config.mjs finds the app-root hfs.json (kind app) and gives every linted file the view of the fe side, and the project graph is built per side; its bundled runtime copies (slots, canon-pins, failure codes, the architecture machine) put .starcistacks and .sops.yaml at the app root; the front end has no tests (FE_NO_TESTS R97 in hfs) and no-vietnamese-in-source (R91) applies.'
   '@starci/eslint-grammar-core':
-    version: 0.21.12
+    version: 0.21.13
     group: starci
     install: registry
     side: fe
     source: packages/eslint-grammar-core/package.json
     why: 'the StarCi Grammar component API lint, versioned with @starci/grammar; front ends compose this family package with the universal FE canon.'
   '@starci/eslint-grammar-offset-pop':
-    version: 0.21.12
+    version: 0.21.13
     group: starci
     install: registry
     side: fe
@@ -92,7 +92,7 @@ pins:
     source: packages/jest-preset/package.json
     why: 'the Jest preset of a back end: the world runner runs up to min(--maxWorkers, slots) world files at once, each in its own process bound to one data slot of the test world (STARCI_TEST_WORLD_SLOT), and reads test-world state protocol 2 only: it pairs exactly with @starci/test-world, and any other state file is JEST_PRESET_WORLD_PAIR_MISMATCH. The unit run writes the lcov Sonar and Codecov import (services only); the integration, e2e and contract projects run every spec file in a worker process of its own (world-runner.cjs), so a process-global framework registry (@nestjs/graphql type metadata) never leaks between e2e files; it ships the unit kit (mockEntityManager, fakeTransaction, fakeQueryBuilder, queueQueryBuilders, fakeIds, FakeClock, Outcome matchers) and the recordingOutbox claim side.'
   '@starci/test-world':
-    version: 1.3.3
+    version: 1.3.4
     group: starci
     install: registry
     side: be
@@ -106,7 +106,7 @@ pins:
     source: packages/ai-router/package.json
     why: 'the AI pool router of a back end: a NestJS module that routes OpenAI-compatible chat, stream and embeddings calls across keys, models and providers, with @starci/ai-router/testing for its specs; @starci/jest-preset compiles it as an ESM-only dependency.'
   '@starci/hfs':
-    version: 5.0.8
+    version: 5.1.0
     group: starci
     install: registry
     side: both

package/runtime/knowledge/hfs/rules.yaml

@@ -924,7 +924,7 @@ rules:
     code: "BE_TEST_TOPOLOGY"
     editions: [lite, full]
     docs: [docs/quality-bar.md#r47-test-topology]
-    law: "One jest config, projects `unit`, `integration`, `e2e` and `contract`, live by folder, `diagnostics: false`; unit specs are `<name>.<role>.spec.ts` beside the file they test: required for the roles of `ruleParams.be.unitRoles` (`<name>.service.spec.ts` beside a `<name>.service.ts`, `<name>.cli.spec.ts` beside a cli command `<name>.cli.ts` of `src/features/cli`), optional for any other logic role (`ruleParams.be.logicRoles`) inside a slot whose `coverage` is required and beside a logic file such a slot declares (`logic`: `passport.tokens.spec.ts` beside `passport.tokens.ts`), except that the commit adding a measured logic file stages its `<name>.<role>.spec.ts` beside it (owner 2026-10-20, judged by `starci app check --staged` in the pre-commit hook), and nowhere else but beside a webhook or realtime door that has no service of its own (`<provider>.webhook.spec.ts`, `<channel>.gateway.spec.ts`, `<x>.subscription.spec.ts`) (every unit-tested subject has exactly one; any other `*.spec.ts` outside `be/src/tests/{world,integration,e2e,contract}` is a finding, including specs in apps), and the unit project collects coverage from the logic roles of the measured roots and the logic files their slots declare only (the scope derived from the slot manifest, R204) with a per-file threshold of 100 on lines, branches, functions and statements (`test` runs `--coverage`; `importHelpers` and `tslib`); `be/src/tests/world/` is the ONLY test infrastructure: `global-setup.ts` starts the app's own stack (`.starcistacks/<env>`, named by `stack` in `test-world.config.ts`, the declaration of the test-world library in its one named form `export const { useTestWorld, useSandbox } = defineTestWorld({...})` (a default export is not read): every service it declares runs REAL, behind toxiproxy, images and versions read from the stack at run time, never spelled in test source) or attaches to a warm one that answers, and runs the migrations once over the cli app's connections (the runner of the cli migrate command); `global-teardown.ts` stops only what its setup started; `use-test-world.ts` exports `useTestWorld({ apps } | { modules })` (`world.apps.<name>.api`, `world.db.<connection>`, `world.infra.<service>` with `latency(ms)`, `cut()` and `restore()` on the real service, `world.fake.<provider>`, `world.waitFor`) and `fakes/<provider>/` holds the network-edge fakes (`failNext`, `replayWebhook`, `delay`, payload fixtures) of external SaaS the team does not operate ONLY: a fake of a service the stack declares is refused, except stateless compute that needs special hardware or an external model (GPU inference, a self-hosted embedding model), whose `stacks` entry in `test-world.config.ts` declares `{ fakedBy: <fake>, reason }` with a non-empty `reason` (a stateful service, or one with a persistent volume, is never accepted); it alone owns containers, DataSource, migrations and `process.env`; nothing under `be/src/tests` overrides a provider or DI token; `be/src/tests/integration/<capability>/*.integration-spec.ts` (`{ modules }`, with the real peer apps its client calls beside them as `apps`; real infrastructure, no HTTP door of ours), `be/src/tests/e2e/<area>/*.e2e-spec.ts` (`{ apps }`) and `be/src/tests/contract/<provider>/*.contract-spec.ts` (provider sandboxes, skipped without sandbox config, run only by `test:contract`, never by `test` or `test:e2e`) agree folder with suffix; an integration or e2e spec passes `useTestWorld` one object literal with plain keys (no variable, spread or computed key) and calls it; the contract layer has no skip either: a contract spec writes `sandbox.describe(...)` from the test-world library's `useSandbox(...)`, and when the sandbox config is absent that describe registers one failing test naming the missing keys (the body never runs), and every `fakes/<provider>/` that serves payload fixtures (`payloads/*.json`) has a `contract/<provider>/*.contract-spec.ts` that references those fixtures and asserts `shapeOf(real)` equals `shapeOf(fixture)` (the helper `shapeOf` is named by `ruleParams.be.contractShape` of the slot manifest; fakes the test-world library provides are guarded by the library); no `.test.ts`, `int-spec` or `harness-spec`, no `live/` and no `be/src/tests/e2e/world`."
+    law: "One jest config, projects `unit`, `integration`, `e2e` and `contract`, live by folder, `diagnostics: false`; unit specs are `<name>.<role>.spec.ts` beside the file they test: required for the roles of `ruleParams.be.unitRoles` (`<name>.service.spec.ts` beside a `<name>.service.ts`, `<name>.cli.spec.ts` beside a cli command `<name>.cli.ts` of `src/features/cli`), optional for any other logic role (`ruleParams.be.logicRoles`) inside a slot whose `coverage` is required and beside a logic file such a slot declares (`logic`: `passport.tokens.spec.ts` beside `passport.tokens.ts`), except that the commit adding a measured logic file stages its `<name>.<role>.spec.ts` beside it (owner 2026-10-20, judged by `starci app check --staged` in the pre-commit hook), and nowhere else but beside a webhook or realtime door that has no service of its own (`<provider>.webhook.spec.ts`, `<channel>.gateway.spec.ts`, `<x>.subscription.spec.ts`) (every unit-tested subject has exactly one; any other `*.spec.ts` outside `be/src/tests/{world,integration,e2e,contract}` is a finding, including specs in apps), and the unit project collects coverage from the logic roles of the measured roots and the logic files their slots declare only (the scope derived from the slot manifest, R204) with a per-file threshold of 100 on lines, branches, functions and statements (`test` runs `--coverage`; `importHelpers` and `tslib`); `be/src/tests/world/` is the ONLY test infrastructure: `global-setup.ts` starts the app's own stack (`.starcistacks/<env>`, named by `stack` in `test-world.config.ts`, the declaration of the test-world library in a named form: `export const { useTestWorld, useSandbox } = defineTestWorld({...})`, or `const world: TestWorldApi = defineTestWorld({...})` with `useTestWorld` and `useSandbox` exported typed from it (a default export is not read): every service it declares runs REAL, behind toxiproxy, images and versions read from the stack at run time, never spelled in test source) or attaches to a warm one that answers, and runs the migrations once over the cli app's connections (the runner of the cli migrate command); `global-teardown.ts` stops only what its setup started; `use-test-world.ts` exports `useTestWorld({ apps } | { modules })` (`world.apps.<name>.api`, `world.db.<connection>`, `world.infra.<service>` with `latency(ms)`, `cut()` and `restore()` on the real service, `world.fake.<provider>`, `world.waitFor`) and `fakes/<provider>/` holds the network-edge fakes (`failNext`, `replayWebhook`, `delay`, payload fixtures) of external SaaS the team does not operate ONLY: a fake of a service the stack declares is refused, except stateless compute that needs special hardware or an external model (GPU inference, a self-hosted embedding model), whose `stacks` entry in `test-world.config.ts` declares `{ fakedBy: <fake>, reason }` with a non-empty `reason` (a stateful service, or one with a persistent volume, is never accepted); it alone owns containers, DataSource, migrations and `process.env`; nothing under `be/src/tests` overrides a provider or DI token; `be/src/tests/integration/<capability>/*.integration-spec.ts` (`{ modules }`, with the real peer apps its client calls beside them as `apps`; real infrastructure, no HTTP door of ours), `be/src/tests/e2e/<area>/*.e2e-spec.ts` (`{ apps }`) and `be/src/tests/contract/<provider>/*.contract-spec.ts` (provider sandboxes, skipped without sandbox config, run only by `test:contract`, never by `test` or `test:e2e`) agree folder with suffix; an integration or e2e spec passes `useTestWorld` one object literal with plain keys (no variable, spread or computed key) and calls it; the contract layer has no skip either: a contract spec writes `sandbox.describe(...)` from the test-world library's `useSandbox(...)`, and when the sandbox config is absent that describe registers one failing test naming the missing keys (the body never runs), and every `fakes/<provider>/` that serves payload fixtures (`payloads/*.json`) has a `contract/<provider>/*.contract-spec.ts` that references those fixtures and asserts `shapeOf(real)` equals `shapeOf(fixture)` (the helper `shapeOf` is named by `ruleParams.be.contractShape` of the slot manifest; fakes the test-world library provides are guarded by the library); no `.test.ts`, `int-spec` or `harness-spec`, no `live/` and no `be/src/tests/e2e/world`."
     kinds: [check, codemod, lint]
     gates: [land, ci]
     failureCodes: ["BE_TEST_TOPOLOGY", "BE_CONTRACT_UNGUARDED", "BE_UNIT_SPEC_NOT_STAGED"]
@@ -6525,3 +6525,54 @@ rules:
         source: owner
         quote: "The skeleton is the ready structure with its data missing; it is drawn from isLoading alone and from the reads the region shows."
         ruling: "Several reads feed one frame: loading is any read loading with no data; a key change reloads only the region keyed by it; a refresh keeps the content."
+  - id: R368
+    code: "HFS_EXPLICIT_EXPORT_SURFACE"
+    law: "An exported declaration states its type where it is exported: the return type of an exported function, the type of an exported variable and the type of its parameters are written, not inferred from a body or from other files, because the isolated declaration emit must be able to write the file's surface alone. A component that returns only JSX is explicit. Each export that cannot be written is reported at its place with what to annotate, in a front-end and a back-end file alike."
+    kinds: [lint]
+    gates: [pre-commit, settle, land, ci]
+    failureCodes: ["HFS_EXPLICIT_EXPORT_SURFACE"]
+    enforcers:
+      - {kind: eslint-fe, id: explicit-export-surface}
+      - {kind: eslint-be, id: explicit-export-surface}
+    editions: [lite, full]
+    docs: [contexts/code/shared/typing.md]
+    templateNa: "A template exports nothing the lint result cache keys on."
+    proves:
+      - {path: packages/eslint-canon-fe/src/explicit-surface.spec.ts, editions: [lite, full], codes: [HFS_EXPLICIT_EXPORT_SURFACE]}
+      - {path: packages/eslint-canon-be/src/explicit-surface.spec.ts, editions: [lite, full], codes: [HFS_EXPLICIT_EXPORT_SURFACE]}
+      - {path: packages/hfs/src/explicit-surface.spec.mts, editions: [lite, full], codes: [HFS_EXPLICIT_EXPORT_SURFACE]}
+    exemplifiedBy:
+      - {path: packages/eslint-canon-fe/src/explicit-surface.spec.ts, editions: [lite, full], codes: [HFS_EXPLICIT_EXPORT_SURFACE]}
+    witness:
+      - {path: packages/eslint-canon-fe/src/explicit-surface.spec.ts, editions: [lite, full], codes: [HFS_EXPLICIT_EXPORT_SURFACE]}
+      - {path: packages/eslint-canon-be/src/explicit-surface.spec.ts, editions: [lite, full], codes: [HFS_EXPLICIT_EXPORT_SURFACE]}
+      - {path: packages/hfs/src/explicit-surface.spec.mts, editions: [lite, full], codes: [HFS_EXPLICIT_EXPORT_SURFACE]}
+    cases:
+      - id: case-1
+        date: "2026-11-03"
+        source: owner
+        quote: "enforce it by lint"
+        ruling: "A file whose exported surface is inferred is open in the lint result cache: one body edit lints every importer again. The exported surface is written out, and the rule reports exactly what the cache counts as open."
+  - id: R369
+    code: "FE_DIRECTIVE_FIRST"
+    law: "A `use client` or `use server` directive is the first statement of its module, above every import: below another statement it is an expression that does nothing (Prettier writes it as a parenthesised string) and next build refuses the file."
+    kinds: [lint]
+    gates: [pre-commit, settle, land, ci]
+    failureCodes: ["FE_DIRECTIVE_FIRST"]
+    enforcers:
+      - {kind: eslint-fe, id: directive-first}
+    editions: [lite, full]
+    docs: [contexts/code/fe/boundaries.md]
+    templateNa: "A template places its directives first."
+    proves:
+      - {path: packages/eslint-canon-fe/src/directive-first.spec.ts, editions: [lite, full], codes: [FE_DIRECTIVE_FIRST]}
+    exemplifiedBy:
+      - {path: packages/eslint-canon-fe/src/directive-first.spec.ts, editions: [lite, full], codes: [FE_DIRECTIVE_FIRST]}
+    witness:
+      - {path: packages/eslint-canon-fe/src/directive-first.spec.ts, editions: [lite, full], codes: [FE_DIRECTIVE_FIRST]}
+    cases:
+      - id: case-1
+        date: "2026-11-03"
+        source: owner
+        quote: "no lint caught it"
+        ruling: "A directive below an import broke Nivo's CI build on 2026-11-02; the directive is the first statement of its module and a lint reports it elsewhere."

package/runtime/scripts/hfs/architecture/test-world-files.d.mts

@@ -18,9 +18,10 @@ interface WorldViolation {
  *    its own slot, be.tests.world.kit) plus files at its root whose role suffix is in ruleParams.be.suffixes
  *    (`stripe.client.ts`, `checkout.contracts.ts`, `test-world.config.ts`, ...). Every tracked file below the world root is
  *    matched by the slot's own entries through `allowsFile`.
- * 2. The declaration. `test-world.config.ts` declares the world in ONE form, the named export R89 allows:
- *    `export const { useTestWorld, useSandbox } = defineTestWorld({ ... })` (an exported `const` initialized by a
- *    `defineTestWorld(<object literal>)` call). A config without it (a default export, or a declaration the machine cannot
+ * 2. The declaration. `test-world.config.ts` declares the world in a named form R89 allows: the destructured export
+ *    `export const { useTestWorld, useSandbox } = defineTestWorld({ ... })`, or the typed form
+ *    `const world: TestWorldApi = defineTestWorld({ ... })` whose `useTestWorld` and `useSandbox` are exported consts typed from
+ *    `TestWorldApi` (a `const` initialized by a `defineTestWorld(<object literal>)` call). A config without it (a default export, or a declaration the machine cannot
  *    read) is refused: the world it declares could not be judged.
  * 3. Fakes against the stack (owner refinement 2026-09-30). Every service the stack declares runs real in the world; a fake
  *    (a `fakes/<provider>/` folder, or a `fakes` entry of the declaration such as `smtp: smtpFake()`) is a network-edge fake

package/runtime/scripts/hfs/architecture/test-world-files.mjs

@@ -15,9 +15,10 @@ import { byCodeUnit } from '../../lib/list.mjs';
  *    its own slot, be.tests.world.kit) plus files at its root whose role suffix is in ruleParams.be.suffixes
  *    (`stripe.client.ts`, `checkout.contracts.ts`, `test-world.config.ts`, ...). Every tracked file below the world root is
  *    matched by the slot's own entries through `allowsFile`.
- * 2. The declaration. `test-world.config.ts` declares the world in ONE form, the named export R89 allows:
- *    `export const { useTestWorld, useSandbox } = defineTestWorld({ ... })` (an exported `const` initialized by a
- *    `defineTestWorld(<object literal>)` call). A config without it (a default export, or a declaration the machine cannot
+ * 2. The declaration. `test-world.config.ts` declares the world in a named form R89 allows: the destructured export
+ *    `export const { useTestWorld, useSandbox } = defineTestWorld({ ... })`, or the typed form
+ *    `const world: TestWorldApi = defineTestWorld({ ... })` whose `useTestWorld` and `useSandbox` are exported consts typed from
+ *    `TestWorldApi` (a `const` initialized by a `defineTestWorld(<object literal>)` call). A config without it (a default export, or a declaration the machine cannot
  *    read) is refused: the world it declares could not be judged.
  * 3. Fakes against the stack (owner refinement 2026-09-30). Every service the stack declares runs real in the world; a fake
  *    (a `fakes/<provider>/` folder, or a `fakes` entry of the declaration such as `smtp: smtpFake()`) is a network-edge fake
@@ -38,6 +39,7 @@ const FAKES_DIRECTORY = 'fakes/';
 const CONFIG_FILE = 'test-world.config.ts';
 const DEFINE = 'defineTestWorld';
 const NAMED_FORM = `export const { useTestWorld, useSandbox } = ${DEFINE}({ ... })`;
+const TYPED_FORM = `const world: TestWorldApi = ${DEFINE}({ ... })` + ' with export const useTestWorld / useSandbox typed from it';
 const defaultEnvironment = DEFAULT_ENVIRONMENT;
 const KEBAB = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;
 const unwrap = (ts, node) => unwrapEach(ts, node, [ts.isParenthesizedExpression, ts.isAsExpression, ts.isSatisfiesExpression]);
@@ -52,21 +54,38 @@ function defineLiteral(ts, expression) {
     const literal = first ? unwrap(ts, first) : null;
     return literal && ts.isObjectLiteralExpression(literal) ? literal : null;
 }
-/** The declaration of the world: the object literal of an exported `const` initialized by `defineTestWorld({ ... })`, or null. */
+/**
+ * The declaration of the world: the object literal of a top-level `const` initialized by `defineTestWorld({ ... })`, or null. The config
+ * exports `useTestWorld` and `useSandbox` either by destructuring that call (the original form) or, typed, from the world the call
+ * built: `const world: TestWorldApi = defineTestWorld({ ... })` with `export const useTestWorld: TestWorldApi["useTestWorld"] = world.useTestWorld`.
+ * Both are read; a world no exported name reaches is refused by the caller.
+ */
 function configLiteral(ts, sourceFile) {
     for (const statement of sourceFile.statements) {
-        if (!ts.isVariableStatement(statement) || !isExported(ts, statement))
+        if (!ts.isVariableStatement(statement))
             continue;
         if (!hasAnyFlag(statement.declarationList.flags, ts.NodeFlags.Const))
             continue;
         for (const declaration of statement.declarationList.declarations) {
             const literal = declaration.initializer ? defineLiteral(ts, declaration.initializer) : null;
-            if (literal)
+            if (literal && (isExported(ts, statement) || exportsWorld(ts, sourceFile)))
                 return literal;
         }
     }
     return null;
 }
+/** Whether the file exports both `useTestWorld` and `useSandbox` as consts (the typed form re-exports them from the built world). */
+function exportsWorld(ts, sourceFile) {
+    const exported = new Set();
+    for (const statement of sourceFile.statements) {
+        if (!ts.isVariableStatement(statement) || !isExported(ts, statement))
+            continue;
+        for (const declaration of statement.declarationList.declarations)
+            if (ts.isIdentifier(declaration.name))
+                exported.add(declaration.name.text);
+    }
+    return exported.has('useTestWorld') && exported.has('useSandbox');
+}
 /** `stack` as the environment it names: the last segment of `".starcistacks/<env>"`; null when absent or not a literal. */
 function environmentOf(ts, literal) {
     const node = literal ? propertyOf(ts, literal, 'stack') : null;
@@ -152,7 +171,7 @@ function worldDeclaration(graph, ts, worldRoot, violations) {
     if (configFile && !literal) {
         violations.push({
             ruleId: RULE, path: configPath, line: 1, column: 1, slot: WORLD_SLOT,
-            message: `${configPath} declares no world the machine can read. Declare it in the one named form \`${NAMED_FORM}\` (an exported const of a ${DEFINE} call with an object literal, imported from @starci/test-world); a default export is refused by R89 and is not read.`,
+            message: `${configPath} declares no world the machine can read. Declare it in the named form \`${NAMED_FORM}\` or the typed form \`${TYPED_FORM}\` (a const of a ${DEFINE} call with an object literal, imported from @starci/test-world); a default export is refused by R89 and is not read.`,
         });
     }
     return { configPath, configFile, literal };