@hominis/fireforge 0.55.0 → 0.60.0

package/dist/src/tokens/settings.js

@@ -0,0 +1,87 @@
+// SPDX-License-Identifier: EUPL-1.2
+/** What the token commands know about the project's token system, and the files they read. */
+import { FireForgeError } from '../kernel/errors.js';
+import { s } from '../kernel/schema.js';
+/**
+ * The engine path of the project's token file: `tokenFile` of the component
+ * configuration, else `browser/themes/shared/<binaryName>-tokens.css`.
+ *
+ * @param binaryName - The project's binary name
+ * @param keys - The component configuration, when the project has one
+ */
+export function tokenFilePath(binaryName, keys) {
+    return keys?.tokenFile ?? `browser/themes/shared/${binaryName}-tokens.css`;
+}
+/**
+ * The token file's text.
+ *
+ * @param files - Where the file lives
+ * @param path - Engine path of the token file
+ * @throws `token-file-missing`
+ */
+export async function readTokenFile(files, path) {
+    const text = await files.read(path);
+    if (text === undefined) {
+        throw new FireForgeError('token-file-missing', `Token file not found: ${path}`, {
+            hint: 'Create it with a :root block, or set tokenFile in furnace.json to the file the project uses.',
+        });
+    }
+    return text;
+}
+const cssVariable = s.string({
+    pattern: /^--[\w-]+$/,
+    format: 'a custom property such as --x',
+});
+const relativePath = s.string({
+    pattern: /^(?!\/)(?![A-Za-z]:)(?!.*\.\.)[^\0\\]+$/,
+    format: 'a relative path without ".." or backslashes',
+});
+/**
+ * The token keys of the component configuration (`furnace.json`), for its
+ * schema to spread in: this is their one declaration.
+ */
+export const tokenSettingsKeys = {
+    tokenFile: relativePath
+        .describe('Engine path of the token file (default browser/themes/shared/<binaryName>-tokens.css)')
+        .optional(),
+    tokenPrefix: s
+        .string({ min: 1 })
+        .describe('Custom-property prefix of the project tokens, such as --brand-')
+        .optional(),
+    tokenAllowlist: s
+        .array(cssVariable)
+        .describe('Custom properties from elsewhere that stylesheets may reference')
+        .optional(),
+    platformPrefixes: s
+        .array(s.string({ min: 1 }))
+        .describe('Prefixes of platform-owned custom properties')
+        .optional(),
+    runtimeVariables: s
+        .array(cssVariable)
+        .describe('Runtime state channels set from script')
+        .optional(),
+    tokenHostDocuments: s
+        .array(relativePath)
+        .describe('Documents that load the token file')
+        .optional(),
+    tokenSiblingSheets: s
+        .record(s.array(relativePath, { min: 1 }))
+        .describe('Sheet glob to the sheets that load beside it')
+        .optional(),
+};
+/**
+ * The project's token conventions, from the token keys of its component
+ * configuration, falling back to the prefix `--<binaryName>-`.
+ *
+ * @param keys - The component configuration, or undefined when the project has none
+ * @param binaryName - The project's binary name
+ */
+export function tokenSettings(keys, binaryName) {
+    return {
+        file: tokenFilePath(binaryName, keys),
+        prefix: keys?.tokenPrefix ?? `--${binaryName}-`,
+        exempt: new Set([...(keys?.tokenAllowlist ?? []), ...(keys?.runtimeVariables ?? [])]),
+        platformPrefixes: keys?.platformPrefixes ?? ['--moz-'],
+        siblingSheets: keys?.tokenSiblingSheets ?? {},
+    };
+}

package/dist/src/tokens/siblings.js

