@codesema/speccov 0.0.0-stage → 0.2.1

package/src/scan/index.ts

@@ -0,0 +1,213 @@
+import type { Dirent } from 'node:fs';
+import { readdir, stat } from 'node:fs/promises';
+import { join, relative } from 'node:path';
+import { climbFor } from './climb';
+import { readGuarantees } from './guarantees';
+import { analyseScope } from './program';
+import { dropIgnored } from './ignored';
+import { loadIgnore, type Ignore } from './speccovignore';
+import type { Scope } from './report';
+import type { ScanResult } from './report';
+import { type Site } from './shapes';
+
+/** Directories never read: this is not the project's code. */
+const IGNORED = new Set(['node_modules', '.git', 'dist', 'build', 'coverage', '.turbo', '.next', '.nuxt']);
+
+const SOURCE = /\.(?:ts|tsx|mts|cts)$/u;
+const GENERATED = /\.d\.ts$/u;
+
+/** Specs are not production code: their fixtures are not defects. */
+const TEST = /\.(?:spec|test|e2e-spec)\.[cm]?tsx?$/u;
+
+/**
+ * Code the pass cannot parse. Counted and declared, never skipped in silence: a
+ * `<script setup lang="ts">` holds real TypeScript that we are not looking at.
+ */
+const UNPARSED = /\.(vue|svelte|astro|jsx?|mjs|cjs)$/u;
+
+export type ScanOptions = {
+    readonly root: string;
+    readonly tsconfig?: string;
+};
+
+/** A purely static pass: reads, parses, runs nothing. */
+export async function scan({ root, tsconfig }: ScanOptions): Promise<ScanResult> {
+    const configs = tsconfig === undefined ? await findConfigs(root) : [tsconfig];
+    const guarantees: readonly Scope[] = configs.map((path) => ({
+        path: relative(root, path) || path,
+        guarantees: readGuarantees(path),
+    }));
+    const isIgnored = await loadIgnore(root);
+    // Type checking happens per scope: one TypeScript program per tsconfig.
+    const seen = new Set<string>();
+    const sites: Site[] = [];
+    let ignoredSites = 0;
+    const refused: { path: string; reason: string }[] = [];
+    for (const path of configs) {
+        const analysis = analyseScope(root, path);
+        if (analysis.kind === 'refused') {
+            refused.push({ path: relative(root, path) || path, reason: analysis.reason });
+            continue;
+        }
+        // A file belonging to two scopes would be counted twice.
+        for (const site of analysis.sites) {
+            // A tsconfig found by climbing covers more than the directory asked for.
+            // Type checking benefits; the report does not: those sites were not asked for.
+            if (site.file.startsWith('..')) {
+                continue;
+            }
+            // The excerpt is part of the key: a signature carries one question per parameter, all
+            // on the same line. The same site seen through two scopes yields the same excerpt, so
+            // the duplicate is still dropped.
+            const key = `${site.kind}\u0000${site.file}\u0000${site.line}\u0000${site.excerpt}`;
+            if (seen.has(key)) {
+                continue;
+            }
+            seen.add(key);
+            // Still type-checked with the rest of its scope: only its questions are left out.
+            if (isIgnored(join(root, site.file))) {
+                ignoredSites += 1;
+                continue;
+            }
+            sites.push(site);
+        }
+    }
+
+    const { ignoredFiles, ...accounted } = await account(root, isIgnored);
+    return { guarantees, sites, ...accounted, ignored: { files: ignoredFiles, sites: ignoredSites }, refused };
+}
+
+type Accounting = Pick<ScanResult, 'filesScanned' | 'unreadable' | 'skipped' | 'testsExcluded'> & {
+    readonly ignoredFiles: number;
+};
+
+/** The walk only serves honest accounting: what was read, and what was not looked at. */
+async function account(root: string, isIgnored: Ignore): Promise<Accounting> {
+    const skipped = new Map<string, number>();
+    let filesScanned = 0;
+    let testsExcluded = 0;
+    let ignoredFiles = 0;
+
+    const { paths, unreadable } = await walkTracked(root);
+    for (const path of paths) {
+        // Asked first: a file the project set aside is neither "not parsed" nor "a test".
+        if (isIgnored(path)) {
+            ignoredFiles += 1;
+            continue;
+        }
+        const unparsed = UNPARSED.exec(path)?.[1];
+        if (unparsed !== undefined) {
+            skipped.set(unparsed, (skipped.get(unparsed) ?? 0) + 1);
+            continue;
+        }
+        if (TEST.test(path)) {
+            testsExcluded += 1;
+            continue;
+        }
+        filesScanned += 1;
+    }
+    return { filesScanned, unreadable, skipped, testsExcluded, ignoredFiles };
+}
+
+/** Everything the walk finds, minus what the repository sets aside, plus what it could not open. */
+async function walkTracked(root: string): Promise<{ readonly paths: readonly string[]; readonly unreadable: readonly string[] }> {
+    const found: string[] = [];
+    const unreadable: string[] = [];
+    for await (const path of walk(root, unreadable)) {
+        found.push(path);
+    }
+    return {
+        paths: await dropIgnored(root, found),
+        unreadable: unreadable.map((path) => relative(root, path) || path),
+    };
+}
+
+/** A monorepo has one tsconfig per app: construction guarantees are evaluated scope by scope. */
+async function* walkConfigs(directory: string): AsyncGenerator<string> {
+    // Unreadable here means one thing only: no scope was found under it. The accounting walk
+    // covers the same tree and is the one that reports the path, so it is not named twice.
+    const entries = await readEntries(directory);
+    if (entries === undefined) {
+        return;
+    }
+    // The order the filesystem lists entries in is not a contract: a scope comes before the
+    // ones nested in it, and siblings come by name, so the report reads the same everywhere.
+    if (entries.some((entry) => entry.isFile() && entry.name === 'tsconfig.json')) {
+        yield join(directory, 'tsconfig.json');
+    }
+    const directories = entries.filter((entry) => entry.isDirectory() && !IGNORED.has(entry.name));
+    for (const entry of directories.sort((a, b) => a.name.localeCompare(b.name))) {
+        yield* walkConfigs(join(directory, entry.name));
+    }
+}
+
+async function findConfigs(root: string): Promise<readonly string[]> {
+    const found: string[] = [];
+    for await (const path of walkConfigs(root)) {
+        found.push(path);
+    }
+    const kept = await dropIgnored(root, found);
+    return kept.length > 0 ? kept : climbForConfig(root);
+}
+
+/**
+ * The first `tsconfig.json` found by climbing, when the descent gave nothing.
+ *
+ * Aiming at a subdirectory is the common gesture — `scan src/context/identity`. There is
+ * no tsconfig in there, but the app's covers it: without this climb, the pass answered
+ * "no scope" on a perfectly analysable directory, in silence.
+ *
+ * We stop at the first one found, and never above the repository root: a tsconfig two
+ * levels above the project no longer describes it.
+ */
+function climbForConfig(root: string): readonly string[] {
+    const found = climbFor('tsconfig.json', root);
+    return found === undefined ? [] : [found];
+}
+
+/** The production TypeScript files, tests excluded. Shared with mutation. */
+export async function collectSources(root: string): Promise<readonly string[]> {
+    // A single file is a legitimate scope: that is how you iterate on one module.
+    if ((await stat(root)).isFile()) {
+        return SOURCE.test(root) && !GENERATED.test(root) ? [root] : [];
+    }
+    const { paths } = await walkTracked(root);
+    return paths.filter((path) => !UNPARSED.test(path) && !TEST.test(path));
+}
+
+/**
+ * The entries of a directory, or nothing when it does not open.
+ *
+ * A directory the process cannot open used to abort the whole scan: one folder with the wrong
+ * mode, and a repository came back with no answer at all. Both walks step over it instead,
+ * because a scan that stops has nothing to say about the rest of the tree.
+ */
+async function readEntries(directory: string): Promise<readonly Dirent[] | undefined> {
+    try {
+        return await readdir(directory, { withFileTypes: true });
+    } catch {
+        return undefined;
+    }
+}
+
+async function* walk(directory: string, unreadable: string[]): AsyncGenerator<string> {
+    const entries = await readEntries(directory);
+    if (entries === undefined) {
+        unreadable.push(directory);
+        return;
+    }
+    for (const entry of entries) {
+        const path = join(directory, entry.name);
+        if (entry.isDirectory()) {
+            if (!IGNORED.has(entry.name)) {
+                yield* walk(path, unreadable);
+            }
+        } else if ((SOURCE.test(entry.name) || UNPARSED.test(entry.name)) && !GENERATED.test(entry.name)) {
+            yield path;
+        }
+    }
+}
+
+export { reportScan, type ScanResult } from './report';
+export type { Guarantee, Guarantees } from './guarantees';
+export { findShapes, type ShapeKind, type Site } from './shapes';

