carrick 0.3.108 → 0.3.110

package/sidecar/dist/src/index.js

@@ -28,6 +28,7 @@ import { Retyper } from './retype.js';
 import { LibraryClaimsVerifier, httpCheck } from './library-claims.js';
 import { PROGRESS_INTERVAL_MS, atMostEvery } from './progress.js';
 import { mergeInferTimings } from './infer-timing.js';
+import { addProgramFiles, listProgramFiles } from './program-files.js';
 // ===========================================================================
 // Module-level state
 // ===========================================================================
@@ -46,6 +47,13 @@ let components = new Map();
  * (carrick#1927).
  */
 const definitionResolver = new DefinitionResolver();
+/** The init'd project loader, or the error every project-backed action gives without one. */
+function initializedLoader() {
+    if (!projectLoader?.isInitialized()) {
+        throw new Error('Sidecar not initialized. Call init first.');
+    }
+    return projectLoader;
+}
 /**
  * Get the project-backed components, building the project if this is the
  * first request that needs it.
@@ -53,15 +61,12 @@ const definitionResolver = new DefinitionResolver();
  * @throws if init has not run, or if the project cannot be built
  */
 function projectComponents(key = '') {
-    if (!projectLoader?.isInitialized()) {
-        throw new Error('Sidecar not initialized. Call init first.');
-    }
+    // Bound here rather than read from the module slot inside the components:
+    // a re-init drops `components` and points the slot at another service, and
+    // nothing built over this project may follow it there.
+    const loader = initializedLoader();
     let built = components.get(key);
     if (!built) {
-        // Bound here rather than read from the module slot inside the components:
-        // a re-init drops `components` and points the slot at another service, and
-        // nothing built over this project may follow it there.
-        const loader = projectLoader;
         const project = loader.getProjectFor(key);
         const repoRoot = loader.getRepoRoot();
         // The module graph, where the project resolved through one, is the only
@@ -501,6 +506,55 @@ function handleResolveDefinitions(request) {
         };
     }
 }
+/**
+ * Handle the 'list_program_files' action - the root files the default
+ * project's program was built from, in order (carrick#2027). It is the only
+ * program a request grows: a file a referenced project owns is in that
+ * project's program from its tsconfig, so a program built for an owning
+ * project (carrick#1604) holds the same files in every process. A process
+ * that has not built the default project lists nothing, and does not build
+ * it to answer.
+ */
+function handleListProgramFiles(request) {
+    try {
+        const project = initializedLoader().builtProject();
+        const files = project ? listProgramFiles(project) : [];
+        log(`Listing ${files.length} program file(s)`);
+        return { request_id: request.request_id, status: 'success', files };
+    }
+    catch (err) {
+        const error = err instanceof Error ? err.message : String(err);
+        logError(`Listing program files failed: ${error}`);
+        return { request_id: request.request_id, status: 'error', errors: [error] };
+    }
+}
+/**
+ * Handle the 'add_program_files' action - add the given files to the default
+ * project's program in the given order, rebuilding it at most once
+ * (carrick#2027). A file a referenced project owns is skipped, as an `infer`
+ * on it would never add it to this program: its owner's program already holds
+ * it.
+ */
+function handleAddProgramFiles(request) {
+    try {
+        const loader = initializedLoader();
+        const startTime = performance.now();
+        const files = request.files
+            .map((file) => path.resolve(loader.getRepoRoot(), file))
+            .filter((file) => loader.projectKeyFor(file) === '');
+        const added = files.length === 0
+            ? 0
+            : addProgramFiles(loader.getProject(), files, (file, reason) => logError(`Not added to the program: ${file}: ${reason}`));
+        log(`Added ${added} of ${request.files.length} file(s) to the program in ` +
+            `${Math.round(performance.now() - startTime)}ms`);
+        return { request_id: request.request_id, status: 'success', added };
+    }
+    catch (err) {
+        const error = err instanceof Error ? err.message : String(err);
+        logError(`Adding program files failed: ${error}`);
+        return { request_id: request.request_id, status: 'error', errors: [error] };
+    }
+}
 /**
  * Handle the 'health' action - report initialization status
  */
@@ -553,6 +607,10 @@ function handleRequest(request) {
             return handleVerifyLibraryClaims(request);
         case 'list_library_surface':
             return handleListLibrarySurface(request);
+        case 'list_program_files':
+            return handleListProgramFiles(request);
+        case 'add_program_files':
+            return handleAddProgramFiles(request);
         case 'health':
             return handleHealth(request);
         case 'shutdown':
@@ -648,6 +706,31 @@ function processLine(line) {
     const response = handleRequest(parseResult.request);
     writeResponse(response);
 }
+/** How often the sidecar looks for the process that started it. */
+const PARENT_CHECK_MS = 1000;
+/**
+ * Exit once the process that started this one is gone (carrick#2029).
+ *
+ * Its death closes stdin, which ends this process, unless another process
+ * still holds the write end. Then the only sign is that this process has a
+ * new parent: whatever adopts it (init, or a subreaper on Linux) has a pid of
+ * its own. So the parent at startup is kept and compared, never 1. A process
+ * already adopted at startup has no parent to watch, and stdin alone decides.
+ *
+ * The timer is unref'd: it never keeps an otherwise finished process alive.
+ * A handler that blocks the event loop holds it off until it returns.
+ */
+function exitWhenParentIsGone() {
+    const startedBy = process.ppid;
+    if (startedBy <= 1)
+        return;
+    setInterval(() => {
+        if (process.ppid !== startedBy) {
+            log(`parent ${startedBy} is gone, exiting`);
+            process.exit(0);
+        }
+    }, PARENT_CHECK_MS).unref();
+}
 /**
  * Start the message loop
  */
@@ -663,6 +746,7 @@ function main() {
         log('stdin closed, exiting');
         process.exit(0);
     });
+    exitWhenParentIsGone();
     // Handle process signals
     process.on('SIGINT', () => {
         log('SIGINT received, exiting');

package/sidecar/dist/src/library-claims.js

@@ -2584,6 +2584,8 @@ class DeclarationReader {
      * repository checked out under a `node_modules` ancestor, is not installed.
      * An install hoisted above the service root (`../../node_modules/pkg`) and
      * a pnpm store (`node_modules/.pnpm/pkg@1/node_modules/pkg`) are.
+     * Mirrored by `installedPackageDirectory` in capture/, which the capture
+     * seam keeps from being shared.
      */
     installedPackage(fileName) {
         const segments = path.relative(this.root, this.realpath(fileName)).split(path.sep);

package/sidecar/dist/src/line-index.d.ts

@@ -1,3 +1,4 @@
+import type { Node } from 'ts-morph';
 /**
  * The 1-based line of a position in a text, counted by line feeds alone: one
  * more than the `\n`s before the position. That is the count ts-morph's
@@ -7,3 +8,11 @@
  * The text is read once; each lookup after that is a binary search.
  */
 export declare function lineIndex(text: string): (pos: number) => number;
+/**
+ * `node.getStartLineNumber()` from a per-file index. ts-morph counts the
+ * file's line feeds from position 0 on every call, so a walk that asks of
+ * every node of a file pays the file's size once per node (carrick#1935).
+ */
+export declare function startLineOf(node: Node): number;
+/** `node.getEndLineNumber()` from the same per-file index. */
+export declare function endLineOf(node: Node): number;

package/sidecar/dist/src/line-index.js

@@ -24,3 +24,27 @@ export function lineIndex(text) {
         return lo + 1;
     };
 }
+const fileLineIndexes = new WeakMap();
+function lineAtIn(node, pos) {
+    // Keyed on the compiler node: a manipulation (`replaceWithText`, a retype)
+    // gives the file a new one, so the index is built again from the new text.
+    const key = node.getSourceFile().compilerNode;
+    let lineAt = fileLineIndexes.get(key);
+    if (!lineAt) {
+        lineAt = lineIndex(key.text);
+        fileLineIndexes.set(key, lineAt);
+    }
+    return lineAt(pos);
+}
+/**
+ * `node.getStartLineNumber()` from a per-file index. ts-morph counts the
+ * file's line feeds from position 0 on every call, so a walk that asks of
+ * every node of a file pays the file's size once per node (carrick#1935).
+ */
+export function startLineOf(node) {
+    return lineAtIn(node, node.getStart());
+}
+/** `node.getEndLineNumber()` from the same per-file index. */
+export function endLineOf(node) {
+    return lineAtIn(node, node.getEnd());
+}

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/response-modes.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Which incoming-message field picks each member of a response union (carrick#2054).
+ *
+ * A handler that sends `{ x }` when `?mode=a` and `{ y }` otherwise publishes
+ * `{ x } | { y }`. A call that states `mode=a` receives only `{ x }`, and a
+ * call that states nothing may receive either. The union alone cannot say
+ * which, so this reads it from the handler: for each success body the union
+ * joined, the tests on its path that compare a value read from the incoming message
+ * with a string literal.
+ *
+ * The reading, in order:
+ *
+ *  - A test counts only when it separates two of the joined bodies: one on
+ *    each side of it, or, for an earlier `if` that cannot complete, one in
+ *    its branch and one after it. A validation guard whose branch only sends
+ *    an error separates nothing the join kept, and is ignored.
+ *  - A counted test is a message read when a value it tests is read from a
+ *    parameter of a function enclosing the send (`messageRead`). A test that
+ *    reads nothing from the incoming message (server state, a local count) is ignored,
+ *    so a body under it is under no test of the field and stays in every case.
+ *  - `===`, `==`, `!==` and `!=` against a string literal, with `!` flipping
+ *    the test, and `switch` labels, are read as values. Any other test of a
+ *    message read leaves its field read with its values unread.
+ *  - `reads` lists every message read among the counted tests. `cases` is
+ *    read only for one placed field whose tests were all read: one case per
+ *    literal compared, plus "any other value" (`value: null`) when a body
+ *    admits one, each the union of the bodies it admits.
+ *  - When every case is the same union, the route has no modes.
+ *
+ * The published union is not changed by any of this.
+ */
+import { Node, type Symbol as TsSymbol } from 'ts-morph';
+/**
+ * Where in the incoming message a field is read from. Only the HTTP sources
+ * are read so far; another protocol (a socket message, a pub/sub payload)
+ * adds its own source here.
+ */
+export type MessageSource = 'query' | 'body' | 'unplaced';
+/** One incoming-message field a response union depends on. */
+export interface ResponseModeRead {
+    /**
+     * `query`: read with `.get(...)` on the default lib's `URLSearchParams`.
+     * `body`: a top-level property of the awaited result of a zero-argument
+     * `json()` the default lib or an installed library declares. `unplaced`:
+     * anything else (a header, a path parameter, the method, a framework's own
+     * accessor, a `json()` the repo declares).
+     */
+    location: MessageSource;
+    field: string;
+}
+/** The union a stated value of the field receives. */
+export interface ResponseModeCase {
+    /** The value; `null` for any value no other case names. */
+    value: string | null;
+    type_string: string;
+}
+export interface ResponseModes {
+    /** Every message field the union depends on, sorted by location, then field. */
+    reads: ResponseModeRead[];
+    /**
+     * Present only when `reads` is one placed field and every test of it was
+     * read. Sorted by value, the `null` case last.
+     */
+    cases?: ResponseModeCase[];
+}
+/** One success body the union joined, in source order. */
+export interface JoinedBody {
+    node: Node;
+    type_string: string;
+}
+/**
+ * The modes of the union joined from `bodies`, or `undefined` when no message
+ * read separates them. `join` builds a union text from member texts with the
+ * rules the published union is built with. `isLibOrExternal` says whether a
+ * symbol is declared by a TypeScript lib or an installed library.
+ */
+export declare function readResponseModes(bodies: JoinedBody[], join: (texts: string[]) => string, isLibOrExternal: (symbol: TsSymbol | undefined) => boolean): ResponseModes | undefined;