carrick 0.3.133 → 0.3.135

package/sidecar/dist/src/capture/result-label.js

@@ -0,0 +1,91 @@
+/**
+ * Reading a labelled call's result (carrick#2818).
+ *
+ * A request library's call rarely returns the response body itself: the body
+ * sits in a member of what comes back (`data`), behind a parse method
+ * (`json()`), or is the whole value. The library store labels which, per
+ * operation, and the scanner sends the label on the consumer's infer anchor.
+ * This reads the labelled part of the located call's type, so the contract the
+ * consumer states is the body and never the library's envelope.
+ *
+ * The label is one of:
+ *  - `{ whole: true }`: the awaited type;
+ *  - `{ member: [m] }`: `m` on every non-nullish constituent of the awaited
+ *    type, `undefined` and `null` removed from what is read;
+ *  - `{ parse: p }`: the awaited return of calling `p()`, read off the type as
+ *    the call returns it (a promise-like with a `json()` method is a thenable,
+ *    and awaiting it first would drop the method).
+ *
+ * A label the type cannot satisfy abstains with `result_member_missing`.
+ */
+import ts from 'typescript';
+const NULLISH = ts.TypeFlags.Undefined | ts.TypeFlags.Null | ts.TypeFlags.Void;
+/** The constituents of a union, or the type alone. */
+export function constituentsOf(type) {
+    return type.isUnion() ? type.types : [type];
+}
+function missing(what) {
+    return { abstain: `result_member_missing: ${what}` };
+}
+/**
+ * Read `label` off a call's type. `raw` is the type as the call returns it and
+ * `awaited` the type after the transport unwrap; `at` is the node properties
+ * are instantiated at.
+ */
+export function readResultLabel(checker, raw, awaited, label, at) {
+    if ('whole' in label)
+        return { type: awaited };
+    if ('member' in label)
+        return readMember(checker, awaited, label.member[0], at);
+    return readParse(checker, raw, awaited, label.parse, at);
+}
+function readMember(checker, awaited, name, at) {
+    const read = [];
+    for (const constituent of constituentsOf(awaited)) {
+        if (constituent.flags & NULLISH)
+            continue;
+        const property = checker.getPropertyOfType(constituent, name);
+        if (!property)
+            return missing(`the labelled member '${name}' is not on every constituent`);
+        const held = checker.getTypeOfSymbolAtLocation(property, at);
+        for (const part of constituentsOf(held)) {
+            if (!(part.flags & NULLISH))
+                read.push(part);
+        }
+    }
+    if (read.length === 0)
+        return missing(`the labelled member '${name}' holds no value`);
+    if (read.length === 1)
+        return { type: read[0] };
+    const union = checker.getUnionType;
+    // Without the checker's own union the members cannot be joined honestly;
+    // abstaining beats publishing the first of them.
+    if (!union)
+        return missing(`the labelled member '${name}' holds several types`);
+    return { type: union.call(checker, read) };
+}
+function readParse(checker, raw, awaited, name, at) {
+    // The method is looked up on the call's own type first: it is the thenable
+    // that carries `json()`, and its awaited value does not.
+    for (const holder of [raw, awaited]) {
+        const method = checker.getPropertyOfType(holder, name);
+        if (!method)
+            continue;
+        const signature = checker
+            .getSignaturesOfType(checker.getTypeOfSymbolAtLocation(method, at), ts.SignatureKind.Call)
+            .find((candidate) => candidate.parameters.every((p) => isOptional(p)));
+        if (!signature)
+            continue;
+        const returned = checker.getReturnTypeOfSignature(signature);
+        return { type: checker.getAwaitedType(returned) ?? returned };
+    }
+    return missing(`the labelled parse method '${name}' is not callable with no arguments`);
+}
+function isOptional(parameter) {
+    const declaration = parameter.valueDeclaration;
+    return (!!declaration &&
+        ts.isParameter(declaration) &&
+        (declaration.questionToken !== undefined ||
+            declaration.initializer !== undefined ||
+            declaration.dotDotDotToken !== undefined));
+}

package/sidecar/dist/src/capture/self-check.js

@@ -232,6 +232,17 @@ function runSelfCheck(args, treeFiles, repaired) {
  * because the module that is missing is no longer imported to be reported.
  * Fail closed: the alias keeps the refusal it had before the repair.
  */
+/**
+ * Detail for a pinned external that does not resolve on an installed checkout.
+ * A subpath on the specifier means the rewrite found no entry of the package
+ * exporting a declaration from that file, so it named the file itself.
+ */
+function unresolvedExternalDetail(spec) {
+    const pkg = packageNameOf(spec);
+    const subpath = spec.slice(pkg.length + 1);
+    const base = `unresolved pinned external '${spec}' on an installed checkout`;
+    return subpath ? `${base}: no entry of '${pkg}' exports a declaration from '${subpath}'` : base;
+}
 function repairedNameFailure(repaired, file, diagnostic, message) {
     if (!repaired || diagnostic.code !== 2304)
         return undefined;
@@ -432,7 +443,7 @@ function checkedRecord(anchor, ctx) {
             }
             else {
                 outcome = 'decayed_internal';
-                detail = `unresolved pinned external '${blamedExternal}' on an installed checkout`;
+                detail = unresolvedExternalDetail(blamedExternal);
             }
         }
         else {
@@ -452,7 +463,7 @@ function checkedRecord(anchor, ctx) {
         }
         else {
             outcome = 'decayed_internal';
-            detail = `unresolved pinned external '${blamedExternal}' on an installed checkout`;
+            detail = unresolvedExternalDetail(blamedExternal);
         }
     }
     return {

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
@@ -525,7 +637,7 @@ function handleListLibrarySurface(request) {
         const { claimsVerifier } = projectComponents();
         const fromDir = path.resolve(projectLoader.getRepoRoot(), request.from_dir);
         log(`Listing the declared surface of ${request.packages.length} specifier(s) from ${fromDir}`);
-        const { surfaces, surface_sha256 } = claimsVerifier.listSurface(fromDir, request.packages, request.max_entries ?? SURFACE_MAX_ENTRIES, request.exports ?? {});
+        const { surfaces, surface_sha256 } = claimsVerifier.listSurface(fromDir, request.packages, request.max_entries ?? SURFACE_MAX_ENTRIES, request.exports ?? {}, { handlers: request.handlers, resultCandidates: request.result_candidates });
         return { request_id: request.request_id, status: 'success', surfaces, surface_sha256 };
     }
     catch (err) {

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.
+        }
+    }
+}