package/src/scan/program.ts

@@ -0,0 +1,137 @@
+import { relative, resolve } from 'node:path';
+import ts from 'typescript';
+import { firstBlocking } from './guarantees';
+import { findShapes, type Site } from './shapes';
+
+/**
+ * What a scope gave: its sites, or the reason for its silence.
+ *
+ * The second case is not a detail. A program that does not build — dependencies missing,
+ * an `extends` that cannot be found, a generated file absent — must not make the tool fall
+ * back on a guess: it would then produce exactly the false positives that type checking
+ * removes, under a look of rigour.
+ */
+export type Analysis =
+    | { readonly kind: 'analysed'; readonly sites: readonly Site[]; readonly filesTyped: number }
+    | { readonly kind: 'refused'; readonly reason: string };
+
+/** A file that carries no project code: neither test, nor installed dependency. */
+const TEST = /\.(?:spec|test|e2e-spec)\.[cm]?tsx?$/u;
+const DECLARATION = /\.d\.ts$/u;
+
+/**
+ * The files speccov writes itself: they carry **the answer**, not the question.
+ *
+ * A `.rules.ts` holds the doubles that measure the site — among them a
+ * `mockResolvedValue({ items, total })` that looks like a paginated return. Without this
+ * exclusion, `scan` re-reads its own drafts and reports its own fixture: measured on a
+ * real-world monorepo, `list-admin-users.rules.ts:84` came out a `metamorphic()` candidate.
+ */
+const RULES = /\.rules\.[cm]?ts$/u;
+
+export function analyseScope(root: string, tsconfigPath: string): Analysis {
+    const { config, error } = ts.readConfigFile(tsconfigPath, ts.sys.readFile);
+    if (error !== undefined) {
+        return { kind: 'refused', reason: flatten(error) };
+    }
+    const parsed = ts.parseJsonConfigFileContent(config, ts.sys, dirOf(tsconfigPath));
+
+    // Same discipline as the flag read. Without it, speccov built a program on a broken
+    // `extends`: TypeScript falls back to its defaults, the types degrade, and the sites
+    // came out presented as sound.
+    const blocking = firstBlocking(parsed.errors);
+    if (blocking !== undefined) {
+        return { kind: 'refused', reason: flatten(blocking) };
+    }
+
+    // A "solution" tsconfig — `files: []` plus `references` — compiles nothing itself.
+    // Stopping there silenced four scopes out of nineteen in a real-world monorepo.
+    const references = parsed.projectReferences ?? [];
+    if (parsed.fileNames.length === 0 && references.length > 0) {
+        return delegate(root, references);
+    }
+    if (parsed.fileNames.length === 0) {
+        return { kind: 'refused', reason: 'no input file in this scope' };
+    }
+
+    // Asked before the program is built, not after. A generated scope declares two files, both
+    // of them declarations, and building its program still costs a second and a half: measured
+    // on codesema, six `.nuxt/tsconfig.*` spent 15s of a 35s scan to type four files between
+    // them. The loop below would have skipped every one of them anyway.
+    // Analysed and empty, never refused: there is nothing here to read, which is not the same
+    // as being unable to read it. Refusing would propagate through `delegate` and silence the
+    // whole app the generated scope belongs to — 14s saved against two scopes lost.
+    if (!parsed.fileNames.some(isWorthTyping)) {
+        return { kind: 'analysed', sites: [], filesTyped: 0 };
+    }
+
+    const program = ts.createProgram(parsed.fileNames, parsed.options);
+    const checker = program.getTypeChecker();
+    const sites: Site[] = [];
+    let filesTyped = 0;
+
+    for (const source of program.getSourceFiles()) {
+        const path = source.fileName;
+        if (source.isDeclarationFile || !isWorthTyping(path)) {
+            continue;
+        }
+        filesTyped += 1;
+        sites.push(...findShapes(source, checker, relative(root, path) || path));
+    }
+    return { kind: 'analysed', sites, filesTyped };
+}
+
+/**
+ * Is this file one the pass would read?
+ *
+ * The same question decides twice: whether a scope is worth a program, and whether a source is
+ * worth walking. Two lists would drift, and the first one would then pay for scopes the second
+ * throws away.
+ */
+function isWorthTyping(path: string): boolean {
+    return !DECLARATION.test(path) && !TEST.test(path) && !RULES.test(path) && !path.includes('/node_modules/');
+}
+
+/** Analyses each referenced project and joins their sites. One unreadable refuses them all. */
+function delegate(root: string, references: readonly ts.ProjectReference[]): Analysis {
+    const sites: Site[] = [];
+    let filesTyped = 0;
+    for (const reference of references) {
+        const resolved = resolveReference(reference.path);
+        if (resolved === undefined) {
+            return { kind: 'refused', reason: `referenced project ${reference.path} was not found` };
+        }
+        const part = analyseScope(root, resolved);
+        if (part.kind === 'refused') {
+            return { kind: 'refused', reason: `${reference.path}: ${part.reason}` };
+        }
+        sites.push(...part.sites);
+        filesTyped += part.filesTyped;
+    }
+    return { kind: 'analysed', sites, filesTyped };
+}
+
+function resolveReference(path: string): string | undefined {
+    if (ts.sys.directoryExists(path)) {
+        const inside = `${path}/tsconfig.json`;
+        return ts.sys.fileExists(inside) ? inside : undefined;
+    }
+    return ts.sys.fileExists(path) ? path : undefined;
+}
+
+/**
+ * The tsconfig's directory, **absolute**.
+ *
+ * `ts.sys.readDirectory` does not resolve a relative `basePath` against the current
+ * directory: it yields zero files, with no diagnostic other than TS18003. A
+ * `speccov scan ../other-repo` then refused all nineteen scopes of a real-world monorepo —
+ * a green report on zero lines read.
+ */
+function dirOf(path: string): string {
+    const cut = path.lastIndexOf('/');
+    return resolve(cut === -1 ? '.' : path.slice(0, cut));
+}
+
+function flatten(diagnostic: ts.Diagnostic): string {
+    return ts.flattenDiagnosticMessageText(diagnostic.messageText, ' ');
+}

