carrick 0.3.107 → 0.3.109

package/sidecar/dist/src/infer-timing.js

@@ -0,0 +1,124 @@
+/**
+ * Which requests of an `infer` batch were slow, and at what (carrick#1985).
+ *
+ * A pass can send thousands of requests and spend most of its time in a few
+ * of them. The inferrer times every request; this module turns those timings
+ * into what the batch's answer carries: how many there were and what they
+ * add up to, the slowest few by name, the request that printed the longest
+ * type, and the requests that were the first asked of their file, apart.
+ *
+ * A request's time is also told apart by what it went on: the compiler call
+ * that computes the type, and the print of that type to text. The two have
+ * different remedies, and a printed length alone cannot say which one a slow
+ * request was: a type of four characters can take seconds to compute, and a
+ * type of a million can take half a second to print.
+ *
+ * It measures and names. It changes no answer and holds no type text.
+ */
+/**
+ * How many of its slowest requests a batch's answer names.
+ *
+ * Enough for a reader adding batches up to say what the slowest hundredth of
+ * a whole pass took: a pass's slowest requests are among its batches'
+ * slowest, and the last one a batch names is the most any it left out can
+ * have taken.
+ */
+export const SLOWEST_SLOTS = 25;
+/** Milliseconds to the microsecond: sums of these stay readable. */
+const rounded = (ms) => Math.round(ms * 1000) / 1000;
+/** How long something that started at `startedMs` has taken by `nowMs`. */
+export function elapsedMs(startedMs, nowMs) {
+    return rounded(nowMs - startedMs);
+}
+/** What this process has spent in each phase since it started, in milliseconds. */
+const spent = { type: 0, print: 0 };
+/**
+ * Run `work`, and count how long it took as `phase`.
+ *
+ * The count is the process's, not a request's: whoever wants one request's
+ * share reads `phaseClock` before the request and after it. One request runs
+ * at a time, so the difference is that request's and nobody else's.
+ */
+export function timedPhase(phase, work) {
+    const started = performance.now();
+    try {
+        return work();
+    }
+    finally {
+        spent[phase] += performance.now() - started;
+    }
+}
+/** What each phase has come to so far, in milliseconds. */
+export function phaseClock() {
+    return { ...spent };
+}
+/**
+ * The `count` slowest of `slots`, slowest first. Requests that took the same
+ * time keep the order they are in.
+ */
+function slowestOf(slots, count) {
+    return [...slots].sort((a, b) => b.ms - a.ms).slice(0, count);
+}
+/**
+ * The one of `slots` that printed the longest type, the earliest of those
+ * that tie; undefined when none printed anything.
+ */
+function longestPrintedOf(slots) {
+    let longest;
+    for (const slot of slots) {
+        if (slot.printed_length > (longest?.printed_length ?? 0))
+            longest = slot;
+    }
+    return longest;
+}
+/**
+ * What a batch's answer says of the time its requests took. `slots` holds one
+ * timing per request, in the order the batch was done with them.
+ */
+export function inferTiming(slots) {
+    let slotsMs = 0;
+    let typeMs = 0;
+    let printMs = 0;
+    let firstInFile = 0;
+    let firstInFileMs = 0;
+    for (const slot of slots) {
+        slotsMs += slot.ms;
+        typeMs += slot.type_ms;
+        printMs += slot.print_ms;
+        if (slot.first_in_file) {
+            firstInFile += 1;
+            firstInFileMs += slot.ms;
+        }
+    }
+    const longest = longestPrintedOf(slots);
+    return {
+        slots: slots.length,
+        slots_ms: rounded(slotsMs),
+        type_ms: rounded(typeMs),
+        print_ms: rounded(printMs),
+        first_in_file_slots: firstInFile,
+        first_in_file_ms: rounded(firstInFileMs),
+        slowest: slowestOf(slots, SLOWEST_SLOTS),
+        ...(longest ? { longest_printed: longest } : {}),
+    };
+}
+/**
+ * One timing for a request several projects answered, each with its own:
+ * the counts and the times added up, and the slowest of all of them.
+ */
+export function mergeInferTimings(parts) {
+    if (parts.length === 1)
+        return parts[0];
+    const sum = (read) => parts.reduce((total, part) => total + read(part), 0);
+    const longest = longestPrintedOf(parts.flatMap((part) => part.longest_printed ?? []));
+    return {
+        slots: sum((part) => part.slots),
+        slots_ms: rounded(sum((part) => part.slots_ms)),
+        type_ms: rounded(sum((part) => part.type_ms)),
+        print_ms: rounded(sum((part) => part.print_ms)),
+        first_in_file_slots: sum((part) => part.first_in_file_slots),
+        first_in_file_ms: rounded(sum((part) => part.first_in_file_ms)),
+        slowest: slowestOf(parts.flatMap((part) => part.slowest), SLOWEST_SLOTS),
+        ...(longest ? { longest_printed: longest } : {}),
+    };
+}

