carrick 0.3.133 → 0.3.134

package/sidecar/dist/src/index.js

@@ -30,6 +30,7 @@ import { readServerLabels } from './server-labels.js';
 import { PROGRESS_INTERVAL_MS, atMostEvery } from './progress.js';
 import { mergeInferTimings } from './infer-timing.js';
 import { addProgramFiles, listProgramFiles } from './program-files.js';
+import { changedSource, inferCacheDir, keepable, programDifference, programRecord, rebuildProgram, readEntry, requestDigest, writeEntry, } from './infer-cache.js';
 import { writePositionRows } from './position-rows.js';
 import { findImplementations } from './implementations.js';
 // ===========================================================================
@@ -37,6 +38,8 @@ import { findImplementations } from './implementations.js';
 // ===========================================================================
 let projectLoader = null;
 let initTimeMs = null;
+/** `requestDigest` of the `init` request this process was last scoped with (carrick#2843). */
+let initDigest = '';
 /**
  * Components by project key (`ProjectLoader.projectKeyFor`): `''` is the
  * default project, any other key the program of a project that owns some of
@@ -160,6 +163,7 @@ function handleInit(request) {
         // Re-init re-scopes the sidecar to another root: drop everything built
         // over the previous project before resolving the new one.
         components = new Map();
+        initDigest = requestDigest(request);
         projectLoader = new ProjectLoader({
             repoRoot: request.repo_root,
             tsconfigPath: request.tsconfig_path,
@@ -336,10 +340,19 @@ async function handleCheckV2Async(request) {
 function handleInfer(request) {
     try {
         log(`Inferring ${request.requests.length} type(s)`);
+        const groups = byProject(request.requests, (item) => item.file_path);
+        const cacheKey = inferAnswerKey(request, groups);
+        if (cacheKey) {
+            const served = servedAnswer(cacheKey);
+            if (served) {
+                log(`Inferred ${request.requests.length} type(s) from the kept answer (carrick#2843)`);
+                return { request_id: request.request_id, ...served };
+            }
+        }
         // One count for the request, whichever programs its items span.
         let done = 0;
         const report = atMostEvery(PROGRESS_INTERVAL_MS, () => writeProgress(request.request_id, 'infer', `${done} of ${request.requests.length}`));
-        const results = [...byProject(request.requests, (item) => item.file_path)].map(([key, items]) => {
+        const results = [...groups].map(([key, items]) => {
             const built = projectComponents(key);
             return built.typeInferrer.infer(items, request.extraction_config, () => {
                 done += 1;
@@ -357,14 +370,19 @@ function handleInfer(request) {
                     errors: errors.length > 0 ? errors : undefined,
                 };
             })();
-        return {
-            request_id: request.request_id,
+        const answer = {
             status: result.success ? 'success' : 'error',
             inferred_types: result.inferred_types,
+            errors: result.errors,
+        };
+        if (cacheKey)
+            keepAnswer(cacheKey, [...groups.keys()], answer);
+        return {
+            request_id: request.request_id,
+            ...answer,
             // Beside the answers and never in them: what the requests cost, for
             // the caller's log (carrick#1985).
             infer_timing: mergeInferTimings(results.map((r) => r.timing)),
-            errors: result.errors,
         };
     }
     catch (err) {
@@ -377,6 +395,100 @@ function handleInfer(request) {
         };
     }
 }
+/**
+ * carrick#2843: what a kept answer to `request` is read against, or
+ * `undefined` when no answer to it is kept: the cache is off, the request
+ * reads server-framework claims (in a program the record does not cover),
+ * the project resolves through a module graph read outside the compiler, or
+ * a request before this one built a program it is answered in (its roots
+ * then depend on that request).
+ */
+function inferAnswerKey(request, groups) {
+    const dir = inferCacheDir();
+    if (!dir)
+        return undefined;
+    const loader = initializedLoader();
+    if (loader.resolvesThroughModuleGraph())
+        return undefined;
+    for (const [key, items] of groups) {
+        if (loader.isBuilt(key) || components.has(key))
+            return undefined;
+        if (request.server_claims &&
+            request.server_claims.checks.length > 0 &&
+            items.some((item) => ROUTE_ROW_KINDS.has(item.infer_kind))) {
+            return undefined;
+        }
+    }
+    return { dir, repoRoot: loader.getRepoRoot(), init: initDigest, request: requestDigest(request) };
+}
+/**
+ * carrick#2843: the kept answer for `key` when every program it was read in
+ * is, built again now, the same program. Each is built from its tsconfig and
+ * given the roots the kept one had, in order, and rebuilt once more when the
+ * kept one had been, so a match leaves the program the inference would have
+ * left. A program that does not match is dropped
+ * again, so the inference that follows builds it as it would have with no
+ * cache.
+ */
+function servedAnswer(key) {
+    const entry = readEntry(key);
+    if (!entry)
+        return undefined;
+    // A file that changed on disk is found without building a program.
+    for (const kept of entry.programs) {
+        const changedFile = changedSource(kept);
+        if (changedFile) {
+            log(`The kept infer answer was read in a program that has changed (${changedFile}): inferring again (carrick#2843)`);
+            return undefined;
+        }
+    }
+    const loader = initializedLoader();
+    const touched = [];
+    let same = true;
+    let changed = 'a root file it could not read';
+    for (const kept of entry.programs) {
+        touched.push(kept.key);
+        const project = loader.getProjectFor(kept.key);
+        addProgramFiles(project, kept.roots, () => {
+            same = false;
+        });
+        if (!same)
+            break;
+        let now = programRecord(kept.key, project);
+        if (now.roots.length < kept.roots.length) {
+            // The inference's own rewrites rebuilt the program after its first
+            // build, and a rebuild names every file the first one reached as a
+            // root. Rebuilt once more here, it names the same.
+            rebuildProgram(project);
+            now = programRecord(kept.key, project);
+        }
+        const difference = programDifference(kept, now);
+        if (difference) {
+            same = false;
+            changed = difference;
+            break;
+        }
+    }
+    if (same)
+        return entry.answer;
+    for (const programKey of touched)
+        loader.releaseProjectFor(programKey);
+    log(`The kept infer answer was read in a program that has changed (${changed}): inferring again (carrick#2843)`);
+    return undefined;
+}
+/** carrick#2843: keep `answer` for `key`, with the programs it was read in as they stand. */
+function keepAnswer(key, programKeys, answer) {
+    if (!keepable(answer))
+        return;
+    try {
+        const loader = initializedLoader();
+        writeEntry(key, programKeys.map((programKey) => programRecord(programKey, loader.getProjectFor(programKey))), answer);
+    }
+    catch (err) {
+        // Keeping an answer never costs the answer.
+        logError(`The infer answer was not kept: ${err instanceof Error ? err.message : String(err)}`);
+    }
+}
 /**
  * How long reading one program's server-framework labels may take: as
  * long as a verify_library_claims request, since the reading builds a

package/sidecar/dist/src/infer-cache.d.ts

@@ -0,0 +1,125 @@
+/**
+ * An `infer` answer kept on disk and served again while nothing it was read
+ * from has changed (carrick#2843).
+ *
+ * A scoped re-scan re-analyses a service when one of its imports changed,
+ * even when nothing the service's own types are read from did. A generated
+ * API client asks hundreds of `infer` requests of a program that a change
+ * elsewhere does not touch, and answering them costs tens of seconds each
+ * time. This keeps the last answer per service and serves it when the
+ * program it was read in is the same program.
+ *
+ * What keys an answer, all of it compared before one is served:
+ * - the sidecar itself: its compiled code, the TypeScript and ts-morph
+ *   versions it runs and the Node version (`sidecarIdentity`);
+ * - the `init` request the process was scoped with, less its id;
+ * - the `infer` request, less its id: every item, the extraction config, the
+ *   model symbols and the server claims;
+ * - for each program the request is answered in: its root files in order,
+ *   its compiler options, and every source file the compiler holds, by path
+ *   and by the sha256 of its text (`programRecord`).
+ *
+ * The program is the compiler's whole view: a declaration it could read is a
+ * source file in it, and a file that would now resolve in place of another
+ * changes the list. To compare it, the lookup builds each program afresh from
+ * its tsconfig, adds the roots the stored answer's program had, in order, and
+ * compares the result. A program that differs is dropped again, so the
+ * inference that follows builds it exactly as it would have with no cache.
+ * A program that matches is the one the inference would have left behind, so
+ * every later request in the process reads the program it would have read.
+ *
+ * Not kept: an answer whose unwidened reading ran out of its time budget (it
+ * depends on the clock), an answer that read server-framework claims (they
+ * are read in a program of their own, which the record does not cover), and
+ * an answer of a process whose program a request before it had built (its
+ * roots then depend on that request).
+ *
+ * On only where `CARRICK_INFER_CACHE_DIR` names a directory: local scans set
+ * it, and a CI scan, which starts on a clean machine, does not.
+ */
+import type { Project } from 'ts-morph';
+import type { InferredType } from './types.js';
+/** The variable naming the directory answers are kept in. */
+export declare const INFER_CACHE_ENV = "CARRICK_INFER_CACHE_DIR";
+/** One program an answer was read in, as `programRecord` saw it. */
+export interface ProgramRecord {
+    key: string;
+    /** The program's root files, in order. */
+    roots: string[];
+    /** Its compiler options, as JSON. */
+    options: string;
+    /** Every source file the compiler holds: path, module format, sha256 of its text. */
+    sources: Array<[string, string, string]>;
+}
+/** The parts of an `infer` answer that are kept and served again. */
+export interface KeptAnswer {
+    status: 'success' | 'error';
+    inferred_types?: InferredType[];
+    errors?: string[];
+}
+/** The directory answers are kept in, or `undefined` when the cache is off. */
+export declare function inferCacheDir(): string | undefined;
+/**
+ * The sidecar that reads the answers: every compiled file of its own, the
+ * compiler and ts-morph versions it loads, and the Node version.
+ */
+export declare function sidecarIdentity(): string;
+/** A request's digest, less the id every request carries. */
+export declare function requestDigest(request: object): string;
+/**
+ * What `now` differs from `kept` in, first difference only, or `undefined`
+ * when they are the same program: the same roots in the same order, the same
+ * options, and the same source files with the same text.
+ */
+export declare function programDifference(kept: ProgramRecord, now: ProgramRecord): string | undefined;
+/** What a kept answer is read against: the process and the request. */
+export interface AnswerKey {
+    /** The directory entries are kept in. */
+    dir: string;
+    /** The service root the process was scoped to: one entry per root. */
+    repoRoot: string;
+    /** `requestDigest` of the `init` request the process was scoped with. */
+    init: string;
+    /** `requestDigest` of the `infer` request. */
+    request: string;
+}
+/**
+ * The kept entry for `key` when the sidecar, the scope and the request are
+ * the ones it was kept for. The programs are not compared here: that needs
+ * them built (`servedAnswer` in `index.ts`).
+ */
+export declare function readEntry(key: AnswerKey): {
+    programs: ProgramRecord[];
+    answer: KeptAnswer;
+} | undefined;
+/** Whether `answer` can be served again: it does not depend on the clock. */
+export declare function keepable(answer: KeptAnswer): boolean;
+/**
+ * Everything the compiler holds for `project` as it stands, under `key`: its
+ * root files in order, its options, and each source file's path, module
+ * format and the sha256 of its text.
+ */
+export declare function programRecord(key: string, project: Project): ProgramRecord;
+/**
+ * The first source file of `kept` whose text on disk is not the text it was
+ * read with, or `undefined` when every one on disk is the same. Read before any
+ * program is built: a changed file, the usual reason an answer is stale, is
+ * found for the cost of reading the files, and no program is built to find
+ * it. The compiler reads a file without its byte-order mark, and so does
+ * this.
+ */
+export declare function changedSource(kept: ProgramRecord): string | undefined;
+/**
+ * Build `project`'s program again with nothing in it changed. ts-morph builds
+ * a program only after a change, and roots it at every file the project has
+ * loaded, the ones earlier builds reached among them: a program built again
+ * after its first build has more roots than the first. Setting one file's
+ * text to the text it has is the change.
+ */
+export declare function rebuildProgram(project: Project): void;
+/**
+ * Keep `answer` for `key`, read in `programs`. Written to a temporary file
+ * and renamed, so a reader never sees half an entry. Entries not written to
+ * for `ENTRY_MAX_AGE_MS` are deleted on the way.
+ */
+export declare function writeEntry(key: AnswerKey, programs: ProgramRecord[], answer: KeptAnswer): void;

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