package/src/scan/report.ts

@@ -0,0 +1,267 @@
+import { version as tsVersion } from 'typescript';
+import type { Guarantees } from './guarantees';
+import type { ShapeKind, Site } from './shapes';
+
+/** A tsconfig and what it proves. A monorepo has several, of differing strictness. */
+export type Scope = {
+    readonly path: string;
+    readonly guarantees: Guarantees;
+};
+
+export type ScanResult = {
+    /** Empty when no tsconfig was found or given. */
+    readonly guarantees: readonly Scope[];
+    readonly sites: readonly Site[];
+    readonly filesScanned: number;
+    /** Paths the walk could not open, a directory the mode refuses among them. Counted, never silenced. */
+    readonly unreadable: readonly string[];
+    /** Code files left unparsed, by extension. Declared, never silenced. */
+    readonly skipped: ReadonlyMap<string, number>;
+    /** Test files deliberately set aside. */
+    readonly testsExcluded: number;
+    /** What the project's `.speccovignore` left out. Counted, never silenced. */
+    readonly ignored: { readonly files: number; readonly sites: number };
+    /** Scopes whose program could not be built. Declared, never guessed at. */
+    readonly refused: readonly { readonly path: string; readonly reason: string }[];
+};
+
+type Candidate = { readonly kind: ShapeKind; readonly rule: string; readonly question: string };
+
+const UNBOUNDED_PRIMITIVE: Candidate = {
+    kind: 'unbounded-primitive',
+    rule: 'forbidden()',
+    question: 'this parameter takes the whole primitive domain (empty string, NaN, negative, unbounded): what is the limit?',
+};
+
+const CANDIDATES: readonly Candidate[] = [
+    {
+        kind: 'unbounded-fanout',
+        rule: 'resource()',
+        question: 'outgoing concurrency follows the size of the collection — what is the ceiling?',
+    },
+    {
+        kind: 'async-per-item',
+        rule: 'complexity()',
+        question: 'one asynchronous call per item — should their number grow?',
+    },
+    {
+        kind: 'awaited-in-loop',
+        rule: 'complexity()',
+        question: 'one awaited call per item, in series — should the wait grow with the collection?',
+    },
+    {
+        kind: 'paginated-return',
+        rule: 'metamorphic()',
+        question: 'should `total` stay the same whatever the page?',
+    },
+    UNBOUNDED_PRIMITIVE,
+];
+
+const MAX_SITES_SHOWN = 6;
+
+function isEnabled(scope: Scope, flag: string): boolean {
+    return scope.guarantees.kind === 'read' && (scope.guarantees.flags.find((entry) => entry.flag === flag)?.enabled ?? false);
+}
+
+const MAX_LISTED = 3;
+
+function list(values: readonly string[]): string {
+    const shown = values.slice(0, MAX_LISTED).join(', ');
+    return values.length > MAX_LISTED ? `${shown} … and ${values.length - MAX_LISTED} more` : shown;
+}
+
+/**
+ * For each flag: what it proves, and the scopes read where it is off.
+ *
+ * Extracted so that the prose and the JSON start from the same source. Two parallel
+ * aggregations would end up diverging, and a report that contradicts itself is worth nothing.
+ */
+export function flagCoverage(result: ScanResult): readonly FlagCoverage[] {
+    const readable = result.guarantees.flatMap((scope) => (scope.guarantees.kind === 'read' ? [scope] : []));
+    const [first] = readable;
+    const flags = first?.guarantees.kind === 'read' ? first.guarantees.flags : [];
+
+    return flags.map(({ flag, proves }) => ({
+        flag,
+        proves,
+        scopesEvaluated: readable.length,
+        offIn: readable.filter((scope) => !isEnabled(scope, flag)).map(({ path }) => path),
+    }));
+}
+
+export type FlagCoverage = {
+    readonly flag: string;
+    readonly proves: string;
+    readonly scopesEvaluated: number;
+    readonly offIn: readonly string[];
+};
+
+export { CANDIDATES };
+
+export function reportScan(result: ScanResult, accepted: readonly Site[] = []): string {
+    const lines = ['', `  ${result.filesScanned} files read, nothing executed.`, ''];
+
+    const readable = result.guarantees.flatMap((scope) => (scope.guarantees.kind === 'read' ? [scope] : []));
+    const everywhere: string[] = [];
+    const partial: string[] = [];
+
+    for (const { flag, proves, offIn: missing } of flagCoverage(result)) {
+        const scope = readable.length > 1 ? `, ${readable.length} scopes evaluated` : '';
+        if (missing.length === 0) {
+            everywhere.push(`     ✓ ${proves}  (${flag}${scope})`);
+        } else if (missing.length === readable.length) {
+            // Never "everywhere": the conclusion bears only on the scopes read.
+            partial.push(`     ⚠ ${proves} — ${flag} is off in all ${readable.length} scope(s) evaluated`);
+        } else {
+            partial.push(`     ⚠ ${proves} — ${flag} is off in ${list(missing)}`);
+        }
+    }
+
+    const bounded = result.sites.filter(({ kind }) => kind === 'bounded-fanout');
+    const drains = result.sites.filter(({ kind }) => kind === 'in-flight-drain');
+    lines.push('  ── Proven by construction ─────────────────────────────────');
+    lines.push(...everywhere);
+    if (bounded.length > 0) {
+        const plural = bounded.length > 1 ? 's' : '';
+        lines.push(
+            `     ✓ ${bounded.length} fan-out${plural} bounded in writing (array literal or a constant written somewhere)`,
+        );
+    }
+    // Counted and said out loud, like everything this pass sets aside. A silenced drain would
+    // read as a site never looked at.
+    if (drains.length > 0) {
+        const plural = drains.length > 1 ? 's' : '';
+        lines.push(`     ✓ ${drains.length} wait${plural} on promises already in flight (started elsewhere, opens nothing)`);
+    }
+    if (everywhere.length === 0 && bounded.length === 0 && drains.length === 0) {
+        lines.push('     nothing to declare');
+    }
+
+    lines.push('', '  ── Guaranteed by nobody ───────────────────────────────────');
+    const unread = result.guarantees.length - readable.length;
+    if (partial.length > 0 && unread > 0) {
+        lines.push(`     (reach: ${readable.length} of ${result.guarantees.length} scope(s) — see “Not measured”)`);
+    }
+    lines.push(...partial);
+    for (const { kind, rule, question } of CANDIDATES) {
+        const sites = result.sites.filter((site) => site.kind === kind);
+        if (sites.length === 0 || kind === UNBOUNDED_PRIMITIVE.kind) {
+            continue;
+        }
+        lines.push('', `     ⚠ ${sites.length} site(s) → ${rule}: ${question}`);
+        for (const site of sites.slice(0, MAX_SITES_SHOWN)) {
+            lines.push(`         ${site.file}:${site.line}  ${site.excerpt}`);
+        }
+        if (sites.length > MAX_SITES_SHOWN) {
+            lines.push(`         … and ${sites.length - MAX_SITES_SHOWN} more`);
+        }
+    }
+
+    // Counted and never hidden, exactly as in `report()`: a forgotten acceptance is the blind
+    // spot this whole tool exists to refuse.
+    if (accepted.length > 0) {
+        const plural = accepted.length > 1 ? 's' : '';
+        lines.push('', `     · ${accepted.length} site${plural} already answered (see the scan answers file)`);
+    }
+
+    lines.push(...typedNotBounded(result.sites));
+
+    lines.push('', '  ── Not measured ───────────────────────────────────────────');
+    lines.push('     This pass is static: no behaviour was observed.');
+    if (result.guarantees.length === 0) {
+        lines.push('     No tsconfig found: nothing is said about construction guarantees.');
+    }
+    const unresolved = result.guarantees.flatMap((scope) =>
+        scope.guarantees.kind === 'unresolved' ? [`${scope.path} (${brief(scope.guarantees.reason)})`] : [],
+    );
+    const unrecognised = result.guarantees.flatMap((scope) =>
+        scope.guarantees.kind === 'read' && scope.guarantees.unrecognised.length > 0
+            ? [`${scope.path} (${scope.guarantees.unrecognised.map((option) => `--${option}`).join(', ')})`]
+            : [],
+    );
+    if (unrecognised.length > 0) {
+        lines.push(`     ${unrecognised.length} scope(s) with an unrecognised option: ${list(unrecognised)}`);
+        lines.push(`     speccov reads tsconfig with TypeScript ${tsVersion}. Those values are unknown`);
+        lines.push('     to it — newer, most likely. The flags above stay correct: the file was');
+        lines.push('     resolved, only the value of those options was not.');
+    }
+    if (unresolved.length > 0) {
+        lines.push(`     ${unresolved.length} unresolved tsconfig(s): ${list(unresolved)}`);
+        lines.push('     Nothing is concluded for those scopes: an unresolved "extends" makes');
+        lines.push('     TypeScript fall back to its defaults in silence, and concluding here');
+        lines.push('     would produce false alarms.');
+        lines.push('     An "extends" pointing at a package assumes its dependencies are installed:');
+        lines.push('     run again after installing to populate "Proven by construction".');
+    }
+    if (result.refused.length > 0) {
+        lines.push(
+            `     ${result.refused.length} scope(s) whose program could not be built: ${list(
+                result.refused.map(({ path, reason }) => `${path} (${brief(reason)})`),
+            )}`,
+        );
+        lines.push('     No site is reported for those scopes. speccov reads types now, and');
+        lines.push('     falling back to guessing by method name would reintroduce exactly the');
+        lines.push('     false positives the type checker removes — under a look of rigour.');
+    }
+    lines.push('     The sites above are candidates, not proven defects.');
+    for (const [extension, count] of [...result.skipped].sort(([, a], [, b]) => b - a)) {
+        lines.push(`     ${count} .${extension} file(s) not read: speccov only parses TypeScript.`);
+    }
+    if (result.testsExcluded > 0) {
+        lines.push(`     ${result.testsExcluded} test file(s) deliberately excluded.`);
+    }
+    if (result.ignored.files > 0) {
+        lines.push(
+            `     ${result.ignored.files} file(s) set aside by .speccovignore, ${result.ignored.sites} site(s) with them.`,
+        );
+    }
+    if (result.unreadable.length > 0) {
+        lines.push(`     ${result.unreadable.length} unreadable path(s): ${result.unreadable.slice(0, 3).join(', ')}`);
+    }
+    lines.push('');
+    return lines.join('\n');
+}
+
+/**
+ * The parameters whose type states no bound, in a block of their own.
+ *
+ * The other candidates describe a behaviour: calls that grow with a collection. This one
+ * describes a type, and there are many more of them: listed alongside, a few hundred
+ * signatures bury the handful of fan-outs. So the block gives the size of the question and
+ * where it concentrates, file by file. Nothing is dropped: every site is in the JSON.
+ */
+function typedNotBounded(sites: readonly Site[]): readonly string[] {
+    const perFile = new Map<string, number>();
+    for (const { kind, file } of sites) {
+        if (kind === UNBOUNDED_PRIMITIVE.kind) {
+            perFile.set(file, (perFile.get(file) ?? 0) + 1);
+        }
+    }
+    if (perFile.size === 0) {
+        return [];
+    }
+    const total = [...perFile.values()].reduce((sum, count) => sum + count, 0);
+    const ranked = [...perFile].sort(([left, a], [right, b]) => b - a || left.localeCompare(right));
+    const lines = [
+        '',
+        '  ── Typed, not bounded ─────────────────────────────────────',
+        `     ⚠ ${total} parameter(s) in ${perFile.size} file(s) → ${UNBOUNDED_PRIMITIVE.rule}: ${UNBOUNDED_PRIMITIVE.question}`,
+        ...ranked.slice(0, MAX_SITES_SHOWN).map(([file, count]) => `         ${file}  ${count}`),
+    ];
+    if (ranked.length > MAX_SITES_SHOWN) {
+        lines.push(`         … and ${ranked.length - MAX_SITES_SHOWN} more file(s)`);
+    }
+    lines.push('     A property of the type, not an observed behaviour. Every site is in the --json output.');
+    return lines;
+}
+
+/**
+ * A TypeScript diagnostic can enumerate every value an option admits — thousands of
+ * characters to say that one of them is wrong. Dumped as-is, it drowns the rest of the
+ * report, and a report nobody can read is no longer of any use for deciding.
+ */
+function brief(reason: string): string {
+    const enumeration = reason.indexOf(' must be: ');
+    const cut = enumeration === -1 ? reason : `${reason.slice(0, enumeration)} has an unrecognised value`;
+    return cut.length <= 120 ? cut : `${cut.slice(0, 119)}…`;
+}