@starci/hfs 5.0.8 → 5.1.0

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 };
+}

package/codemod/explicit-surface.d.mts

@@ -0,0 +1,50 @@
+/** 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 annotation written: the type of an export that was inferred. */
+export interface ExplicitSurfaceChange {
+    file: string;
+    line: number;
+    column: number;
+    code: string;
+    name: string;
+    from: string;
+    to: string;
+}
+/** One export left for a person, with why and what to do. */
+export interface ExplicitSurfaceFinding {
+    file: string;
+    line: number;
+    column: number;
+    code: string;
+    name: string;
+    annotate: string;
+    reason: string;
+    suggestion: string;
+}
+/** The report of a migration (`starci app codemod explicit-surface`). */
+export interface ExplicitSurfaceReport {
+    schema: string;
+    root: string;
+    write: boolean;
+    maxTypeLength: number;
+    filesScanned: number;
+    filesOpen: number;
+    filesChanged: string[];
+    filesStillOpen: number;
+    formatted: boolean;
+    changes: ExplicitSurfaceChange[];
+    findings: ExplicitSurfaceFinding[];
+}
+/**
+ * Preview or apply the explicit type annotations of one app: for every TypeScript source of each side that the declaration classifier counts as open
+ * (R368, HFS_EXPLICIT_EXPORT_SURFACE), the types the app's own checker infers are written where they are short, named and sound. Every other export is kept in the report.
+ */
+export declare function migrateExplicitSurface({ root, write, ts: given, maxTypeLength }: {
+    root: string;
+    write?: boolean;
+    ts?: Ts | null;
+    maxTypeLength?: number;
+}): Promise<ExplicitSurfaceReport>;
+/** Render the annotations and what is left for a person as Markdown; JSON consumers read the same report object. */
+export declare function explicitSurfaceMarkdown(report: ExplicitSurfaceReport): string;
+export {};

package/codemod/explicit-surface.mjs

