carrick 0.3.108 → 0.3.109

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.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_';
@@ -233,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

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

@@ -1186,6 +1186,17 @@ export declare class TypeInferrer {
      * keep both segments.
      */
     private declaringPackageOf;
+    /**
+     * The declaration a symbol is attributed to (carrick#2031). One declaration
+     * is itself. Where several files merge one symbol (a global interface the
+     * compiler's library declares and a typings package augments), their order
+     * is the order the checker merged them in, and on TypeScript 6 that changes
+     * once the program is rebuilt, so the first one is not an answer. The
+     * compiler's default library wins where it declares the symbol; otherwise,
+     * and among the library's own files, the declaring file whose path sorts
+     * first, then the earliest declaration in it.
+     */
+    private attributedDeclaration;
     /**
      * The awaited return type of the member invoked on the receiver. Reported as
      * a fact next to the receiver; a caller that classified on it alone would be

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

@@ -19,6 +19,7 @@
  */
 import * as path from 'node:path';
 import { Node, SyntaxKind, ts, } from 'ts-morph';
+import { typeToStringAsDeclared } from './print-type.js';
 import { validateInferRequestItem } from './validators.js';
 import { notePrintedType, PrintedTypes } from './printed-names.js';
 import { externalImportsOf, isExternalOrigin } from './origin.js';
@@ -242,8 +243,12 @@ const RAW_TEXT_FORMAT = 'text';
 const TYPE_TEXT_FLAGS = ts.TypeFormatFlags.NoTruncation | ts.TypeFormatFlags.InTypeAlias;
 function typeText(type, enclosingNode) {
     // Timed as the print (carrick#1985): the type is already computed when it
-    // gets here, so this is what its length costs.
-    const text = timedPhase('print', () => type.getText(enclosingNode, TYPE_TEXT_FLAGS));
+    // gets here, so this is what its length costs. A module the print names is
+    // written as its declaring file, whichever file it is printed from
+    // (carrick#2019).
+    const text = timedPhase('print', () => enclosingNode
+        ? typeToStringAsDeclared(enclosingNode.getProject().getTypeChecker().compilerObject, type.compilerType, enclosingNode.compilerNode, TYPE_TEXT_FLAGS)
+        : type.getText(undefined, TYPE_TEXT_FLAGS));
     notePrintedType(type, enclosingNode, text);
     return text;
 }
@@ -4625,7 +4630,7 @@ export class TypeInferrer {
      */
     declaringPackageOf(type) {
         const symbol = type.getSymbol() ?? type.getAliasSymbol();
-        const declaration = symbol?.getDeclarations()?.[0];
+        const declaration = this.attributedDeclaration(symbol?.getDeclarations() ?? []);
         if (!declaration) {
             return undefined;
         }
@@ -4648,6 +4653,28 @@ export class TypeInferrer {
         }
         return rest[0];
     }
+    /**
+     * The declaration a symbol is attributed to (carrick#2031). One declaration
+     * is itself. Where several files merge one symbol (a global interface the
+     * compiler's library declares and a typings package augments), their order
+     * is the order the checker merged them in, and on TypeScript 6 that changes
+     * once the program is rebuilt, so the first one is not an answer. The
+     * compiler's default library wins where it declares the symbol; otherwise,
+     * and among the library's own files, the declaring file whose path sorts
+     * first, then the earliest declaration in it.
+     */
+    attributedDeclaration(declarations) {
+        if (declarations.length <= 1)
+            return declarations[0];
+        const program = this.project.getProgram().compilerObject;
+        const fromLibrary = declarations.filter((declaration) => program.isSourceFileDefaultLibrary(declaration.getSourceFile().compilerNode));
+        const candidates = fromLibrary.length > 0 ? fromLibrary : declarations;
+        return [...candidates].sort((a, b) => {
+            const pathA = a.getSourceFile().getFilePath();
+            const pathB = b.getSourceFile().getFilePath();
+            return pathA < pathB ? -1 : pathA > pathB ? 1 : a.getStart() - b.getStart();
+        })[0];
+    }
     /**
      * The awaited return type of the member invoked on the receiver. Reported as
      * a fact next to the receiver; a caller that classified on it alone would be

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

@@ -206,6 +206,22 @@ export interface HealthRequest extends BaseRequest {
 export interface ShutdownRequest extends BaseRequest {
     action: 'shutdown';
 }
+/**
+ * List the root files the init'd project's program was built from, in order
+ * (carrick#2027).
+ */
+export interface ListProgramFilesRequest extends BaseRequest {
+    action: 'list_program_files';
+}
+/**
+ * Add files to the programs that type them, in the given order
+ * (carrick#2027).
+ */
+export interface AddProgramFilesRequest extends BaseRequest {
+    action: 'add_program_files';
+    /** Absolute paths, or relative to the init'd root. */
+    files: string[];
+}
 /**
  * Request to resolve type definitions from a v2 capture stub package.
  * Returns both the original declaration and the compiler-expanded form for
@@ -461,7 +477,7 @@ export interface ListLibrarySurfaceRequest extends BaseRequest {
 /**
  * Union type for all possible sidecar requests
  */
-export type SidecarRequest = RetypeCheckRequest | VerifyClientSemanticsRequest | VerifyLibraryClaimsRequest | ListLibrarySurfaceRequest | InitRequest | BundleRequest | CaptureV2Request | CheckV2Request | InferRequest | ResolveDefinitionsRequest | HealthRequest | ShutdownRequest;
+export type SidecarRequest = RetypeCheckRequest | VerifyClientSemanticsRequest | VerifyLibraryClaimsRequest | ListLibrarySurfaceRequest | InitRequest | BundleRequest | CaptureV2Request | CheckV2Request | InferRequest | ResolveDefinitionsRequest | HealthRequest | ShutdownRequest | ListProgramFilesRequest | AddProgramFilesRequest;
 /**
  * Request for a specific symbol to be bundled
  */
@@ -645,6 +661,22 @@ export interface HealthResponse extends BaseResponse {
 export interface ShutdownResponse extends BaseResponse {
     status: 'success';
 }
+/**
+ * Response for list_program_files action
+ */
+export interface ListProgramFilesResponse extends BaseResponse {
+    /** The program's root files, as absolute paths, in order. */
+    files?: string[];
+    errors?: string[];
+}
+/**
+ * Response for add_program_files action
+ */
+export interface AddProgramFilesResponse extends BaseResponse {
+    /** How many of the given files were added. */
+    added?: number;
+    errors?: string[];
+}
 /**
  * Error response
  */
@@ -785,7 +817,7 @@ export interface ListLibrarySurfaceResponse extends BaseResponse {
 /**
  * Union type for all possible sidecar responses
  */
-export type SidecarResponse = RetypeCheckResponse | VerifyClientSemanticsResponse | VerifyLibraryClaimsResponse | ListLibrarySurfaceResponse | InitResponse | BundleResponse | CaptureV2Response | CheckV2Response | InferResponse | ResolveDefinitionsResponse | HealthResponse | ShutdownResponse | ErrorResponse;
+export type SidecarResponse = RetypeCheckResponse | VerifyClientSemanticsResponse | VerifyLibraryClaimsResponse | ListLibrarySurfaceResponse | InitResponse | BundleResponse | CaptureV2Response | CheckV2Response | InferResponse | ResolveDefinitionsResponse | HealthResponse | ShutdownResponse | ListProgramFilesResponse | AddProgramFilesResponse | ErrorResponse;
 /**
  * An entry in the type manifest
  */