package/sidecar/dist/src/print-type.d.ts

@@ -0,0 +1,48 @@
+/**
+ * The compiler's own print of a type, with a module the print names written
+ * as the file that declares it (carrick#2019).
+ *
+ * When a type comes from a module the enclosing file does not import, the
+ * compiler writes it as `import("<module>").Name`. TypeScript 5 wrote the
+ * declaring file's path there: the node builder had no module-specifier host
+ * unless a declaration emit gave it one. TypeScript 6 gives every print a
+ * host, so the same type printed at an enclosing node reads
+ * `import("../model").Name` or `import("<package>").Name`: a specifier that
+ * depends on which file it was printed from, so one type printed from two
+ * files gives two texts. Everything downstream reads the declaring file's
+ * path: the scanner's path scrub writes it repo-relative or as
+ * `<package>@<version>`, and a capture pastes an inferred text into its
+ * surface entry, where a specifier relative to another file names nothing.
+ *
+ * These functions run the compiler's own code with no host: a tracker whose
+ * `moduleResolverHost` is `false` (falsy, so the builder writes the declaring
+ * file; not nullish, so the builder does not supply its own). Nothing in the
+ * text is rewritten afterwards. `typeToStringAsDeclared` is the checker's
+ * `typeToString`, step for step, with that one tracker.
+ *
+ * Only prints with an enclosing node differ: with none, the compiler has no
+ * file to write a specifier relative to and writes the declaring file
+ * anyway. A print that must name modules the way a declaration file would
+ * (the capture's surface emit) passes a host of its own and does not use
+ * this.
+ */
+import { ts } from 'ts-morph';
+/**
+ * The compiler's internal `SymbolTracker`: callbacks the node builder reports
+ * to, and the module-specifier host it writes specifiers with.
+ */
+export interface SymbolTracker {
+    moduleResolverHost?: unknown;
+}
+/**
+ * The checker's `typeToTypeNode`, writing each module a node names as the
+ * file that declares it. A caller's own tracker keeps its callbacks.
+ */
+export declare function typeToTypeNodeAsDeclared(checker: ts.TypeChecker, type: ts.Type, enclosing: ts.Node | undefined, flags: ts.NodeBuilderFlags, tracker?: SymbolTracker): ts.TypeNode | undefined;
+/**
+ * The checker's `typeToString(type, enclosing, flags)`, writing each module
+ * the print names as the file that declares it. `noErrorTruncation` is the
+ * program's option of that name, which `typeToString` reads when `flags`
+ * leave truncation on.
+ */
+export declare function typeToStringAsDeclared(checker: ts.TypeChecker, type: ts.Type, enclosing: ts.Node | undefined, flags?: ts.TypeFormatFlags, noErrorTruncation?: boolean): string;

package/sidecar/dist/src/print-type.js

