@starci/hfs 5.0.8 → 5.2.0

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

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