@starci/hfs 5.0.8 → 5.1.0

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## 5.1.0
+
+- Added: `starci app codemod explicit-surface` writes the inferred type of every export the classifier counts as open (R368): return types, variable, parameter and property types, from the app's own TypeScript program. It prefers a named type the program exports, writes `ReactElement` for components and Next's `Metadata` for `generateMetadata`, adds merged type-only imports after a directive prologue, compiles the result beside the original and writes a file only when it gains no diagnostic, and reports (with a suggested fix) destructured exports and anonymous, computed, too long, `any`, unnameable and predicate types. Prettier of the app formats what is written.
+- Added: `starci app codemod directive-first` moves a `"use client"` or `"use server"` below another statement, or in the form `("use client")`, to the first statement of its module (R369).
+- Changed: the test-world declaration (R47, R89) is read in its typed form, `const world: TestWorldApi = defineTestWorld({ ... })` with `useTestWorld` and `useSandbox` exported typed from it, as well as in the destructured form; the template writes the typed form, and a config with neither is still refused.
+- Added: `template-surface.spec.mts` holds every TypeScript template to R368 and R369 (the front-end units are judged through their generators).
+- Changed: the scaffold templates write the type of every export (R368): Nest module definitions export each `ConfigurableModuleHost` member with its type, hooks name their result interface, async pages and layouts return `Promise<ReactElement>`, redux, zustand, next-intl and Apollo exports are typed, SQL texts are `SqlText`, entity and migration lists are `DatabaseConnectionOptions` members. A new app scaffolds clean under `explicit-export-surface`.
+- Added: `runtime/scripts/lib/declaration-surface.mjs`, the one classifier of a TypeScript file's exported type surface (the isolated declaration emit and the exports it cannot write without inference, with the JSX-only component exemption), and `runtime/scripts/hfs/explicit-surface-rule.mjs`, the factory of the `explicit-export-surface` rule both lint canons build (R368). The app-check ESLint cache reads the same classifier for `open`, so the rule reports exactly the files the cache counts as open.
+- Changed: the ESLint child of the cached lint hands its project-graph snapshot out. The list runner (`lint/eslint-list.cjs`, now also the runner of a whole-side run, as the list `.`) asks each installed canon for `projectGraphSnapshot` after the lint and writes the findings beside its results; `lintSide` writes the `graph` records from them and builds the graph itself only for a canon the child did not answer for. A whole-side lint no longer builds the project graph a second time in the CLI process.
+
 ## 5.0.8
 
 - Removed: the `starci app lint` verb. `starci app check` is the one verb for app quality and carries what the lint verb carried: `--side be|fe` limits the lint gate to one side (reading and writing that side's cache records), `--out <file>` writes the merged Sonar Generic Issue Import document of the run (the findings of the selected gates under `starci-hfs`, then ESLint and stylelint), and `--fix` runs ESLint and stylelint with `--fix` before the check (with `--gate lint`). There is no `--changed` and no `--workspace`: the cache makes a whole-app check of an unchanged tree take seconds. The rendered `lint` and `lint:fix` scripts, the managed CI lint step and the release gate's Sonar row call `app check --gate lint`, and rule R13 requires that form.

package/cache/import-graph.mjs

@@ -6,6 +6,7 @@
 // added or removed file and every file that reaches one through imports, in the new graph and in the recorded one. Everything here is pure over
 // its inputs (the compiler, a file reader, the hashes), so a spec drives it with fixtures and the cache itself stays in lint-family.mts.
 import path from 'node:path';
+import { DECLARATION, SCRIPT, TYPESCRIPT, declarationSurface } from '../runtime/scripts/lib/declaration-surface.mjs';
 import { hashText } from './hash.mjs';
 export const posix = (file) => file.replace(/\\/g, '/').replace(/^\.\//, '');
 /** The compiler options of the side's own tsconfig (the file the typed ESLint run reads), or the permissive defaults when the side holds none. */
@@ -120,58 +121,6 @@ export function resolveImports(host, options, file, text) {
     }
     return [...found].sort();
 }
-/** Whether `expression` is a JSX element, fragment, `null` or `undefined`, or a conditional of those: its type does not depend on any other file. */
-function isJsxValue(ts, expression) {
-    if (expression === undefined)
-        return false;
-    let node = expression;
-    while (ts.isParenthesizedExpression(node))
-        node = node.expression;
-    if (ts.isJsxElement(node) || ts.isJsxSelfClosingElement(node) || ts.isJsxFragment(node) || node.kind === ts.SyntaxKind.NullKeyword)
-        return true;
-    if (ts.isIdentifier(node))
-        return node.text === 'undefined';
-    return ts.isConditionalExpression(node) && isJsxValue(ts, node.whenTrue) && isJsxValue(ts, node.whenFalse);
-}
-/**
- * Whether the function (or method) the declaration diagnostic at `start` points at has the type `JSX.Element | null | undefined` whatever its body
- * reads: not async, not a generator, and every `return` of its own (and its concise body) a JSX value. A React component written without a return
- * type is the common case; its inferred type is one the JSX namespace of the installed packages gives, which a lockfile change dirties as a whole.
- */
-function returnsOnlyJsx(ts, source, start) {
-    let found;
-    const find = (node) => {
-        if (found !== undefined || start < node.getFullStart() || start >= node.end)
-            return;
-        const named = (ts.isFunctionDeclaration(node) || ts.isMethodDeclaration(node)) && node.name !== undefined && node.name.getStart(source) === start;
-        if (named || ((ts.isArrowFunction(node) || ts.isFunctionExpression(node)) && node.getStart(source) === start)) {
-            found = node;
-            return;
-        }
-        ts.forEachChild(node, find);
-    };
-    find(source);
-    const fn = found;
-    if (fn === undefined || fn.type !== undefined || fn.body === undefined)
-        return false;
-    if (fn.asteriskToken !== undefined || (ts.getCombinedModifierFlags(fn) & ts.ModifierFlags.Async) !== 0)
-        return false;
-    if (!ts.isBlock(fn.body))
-        return isJsxValue(ts, fn.body);
-    let only = true;
-    const visit = (node) => {
-        if (!only || ts.isFunctionLike(node) || ts.isClassLike(node))
-            return;
-        if (ts.isReturnStatement(node) && node.expression !== undefined && !isJsxValue(ts, node.expression))
-            only = false;
-        ts.forEachChild(node, visit);
-    };
-    ts.forEachChild(fn.body, visit);
-    return only;
-}
-const SCRIPT = /\.(?:[cm]?jsx?)$/;
-const DECLARATION = /\.d\.[cm]?ts$/;
-const TYPESCRIPT = /\.(?:[cm]?tsx?)$/;
 /**
  * The type surface of one source file: the digest of its isolated declaration emit (`ts.transpileDeclaration`, TypeScript 5.5 and later, which reads the
  * file alone) and whether it is open. A body-only edit leaves the emit, and so the digest, as it was; a changed signature, export list or doc comment
@@ -184,16 +133,12 @@ export function surfaceOf(host, options, file, text) {
         return { api: hashText(text), open: true, refs: undefined };
     if (!TYPESCRIPT.test(file))
         return { api: hashText(text), open: false, refs: [] };
-    const emit = ts.transpileDeclaration;
-    if (emit === undefined)
-        return { api: undefined, open: true, refs: undefined };
     try {
-        const declared = emit.call(ts, text, { compilerOptions: { jsx: ts.JsxEmit.Preserve, target: ts.ScriptTarget.Latest, ...(options.module === undefined ? {} : { module: options.module }) }, fileName: file, reportDiagnostics: true });
-        const diagnostics = (declared.diagnostics ?? []);
-        // a declaration whose only diagnostics are components returning JSX has the surface its emit shows
-        const source = diagnostics.length === 0 ? undefined : ts.createSourceFile(file, text, ts.ScriptTarget.Latest, true, file.endsWith('x') ? ts.ScriptKind.TSX : ts.ScriptKind.TS);
-        const inferred = source !== undefined && !diagnostics.every((diagnostic) => (diagnostic.code === 9007 || diagnostic.code === 9008) && diagnostic.start !== undefined && returnsOnlyJsx(ts, source, diagnostic.start));
-        return { api: hashText(declared.outputText), open: inferred, refs: resolveImports(host, options, file, declared.outputText) };
+        const surface = declarationSurface(ts, file, text, options.module);
+        if (surface === null)
+            return { api: undefined, open: true, refs: undefined };
+        // the classifier is the one the explicit-export-surface rule of the canons reports with: a file is open exactly when it has a problem
+        return { api: hashText(surface.outputText), open: surface.problems.length > 0, refs: resolveImports(host, options, file, surface.outputText) };
     }
     catch {
         return { api: undefined, open: true, refs: undefined };

package/cache/lint-family.d.mts

@@ -78,10 +78,14 @@ export interface StylelintResult {
     warnings: StylelintWarning[];
     [key: string]: unknown;
 }
-/** The answer of a linter seam: validated results of the files it was asked about, or why it could not complete. */
+/**
+ * The answer of a linter seam: validated results of the files it was asked about, or why it could not complete. `graph` is, for ESLint, the project-graph
+ * snapshot each canon's graph rules built in the child, by canon name: the records of the `graph` step are written from it instead of building the graph again.
+ */
 export interface LinterOutcome<R> {
     results: R[];
     errors: string[];
+    graph?: Readonly<Record<string, GraphSnapshot>> | undefined;
 }
 /** Everything one side's cached lint needs. */
 export interface LintSideInput {
@@ -147,6 +151,11 @@ export declare function crossDigestFactory(options: {
 }): (file: string) => string | undefined;
 /** The TypeScript the app installed, resolved from the side folder like the linters are (not this package's own copy). */
 export declare function loadAppTypeScript(sideRoot: string): Ts;
+/**
+ * The graph findings of every canon that publishes graph rules, merged by file and sorted. A canon whose snapshot the ESLint child handed out (`handed`, by
+ * canon name) is not asked to build its graph again; any other canon builds it through its `projectGraph`.
+ */
+export declare function mergedSnapshot(sideRoot: string, canons: readonly CanonDeclarations[], handed?: Readonly<Record<string, GraphSnapshot>>): Record<string, GraphFinding[]> | null;
 /**
  * Judges one side: ESLint (and, for fe, stylelint) over what the records cannot vouch for, the records of the rest, and the new records.
  * Never throws for a tool failure: those come back in `errors`, and a side with an error stores nothing.

package/cache/lint-family.mjs

@@ -164,15 +164,20 @@ function graphHost(ts, sideRoot, hashOf) {
 }
 /** A record's `data` object, or an empty one. */
 const dataOf = (record) => (record.data !== null && typeof record.data === 'object' && !Array.isArray(record.data) ? record.data : {});
-/** The graph findings of every canon that publishes graph rules, merged by file and sorted. */
-function mergedSnapshot(sideRoot, canons) {
+/**
+ * The graph findings of every canon that publishes graph rules, merged by file and sorted. A canon whose snapshot the ESLint child handed out (`handed`, by
+ * canon name) is not asked to build its graph again; any other canon builds it through its `projectGraph`.
+ */
+export function mergedSnapshot(sideRoot, canons, handed) {
     const merged = {};
     for (const canon of canons) {
         if (!canon.graphRules)
             continue;
-        if (canon.projectGraph === null)
+        const given = handed?.[canon.name];
+        if (given === undefined && canon.projectGraph === null)
             return null;
-        for (const [file, findings] of Object.entries(canon.projectGraph({ repoRoot: sideRoot }).byFile))
+        const { byFile } = given ?? canon.projectGraph({ repoRoot: sideRoot });
+        for (const [file, findings] of Object.entries(byFile))
             merged[posix(file)] = [...(merged[posix(file)] ?? []), ...findings];
     }
     for (const list of Object.values(merged))
@@ -331,12 +336,14 @@ export async function lintSide(input) {
     // ------------------------------------------------------------------ the run
     const eslintList = [...dirtyEslint].sort();
     const styleList = [...dirtyStyle].sort();
+    let handedGraph;
     const freshEslint = new Map();
     const freshStyle = new Map();
     const rootOf = (file) => path.relative(sideRoot, file).replace(/\\/g, '/');
     if (eslintList.length > 0) {
         const run = await input.eslint(whole !== null ? null : eslintList);
         errors.push(...run.errors);
+        handedGraph = run.graph;
         for (const result of run.results)
             freshEslint.set(posix(rootOf(result.filePath)), result);
     }
@@ -408,7 +415,7 @@ export async function lintSide(input) {
                 if (!moved.has(file))
                     records.push({ path: file, step: LINT_STEPS.imports, hash: node.hash, findings: [], data: { globals: node.declaresGlobals, imports: node.imports, ...(node.api === undefined ? {} : { api: node.api }), open: node.open !== false, ...(node.refs === undefined ? {} : { refs: node.refs }) } });
             }
-            snapshot ??= mergedSnapshot(sideRoot, input.canons);
+            snapshot ??= mergedSnapshot(sideRoot, input.canons, handedGraph);
             for (const [file, findings] of Object.entries(snapshot ?? {})) {
                 if (scopeSet.has(file) && !moved.has(file) && findings.length > 0)
                     records.push({ path: file, step: LINT_STEPS.graph, hash: planHash(file), findings: graphRecordFindings(side, file, findings) });

package/codemod/directive-first.d.mts

@@ -0,0 +1,48 @@
+/** The TypeScript compiler API of the app's own install (loadTypescript), typed by the version this package develops against. */
+type Ts = typeof import('typescript');
+/** One move of the report: a directive taken from `line` to the top of its module. */
+export interface DirectiveFirstChange {
+    file: string;
+    line: number;
+    column: number;
+    code: string;
+    from: string;
+    to: string;
+}
+/** One case left for a person. */
+export interface DirectiveFirstFinding {
+    file: string;
+    line: number;
+    column: number;
+    code: string;
+    reason: string;
+}
+/** The report of a migration (`starci app codemod directive-first`). */
+export interface DirectiveFirstReport {
+    schema: string;
+    root: string;
+    write: boolean;
+    filesScanned: number;
+    filesChanged: string[];
+    changes: DirectiveFirstChange[];
+    findings: DirectiveFirstFinding[];
+}
+/** Move every `"use client"` / `"use server"` that is not in the prologue of the module to the top of it, as its first statement, with one blank line after. */
+export declare function transformDirectiveFirst({ ts, text, file }: {
+    ts: Ts;
+    text: string;
+    file?: string;
+}): {
+    text: string;
+    changes: DirectiveFirstChange[];
+    findings: DirectiveFirstFinding[];
+};
+/** Preview or apply the moves in one app (`be/`, `fe/`, or `src/` of a single-side app); a conflicting module is kept in the returned report. */
+export declare function migrateDirectiveFirst({ root, write, ts }: {
+    root: string;
+    write?: boolean;
+    ts?: Ts | null;
+}): DirectiveFirstReport;
+/** Render the moves and what is left for a person as Markdown; JSON consumers read the same report object. */
+export declare function directiveFirstMarkdown(report: DirectiveFirstReport): string;
+export {};

package/codemod/directive-first.mjs

@@ -0,0 +1,136 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { loadTypescript } from '../runtime/scripts/lib/package-at.mjs';
+import { sourceLocation } from '../runtime/scripts/lib/ts-ast.mjs';
+import { filesUnder, relativePosix, sideFolders } from './source-tree.mjs';
+const PACKAGE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+/** The directives Next.js reads from the prologue of a module (R369, FE_DIRECTIVE_FIRST). */
+const DIRECTIVES = new Set(['use client', 'use server']);
+const SOURCE = /\.(?:[cm]?[jt]s|[jt]sx)$/i;
+const DECLARATION = /\.d\.[cm]?ts$/i;
+/** The string literal a statement is made of, through the parentheses Prettier wraps it in, or null. */
+function stringStatement(ts, statement) {
+    if (!ts.isExpressionStatement(statement))
+        return null;
+    let expression = statement.expression;
+    while (ts.isParenthesizedExpression(expression))
+        expression = expression.expression;
+    return ts.isStringLiteral(expression) ? expression : null;
+}
+/** The span to delete for `statement`: its own line when nothing else is on it (with a `;` Prettier put before a parenthesized statement), else the statement alone. */
+function removalSpan(text, statement, source) {
+    let start = statement.getStart(source);
+    let end = statement.end;
+    let from = start;
+    while (from > 0 && (text[from - 1] === ' ' || text[from - 1] === '\t'))
+        from -= 1;
+    if (text[from - 1] === ';' && (from - 1 === 0 || text[from - 2] === '\n'))
+        from -= 1;
+    const startsLine = from === 0 || text[from - 1] === '\n';
+    let to = end;
+    while (to < text.length && (text[to] === ' ' || text[to] === '\t'))
+        to += 1;
+    const endsLine = to >= text.length || text[to] === '\n' || text[to] === '\r';
+    if (startsLine && endsLine) {
+        start = from;
+        end = text[to] === '\r' ? to + 2 : to + 1;
+    }
+    return { start, end: Math.min(end, text.length) };
+}
+/** Move every `"use client"` / `"use server"` that is not in the prologue of the module to the top of it, as its first statement, with one blank line after. */
+export function transformDirectiveFirst({ ts, text, file = 'module.tsx' }) {
+    const none = { text, changes: [], findings: [] };
+    if (!text.includes('use client') && !text.includes('use server'))
+        return none;
+    const kind = /\.tsx$/i.test(file) ? ts.ScriptKind.TSX : /\.jsx$/i.test(file) ? ts.ScriptKind.JSX : /\.[cm]?js$/i.test(file) ? ts.ScriptKind.JS : ts.ScriptKind.TS;
+    const source = ts.createSourceFile(file, text, ts.ScriptTarget.Latest, true, kind);
+    const first = source.statements[0];
+    if (first === undefined)
+        return none;
+    // The prologue is the run of plain string statements at the top; a parenthesized one is an expression, not a directive.
+    let prologueEnd = 0;
+    const kept = new Set();
+    while (prologueEnd < source.statements.length) {
+        const statement = source.statements[prologueEnd];
+        if (!ts.isExpressionStatement(statement) || !ts.isStringLiteral(statement.expression))
+            break;
+        kept.add(statement.expression.text);
+        prologueEnd += 1;
+    }
+    const misplaced = source.statements.slice(prologueEnd).flatMap((statement, offset) => {
+        const literal = stringStatement(ts, statement);
+        return literal !== null && DIRECTIVES.has(literal.text) ? [{ statement, literal, before: prologueEnd + offset }] : [];
+    });
+    if (!misplaced.length)
+        return none;
+    const changes = [];
+    const findings = [];
+    const opposite = (directive) => (directive === 'use client' ? 'use server' : 'use client');
+    const wanted = new Set(misplaced.map(entry => entry.literal.text));
+    const edits = [];
+    const toTop = [];
+    const placed = new Set(kept);
+    for (const { statement, literal, before } of misplaced) {
+        const place = sourceLocation(source, statement);
+        const directive = literal.text;
+        if (kept.has(opposite(directive)) || wanted.has(opposite(directive))) {
+            findings.push({ file, ...place, code: 'CONFLICTING_DIRECTIVES', reason: `"use client" and "use server" cannot share a module: split it, then keep the one directive that stays at the top` });
+            continue;
+        }
+        edits.push({ ...removalSpan(text, statement, source), text: '' });
+        if (!placed.has(directive)) {
+            toTop.push(literal.getText(source) + (statement.getText(source).endsWith(';') ? ';' : ''));
+            placed.add(directive);
+        }
+        const mangled = ts.isExpressionStatement(statement) && ts.isParenthesizedExpression(statement.expression);
+        changes.push({ file, ...place, code: mangled ? 'DIRECTIVE_PARENTHESIZED' : 'DIRECTIVE_BELOW_STATEMENT', from: `${mangled ? 'parenthesized, ' : ''}after ${before} statement${before === 1 ? '' : 's'}`, to: 'first statement' });
+    }
+    if (toTop.length)
+        edits.push({ start: first.getStart(source), end: first.getStart(source), text: `${toTop.join('\n')}\n\n` });
+    let output = text;
+    for (const edit of edits.sort((a, b) => b.start - a.start || b.end - a.end))
+        output = output.slice(0, edit.start) + edit.text + output.slice(edit.end);
+    return { text: output, changes, findings };
+}
+/** Preview or apply the moves in one app (`be/`, `fe/`, or `src/` of a single-side app); a conflicting module is kept in the returned report. */
+export function migrateDirectiveFirst({ root, write = false, ts = loadTypescript(root, PACKAGE_ROOT) }) {
+    if (!ts)
+        throw new Error('directive-first needs TypeScript installed in the app or @starci/hfs development checkout');
+    const folders = sideFolders(root);
+    if (!folders.length)
+        throw new Error('directive-first runs at an app root with a fe/ directory');
+    const report = { schema: 'starci/directive-first-report@1', root, write, filesScanned: 0, filesChanged: [], changes: [], findings: [] };
+    for (const target of folders.flatMap(folder => filesUnder(folder, SOURCE)).filter(target => !DECLARATION.test(target))) {
+        const file = relativePosix(root, target);
+        const original = fs.readFileSync(target, 'utf8');
+        const result = transformDirectiveFirst({ ts, text: original, file });
+        report.filesScanned += 1;
+        report.changes.push(...result.changes);
+        report.findings.push(...result.findings);
+        if (result.text !== original) {
+            report.filesChanged.push(file);
+            if (write)
+                fs.writeFileSync(target, result.text);
+        }
+    }
+    return report;
+}
+const cell = (value) => String(value).replaceAll('|', '\\|').replaceAll('\n', ' ');
+/** Render the moves and what is left for a person as Markdown; JSON consumers read the same report object. */
+export function directiveFirstMarkdown(report) {
+    const out = ['# directive-first', '', `Scanned ${report.filesScanned} files, ${report.filesChanged.length} ${report.write ? 'changed' : 'would change'}, ${report.changes.length} directives moved, ${report.findings.length} left for a person.`, ''];
+    if (report.findings.length) {
+        out.push('## Left for a person', '', '| location | code | reason |', '|---|---|---|');
+        for (const finding of report.findings)
+            out.push(`| ${cell(`${finding.file}:${finding.line}:${finding.column}`)} | ${finding.code} | ${cell(finding.reason)} |`);
+        out.push('');
+    }
+    if (report.changes.length) {
+        out.push('## Moves', '', '| location | code | from | to |', '|---|---|---|---|');
+        for (const item of report.changes)
+            out.push(`| ${cell(`${item.file}:${item.line}:${item.column}`)} | ${item.code} | ${cell(item.from)} | ${cell(item.to)} |`);
+        out.push('');
+    }
+    return `${out.join('\n')}\n`;
+}

package/codemod/explicit-surface-edit.d.mts

@@ -0,0 +1,14 @@
+import type { ImportNeed } from './explicit-surface-render.mjs';
+import type * as TsTypes from 'typescript';
+type Ts = typeof import('typescript');
+/** One text edit of the source: the span `start`..`end` becomes `text`. */
+export interface Edit {
+    start: number;
+    end: number;
+    text: string;
+}
+/** The edits that give a file the imports `needs` names: a specifier added to a named import of the same module, else one `import type` line per module. */
+export declare function importEdits(ts: Ts, source: TsTypes.SourceFile, text: string, needs: readonly ImportNeed[]): Edit[];
+/** `text` with `edits` applied, last position first so every offset stays true; edits at one position keep their order. */
+export declare function applyEdits(text: string, edits: readonly Edit[]): string;
+export {};

package/codemod/explicit-surface-edit.mjs

@@ -0,0 +1,57 @@
+/** The edits that give a file the imports `needs` names: a specifier added to a named import of the same module, else one `import type` line per module. */
+export function importEdits(ts, source, text, needs) {
+    if (!needs.length)
+        return [];
+    const eol = text.includes('\r\n') ? '\r\n' : '\n';
+    const imports = source.statements.filter(ts.isImportDeclaration);
+    const first = imports[0];
+    const quote = first !== undefined && ts.isStringLiteral(first.moduleSpecifier) ? first.moduleSpecifier.getText(source).slice(0, 1) : '"';
+    const semicolon = first !== undefined && first.getText(source).endsWith(';') ? ';' : '';
+    const edits = [];
+    const lines = [];
+    const bySpecifier = new Map();
+    for (const need of needs)
+        bySpecifier.set(need.specifier, [...(bySpecifier.get(need.specifier) ?? []), need.name]);
+    for (const [specifier, names] of bySpecifier) {
+        const sorted = [...new Set(names)].sort();
+        const home = imports.find(declaration => ts.isStringLiteral(declaration.moduleSpecifier) && declaration.moduleSpecifier.text === specifier
+            && declaration.importClause?.namedBindings !== undefined && ts.isNamedImports(declaration.importClause.namedBindings) && declaration.importClause.namedBindings.elements.length > 0);
+        const clause = home?.importClause;
+        const bindings = clause?.namedBindings;
+        if (clause !== undefined && bindings !== undefined && ts.isNamedImports(bindings)) {
+            const last = bindings.elements[bindings.elements.length - 1];
+            edits.push({ start: last.end, end: last.end, text: sorted.map(name => `, ${clause.isTypeOnly ? '' : 'type '}${name}`).join('') });
+        }
+        else
+            lines.push(`import type { ${sorted.join(', ')} } from ${quote}${specifier}${quote}${semicolon}`);
+    }
+    if (lines.length)
+        edits.push(newImports(ts, source, text, lines, eol));
+    return edits;
+}
+/** The edit that adds whole import lines: after the last import, else after the directive prologue, else above the first statement. */
+function newImports(ts, source, text, lines, eol) {
+    const block = lines.join(eol);
+    const last = source.statements.filter(ts.isImportDeclaration).at(-1);
+    if (last !== undefined)
+        return { start: last.end, end: last.end, text: `${eol}${block}` };
+    let prologue;
+    for (const statement of source.statements) {
+        if (!ts.isExpressionStatement(statement) || !ts.isStringLiteral(statement.expression))
+            break;
+        prologue = statement;
+    }
+    if (prologue !== undefined)
+        return { start: prologue.end, end: prologue.end, text: `${eol}${eol}${block}` };
+    const first = source.statements[0];
+    const at = first === undefined ? text.length : first.getStart(source);
+    return { start: at, end: at, text: `${block}${eol}${eol}` };
+}
+/** `text` with `edits` applied, last position first so every offset stays true; edits at one position keep their order. */
+export function applyEdits(text, edits) {
+    const ordered = edits.map((edit, at) => ({ edit, at })).sort((a, b) => b.edit.start - a.edit.start || b.edit.end - a.edit.end || b.at - a.at);
+    let output = text;
+    for (const { edit } of ordered)
+        output = output.slice(0, edit.start) + edit.text + output.slice(edit.end);
+    return output;
+}

package/codemod/explicit-surface-names.d.mts

@@ -0,0 +1,30 @@
+import type * as TsTypes from 'typescript';
+/** The TypeScript compiler API of the app's own install, typed by the version this package develops against. */
+type Ts = typeof import('typescript');
+/** What naming a type reads of the app: its compiler, program and one source file. */
+export interface NamingContext {
+    ts: Ts;
+    program: TsTypes.Program;
+    checker: TsTypes.TypeChecker;
+    options: TsTypes.CompilerOptions;
+    source: TsTypes.SourceFile;
+    /** The absolute, forward-slash name of the file being annotated. */
+    file: string;
+    text: string;
+}
+/** The source file of the program a module path (absolute, without its extension) names, or undefined. */
+export declare function moduleFile(c: NamingContext, modulePath: string): TsTypes.SourceFile | undefined;
+/** The symbol a module exports under `name`, with aliases resolved, or undefined. */
+export declare function exportedSymbol(c: NamingContext, file: TsTypes.SourceFile, name: string): TsTypes.Symbol | undefined;
+/** The declaration `symbol` stands for: an import resolved to what it imports, a local export to its export symbol, so two names of one declaration compare equal. */
+export declare function declarationOf(c: NamingContext, symbol: TsTypes.Symbol): TsTypes.Symbol;
+/** The names that can be written at `enclosing` without an import, as symbols; what a function body declares is not visible from its signature. */
+export declare function namesInScope(c: NamingContext, enclosing: TsTypes.Node): Map<string, TsTypes.Symbol>;
+/**
+ * `node` (the type node the checker wrote for `type`) with every anonymous object type that an exported type of the app stands for replaced by a
+ * reference to that type. It follows type arguments (`Promise<{...}>`), arrays and unions; any other anonymous part stays for the caller to refuse.
+ */
+export declare function nameAnonymousParts(c: NamingContext, node: TsTypes.TypeNode, type: TsTypes.Type, enclosing: TsTypes.Node): TsTypes.TypeNode;
+/** The directory-relative form of `target` from the folder of `from`, without extension, the way a relative import is written. */
+export declare function relativeSpecifier(from: string, target: string): string;
+export {};

package/codemod/explicit-surface-names.mjs

@@ -0,0 +1,135 @@
+import path from 'node:path';
+const EXTENSIONS = ['', '.ts', '.tsx', '.d.ts', '.mts', '.d.mts', '.cts', '.d.cts', '/index.ts', '/index.tsx', '/index.d.ts'];
+const posix = (file) => file.replaceAll('\\', '/');
+/** The source file of the program a module path (absolute, without its extension) names, or undefined. */
+export function moduleFile(c, modulePath) {
+    for (const extension of EXTENSIONS) {
+        const found = c.program.getSourceFile(posix(modulePath) + extension);
+        if (found !== undefined)
+            return found;
+    }
+    return undefined;
+}
+/** The symbol a module exports under `name`, with aliases resolved, or undefined. */
+export function exportedSymbol(c, file, name) {
+    const module = c.checker.getSymbolAtLocation(file);
+    if (module === undefined)
+        return undefined;
+    const found = c.checker.getExportsOfModule(module).find(symbol => symbol.name === name);
+    if (found === undefined)
+        return undefined;
+    return (found.flags & c.ts.SymbolFlags.Alias) === 0 ? found : c.checker.getAliasedSymbol(found);
+}
+/** The declaration `symbol` stands for: an import resolved to what it imports, a local export to its export symbol, so two names of one declaration compare equal. */
+export function declarationOf(c, symbol) {
+    const target = (symbol.flags & c.ts.SymbolFlags.Alias) === 0 ? symbol : c.checker.getAliasedSymbol(symbol);
+    return c.checker.getExportSymbolOfSymbol(target);
+}
+/** The key that groups candidate types before the expensive assignability test: the sorted property names. */
+const shapeKey = (names) => [...names].sort().join(',');
+const indexes = new WeakMap();
+/** The exported, non-generic object types of the app's own files (never installed packages or declaration files), by their property names. */
+function namedTypes(c) {
+    const known = indexes.get(c.program);
+    if (known !== undefined)
+        return known;
+    const found = new Map();
+    for (const file of c.program.getSourceFiles()) {
+        if (file.isDeclarationFile || c.program.isSourceFileFromExternalLibrary(file) || file.fileName.includes('/node_modules/'))
+            continue;
+        const module = c.checker.getSymbolAtLocation(file);
+        if (module === undefined)
+            continue;
+        for (const symbol of c.checker.getExportsOfModule(module)) {
+            const target = (symbol.flags & c.ts.SymbolFlags.Alias) === 0 ? symbol : c.checker.getAliasedSymbol(symbol);
+            if ((target.flags & (c.ts.SymbolFlags.TypeAlias | c.ts.SymbolFlags.Interface)) === 0)
+                continue;
+            const type = c.checker.getDeclaredTypeOfSymbol(target);
+            const generic = type.typeParameters?.length ?? type.aliasTypeArguments?.length ?? 0;
+            if (generic > 0 || (type.flags & c.ts.TypeFlags.Object) === 0)
+                continue;
+            const key = shapeKey(c.checker.getPropertiesOfType(type).map(property => property.name));
+            if (key === '')
+                continue;
+            found.set(key, [...(found.get(key) ?? []), { name: symbol.name, type, file: file.fileName }]);
+        }
+    }
+    indexes.set(c.program, found);
+    return found;
+}
+/** The names that can be written at `enclosing` without an import, as symbols; what a function body declares is not visible from its signature. */
+export function namesInScope(c, enclosing) {
+    const flags = c.ts.SymbolFlags.Type | c.ts.SymbolFlags.Namespace | c.ts.SymbolFlags.Alias | c.ts.SymbolFlags.Value;
+    const body = enclosing.body;
+    const inBody = (symbol) => body !== undefined && symbol.declarations?.length !== 0 && symbol.declarations?.every(declaration => declaration.pos >= body.pos && declaration.end <= body.end) === true;
+    return new Map(c.checker.getSymbolsInScope(enclosing, flags).filter(symbol => !inBody(symbol)).map(symbol => [symbol.name, symbol]));
+}
+/**
+ * The one exported type of the app that is interchangeable with the inferred object type `type` (each assignable to the other and the same property names),
+ * preferring a name the file already has in scope; undefined when none or more than one fits, so a guess never stands for the inference.
+ */
+function matchingName(c, type, enclosing) {
+    if ((type.flags & c.ts.TypeFlags.Object) === 0)
+        return undefined;
+    const key = shapeKey(c.checker.getPropertiesOfType(type).map(property => property.name));
+    const fits = (namedTypes(c).get(key) ?? []).filter(named => c.checker.isTypeAssignableTo(type, named.type) && c.checker.isTypeAssignableTo(named.type, type));
+    if (fits.length <= 1)
+        return fits[0];
+    const scope = namesInScope(c, enclosing);
+    const local = fits.filter(named => scope.has(named.name));
+    return local.length === 1 ? local[0] : undefined;
+}
+/** The type argument nodes of `node` paired with the type arguments the checker holds for `type`. */
+function argumentsOf(c, type) {
+    if ((type.flags & c.ts.TypeFlags.Object) !== 0 && (type.objectFlags & c.ts.ObjectFlags.Reference) !== 0)
+        return c.checker.getTypeArguments(type);
+    return type.aliasTypeArguments ?? [];
+}
+/**
+ * `node` (the type node the checker wrote for `type`) with every anonymous object type that an exported type of the app stands for replaced by a
+ * reference to that type. It follows type arguments (`Promise<{...}>`), arrays and unions; any other anonymous part stays for the caller to refuse.
+ */
+export function nameAnonymousParts(c, node, type, enclosing) {
+    const { ts } = c;
+    const reference = (named) => c.checker.typeToTypeNode(named.type, enclosing, ts.NodeBuilderFlags.NoTruncation);
+    if (ts.isTypeLiteralNode(node) && node.members.length > 0) {
+        const named = matchingName(c, type, enclosing);
+        return (named === undefined ? undefined : reference(named)) ?? node;
+    }
+    if (ts.isArrayTypeNode(node) || ts.isTypeReferenceNode(node) || ts.isImportTypeNode(node)) {
+        const given = ts.isArrayTypeNode(node) ? [node.elementType] : node.typeArguments ?? [];
+        const held = argumentsOf(c, type);
+        if (!given.length || held.length < given.length)
+            return node;
+        const named = given.map((child, at) => nameAnonymousParts(c, child, held[at], enclosing));
+        if (named.every((child, at) => child === given[at]))
+            return node;
+        const { factory } = ts;
+        if (ts.isArrayTypeNode(node))
+            return factory.updateArrayTypeNode(node, named[0]);
+        if (ts.isImportTypeNode(node))
+            return factory.updateImportTypeNode(node, node.argument, node.attributes, node.qualifier, named, node.isTypeOf);
+        return factory.updateTypeReferenceNode(node, node.typeName, factory.createNodeArray(named));
+    }
+    if (ts.isUnionTypeNode(node) && type.isUnion()) {
+        const members = type.types.filter(member => (member.flags & ts.TypeFlags.Object) !== 0);
+        const used = new Set();
+        const named = node.types.map(child => {
+            if (!ts.isTypeLiteralNode(child))
+                return child;
+            const key = shapeKey(child.members.map(member => (member.name === undefined ? '' : ts.isIdentifier(member.name) || ts.isStringLiteral(member.name) ? member.name.text : '')));
+            const match = members.find(member => !used.has(member) && shapeKey(c.checker.getPropertiesOfType(member).map(property => property.name)) === key);
+            if (match === undefined)
+                return child;
+            used.add(match);
+            return nameAnonymousParts(c, child, match, enclosing);
+        });
+        return named.every((child, at) => child === node.types[at]) ? node : ts.factory.updateUnionTypeNode(node, ts.factory.createNodeArray(named));
+    }
+    return node;
+}
+/** The directory-relative form of `target` from the folder of `from`, without extension, the way a relative import is written. */
+export function relativeSpecifier(from, target) {
+    const relative = posix(path.relative(path.dirname(from), target)).replace(/\.(?:d\.)?[cm]?tsx?$/, '');
+    return relative.startsWith('.') ? relative : `./${relative}`;
+}

package/codemod/explicit-surface-render.d.mts

@@ -0,0 +1,29 @@
+import { type NamingContext } from './explicit-surface-names.mjs';
+import type * as TsTypes from 'typescript';
+/** An import the written type needs: `name` exported by the module `specifier`. */
+export interface ImportNeed {
+    name: string;
+    specifier: string;
+}
+/** A type written as source text, with the imports it needs. */
+export interface Rendered {
+    ok: true;
+    text: string;
+    needs: ImportNeed[];
+}
+/** Why a type is not written: a code of the report, the reason, and what a person does about it. */
+export interface Refused {
+    ok: false;
+    code: string;
+    reason: string;
+    suggestion: string;
+}
+/** The longest type the codemod writes on one line; a longer one is a type a person names. */
+export declare const MAX_TYPE_LENGTH = 100;
+/**
+ * The type Next.js names for a route export (`generateMetadata`: `Promise<Metadata>`, `metadata`: `Metadata`, and the viewport pair), when `next` is installed and the inferred
+ * type is assignable to it; undefined for any other export, so the inferred type is written instead.
+ */
+export declare function conventionType(c: NamingContext, name: string, inferred: TsTypes.Type, enclosing: TsTypes.Node, kind: 'function' | 'variable'): Rendered | undefined;
+/** Writes `type`, as it is seen from `enclosing`, as source text: named types by name, the imports they need, or the reason it is left to a person. */
+export declare function renderType(c: NamingContext, type: TsTypes.Type, enclosing: TsTypes.Node, maxLength?: number): Rendered | Refused;