@@ -0,0 +1,71 @@
+/**
+ * The compiler's own print of a type, with a module the print names written
+ * as the file that declares it (carrick#2019).
+ *
+ * When a type comes from a module the enclosing file does not import, the
+ * compiler writes it as `import("<module>").Name`. TypeScript 5 wrote the
+ * declaring file's path there: the node builder had no module-specifier host
+ * unless a declaration emit gave it one. TypeScript 6 gives every print a
+ * host, so the same type printed at an enclosing node reads
+ * `import("../model").Name` or `import("<package>").Name`: a specifier that
+ * depends on which file it was printed from, so one type printed from two
+ * files gives two texts. Everything downstream reads the declaring file's
+ * path: the scanner's path scrub writes it repo-relative or as
+ * `<package>@<version>`, and a capture pastes an inferred text into its
+ * surface entry, where a specifier relative to another file names nothing.
+ *
+ * These functions run the compiler's own code with no host: a tracker whose
+ * `moduleResolverHost` is `false` (falsy, so the builder writes the declaring
+ * file; not nullish, so the builder does not supply its own). Nothing in the
+ * text is rewritten afterwards. `typeToStringAsDeclared` is the checker's
+ * `typeToString`, step for step, with that one tracker.
+ *
+ * Only prints with an enclosing node differ: with none, the compiler has no
+ * file to write a specifier relative to and writes the declaring file
+ * anyway. A print that must name modules the way a declaration file would
+ * (the capture's surface emit) passes a host of its own and does not use
+ * this.
+ */
+import { ts } from 'ts-morph';
+/** A symbol tracker that leaves the node builder without a module-specifier host. */
+const NO_SPECIFIER_HOST = { moduleResolverHost: false };
+/** The checker's own default for `typeToString`. */
+const DEFAULT_TYPE_FORMAT = ts.TypeFormatFlags.AllowUniqueESSymbolType | ts.TypeFormatFlags.UseAliasDefinedOutsideCurrentScope;
+/** `typeToString`'s caps: a print this long is cut, `...` included. */
+const DEFAULT_MAXIMUM_LENGTH = 160;
+const NO_TRUNCATION_MAXIMUM_LENGTH = 1_000_000;
+/** `typeToString`'s printers: comments removed, except for the unresolved type. */
+const PRINTER = ts.createPrinter({ removeComments: true });
+const PRINTER_WITH_COMMENTS = ts.createPrinter({});
+/**
+ * The checker's `typeToTypeNode`, writing each module a node names as the
+ * file that declares it. A caller's own tracker keeps its callbacks.
+ */
+export function typeToTypeNodeAsDeclared(checker, type, enclosing, flags, tracker) {
+    const withoutHost = tracker
+        ? Object.assign(Object.create(tracker), { moduleResolverHost: false })
+        : NO_SPECIFIER_HOST;
+    return checker.typeToTypeNode(type, enclosing, flags, undefined, withoutHost);
+}
+/**
+ * The checker's `typeToString(type, enclosing, flags)`, writing each module
+ * the print names as the file that declares it. `noErrorTruncation` is the
+ * program's option of that name, which `typeToString` reads when `flags`
+ * leave truncation on.
+ */
+export function typeToStringAsDeclared(checker, type, enclosing, flags = DEFAULT_TYPE_FORMAT, noErrorTruncation = false) {
+    const noTruncation = noErrorTruncation || (flags & ts.TypeFormatFlags.NoTruncation) !== 0;
+    const node = typeToTypeNodeAsDeclared(checker, type, enclosing, (flags & ts.TypeFormatFlags.NodeBuilderFlagsMask) |
+        ts.NodeBuilderFlags.IgnoreErrors |
+        (noTruncation ? ts.NodeBuilderFlags.NoTruncation : 0));
+    // `typeToString` asserts a node here too (`Debug.fail`). Falling back to it
+    // would print the other specifier form, so fail the same way it does.
+    if (node === undefined)
+        throw new Error('the node builder gave no type node to print');
+    const unresolved = type.intrinsicName === 'unresolved';
+    const writer = ts.createTextWriter('');
+    (unresolved ? PRINTER_WITH_COMMENTS : PRINTER).writeNode(ts.EmitHint.Unspecified, node, enclosing?.getSourceFile(), writer);
+    const result = writer.getText();
+    const maximum = (noTruncation ? NO_TRUNCATION_MAXIMUM_LENGTH : DEFAULT_MAXIMUM_LENGTH) * 2;
+    return result.length >= maximum ? result.substring(0, maximum - 3) + '...' : result;
+}

package/sidecar/dist/src/printed-names.js

@@ -23,6 +23,7 @@
  * no more than keeping the list.
  */
 import { ts } from 'ts-morph';