@@ -0,0 +1,244 @@
+/**
+ * An `infer` answer kept on disk and served again while nothing it was read
+ * from has changed (carrick#2843).
+ *
+ * A scoped re-scan re-analyses a service when one of its imports changed,
+ * even when nothing the service's own types are read from did. A generated
+ * API client asks hundreds of `infer` requests of a program that a change
+ * elsewhere does not touch, and answering them costs tens of seconds each
+ * time. This keeps the last answer per service and serves it when the
+ * program it was read in is the same program.
+ *
+ * What keys an answer, all of it compared before one is served:
+ * - the sidecar itself: its compiled code, the TypeScript and ts-morph
+ *   versions it runs and the Node version (`sidecarIdentity`);
+ * - the `init` request the process was scoped with, less its id;
+ * - the `infer` request, less its id: every item, the extraction config, the
+ *   model symbols and the server claims;
+ * - for each program the request is answered in: its root files in order,
+ *   its compiler options, and every source file the compiler holds, by path
+ *   and by the sha256 of its text (`programRecord`).
+ *
+ * The program is the compiler's whole view: a declaration it could read is a
+ * source file in it, and a file that would now resolve in place of another
+ * changes the list. To compare it, the lookup builds each program afresh from
+ * its tsconfig, adds the roots the stored answer's program had, in order, and
+ * compares the result. A program that differs is dropped again, so the
+ * inference that follows builds it exactly as it would have with no cache.
+ * A program that matches is the one the inference would have left behind, so
+ * every later request in the process reads the program it would have read.
+ *
+ * Not kept: an answer whose unwidened reading ran out of its time budget (it
+ * depends on the clock), an answer that read server-framework claims (they
+ * are read in a program of their own, which the record does not cover), and
+ * an answer of a process whose program a request before it had built (its
+ * roots then depend on that request).
+ *
+ * On only where `CARRICK_INFER_CACHE_DIR` names a directory: local scans set
+ * it, and a CI scan, which starts on a clean machine, does not.
+ */
+import { createHash } from 'node:crypto';
+import * as fs from 'node:fs';
+import { createRequire } from 'node:module';
+import * as path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { WriteGuard } from './capture/index.js';
+import { listProgramFiles } from './program-files.js';
+/** The variable naming the directory answers are kept in. */
+export const INFER_CACHE_ENV = 'CARRICK_INFER_CACHE_DIR';
+/** Bumped when the entry's shape or what keys it changes. */
+const ENTRY_VERSION = 1;
+/** An entry older than this is deleted when another is written. */
+const ENTRY_MAX_AGE_MS = 14 * 24 * 60 * 60 * 1000;
+const sha256 = (text) => createHash('sha256').update(text).digest('hex');
+/** The directory answers are kept in, or `undefined` when the cache is off. */
+export function inferCacheDir() {
+    const dir = process.env[INFER_CACHE_ENV];
+    return dir && dir.trim() !== '' ? dir : undefined;
+}
+let identity;
+/**
+ * The sidecar that reads the answers: every compiled file of its own, the
+ * compiler and ts-morph versions it loads, and the Node version.
+ */
+export function sidecarIdentity() {
+    if (identity !== undefined)
+        return identity;
+    const here = path.dirname(fileURLToPath(import.meta.url));
+    const files = [];
+    const walk = (dir) => {
+        for (const entry of fs.readdirSync(dir, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+            const full = path.join(dir, entry.name);
+            if (entry.isDirectory())
+                walk(full);
+            else if (entry.name.endsWith('.js'))
+                files.push(full);
+        }
+    };
+    walk(here);
+    const hash = createHash('sha256');
+    for (const file of files) {
+        hash.update(path.relative(here, file)).update('\0').update(fs.readFileSync(file)).update('\0');
+    }
+    const require = createRequire(import.meta.url);
+    for (const pkg of ['typescript', 'ts-morph']) {
+        const manifest = JSON.parse(fs.readFileSync(require.resolve(`${pkg}/package.json`), 'utf8'));
+        hash.update(`${pkg}@${manifest.version ?? ''}\0`);
+    }
+    hash.update(process.version);
+    identity = hash.digest('hex');
+    return identity;
+}
+/** A request's digest, less the id every request carries. */
+export function requestDigest(request) {
+    const { request_id: _id, ...rest } = request;
+    return sha256(JSON.stringify(rest));
+}
+/**
+ * What `now` differs from `kept` in, first difference only, or `undefined`
+ * when they are the same program: the same roots in the same order, the same
+ * options, and the same source files with the same text.
+ */
+export function programDifference(kept, now) {
+    if (JSON.stringify(kept.roots) !== JSON.stringify(now.roots)) {
+        const at = kept.roots.findIndex((file, i) => now.roots[i] !== file);
+        const place = at === -1 ? now.roots.length - 1 : at;
+        return `its root files, from root ${place}: ${kept.roots[place] ?? 'none'} kept, ${now.roots[place] ?? 'none'} now (${kept.roots.length} kept, ${now.roots.length} now)`;
+    }
+    if (kept.options !== now.options)
+        return 'its compiler options';
+    const before = new Map(kept.sources.map(([file, format, hash]) => [file, `${format}:${hash}`]));
+    for (const [file, format, hash] of now.sources) {
+        const was = before.get(file);
+        if (was === undefined)
+            return `${file}, which it now reads`;
+        if (was !== `${format}:${hash}`)
+            return `${file}, whose text changed`;
+        before.delete(file);
+    }
+    const gone = before.keys().next();
+    if (!gone.done)
+        return `${gone.value}, which it no longer reads`;
+    if (JSON.stringify(kept.sources.map(([f]) => f)) !== JSON.stringify(now.sources.map(([f]) => f))) {
+        return 'the order of its source files';
+    }
+    return undefined;
+}
+const entryPath = (key) => path.join(key.dir, `${sha256(key.repoRoot)}.json`);
+/**
+ * The kept entry for `key` when the sidecar, the scope and the request are
+ * the ones it was kept for. The programs are not compared here: that needs
+ * them built (`servedAnswer` in `index.ts`).
+ */
+export function readEntry(key) {
+    let entry;
+    try {
+        entry = JSON.parse(fs.readFileSync(entryPath(key), 'utf8'));
+    }
+    catch {
+        return undefined;
+    }
+    if (entry.version !== ENTRY_VERSION ||
+        entry.identity !== sidecarIdentity() ||
+        entry.init !== key.init ||
+        entry.request !== key.request ||
+        !Array.isArray(entry.programs) ||
+        !entry.answer) {
+        return undefined;
+    }
+    return { programs: entry.programs, answer: entry.answer };
+}
+/** Whether `answer` can be served again: it does not depend on the clock. */
+export function keepable(answer) {
+    return !(answer.inferred_types ?? []).some((t) => t.unwidened_out_of_budget === true);
+}
+/**
+ * Everything the compiler holds for `project` as it stands, under `key`: its
+ * root files in order, its options, and each source file's path, module
+ * format and the sha256 of its text.
+ */
+export function programRecord(key, project) {
+    const program = project.getProgram().compilerObject;
+    return {
+        key,
+        roots: listProgramFiles(project),
+        options: JSON.stringify(program.getCompilerOptions()),
+        sources: program
+            .getSourceFiles()
+            .map((file) => [file.fileName, String(file.impliedNodeFormat ?? ''), sha256(file.text)]),
+    };
+}
+/**
+ * The first source file of `kept` whose text on disk is not the text it was
+ * read with, or `undefined` when every one on disk is the same. Read before any
+ * program is built: a changed file, the usual reason an answer is stale, is
+ * found for the cost of reading the files, and no program is built to find
+ * it. The compiler reads a file without its byte-order mark, and so does
+ * this.
+ */
+export function changedSource(kept) {
+    for (const [file, , hash] of kept.sources) {
+        let text;
+        try {
+            text = fs.readFileSync(file, 'utf8');
+        }
+        catch {
+            // Not on disk: ts-morph serves the default library from memory. A
+            // file that is really gone is found when the program is built.
+            continue;
+        }
+        if (text.charCodeAt(0) === 0xfeff)
+            text = text.slice(1);
+        if (sha256(text) !== hash)
+            return `${file}, whose text changed`;
+    }
+    return undefined;
+}
+/**
+ * Build `project`'s program again with nothing in it changed. ts-morph builds
+ * a program only after a change, and roots it at every file the project has
+ * loaded, the ones earlier builds reached among them: a program built again
+ * after its first build has more roots than the first. Setting one file's
+ * text to the text it has is the change.
+ */
+export function rebuildProgram(project) {
+    const file = project.getSourceFiles()[0];
+    if (!file)
+        return;
+    file.replaceWithText(file.getFullText());
+    project.getProgram().compilerObject;
+}
+/**
+ * Keep `answer` for `key`, read in `programs`. Written to a temporary file
+ * and renamed, so a reader never sees half an entry. Entries not written to
+ * for `ENTRY_MAX_AGE_MS` are deleted on the way.
+ */
+export function writeEntry(key, programs, answer) {
+    // The cache directory is the only place this writes, and never the
+    // service it read (carrick#1748).
+    const guard = WriteGuard.of({ dirs: [key.dir], protect: [key.repoRoot] });
+    guard.mkdir(key.dir);
+    const entry = {
+        version: ENTRY_VERSION,
+        identity: sidecarIdentity(),
+        init: key.init,
+        request: key.request,
+        programs,
+        answer,
+    };
+    const target = entryPath(key);
+    const temporary = `${target}.${process.pid}.tmp`;
+    guard.writeFile(temporary, JSON.stringify(entry));
+    guard.rename(temporary, target);
+    const now = Date.now();
+    for (const name of fs.readdirSync(key.dir)) {
+        const file = path.join(key.dir, name);
+        try {
+            if (now - fs.statSync(file).mtimeMs > ENTRY_MAX_AGE_MS)
+                guard.remove(file);
+        }
+        catch {
+            // Another process removed it first.
+        }
+    }
+}

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

@@ -39,6 +39,7 @@ import * as crypto from 'node:crypto';
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { ts } from 'ts-morph';
+import { holdsResult, resultCandidatesOf } from './result-candidates.js';
 import { PathNames, declaringFileName } from './position-rows.js';
 import { memberDeclaration } from './declaration-attribution.js';
 /** The methods a `verb` claim may name, and a method key may accept. */
@@ -771,9 +772,10 @@ export function fullSurfaceSha256(surfaces) {
         .filter(surface => surface.reason === undefined && surface.exports.length > 0)
         .map(surface => [surface.package, surface.exports])
         .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
-    // A member's `handlers` (carrick#2674) is out of the hash at every depth, so
-    // a package's key does not change when the lister learns to list them.
-    const text = JSON.stringify(listed, (key, value) => (key === 'handlers' ? undefined : value));
+    // A member's `handlers` (carrick#2674) and a signature's `result_candidates`
+    // (carrick#2817) are out of the hash at every depth, so a package's key does
+    // not change when the lister learns to list them.
+    const text = JSON.stringify(listed, (key, value) => key === 'handlers' || key === 'result_candidates' ? undefined : value);
     return crypto.createHash('sha256').update(text).digest('hex');
 }
 function exportKey(check) {
@@ -1365,6 +1367,8 @@ class DeclarationReader {
      * `claim_invalid`.
      */
     judgeHttp(receiver, claim) {
+        if (claim.kind === 'result')
+            return this.judgeHttpResult(receiver, claim);
         if (claim.kind === 'make') {
             const base = claim.base;
             if (claim.form !== 'call' ||
@@ -1624,8 +1628,38 @@ class DeclarationReader {
                 return { outcome: this.judgeOp(receiver, claim, rules) };
             case 'reserved':
                 return { outcome: this.judgeReserved(receiver, claim) };
+            case 'result':
+                return { outcome: this.resultOutcome(this.ownCallee(receiver, claim.path ?? [], claim.member, 'call'), claim.result) };
         }
     }
+    /**
+     * A `result` claim (carrick#2817): the claimed result is a candidate of at
+     * least one signature the callee declares, by rule R (`result-candidates.ts`).
+     * Anything else, including a call that returns nothing, is
+     * `result_not_candidate`.
+     */
+    resultOutcome(callee, shape) {
+        if ('failure' in callee)
+            return callee.failure;
+        for (const signature of callee.signatures) {
+            const candidates = resultCandidatesOf(this.checker, signature);
+            if (candidates !== undefined && holdsResult(candidates, shape))
+                return VERIFIED;
+        }
+        return failed('result_not_candidate');
+    }
+    /** A `result` claim on an HTTP receiver: `path` walked from it, then `member` of what that reaches. */
+    judgeHttpResult(receiver, claim) {
+        let holder = receiver;
+        for (const hop of claim.path ?? []) {
+            const property = this.declaredProperty(holder, hop);
+            if (!property)
+                return failed('member_missing');
+            holder = this.checker.getTypeOfSymbol(property);
+        }
+        const callee = claim.member === null ? this.callSignatures(holder) : this.callableProperty(holder, claim.member);
+        return this.resultOutcome(callee, claim.result);
+    }
     /**
      * `member` (or the export itself, when null) is callable (`call`) or
      * constructible (`new`) through signatures the receiver's home packages
@@ -3356,7 +3390,11 @@ class DeclarationReader {
                     param.literals = [...literals].sort();
                 params.push(param);
             }
-            listed.push({ params, returns: this.printed(this.checker.getReturnTypeOfSignature(signature)) });
+            const entry = { params, returns: this.printed(this.checker.getReturnTypeOfSignature(signature)) };
+            const candidates = resultCandidatesOf(this.checker, signature);
+            if (candidates !== undefined)
+                entry.result_candidates = candidates;
+            listed.push(entry);
         }
         return listed;
     }

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

@@ -0,0 +1,53 @@
+/**
+ * Every node of a source file, walked once per file (carrick#1935).
+ *
+ * The inferrer locates each item by a line, a text near a line, or a span.
+ * Each of those lookups used to call `sourceFile.getDescendants()`, which
+ * walks and wraps every node of the file, once per item: on a generated
+ * client of 8,000+ lines that was 71% of an infer request's time. Here the
+ * file is walked once, the positions are read once, and a lookup wraps only
+ * the nodes it returns.
+ *
+ * The walk is ts-morph's own (`getDescendants()` iterates the same compiler
+ * nodes in the same order, tokens, syntax lists and its comment nodes
+ * included), and a node is wrapped through the project's own factory, so a
+ * lookup returns the very wrapper the walk returned.
+ *
+ * The index belongs to the compiler's source file node, not to the file's
+ * name: replacing a file's text gives it a new node, so a file rewritten for
+ * one reading and then restored is indexed again each time.
+ */
+import { Node, SyntaxKind, ts, type SourceFile } from 'ts-morph';
+/** One node of the file, with what the lookups read of it. */
+export interface IndexedNode {
+    node: ts.Node;
+    kind: SyntaxKind;
+    /** `getStart()`: the first character of its own text. */
+    start: number;
+    /** `getEnd()`. */
+    end: number;
+    /** `getStartLineNumber()`. */
+    line: number;
+    /** Its place in `getDescendants()` order. */
+    order: number;
+}
+/** How many file indexes have been built: tests read it to prove reuse. */
+export declare function nodeIndexBuilds(): number;
+/** The ts-morph node for an indexed one. */
+export declare function wrap<T extends Node = Node>(sourceFile: SourceFile, entry: IndexedNode): T;
+/** Every descendant, in `getDescendants()` order. */
+export declare function descendantsOf(sourceFile: SourceFile): readonly IndexedNode[];
+/**
+ * The call expressions, in `getDescendantsOfKind(SyntaxKind.CallExpression)`
+ * order.
+ */
+export declare function callsOf(sourceFile: SourceFile): readonly IndexedNode[];
+/** The descendants that start on `line`, in walk order. */
+export declare function descendantsOnLine(sourceFile: SourceFile, line: number): readonly IndexedNode[];
+/**
+ * The descendants that start on a line from `first` to `last`, in walk
+ * order. Walk order is not line order (a doc comment starts before the node
+ * that owns it but follows it in the walk), so the lines' lists are merged
+ * back into walk order.
+ */
+export declare function descendantsOnLines(sourceFile: SourceFile, first: number, last: number): IndexedNode[];