@starci/hfs 5.0.7 → 5.1.0

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;

package/codemod/explicit-surface-render.mjs

@@ -0,0 +1,197 @@
+import path from 'node:path';
+import { declarationOf, exportedSymbol, moduleFile, nameAnonymousParts, namesInScope, relativeSpecifier } from './explicit-surface-names.mjs';
+/** The longest type the codemod writes on one line; a longer one is a type a person names. */
+export const MAX_TYPE_LENGTH = 100;
+const refuse = (code, reason, suggestion) => ({ ok: false, code, reason, suggestion });
+const posix = (file) => file.replaceAll('\\', '/');
+const ABSOLUTE = /^(?:[A-Za-z]:)?\//;
+const JSX_ELEMENT = new Set(['JSX.Element', 'React.JSX.Element']);
+/** The text of an entity name (`A.B.C`). */
+function entityText(ts, name) {
+    return ts.isIdentifier(name) ? name.text : `${entityText(ts, name.left)}.${name.right.text}`;
+}
+/** The leftmost identifier of an entity name. */
+function rootIdentifier(ts, name) {
+    return ts.isIdentifier(name) ? name : rootIdentifier(ts, name.left);
+}
+/** The package specifier of a file under `node_modules` (`@types/react` is `react`, `@types/a__b` is `@a/b`), and the path inside it. */
+function packageOf(file) {
+    const at = file.lastIndexOf('/node_modules/');
+    if (at < 0)
+        return undefined;
+    const parts = file.slice(at + '/node_modules/'.length).split('/');
+    const scoped = parts[0]?.startsWith('@') === true;
+    let name = parts.slice(0, scoped ? 2 : 1).join('/');
+    const typed = /^@types\/(.+)$/.exec(name);
+    if (typed?.[1] !== undefined)
+        name = typed[1].includes('__') ? `@${typed[1].replace('__', '/')}` : typed[1];
+    return { name, inner: parts.slice(scoped ? 2 : 1).join('/').replace(/\.(?:d\.)?[cm]?tsx?$/, '').replace(/\/?index$/, '') };
+}
+/** The specifiers an import of `target` from `c.file` can be written with, best first: a package name, a path alias the file already uses, a relative path. */
+function specifierCandidates(c, target) {
+    const installed = packageOf(posix(target.fileName));
+    if (installed !== undefined)
+        return [installed.name, ...(installed.inner ? [`${installed.name}/${installed.inner}`] : [])];
+    const relative = relativeSpecifier(c.file, target.fileName);
+    const nodeNext = c.options.moduleResolution === c.ts.ModuleResolutionKind.NodeNext || c.options.moduleResolution === c.ts.ModuleResolutionKind.Node16;
+    const extension = /\.([cm]?)tsx?$/.exec(target.fileName);
+    const written = nodeNext ? `${relative}.${extension?.[1] === 'm' ? 'mjs' : extension?.[1] === 'c' ? 'cjs' : 'js'}` : relative;
+    const aliases = [];
+    const base = c.options.baseUrl ?? c.options['pathsBasePath'] ?? path.dirname(c.file);
+    const bare = posix(target.fileName).replace(/\.(?:d\.)?[cm]?tsx?$/, '');
+    for (const [pattern, targets] of Object.entries(c.options.paths ?? {})) {
+        for (const to of targets) {
+            const [head = '', tail = ''] = to.split('*');
+            const prefix = posix(path.resolve(base, head)) + (head.endsWith('/') ? '/' : '');
+            if (to.includes('*') && bare.startsWith(prefix) && bare.endsWith(tail))
+                aliases.push(pattern.replace('*', bare.slice(prefix.length, bare.length - tail.length)));
+            else if (!to.includes('*') && bare === posix(path.resolve(base, to)).replace(/\.(?:d\.)?[cm]?tsx?$/, ''))
+                aliases.push(pattern);
+        }
+    }
+    const usesAlias = c.source.statements.some(statement => c.ts.isImportDeclaration(statement) && c.ts.isStringLiteral(statement.moduleSpecifier)
+        && Object.keys(c.options.paths ?? {}).some(pattern => statement.moduleSpecifier.getText(c.source).slice(1, -1).startsWith(pattern.replace('*', ''))));
+    return usesAlias ? [...aliases, written] : [written, ...aliases];
+}
+/** Whether `specifier`, written in `c.file`, reaches the same declaration of `name` that `target` holds. */
+function reaches(c, specifier, name, target) {
+    const resolved = c.ts.resolveModuleName(specifier, c.file, c.options, c.ts.sys).resolvedModule?.resolvedFileName;
+    const file = resolved === undefined ? undefined : c.program.getSourceFile(posix(resolved));
+    return file !== undefined && exportedSymbol(c, file, name) === target;
+}
+/** The module file a raw specifier of the checker's import type names: an absolute path without extension, or a module name. */
+function targetModule(c, raw) {
+    if (ABSOLUTE.test(raw))
+        return moduleFile(c, raw);
+    const resolved = c.ts.resolveModuleName(raw, c.file, c.options, c.ts.sys).resolvedModule?.resolvedFileName;
+    return resolved === undefined ? undefined : c.program.getSourceFile(posix(resolved));
+}
+/**
+ * How `name`, exported by the module the checker named with `raw`, is written in the file: an import specifier to add, `null` when the file already has the
+ * name bound to that very declaration, or a refusal when the name is taken by something else or no specifier of the file reaches it.
+ */
+function resolveNeed(c, scope, name, raw) {
+    const file = targetModule(c, raw);
+    const target = file === undefined ? undefined : exportedSymbol(c, file, name);
+    if (file === undefined || target === undefined)
+        return refuse('TYPE_UNNAMEABLE', `\`${name}\` is not exported by a module the file can import`, `export ${name} from its module, or declare a named type in this file`);
+    const taken = scope.get(name);
+    if (taken !== undefined) {
+        if (declarationOf(c, taken) === declarationOf(c, target))
+            return { specifier: null };
+        const global = taken.declarations?.every(declaration => !c.ts.isExternalModule(declaration.getSourceFile())) === true;
+        if (!global || new RegExp(`\\b${name}\\b`).test(c.text))
+            return refuse('TYPE_UNNAMEABLE', `\`${name}\` is already another name in this file`, `rename one of the two, or declare a named type in this file`);
+    }
+    const specifier = specifierCandidates(c, file).find(candidate => reaches(c, candidate, name, target));
+    return specifier === undefined ? refuse('TYPE_UNNAMEABLE', `no import path of this file reaches \`${name}\` (${posix(file.fileName)})`, `export ${name} from a module this file can import, or declare a named type in this file`) : { specifier };
+}
+/** Writes the checker's type node as source: import types become names plus imports, `JSX.Element` becomes `ReactElement`, and anonymous, `any` and non-nameable parts are refused. */
+function rewrite(c, node, scope, needs) {
+    const { ts } = c;
+    let refused;
+    const need = (name, raw) => {
+        const resolved = resolveNeed(c, scope, name, raw);
+        if ('ok' in resolved)
+            refused ??= resolved;
+        else if (resolved.specifier !== null && !needs.some(entry => entry.name === name && entry.specifier === resolved.specifier))
+            needs.push({ name, specifier: resolved.specifier });
+    };
+    // The checker names a type by an identifier that carries its symbol: a name the file cannot write is imported from the module that exports it.
+    const named = (id) => {
+        const symbol = id.symbol;
+        if (symbol === undefined)
+            return;
+        if ((symbol.flags & ts.SymbolFlags.TypeParameter) !== 0)
+            return;
+        const taken = scope.get(id.text);
+        if (taken !== undefined && declarationOf(c, taken) === declarationOf(c, symbol))
+            return;
+        const file = symbol.declarations?.[0]?.getSourceFile();
+        if (file !== undefined && ts.isExternalModule(file))
+            need(id.text, file.fileName);
+    };
+    const result = ts.transform(node, [context => root => {
+            const visit = (child) => {
+                if (ts.isImportTypeNode(child)) {
+                    const literal = ts.isLiteralTypeNode(child.argument) && ts.isStringLiteral(child.argument.literal) ? child.argument.literal.text : undefined;
+                    if (child.isTypeOf || child.qualifier === undefined || literal === undefined) {
+                        refused ??= refuse('TYPE_UNNAMEABLE', 'the type is a module or a `typeof import(...)`', 'declare a named type and annotate with it');
+                        return child;
+                    }
+                    const args = child.typeArguments?.map(argument => visit(argument));
+                    if (JSX_ELEMENT.has(entityText(ts, child.qualifier))) {
+                        need('ReactElement', 'react');
+                        return context.factory.createTypeReferenceNode('ReactElement');
+                    }
+                    need(rootIdentifier(ts, child.qualifier).text, literal);
+                    return context.factory.createTypeReferenceNode(child.qualifier, args);
+                }
+                if (ts.isTypeReferenceNode(child) && JSX_ELEMENT.has(entityText(ts, child.typeName))) {
+                    need('ReactElement', 'react');
+                    return context.factory.createTypeReferenceNode('ReactElement');
+                }
+                if (ts.isTypeReferenceNode(child))
+                    named(rootIdentifier(ts, child.typeName));
+                if (ts.isTypeQueryNode(child))
+                    named(rootIdentifier(ts, child.exprName));
+                if (child.kind === ts.SyntaxKind.AnyKeyword) {
+                    refused ??= refuse('TYPE_ANY', 'the inferred type contains `any`', 'write the type the value really has; an `any` on a surface hides the contract');
+                    return child;
+                }
+                if (ts.isTypeLiteralNode(child) && child.members.length > 0) {
+                    refused ??= refuse('TYPE_ANONYMOUS', 'the inferred type is an anonymous object type', 'declare a named type (`type X = ...`), export it and annotate with it');
+                    return child;
+                }
+                if (ts.isMappedTypeNode(child) || ts.isConditionalTypeNode(child) || (ts.isTypeOperatorNode(child) && child.operator === ts.SyntaxKind.UniqueKeyword)) {
+                    refused ??= refuse('TYPE_ANONYMOUS', 'the inferred type is computed (mapped, conditional or `unique symbol`)', 'declare a named type for it and annotate with it');
+                    return child;
+                }
+                return ts.visitEachChild(child, visit, context);
+            };
+            return visit(root);
+        }]);
+    return refused ?? { node: result.transformed[0] };
+}
+/** The Next.js export conventions whose type the framework names: the export, its type in `next`, and whether it is a function. */
+const CONVENTIONS = new Map([
+    ['generateMetadata', { type: 'Metadata', kind: 'function' }], ['metadata', { type: 'Metadata', kind: 'variable' }],
+    ['generateViewport', { type: 'Viewport', kind: 'function' }], ['viewport', { type: 'Viewport', kind: 'variable' }],
+]);
+/**
+ * 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 function conventionType(c, name, inferred, enclosing, kind) {
+    const row = CONVENTIONS.get(name);
+    const file = row?.kind === kind ? targetModule(c, 'next') : undefined;
+    const symbol = row === undefined || file === undefined ? undefined : exportedSymbol(c, file, row.type);
+    if (row === undefined || symbol === undefined)
+        return undefined;
+    const awaited = kind === 'function' ? c.checker.getAwaitedType(inferred) : inferred;
+    if (awaited === undefined || !c.checker.isTypeAssignableTo(awaited, c.checker.getDeclaredTypeOfSymbol(symbol)))
+        return undefined;
+    const resolved = resolveNeed(c, namesInScope(c, enclosing), row.type, 'next');
+    if ('ok' in resolved)
+        return undefined;
+    const written = awaited === inferred ? row.type : `Promise<${row.type}>`;
+    return { ok: true, text: written, needs: resolved.specifier === null ? [] : [{ name: row.type, specifier: resolved.specifier }] };
+}
+/** 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 function renderType(c, type, enclosing, maxLength = MAX_TYPE_LENGTH) {
+    const { ts } = c;
+    if ((type.flags & ts.TypeFlags.Any) !== 0)
+        return refuse('TYPE_ANY', 'the inferred type is `any`', 'write the type the value really has; an `any` on a surface hides the contract');
+    const flags = ts.NodeBuilderFlags.NoTruncation;
+    const drawn = c.checker.typeToTypeNode(type, enclosing, flags | ts.NodeBuilderFlags.UseAliasDefinedOutsideCurrentScope) ?? c.checker.typeToTypeNode(type, enclosing, flags);
+    if (drawn === undefined)
+        return refuse('TYPE_UNNAMEABLE', 'the compiler cannot write the type', 'declare a named type and annotate with it');
+    const needs = [];
+    const rewritten = rewrite(c, nameAnonymousParts(c, drawn, type, enclosing), namesInScope(c, enclosing), needs);
+    if ('ok' in rewritten)
+        return rewritten;
+    const text = ts.createPrinter({ removeComments: true }).printNode(ts.EmitHint.Unspecified, rewritten.node, c.source);
+    if (text.length > maxLength)
+        return refuse('TYPE_TOO_LONG', `the type is ${text.length} characters (${text.slice(0, 60)}...)`, 'declare a named type (`type X = ...`), export it and annotate with it');
+    return { ok: true, text, needs };
+}