+import { typeToTypeNodeAsDeclared } from './print-type.js';
 /** The prints of the inference running now, when one is recording. */
 let recording;
 /**
@@ -82,7 +83,7 @@ export class PrintedTypes {
             visited.set(type, at.add(enclosing));
             let node;
             try {
-                node = checker.typeToTypeNode(type, enclosing, NODE_FLAGS);
+                node = typeToTypeNodeAsDeclared(checker, type, enclosing, NODE_FLAGS);
             }
             catch {
                 continue;

package/sidecar/dist/src/program-files.d.ts

@@ -0,0 +1,44 @@
+/**
+ * The files a program was built from, and files added to a program in an
+ * order the caller gives (carrick#2027).
+ *
+ * With `stableTypeOrdering` the compiler orders two types of the same name by
+ * where their declarations sit in the program's file list. That list follows
+ * the program's root files: the compiler lists each root after the files it
+ * imports. ts-morph hands the compiler every file it has loaded as a root, in
+ * the order it loaded them, and a process asked about a file outside its
+ * tsconfig loads it when it is asked. Two processes asked the same questions
+ * in different orders therefore build from roots in different orders, and
+ * print a union of two same-named types in different orders.
+ *
+ * The roots decide the whole program, not only its order. A dependency file
+ * the compiler reached by resolving an import is not the same to it as the
+ * same file named as a root: a second copy of a package reached by resolution
+ * is folded into the first, and named as a root it is read as a file of its
+ * own and its imports are followed. So the list here is the roots themselves.
+ * A process that has built only what its tsconfig names, given another
+ * process's roots in order, ends with the same roots and builds the same
+ * program.
+ */
+import type { Project } from 'ts-morph';
+/**
+ * The root files `project`'s program was built from, in order, as absolute
+ * paths: every file the project had loaded when the program was last built,
+ * the compiler's library files and the dependencies earlier builds reached
+ * among them.
+ */
+export declare function listProgramFiles(project: Project): string[];
+/**
+ * Add to `project` each of `files` it has not loaded, in the given order, and
+ * build the program once if any was added. A file it has loaded keeps its
+ * place. A file that cannot be read is skipped and reported to `onSkipped`.
+ *
+ * Nothing is built before the files join. A project built from a tsconfig has
+ * built once already, from the files the tsconfig names, as every process's
+ * does; one built from source patterns or a Deno graph has loaded only its
+ * own files, and the given list names whatever the other process's first
+ * build loaded, in the place that build put it.
+ *
+ * @returns how many files were added
+ */
+export declare function addProgramFiles(project: Project, files: readonly string[], onSkipped: (file: string, reason: string) => void): number;

package/sidecar/dist/src/program-files.js

@@ -0,0 +1,64 @@
+/**
+ * The files a program was built from, and files added to a program in an
+ * order the caller gives (carrick#2027).
+ *
+ * With `stableTypeOrdering` the compiler orders two types of the same name by
+ * where their declarations sit in the program's file list. That list follows
+ * the program's root files: the compiler lists each root after the files it
+ * imports. ts-morph hands the compiler every file it has loaded as a root, in
+ * the order it loaded them, and a process asked about a file outside its
+ * tsconfig loads it when it is asked. Two processes asked the same questions
+ * in different orders therefore build from roots in different orders, and
+ * print a union of two same-named types in different orders.
+ *
+ * The roots decide the whole program, not only its order. A dependency file
+ * the compiler reached by resolving an import is not the same to it as the
+ * same file named as a root: a second copy of a package reached by resolution
+ * is folded into the first, and named as a root it is read as a file of its
+ * own and its imports are followed. So the list here is the roots themselves.
+ * A process that has built only what its tsconfig names, given another
+ * process's roots in order, ends with the same roots and builds the same
+ * program.
+ */
+/**
+ * The root files `project`'s program was built from, in order, as absolute
+ * paths: every file the project had loaded when the program was last built,
+ * the compiler's library files and the dependencies earlier builds reached
+ * among them.
+ */
+export function listProgramFiles(project) {
+    return [...project.getProgram().compilerObject.getRootFileNames()];
+}
+/**
+ * Add to `project` each of `files` it has not loaded, in the given order, and
+ * build the program once if any was added. A file it has loaded keeps its
+ * place. A file that cannot be read is skipped and reported to `onSkipped`.
+ *
+ * Nothing is built before the files join. A project built from a tsconfig has
+ * built once already, from the files the tsconfig names, as every process's
+ * does; one built from source patterns or a Deno graph has loaded only its
+ * own files, and the given list names whatever the other process's first
+ * build loaded, in the place that build put it.
+ *
+ * @returns how many files were added
+ */
+export function addProgramFiles(project, files, onSkipped) {
+    let added = 0;
+    for (const file of new Set(files)) {
+        if (project.getSourceFile(file) !== undefined)
+            continue;
+        try {
+            project.addSourceFileAtPath(file);
+            added += 1;
+        }
+        catch (err) {
+            onSkipped(file, err instanceof Error ? err.message : String(err));
+        }
+    }
+    // ts-morph drops its program on each add and builds the next one when it is
+    // read, so reading it once here is the one rebuild the adds need, done in
+    // this request rather than in the next one.
+    if (added > 0)
+        project.getProgram().compilerObject;
+    return added;
+}