@@ -0,0 +1,374 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { declarationSurface, isEmittableSource } from '../runtime/scripts/lib/declaration-surface.mjs';
+import { loadTypescript } from '../runtime/scripts/lib/package-at.mjs';
+import { loadPrettier } from '../sync/format.mjs';
+import { applyEdits, importEdits } from './explicit-surface-edit.mjs';
+import { conventionType, MAX_TYPE_LENGTH, renderType } from './explicit-surface-render.mjs';
+import { GENERATED, relativePosix, sideFolders } from './source-tree.mjs';
+const PACKAGE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const posix = (file) => file.replaceAll('\\', '/');
+/** A file a generator wrote: it is regenerated, never edited. */
+const GENERATED_HEADER = /@generated|do not edit|auto-generated|autogenerated/i;
+/** What to do about an export the classifier reports and the codemod does not edit, by what the classifier says to annotate. */
+const SUGGESTIONS = {
+    'destructured export': 'export each name as its own variable with a type: `export const name: Type = source.name`',
+    'accessor type': 'write the accessor type: `get name(): Type`',
+    'property type': 'write the property type: `name: Type = ...`',
+    'exported value': 'declare a named type, export it and annotate the export: `export default value satisfies Type` or `export const name: Type = ...`',
+};
+/** The innermost node of `source` that contains `start`. */
+function innermostAt(ts, source, start) {
+    let found = source;
+    const descend = (node) => {
+        if (start < node.getStart(source) || start >= node.end)
+            return;
+        found = node;
+        ts.forEachChild(node, descend);
+    };
+    ts.forEachChild(source, descend);
+    return found;
+}
+/** The declaration a diagnostic of the isolated declaration emit sits in, or undefined when the codemod has no annotation for it. */
+function locate(ts, source, problem) {
+    for (let node = innermostAt(ts, source, problem.start); node !== undefined && node !== source; node = node.parent) {
+        const named = (ts.isFunctionDeclaration(node) || ts.isMethodDeclaration(node)) && node.name !== undefined && node.name.getStart(source) === problem.start;
+        if ((problem.code === 9007 || problem.code === 9008) && (named || ((ts.isArrowFunction(node) || ts.isFunctionExpression(node)) && node.getStart(source) === problem.start))) {
+            return { kind: 'return', node: node };
+        }
+        if (problem.code === 9010 && ts.isVariableDeclaration(node) && node.name.getStart(source) === problem.start)
+            return { kind: 'variable', node };
+        if ((problem.code === 9011 || problem.code === 9025) && ts.isParameter(node))
+            return { kind: 'parameter', node };
+        if (problem.code === 9012 && ts.isPropertyDeclaration(node) && node.name.getStart(source) === problem.start)
+            return { kind: 'property', node };
+    }
+    return problem.annotate === 'exported value' ? declarationOfExpression(ts, source, problem.start) : undefined;
+}
+/** The function, variable, parameter or property whose type an expression the emit cannot read (an array, an object with a shorthand, a call) stands for. */
+function declarationOfExpression(ts, source, start) {
+    for (let node = innermostAt(ts, source, start); node !== source; node = node.parent) {
+        const { parent } = node;
+        if (ts.isReturnStatement(node)) {
+            for (let owner = node; owner !== source; owner = owner.parent) {
+                if (ts.isFunctionDeclaration(owner) || ts.isMethodDeclaration(owner) || ts.isArrowFunction(owner) || ts.isFunctionExpression(owner))
+                    return { kind: 'return', node: owner };
+            }
+            return undefined;
+        }
+        if (ts.isArrowFunction(parent) && parent.body === node)
+            return { kind: 'return', node: parent };
+        if (ts.isVariableDeclaration(parent) && parent.initializer === node)
+            return { kind: 'variable', node: parent };
+        if (ts.isParameter(parent) && parent.initializer === node)
+            return { kind: 'parameter', node: parent };
+        if (ts.isPropertyDeclaration(parent) && parent.initializer === node)
+            return { kind: 'property', node: parent };
+    }
+    return undefined;
+}
+/** The edits that write `typeText` on `target`. */
+function annotationEdits(ts, source, target, typeText) {
+    const insert = (at, text) => ({ start: at, end: at, text });
+    if (target.kind === 'variable')
+        return [insert(target.node.exclamationToken?.end ?? target.node.name.end, `: ${typeText}`)];
+    if (target.kind === 'parameter')
+        return [insert(target.node.questionToken?.end ?? target.node.name.end, `: ${typeText}`)];
+    if (target.kind === 'property')
+        return [insert((target.node.questionToken ?? target.node.exclamationToken)?.end ?? target.node.name.end, `: ${typeText}`)];
+    const { node } = target;
+    const children = node.getChildren(source);
+    const open = children.find(child => child.kind === ts.SyntaxKind.OpenParenToken);
+    if (open === undefined) {
+        // `x => x` has no parentheses to carry a return type: `(x): T => x`.
+        const only = node.parameters[0];
+        return [insert(only.getStart(source), '('), insert(only.end, `): ${typeText}`)];
+    }
+    const close = children.find(child => child.kind === ts.SyntaxKind.CloseParenToken && child.pos >= node.parameters.end);
+    return [insert(close.end, `: ${typeText}`)];
+}
+/** The change kind of a target, as the report names it. */
+const CODE = { return: 'RETURN_TYPE', variable: 'VARIABLE_TYPE', parameter: 'PARAMETER_TYPE', property: 'PROPERTY_TYPE' };
+/** The type to write for `target`, from the checker, or the reason it is not written. */
+function typeFor(c, target, name, maxLength) {
+    const { checker, ts } = c;
+    if (target.kind === 'return') {
+        const signature = checker.getSignatureFromDeclaration(target.node);
+        if (signature === undefined || target.node.body === undefined)
+            return { ok: false, code: 'NO_SIGNATURE', reason: 'the function has no body to infer from', suggestion: 'write the return type by hand' };
+        if (checker.getTypePredicateOfSignature(signature) !== undefined)
+            return { ok: false, code: 'TYPE_PREDICATE', reason: 'the return type is an inferred type predicate, which `boolean` would erase', suggestion: 'write the predicate: `value is Type`' };
+        const inferred = checker.getReturnTypeOfSignature(signature);
+        return conventionType(c, name, inferred, target.node, 'function') ?? renderType(c, inferred, target.node, maxLength);
+    }
+    const node = target.kind === 'parameter' ? target.node : target.node.name;
+    if (target.kind === 'parameter' && !ts.isIdentifier(target.node.name))
+        return { ok: false, code: 'DESTRUCTURED_PARAMETER', reason: 'the parameter is a destructuring pattern', suggestion: 'write the parameter type: `({ a, b }: Props)`' };
+    const inferred = checker.getTypeAtLocation(node);
+    return (target.kind === 'variable' ? conventionType(c, name, inferred, node, 'variable') : undefined) ?? renderType(c, inferred, node, maxLength);
+}
+/** Plans the annotations of one open file; every problem it does not annotate becomes a finding. */
+function planFile(c, file, problems, maxLength) {
+    const plan = { edits: [], needs: [], changes: [], findings: [] };
+    const seen = new Set();
+    for (const problem of problems) {
+        const place = c.source.getLineAndCharacterOfPosition(problem.start);
+        const where = { file, line: place.line + 1, column: place.character + 1, name: problem.name, annotate: problem.annotate };
+        const target = locate(c.ts, c.source, problem);
+        if (target === undefined) {
+            plan.findings.push({ ...where, code: problem.annotate === 'destructured export' ? 'DESTRUCTURED_EXPORT' : 'NOT_ANNOTATED', reason: problem.reason, suggestion: SUGGESTIONS[problem.annotate] ?? 'annotate it by hand' });
+            continue;
+        }
+        const key = `${target.kind}:${target.node.pos}`;
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        const rendered = typeFor(c, target, problem.name, maxLength);
+        if (!rendered.ok) {
+            plan.findings.push({ ...where, code: rendered.code, reason: rendered.reason, suggestion: rendered.suggestion });
+            continue;
+        }
+        plan.edits.push(...annotationEdits(c.ts, c.source, target, rendered.text));
+        plan.needs.push(...rendered.needs);
+        plan.changes.push({ ...where, code: CODE[target.kind], from: 'inferred', to: rendered.text });
+    }
+    return plan;
+}
+/** The diagnostics of a file as a multiset of `code: message`, with positions left out so an edit above them does not count. */
+function diagnosticsOf(ts, program, file) {
+    const counts = new Map();
+    for (const diagnostic of [...program.getSyntacticDiagnostics(file), ...program.getSemanticDiagnostics(file)]) {
+        const key = `${diagnostic.code}: ${ts.flattenDiagnosticMessageText(diagnostic.messageText, '\n')}`;
+        counts.set(key, (counts.get(key) ?? 0) + 1);
+    }
+    return counts;
+}
+/** The first diagnostic the new text has that the old text did not, or undefined. */
+function addedDiagnostic(before, after) {
+    for (const [key, count] of after)
+        if (count > (before.get(key) ?? 0))
+            return key;
+    return undefined;
+}
+/** The tsconfig that owns `file`: the nearest `tsconfig.json` from its folder up to `top`, else undefined. */
+function owningConfig(file, top) {
+    for (let folder = path.dirname(file); folder.length >= top.length; folder = path.dirname(folder)) {
+        const candidate = path.join(folder, 'tsconfig.json');
+        if (fs.existsSync(candidate))
+            return candidate;
+        if (folder === path.dirname(folder))
+            break;
+    }
+    return undefined;
+}
+/** The options and root files of the tsconfig at `config`, or the inferred ones when there is none. */
+function groupOf(ts, config, files) {
+    const parsed = config === undefined ? undefined : ts.getParsedCommandLineOfConfigFile(config, {}, { ...ts.sys, onUnRecoverableConfigFileDiagnostic: () => undefined });
+    const options = parsed?.options ?? { jsx: ts.JsxEmit.Preserve, target: ts.ScriptTarget.Latest, module: ts.ModuleKind.ESNext, moduleResolution: ts.ModuleResolutionKind.Bundler, strict: true, noEmit: true };
+    const known = new Set((parsed?.fileNames ?? []).map(posix));
+    return { options: { ...options, noEmit: true }, rootNames: [...known, ...files.map(posix).filter(file => !known.has(file))], files: [...files] };
+}
+/** The source file the program holds for `file`, found by its forward-slash name, ignoring the case of the drive letter. */
+function programFile(program, file) {
+    const normal = posix(file);
+    return program.getSourceFile(normal) ?? program.getSourceFile(normal.replace(/^[a-z]:/, drive => drive.toUpperCase())) ?? program.getSourceFile(normal.replace(/^[A-Z]:/, drive => drive.toLowerCase()));
+}
+/** A program that reads `texts` in place of the files on disk, reusing the old program's unchanged files. */
+function programWith(ts, group, texts, old) {
+    const host = ts.createCompilerHost(group.options, true);
+    const original = host.getSourceFile.bind(host);
+    const wanted = new Map([...texts].map(([file, text]) => [posix(file).toLowerCase(), text]));
+    host.getSourceFile = (fileName, languageVersionOrOptions, onError, shouldCreate) => {
+        const text = wanted.get(posix(fileName).toLowerCase());
+        return text === undefined ? original(fileName, languageVersionOrOptions, onError, shouldCreate) : ts.createSourceFile(fileName, text, languageVersionOrOptions, true);
+    };
+    return ts.createProgram({ rootNames: group.rootNames, options: group.options, host, ...(old === undefined ? {} : { oldProgram: old }) });
+}
+/** The files of a side the codemod reads: those the installed lint canon selects, else every TypeScript source outside generated folders. */
+async function sideSources(root, side, folder) {
+    let selects;
+    let ignores;
+    try {
+        const lint = await import('../lint/run.mjs');
+        const scope = lint.canonScope(await lint.installedLintConfig({ repoRoot: root, cwd: folder, side }));
+        selects = scope.source;
+        ignores = (relative) => scope.ignored(relative) || scope.ignored(`${relative}/__starci_scope_probe__`);
+    }
+    catch { /* an app without its canon installed is read by walking */ }
+    const files = [];
+    const visit = (directory) => {
+        for (const entry of fs.readdirSync(directory, { withFileTypes: true })) {
+            const target = path.join(directory, entry.name);
+            const relative = relativePosix(folder, target);
+            if (entry.isDirectory()) {
+                if (!GENERATED.has(entry.name) && ignores?.(relative) !== true)
+                    visit(target);
+            }
+            else if (entry.isFile() && isEmittableSource(entry.name) && (selects?.(relative) ?? true) && ignores?.(relative) !== true)
+                files.push(target);
+        }
+    };
+    visit(folder);
+    return { files: files.sort(), scope: selects === undefined ? 'walk' : 'canon' };
+}
+/** The app's own Prettier, from the first side or the root that installs one, or undefined. */
+function prettierOf(root, folders) {
+    for (const folder of [...folders, root]) {
+        try {
+            return loadPrettier(folder);
+        }
+        catch { /* the next folder */ }
+    }
+    return undefined;
+}
+/** `text` formatted by the app's Prettier the way `app check --format` judges it, or unchanged when the file is ignored or cannot be formatted. */
+async function formatted(prettier, root, file, text) {
+    const ignorePath = path.join(root, '.prettierignore');
+    try {
+        const info = await prettier.getFileInfo(file, { ignorePath: fs.existsSync(ignorePath) ? ignorePath : undefined, resolveConfig: true });
+        if (info.ignored || !info.inferredParser)
+            return text;
+        const options = (await prettier.resolveConfig(file, { editorconfig: true, useCache: true })) ?? {};
+        return await prettier.format(text, { ...options, filepath: file });
+    }
+    catch {
+        return text;
+    }
+}
+/** The side-relative name a report gives `absolute`. */
+const nameOf = (root, absolute) => relativePosix(root, absolute);
+/** Plans every open file of one program, checks that the rewritten files read no worse than the originals, and returns what each file becomes. */
+async function migrateGroup({ ts, root, group, open, maxLength, report }) {
+    let program = programWith(ts, group, new Map());
+    const extra = ['react', 'next'].flatMap(name => {
+        const resolved = ts.resolveModuleName(name, open[0]?.absolute ?? root, group.options, ts.sys).resolvedModule?.resolvedFileName;
+        return resolved === undefined || programFile(program, resolved) !== undefined ? [] : [posix(resolved)];
+    });
+    if (extra.length) {
+        group.rootNames = [...group.rootNames, ...extra];
+        program = programWith(ts, group, new Map());
+    }
+    const checker = program.getTypeChecker();
+    const rewritten = new Map();
+    const planned = new Map();
+    for (const file of open) {
+        const source = programFile(program, file.absolute);
+        if (source === undefined || source.text !== file.text) {
+            report.findings.push(...file.problems.map(problem => ({ file: file.relative, line: 1, column: 1, code: 'NOT_IN_PROGRAM', name: problem.name, annotate: problem.annotate, reason: 'the file is not part of the side\'s TypeScript program', suggestion: 'include it in the tsconfig, then run the codemod again' })));
+            continue;
+        }
+        const context = { ts, program, checker, options: group.options, source, file: posix(file.absolute), text: file.text };
+        const plan = planFile(context, file.relative, file.problems, maxLength);
+        planned.set(file.absolute, plan);
+        if (plan.edits.length)
+            rewritten.set(file.absolute, applyEdits(file.text, [...plan.edits, ...importEdits(ts, source, file.text, plan.needs)]));
+    }
+    for (const [absolute, plan] of planned)
+        if (!rewritten.has(absolute))
+            report.findings.push(...plan.findings);
+    if (!rewritten.size)
+        return rewritten;
+    const after = programWith(ts, group, rewritten, program);
+    for (const [absolute, text] of [...rewritten]) {
+        const plan = planned.get(absolute);
+        const before = programFile(program, absolute);
+        const added = addedDiagnostic(diagnosticsOf(ts, program, before), diagnosticsOf(ts, after, programFile(after, absolute)));
+        if (added !== undefined) {
+            rewritten.delete(absolute);
+            report.findings.push(...plan.changes.map(change => ({ file: change.file, line: change.line, column: change.column, code: 'NOT_SOUND', name: change.name, annotate: change.code, reason: `writing \`${change.to}\` makes the compiler report: ${added}`, suggestion: 'write the type by hand' })), ...plan.findings);
+            continue;
+        }
+        report.changes.push(...plan.changes);
+        report.findings.push(...plan.findings);
+        const remaining = declarationSurface(ts, absolute, text, group.options.module)?.problems ?? [];
+        for (const problem of remaining) {
+            if (report.findings.some(found => found.file === nameOf(root, absolute) && found.name === problem.name && found.annotate === problem.annotate))
+                continue;
+            const place = ts.createSourceFile(absolute, text, ts.ScriptTarget.Latest).getLineAndCharacterOfPosition(problem.start);
+            report.findings.push({ file: nameOf(root, absolute), line: place.line + 1, column: place.character + 1, code: 'STILL_OPEN', name: problem.name, annotate: problem.annotate, reason: problem.reason, suggestion: SUGGESTIONS[problem.annotate] ?? 'annotate it by hand' });
+        }
+    }
+    return rewritten;
+}
+/**
+ * Preview or apply the explicit type annotations of one app: for every TypeScript source of each side that the declaration classifier counts as open
+ * (R368, HFS_EXPLICIT_EXPORT_SURFACE), the types the app's own checker infers are written where they are short, named and sound. Every other export is kept in the report.
+ */
+export async function migrateExplicitSurface({ root, write = false, ts: given, maxTypeLength = MAX_TYPE_LENGTH }) {
+    const folders = sideFolders(root);
+    if (!folders.length)
+        throw new Error('explicit-surface runs at an app root with a be/ or fe/ directory');
+    const report = {
+        schema: 'starci/explicit-surface-report@1', root, write, maxTypeLength, filesScanned: 0, filesOpen: 0, filesChanged: [], filesStillOpen: 0, formatted: false, changes: [], findings: [],
+    };
+    const written = new Map();
+    for (const folder of folders) {
+        const ts = given ?? loadTypescript(folder, root, PACKAGE_ROOT);
+        if (!ts)
+            throw new Error('explicit-surface needs TypeScript installed in the app or @starci/hfs development checkout');
+        if (ts.transpileDeclaration === undefined)
+            throw new Error('explicit-surface needs TypeScript 5.5 or later, which writes declarations file by file');
+        const { files } = await sideSources(root, path.basename(folder), folder);
+        const groups = new Map();
+        for (const absolute of files) {
+            const text = fs.readFileSync(absolute, 'utf8');
+            report.filesScanned += 1;
+            if (GENERATED_HEADER.test(text.slice(0, 400)))
+                continue;
+            const config = owningConfig(absolute, root);
+            const entry = groups.get(config ?? '') ?? { config, files: [] };
+            entry.files.push(absolute);
+            groups.set(config ?? '', entry);
+        }
+        for (const { config, files: members } of groups.values()) {
+            const group = groupOf(ts, config, members);
+            const open = [];
+            for (const absolute of members) {
+                const text = fs.readFileSync(absolute, 'utf8');
+                const surface = declarationSurface(ts, posix(absolute), text, group.options.module);
+                if (surface !== null && surface.problems.length)
+                    open.push({ absolute, relative: nameOf(root, absolute), text, problems: surface.problems });
+            }
+            report.filesOpen += open.length;
+            if (!open.length)
+                continue;
+            for (const [absolute, text] of await migrateGroup({ ts, root, group, open, maxLength: maxTypeLength, report }))
+                written.set(absolute, text);
+        }
+    }
+    const prettier = prettierOf(root, folders);
+    report.formatted = prettier !== undefined && written.size > 0;
+    for (const [absolute, text] of written) {
+        const final = prettier === undefined ? text : await formatted(prettier, root, absolute, text);
+        report.filesChanged.push(nameOf(root, absolute));
+        if (write)
+            fs.writeFileSync(absolute, final);
+    }
+    report.filesStillOpen = new Set(report.findings.map(finding => finding.file)).size;
+    report.changes.sort((a, b) => (a.file < b.file ? -1 : a.file > b.file ? 1 : a.line - b.line));
+    report.findings.sort((a, b) => (a.file < b.file ? -1 : a.file > b.file ? 1 : a.line - b.line));
+    report.filesChanged.sort();
+    return report;
+}
+const cell = (value) => String(value).replaceAll('|', '\\|').replaceAll('\n', ' ');
+/** Render the annotations and what is left for a person as Markdown; JSON consumers read the same report object. */
+export function explicitSurfaceMarkdown(report) {
+    const out = [
+        '# explicit-surface', '',
+        `Scanned ${report.filesScanned} files, ${report.filesOpen} open, ${report.filesChanged.length} ${report.write ? 'changed' : 'would change'}, ${report.changes.length} annotations, ${report.findings.length} exports in ${report.filesStillOpen} files left for a person.`, '',
+    ];
+    if (report.findings.length) {
+        out.push('## Left for a person', '', '| location | export | code | reason | suggested fix |', '|---|---|---|---|---|');
+        for (const finding of report.findings)
+            out.push(`| ${cell(`${finding.file}:${finding.line}:${finding.column}`)} | ${cell(finding.name)} | ${finding.code} | ${cell(finding.reason)} | ${cell(finding.suggestion)} |`);
+        out.push('');
+    }
+    if (report.changes.length) {
+        out.push('## Annotations', '', '| location | export | code | type written |', '|---|---|---|---|');
+        for (const item of report.changes)
+            out.push(`| ${cell(`${item.file}:${item.line}:${item.column}`)} | ${cell(item.name)} | ${item.code} | \`${cell(item.to)}\` |`);
+        out.push('');
+    }
+    return `${out.join('\n')}\n`;
+}

package/codemod/main.d.mts

@@ -1,16 +1,18 @@
 /** The codemods `starci app codemod` runs, by name. */
 export declare const CODEMODS: readonly string[];
-/** 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. */
+/** The arguments of every report-style `starci app codemod`: --execute, --json, --format and --out; any other is refused. */
 export declare function spacingRolesArguments(argv: readonly string[]): {
     write: boolean;
     format: 'json' | 'markdown';
     out?: string;
 };
+type Io = {
+    cwd: string;
+    stdout: (text: string) => unknown;
+};
 /**
  * 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.
  */
-export declare function codemodMain(argv: string[], io: {
-    cwd: string;
-    stdout: (text: string) => unknown;
-}): number;
+export declare function codemodMain(argv: string[], io: Io): number | Promise<number>;
+export {};