@starci/hfs 5.0.8 → 5.2.0

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

package/codemod/main.mjs

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

package/codemod/source-tree.d.mts

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

package/codemod/source-tree.mjs

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

package/db/postgres.mjs

@@ -35,7 +35,15 @@ export function dbTarget(ctx, name = DEFAULT_DB_URL_ENV) {
     const parsed = parseConnection(value);
     if (!parsed)
         throw refusal('DB_URL_INVALID', `${name} is not a postgres connection URL`);
-    return { kind: 'url', how: `connection string from ${name}`, urlEnv: name, url: parsed.url, env: parsed.password ? { PGPASSWORD: parsed.password } : {}, secrets: [value, parsed.password].filter(Boolean) };
+    const target = { kind: 'url', how: `connection string from ${name}`, urlEnv: name, url: parsed.url, env: parsed.password ? { PGPASSWORD: parsed.password } : {}, secrets: [value, parsed.password].filter(Boolean) };
+    // A dev environment's database runs in its own container (starci app stack up): STARCI_DB_CONTAINER runs the client tools inside it, so the host needs no PostgreSQL client.
+    const container = ctx.env.STARCI_DB_CONTAINER;
+    if (!container)
+        return target;
+    const inside = inContainer(target, container);
+    const url = new URL(inside.url);
+    url.port = '5432';
+    return { ...target, ...inside, kind: 'url', urlEnv: name, url: url.toString() };
 }
 /** Where a `-f` file of an in-container target is copied before the client reads it. */
 const CONTAINER_DIR = '/tmp/starci-db';

package/lint/eslint-list.cjs

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