package/sidecar/dist/src/project-loader.d.ts

@@ -120,6 +120,11 @@ export declare class ProjectLoader {
      * @throws Error if load() has not succeeded, or if the build fails
      */
     getProject(): Project;
+    /**
+     * The default project when a request has built it, and `undefined` before
+     * that, without building it (carrick#2027).
+     */
+    builtProject(): Project | undefined;
     /**
      * The registry package a resolved file belongs to, when the module graph
      * names one (carrick#1260). `undefined` for a project that did not resolve

package/sidecar/dist/src/project-loader.js

@@ -9,10 +9,10 @@
  * - Tsconfig snapshot (closed/merged extends chains) for synthetic monorepo
  * - Pinned dependency snapshots for deterministic builds
  */
-import { Project } from 'ts-morph';
+import { Project, getCompilerOptionsFromTsConfig } from 'ts-morph';
 import * as path from 'node:path';
 import * as fs from 'node:fs';
-import { DenoProject, findDenoConfig, findServiceTsconfig, serviceConfigPath } from './capture/index.js';
+import { DenoProject, findDenoConfig, findServiceTsconfig, serviceConfigPath, sidecarCompilerOptions, } from './capture/index.js';
 import { moduleFormatResolutionHost } from './module-format.js';
 import { ExternalImports, registerExternalImports } from './origin.js';
 /**
@@ -177,7 +177,7 @@ export class ProjectLoader {
                 this.log('Project will load with tsconfig snapshot');
                 this.buildProject = () => {
                     const project = new Project({
-                        compilerOptions: this.snapshotToCompilerOptions(snapshot),
+                        compilerOptions: sidecarCompilerOptions(this.snapshotToCompilerOptions(snapshot)),
                         skipAddingFilesFromTsConfig: true,
                     });
                     this.addDefaultSourceFiles(project);
@@ -197,7 +197,7 @@ export class ProjectLoader {
                         // rebuilds that drop them (carrick#1731).
                         const imports = new ExternalImports();
                         const project = new Project({
-                            compilerOptions: deno.parsed.options,
+                            compilerOptions: sidecarCompilerOptions(deno.parsed.options),
                             skipAddingFilesFromTsConfig: true,
                             resolutionHost: imports.recording((host, getOptions) => ({
                                 resolveModuleNames: (names, from) => names.map(name => deno.resolve(name, from, getOptions(), host)),
@@ -221,7 +221,7 @@ export class ProjectLoader {
                     this.log('No tsconfig.json found, using default compiler options');
                     this.buildProject = () => {
                         const project = new Project({
-                            compilerOptions: DEFAULT_COMPILER_OPTIONS,
+                            compilerOptions: sidecarCompilerOptions(DEFAULT_COMPILER_OPTIONS),
                             skipAddingFilesFromTsConfig: true,
                         });
                         // Add source files from common locations
@@ -323,6 +323,8 @@ export class ProjectLoader {
         const imports = new ExternalImports();
         const project = new Project({
             tsConfigFilePath: configPath,
+            // Over the tsconfig's own options: ts-morph lays these on top.
+            compilerOptions: sidecarCompilerOptions(getCompilerOptionsFromTsConfig(configPath).options),
             skipAddingFilesFromTsConfig: false,
             // Each import resolves in its file's own module format (carrick#1619),
             // and every external-library answer is kept past the program rebuilds
@@ -385,6 +387,13 @@ export class ProjectLoader {
         }
         return this.project;
     }
+    /**
+     * The default project when a request has built it, and `undefined` before
+     * that, without building it (carrick#2027).
+     */
+    builtProject() {
+        return this.project ?? undefined;
+    }
     /**
      * The registry package a resolved file belongs to, when the module graph
      * names one (carrick#1260). `undefined` for a project that did not resolve

package/sidecar/dist/src/retype.d.ts

@@ -53,9 +53,11 @@ export declare class Retyper {
      * Judge every item, spending at most `budgetMs`. Each item rebuilds the
      * program at least twice, so a consumer with many calls could otherwise
      * outrun the caller's read deadline and lose every answer; the items the
-     * budget does not reach abstain and say so.
+     * budget does not reach abstain and say so. `onJudged` is called after each
+     * item the budget reached, so the caller can report progress while the
+     * event loop is blocked (carrick#1945).
      */
-    run(items: RetypeItem[], budgetMs: number): RetypeOutcome[];
+    run(items: RetypeItem[], budgetMs: number, onJudged?: () => void): RetypeOutcome[];
     private runOne;
     /**
      * The rewrite that states the producer's UNWIDENED return (carrick#1516),

package/sidecar/dist/src/retype.js

@@ -27,6 +27,7 @@
 import { Node, SyntaxKind, ts } from 'ts-morph';
 import { readsResponseStatus, statusesIn, SUCCEEDED, testsOnPath, } from './failure-path.js';
 import { lineIndex } from './line-index.js';
+import { typeToStringAsDeclared } from './print-type.js';
 import { fileDiagnostics } from './unwidened.js';
 /** Names appended to a file that is not ours carry this prefix. */
 const PREFIX = '__carrick_';
@@ -53,9 +54,11 @@ export class Retyper {
      * Judge every item, spending at most `budgetMs`. Each item rebuilds the
      * program at least twice, so a consumer with many calls could otherwise
      * outrun the caller's read deadline and lose every answer; the items the
-     * budget does not reach abstain and say so.
+     * budget does not reach abstain and say so. `onJudged` is called after each
+     * item the budget reached, so the caller can report progress while the
+     * event loop is blocked (carrick#1945).
      */
-    run(items, budgetMs) {
+    run(items, budgetMs, onJudged) {
         const deadline = performance.now() + budgetMs;
         // What each file said before any rewrite. Every rewrite is undone, so it
         // is the same for every item in the file.
@@ -64,12 +67,15 @@ export class Retyper {
             if (performance.now() >= deadline) {
                 return abstain(item, `the retype check ran out of its ${budgetMs}ms budget`);
             }
+            let outcome;
             try {
-                return this.runOne(item, before);
+                outcome = this.runOne(item, before);
             }
             catch (err) {
-                return abstain(item, `the retype check failed: ${err instanceof Error ? err.message : String(err)}`);
+                outcome = abstain(item, `the retype check failed: ${err instanceof Error ? err.message : String(err)}`);
             }
+            onJudged?.();
+            return outcome;
         });
     }
     runOne(item, before) {
@@ -228,7 +234,12 @@ export class Retyper {
             };
         }
         return (`the consumer call takes no type argument and returns ` +
-            `'${call.getType().getText(call)}', so it cannot be retyped`);
+            `'${typeToStringAsDeclared(call.getProject().getTypeChecker().compilerObject, call.getType().compilerType, call.compilerNode, 
+            // ts-morph's own default for Type.getText, which this print used.
+            ts.TypeFormatFlags.UseTypeOfFunction |
+                ts.TypeFormatFlags.NoTruncation |
+                ts.TypeFormatFlags.UseFullyQualifiedType |
+                ts.TypeFormatFlags.WriteTypeArgumentsOfSignature)}', so it cannot be retyped`);
     }
     /**
      * Apply one rewrite, type-check, restore. Returns the diagnostics the