@@ -0,0 +1,104 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Which stylesheets load together, so that a token one sheet references can
+ * be looked up in the sheets beside it. Sheets linked from one document are
+ * siblings of each other, as are a sheet and what it `@import`s. Links are
+ * read from `<link rel="stylesheet">`, `<?xml-stylesheet?>` and `@import`;
+ * `chrome://` URLs resolve through jar.mn, relative URLs beside the document.
+ * Settings add pairings no link shows.
+ */
+import { posix } from 'node:path';
+import { matchesAnyGlob } from '../kernel/glob.js';
+import { manifestKind, parseJar, resolveManifestPath } from '../mozbuild/index.js';
+const LINK_TAG = /<(?:html:)?link\b[^>]*>/gi;
+const STYLESHEET_PI = /<\?xml-stylesheet\b[^?]*?href\s*=\s*["']([^"']+)["']/gi;
+const CSS_IMPORT = /@import\s+(?:url\(\s*)?["']([^"']+)["']/gi;
+/** The stylesheet URLs a document or sheet loads. */
+function stylesheetUrls(file, content) {
+    if (file.endsWith('.css'))
+        return [...content.matchAll(CSS_IMPORT)].map((m) => m[1] ?? '');
+    const urls = [];
+    for (const [tag] of content.matchAll(LINK_TAG)) {
+        if (!/\brel\s*=\s*["']stylesheet["']/i.test(tag))
+            continue;
+        const href = /\bhref\s*=\s*["']([^"'$]+)["']/i.exec(tag)?.[1];
+        if (href !== undefined)
+            urls.push(href);
+    }
+    for (const match of content.matchAll(STYLESHEET_PI))
+        urls.push(match[1] ?? '');
+    return urls.filter((url) => url.endsWith('.css'));
+}
+/** jar target (`content/<package>/<path>`) to the engine path it packages, over the owned jar manifests. */
+async function jarTargets(owned) {
+    const targets = new Map();
+    for (const manifest of owned.paths.filter((path) => manifestKind(path) === 'jar')) {
+        for (const entry of parseJar((await owned.read(manifest)) ?? '').entries) {
+            if (entry.source === undefined || entry.localized)
+                continue;
+            const exact = resolveManifestPath(manifest, entry.source)?.exact;
+            if (exact !== undefined)
+                targets.set(entry.target, exact);
+        }
+    }
+    return targets;
+}
+function resolveUrl(url, from, targets, sheets) {
+    const chrome = /^chrome:\/\/([\w.-]+)\/(content|skin|locale)\/(.+)$/.exec(url);
+    if (chrome !== null) {
+        const [, pkg = '', kind = '', path = ''] = chrome;
+        const candidates = kind === 'skin'
+            ? [`skin/classic/${pkg}/${path}`, `skin/${pkg}/${path}`]
+            : [`${kind}/${pkg}/${path}`];
+        return candidates.map((target) => targets.get(target)).find((source) => source !== undefined);
+    }
+    if (/^[a-z][\w+.-]*:/i.test(url))
+        return undefined;
+    const resolved = posix.normalize(posix.join(posix.dirname(from), url));
+    return sheets.has(resolved) ? resolved : undefined;
+}
+/**
+ * Maps each sheet to the sheets that load beside it. A sheet with no
+ * siblings is absent.
+ *
+ * @param owned - The project's files: the documents to read links from, and jar manifests
+ * @param sheets - The sheets being judged
+ * @param settings - `siblingSheets` pairings
+ */
+export async function siblingSheets(owned, sheets, settings) {
+    const known = new Set(sheets);
+    const targets = await jarTargets(owned);
+    const siblings = new Map();
+    const link = (group) => {
+        for (const sheet of group) {
+            const set = siblings.get(sheet) ?? new Set();
+            for (const other of group)
+                if (other !== sheet)
+                    set.add(other);
+            if (set.size > 0)
+                siblings.set(sheet, set);
+        }
+    };
+    for (const file of owned.paths.filter((path) => /\.(?:css|xhtml|html|xml|mjs|js)$/.test(path))) {
+        const linked = stylesheetUrls(file, (await owned.read(file)) ?? '')
+            .map((url) => resolveUrl(url, file, targets, known))
+            .filter((sheet) => sheet !== undefined);
+        link(file.endsWith('.css') ? [file, ...linked] : linked);
+    }
+    for (const [pattern, partners] of Object.entries(settings.siblingSheets)) {
+        for (const owner of sheets.filter((sheet) => matchesAnyGlob(sheet, [pattern]))) {
+            const set = siblings.get(owner) ?? new Set();
+            for (const partner of partners) {
+                for (const sheet of /[*?]/.test(partner)
+                    ? sheets.filter((s) => matchesAnyGlob(s, [partner]))
+                    : [partner]) {
+                    if (sheet !== owner)
+                        set.add(sheet);
+                }
+            }
+            if (set.size > 0)
+                siblings.set(owner, set);
+        }
+    }
+    return siblings;
+}

package/dist/src/typecheck/explain.js

@@ -0,0 +1,123 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * `typecheck --explain <file>`: which programs see one file, and how,
+ * without checking anything. Assembled from the functions the programs are
+ * built with, so it cannot drift from them.
+ */
+import { isAbsolute, join, relative } from 'node:path';
+import { exists, isInside, toPosixPath } from '../kernel/fs.js';
+import { explainOwnedTypes, loadTypeScript } from '../lint/index.js';
+import { displayPath, optsOut, parseProject, projectLayout, projectShim, projectsOf, resolveProjectPath, } from './typecheck.js';
+/** A file a user names (absolute, `engine/…`, or project-relative) as the layout names it. */
+function fileInLayout(request, layout, file) {
+    if (!isAbsolute(file))
+        return resolveProjectPath(layout, file);
+    if (isInside(request.engineDir, file)) {
+        return join(layout, 'engine', relative(request.engineDir, file));
+    }
+    return isInside(request.projectRoot, file)
+        ? join(layout, relative(request.projectRoot, file))
+        : file;
+}
+/**
+ * Explains how both passes see a file.
+ *
+ * @param request - The run, as `runTypecheck` would get it
+ * @param file - Absolute, `engine/…`, or project-relative
+ */
+export async function explainTypecheck(request, file) {
+    const layout = await projectLayout(request);
+    const absolute = fileInLayout(request, layout, file);
+    const { projects, settings } = projectsOf(request);
+    const views = [];
+    const ts = projects.length > 0 ? await loadTypeScript() : undefined;
+    for (const project of projects) {
+        const shim = projectShim(settings, project);
+        const base = {
+            project,
+            litTypes: settings?.litTypes ?? false,
+            undefinedIdentifiers: settings?.undefinedIdentifiers ?? 'warning',
+            ...(shim === undefined ? {} : { shim }),
+        };
+        const configFile = resolveProjectPath(layout, project);
+        if (ts === undefined || !(await exists(configFile))) {
+            views.push({ ...base, membership: 'unreadable', detail: 'the project file does not exist' });
+            continue;
+        }
+        const read = parseProject(ts, configFile);
+        if ('problem' in read) {
+            const detail = ts.flattenDiagnosticMessageText(read.problem.messageText, '\n');
+            views.push({ ...base, membership: 'unreadable', detail });
+            continue;
+        }
+        const roots = new Set(read.parsed.fileNames.map((name) => join(name)));
+        const membership = optsOut(read.raw)
+            ? 'skipped'
+            : roots.has(join(absolute))
+                ? 'root'
+                : 'not-root';
+        views.push({ ...base, membership });
+    }
+    const engineInLayout = join(layout, 'engine');
+    const enginePath = isInside(engineInLayout, absolute)
+        ? toPosixPath(relative(engineInLayout, absolute))
+        : undefined;
+    const owned = enginePath === undefined
+        ? { program: 'none', reason: 'the file is not in the engine', heads: [], imports: [] }
+        : await explainOwnedTypes(request.changes, request.engine, request.config, { projectRoot: request.projectRoot }, enginePath);
+    return {
+        file: displayPath(request, layout, absolute),
+        exists: await exists(absolute),
+        projects: views,
+        owned,
+    };
+}
+/**
+ * The `--json` document of an explanation.
+ *
+ * @param explanation - The explanation
+ */
+export function explanationJson(explanation) {
+    const { owned } = explanation;
+    return {
+        file: explanation.file,
+        exists: explanation.exists,
+        projects: explanation.projects.map((view) => ({ ...view })),
+        owned: {
+            program: owned.program,
+            reason: owned.reason ?? null,
+            heads: [...owned.heads],
+            imports: owned.imports.map((entry) => ({ ...entry })),
+            shim: owned.shim ?? null,
+        },
+    };
+}
+/**
+ * Human lines for an explanation.
+ *
+ * @param explanation - The explanation
+ */
+export function renderExplanation(explanation) {
+    const lines = [
+        `${explanation.file}${explanation.exists ? '' : ' (does not exist)'}`,
+        '',
+        'Projects:',
+    ];
+    if (explanation.projects.length === 0)
+        lines.push('  none configured');
+    for (const view of explanation.projects) {
+        const detail = view.detail === undefined ? '' : ` (${view.detail})`;
+        lines.push(`  ${view.project}: ${view.membership}${detail}; shim ${view.shim ?? 'built-in only'}, ` +
+            `litTypes ${String(view.litTypes)}, undefinedIdentifiers ${view.undefinedIdentifiers}`);
+    }
+    const owned = explanation.owned;
+    lines.push('', `Owned files: ${owned.program === 'none' ? `not checked (${owned.reason ?? ''})` : `${owned.program} program`}`);
+    if (owned.shim !== undefined)
+        lines.push(`  shim ${owned.shim}`);
+    for (const head of owned.heads)
+        lines.push(`  head ${head}`);
+    for (const entry of owned.imports) {
+        lines.push(`  import ${entry.specifier}: ${entry.resolution}${entry.target === undefined ? '' : ` ${entry.target}`}`);
+    }
+    return lines;
+}

package/dist/src/typecheck/index.js

@@ -0,0 +1,8 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Whole-project type checking: the configured jsconfig projects in the
+ * workspace's engine, plus the strict typing of the owned files that `lint`
+ * runs, as one result.
+ */
+export { explainTypecheck, explanationJson, renderExplanation } from './explain.js';
+export { renderTypecheckReport, runTypecheck, typecheckReportJson, typecheckVerdict, } from './typecheck.js';

package/dist/src/typecheck/typecheck.js

@@ -0,0 +1,332 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * `fireforge typecheck`: the configured jsconfig projects, each checked
+ * whole with its own compiler options and the Firefox-globals shim, plus
+ * the strict typing of the owned files that `lint` runs. One command, one
+ * result: a run is green only when both are.
+ *
+ * A project path is project-relative; one under `engine/` names the file in
+ * the workspace's engine, so the same configuration serves a project whose
+ * engine is its own `engine/` and one whose engine is a leased workspace.
+ */
+import { dirname, isAbsolute, join, relative } from 'node:path';
+import { ExitCode, FireForgeError, toError } from '../kernel/errors.js';
+import { ensureDir, exists, isInside, listDir, readLink, remove, toPosixPath, writeLink, } from '../kernel/fs.js';
+import { hash } from '../kernel/hash.js';
+import { checkOwnedTypes, composeShim, judgeDiagnostic, loadTypeScript, withGeckoDomTypes, } from '../lint/index.js';
+import { configuredPath, projectPaths } from '../project/index.js';
+/** The projects of a run and the settings they share. */
+export function projectsOf(request) {
+    const configured = request.config.typecheck;
+    return { projects: request.projects ?? configured?.projects ?? [], settings: configured };
+}
+/**
+ * The directory a run's projects are read in: the project's files with the
+ * engine at `engine/`. Project files name engine files, and engine files
+ * name project files, by relative paths that assume this layout (the paths
+ * Furnace writes into a jsconfig among them).
+ *
+ * A patch-mode project is that layout. For a workspace elsewhere, it is a
+ * directory of links under the project's state directory: `engine` to the
+ * workspace's engine, and one link per entry of the project directory.
+ *
+ * @param request - The project directory and the engine
+ */
+export async function projectLayout(request) {
+    const { projectRoot, engineDir } = request;
+    if (join(projectRoot, 'engine') === join(engineDir))
+        return projectRoot;
+    const { stateDir } = projectPaths(projectRoot);
+    const view = join(stateDir, 'view', hash(engineDir).slice(0, 16));
+    const wanted = new Map([['engine', engineDir]]);
+    for (const entry of await listDir(projectRoot)) {
+        if (entry.name === 'engine' || join(projectRoot, entry.name) === stateDir)
+            continue;
+        wanted.set(entry.name, join(projectRoot, entry.name));
+    }
+    await ensureDir(view);
+    for (const entry of await listDir(view)) {
+        if (!wanted.has(entry.name))
+            await remove(join(view, entry.name));
+    }
+    for (const [name, target] of wanted) {
+        const link = join(view, name);
+        const current = await readLink(link).catch(() => undefined);
+        if (current !== target)
+            await writeLink(link, target);
+    }
+    return view;
+}
+/**
+ * The absolute path of a configured project path inside a layout:
+ * `engine/…` names the engine, anything else a project file.
+ *
+ * @param layout - From {@link projectLayout}
+ * @param path - A path as configured or typed
+ */
+export function resolveProjectPath(layout, path) {
+    if (isAbsolute(path))
+        return path;
+    const named = configuredPath(path);
+    return named.tree === 'engine' ? join(layout, 'engine', named.path) : join(layout, named.path);
+}
+/**
+ * A file as reports name it: project-relative, `engine/…` for a file in
+ * the engine, or absolute outside both.
+ *
+ * @param request - The project directory and the engine
+ * @param layout - From {@link projectLayout}
+ * @param file - An absolute path
+ */
+export function displayPath(request, layout, file) {
+    if (isInside(layout, file))
+        return toPosixPath(relative(layout, file));
+    if (isInside(request.engineDir, file)) {
+        return `engine/${toPosixPath(relative(request.engineDir, file))}`;
+    }
+    if (isInside(request.projectRoot, file))
+        return toPosixPath(relative(request.projectRoot, file));
+    return file;
+}
+/**
+ * The project shim a project uses: its `projectOverrides` entry (a path, or
+ * null for none) when it has one, else `extraShim`.
+ *
+ * @param settings - The `typecheck` block
+ * @param project - The project as configured or given
+ */
+export function projectShim(settings, project) {
+    const overrides = settings?.projectOverrides ?? {};
+    const key = Object.keys(overrides).find((candidate) => candidate.replace(/^\.\//, '') === project.replace(/^\.\//, ''));
+    if (key !== undefined)
+        return overrides[key] ?? undefined;
+    return settings?.extraShim;
+}
+function fileIssue(path, message, severity = 'error') {
+    return { path, line: 1, column: 1, code: 0, severity, message };
+}
+function diagnosticIssue(run, diagnostic, judged, configFile) {
+    const file = diagnostic.file;
+    const position = file === undefined || diagnostic.start === undefined
+        ? { line: 0, character: 0 }
+        : file.getLineAndCharacterOfPosition(diagnostic.start);
+    return {
+        path: displayPath(run.request, run.layout, file?.fileName ?? configFile),
+        line: position.line + 1,
+        column: position.character + 1,
+        code: diagnostic.code,
+        severity: judged.severity,
+        message: judged.message,
+    };
+}
+/** Reads and parses a project's jsconfig, or explains why it cannot be. */
+export function parseProject(ts, configFile) {
+    const read = ts.readConfigFile(configFile, (path) => ts.sys.readFile(path));
+    if (read.error !== undefined)
+        return { problem: read.error };
+    const parsed = ts.parseJsonConfigFileContent(read.config, ts.sys, dirname(configFile), undefined, configFile);
+    return { parsed, raw: read.config };
+}
+/** Whether a jsconfig turns checkJs off explicitly, which skips the project. */
+export function optsOut(raw) {
+    if (typeof raw !== 'object' || raw === null || !('compilerOptions' in raw))
+        return false;
+    const options = raw.compilerOptions;
+    return (typeof options === 'object' &&
+        options !== null &&
+        'checkJs' in options &&
+        options.checkJs === false);
+}
+function checkProject(run, configFile) {
+    const { ts, project } = run;
+    const read = parseProject(ts, configFile);
+    if ('problem' in read) {
+        const judged = {
+            severity: 'error',
+            message: ts.flattenDiagnosticMessageText(read.problem.messageText, '\n'),
+        };
+        return {
+            project,
+            filesChecked: 0,
+            issues: [diagnosticIssue(run, read.problem, judged, configFile)],
+        };
+    }
+    const { parsed, raw } = read;
+    const issues = [];
+    const shimPath = join(dirname(configFile), `.fireforge-${run.shim.fileName}`).replaceAll('\\', '/');
+    const keep = (diagnostic, isResolved) => {
+        if (diagnostic.file?.fileName === shimPath)
+            return;
+        const judged = judgeDiagnostic(ts, diagnostic, {
+            undefinedIdentifiers: run.undefinedIdentifiers,
+            isResolved,
+        });
+        if (judged !== undefined)
+            issues.push(diagnosticIssue(run, diagnostic, judged, configFile));
+    };
+    for (const diagnostic of parsed.errors)
+        keep(diagnostic, () => false);
+    if (optsOut(raw)) {
+        issues.push(fileIssue(project, 'The project sets "checkJs": false, so it was skipped.', 'warning'));
+        return { project, filesChecked: parsed.fileNames.length, issues };
+    }
+    const options = {
+        ...parsed.options,
+        noEmit: true,
+        allowJs: parsed.options.allowJs ?? true,
+        checkJs: parsed.options.checkJs ?? true,
+        incremental: false,
+    };
+    delete options.tsBuildInfoFile;
+    const base = withGeckoDomTypes(ts, ts.createCompilerHost(options));
+    const host = {
+        ...base,
+        getSourceFile: (fileName, languageVersion, onError, shouldCreate) => fileName === shimPath
+            ? ts.createSourceFile(fileName, run.shim.source, languageVersion, true)
+            : base.getSourceFile(fileName, languageVersion, onError, shouldCreate),
+        fileExists: (fileName) => fileName === shimPath || base.fileExists(fileName),
+        readFile: (fileName) => (fileName === shimPath ? run.shim.source : base.readFile(fileName)),
+        // Files keep the names the layout gives them, links included.
+        realpath: (fileName) => fileName,
+    };
+    const program = ts.createProgram([...parsed.fileNames, shimPath], options, host);
+    const resolved = new Map();
+    const isResolved = (file, specifier) => {
+        const key = `${file}\0${specifier}`;
+        let hit = resolved.get(key);
+        if (hit === undefined) {
+            hit = ts.resolveModuleName(specifier, file, options, host).resolvedModule !== undefined;
+            resolved.set(key, hit);
+        }
+        return hit;
+    };
+    for (const diagnostic of [
+        ...program.getOptionsDiagnostics(),
+        ...program.getGlobalDiagnostics(),
+        ...program.getSyntacticDiagnostics(),
+        ...program.getSemanticDiagnostics(),
+    ]) {
+        keep(diagnostic, isResolved);
+    }
+    return { project, filesChecked: parsed.fileNames.length, issues };
+}
+/**
+ * Runs the configured projects and the strict pass over the owned files.
+ *
+ * @param request - See {@link TypecheckRequest}
+ * @throws FireForgeError `typecheck-unconfigured` when there is nothing to
+ *   check, `typescript-missing` when the compiler API is not installed
+ */
+export async function runTypecheck(request) {
+    const { projects, settings } = projectsOf(request);
+    if (projects.length === 0 && !request.config.patchLint.checkJs) {
+        throw new FireForgeError('typecheck-unconfigured', 'There is nothing to type-check.', {
+            exitCode: ExitCode.CONFIG_ERROR,
+            hint: 'Configure "typecheck.projects" or "patchLint.checkJs" in fireforge.json, or pass --project.',
+        });
+    }
+    const results = [];
+    if (projects.length > 0) {
+        const ts = await loadTypeScript();
+        const layout = await projectLayout(request);
+        for (const project of projects) {
+            const configFile = resolveProjectPath(layout, project);
+            if (!(await exists(configFile))) {
+                results.push({
+                    project,
+                    filesChecked: 0,
+                    issues: [fileIssue(project, `The project file ${project} does not exist.`)],
+                });
+                continue;
+            }
+            let shim;
+            try {
+                shim = await composeShim(request.projectRoot, projectShim(settings, project), {
+                    litTypes: settings?.litTypes ?? false,
+                });
+            }
+            catch (error) {
+                results.push({
+                    project,
+                    filesChecked: 0,
+                    issues: [fileIssue(project, toError(error).message)],
+                });
+                continue;
+            }
+            results.push(checkProject({
+                ts,
+                request,
+                layout,
+                project,
+                shim,
+                undefinedIdentifiers: settings?.undefinedIdentifiers ?? 'warning',
+            }, configFile));
+        }
+    }
+    const owned = await checkOwnedTypes(request.changes, request.engine, request.config, {
+        projectRoot: request.projectRoot,
+        ...(request.cacheDir === undefined ? {} : { cacheDir: request.cacheDir }),
+    });
+    return { projects: results, owned };
+}
+/** Counts and the judgement of a report: any error fails, warnings do not. */
+export function typecheckVerdict(report) {
+    const severities = [
+        ...report.projects.flatMap((result) => result.issues.map((issue) => issue.severity)),
+        ...report.owned.map((finding) => finding.severity),
+    ];
+    const errors = severities.filter((severity) => severity === 'error').length;
+    return {
+        pass: errors === 0,
+        errors,
+        warnings: severities.filter((severity) => severity === 'warning').length,
+    };
+}
+/**
+ * Human lines: `[<project>] <path>:<line>:<column> TS<code> <message>`, as
+ * `tsc --pretty false` writes them, then the strict pass, then a summary.
+ *
+ * @param report - The report
+ */
+export function renderTypecheckReport(report) {
+    const lines = [];
+    for (const result of report.projects) {
+        for (const issue of result.issues) {
+            const code = issue.code > 0 ? ` TS${issue.code}` : '';
+            lines.push(`[${result.project}] ${issue.path}:${issue.line}:${issue.column}${code} ${issue.severity} ${issue.message}`);
+        }
+    }
+    for (const finding of report.owned) {
+        lines.push(`[owned files] engine/${finding.path ?? ''}:${finding.line ?? 1} ${finding.severity} ${finding.message}`);
+    }
+    const verdict = typecheckVerdict(report);
+    if (lines.length > 0)
+        lines.push('');
+    lines.push(`Typecheck: ${verdict.errors} error(s), ${verdict.warnings} warning(s) across ${report.projects.length} project(s) and the owned files`);
+    return lines;
+}
+/**
+ * The `--json` document of a run.
+ *
+ * @param report - The report
+ */
+export function typecheckReportJson(report) {
+    const verdict = typecheckVerdict(report);
+    return {
+        pass: verdict.pass,
+        errors: verdict.errors,
+        warnings: verdict.warnings,
+        projects: report.projects.map((result) => ({
+            project: result.project,
+            filesChecked: result.filesChecked,
+            issues: result.issues.map((issue) => ({ ...issue })),
+        })),
+        owned: report.owned.map((finding) => ({
+            path: finding.path ?? null,
+            line: finding.line ?? null,
+            severity: finding.severity,
+            message: finding.message,
+            group: finding.group ?? null,
+        })),
+    };
+}