carrick 0.3.106 → 0.3.108

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

@@ -0,0 +1,162 @@
+/**
+ * The function a line names, from an index built once per source file
+ * (carrick#1915).
+ *
+ * A signature request carries only the line its function starts on, and a
+ * signature pass sends one request per unannotated slot: thousands of
+ * lookups, several per function and many per file. Answering each by walking
+ * the file's every node cost the file's size per slot, and was 81% of the
+ * pass on a 2,345-file program. Here the file is walked once, over the
+ * compiler's own nodes, and each lookup reads the few entries near its line.
+ *
+ * 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 (the unwidened reading, the retype check) and then restored is
+ * indexed again each time, and never answered from positions it no longer has.
+ */
+import { SyntaxKind, ts, } from 'ts-morph';
+import { lineIndex } from './line-index.js';
+/** How far, in lines, a function may start from the line that names it. */
+const LINE_TOLERANCE = 2;
+const FUNCTION_KINDS = new Set([
+    SyntaxKind.FunctionDeclaration,
+    SyntaxKind.ArrowFunction,
+    SyntaxKind.FunctionExpression,
+    SyntaxKind.MethodDeclaration,
+]);
+/** The kinds ts-morph's `Node.isStatement` accepts. */
+const STATEMENT_KINDS = new Set([
+    SyntaxKind.Block,
+    SyntaxKind.BreakStatement,
+    SyntaxKind.ClassDeclaration,
+    SyntaxKind.ContinueStatement,
+    SyntaxKind.DebuggerStatement,
+    SyntaxKind.DoStatement,
+    SyntaxKind.EmptyStatement,
+    SyntaxKind.EnumDeclaration,
+    SyntaxKind.ExportAssignment,
+    SyntaxKind.ExportDeclaration,
+    SyntaxKind.ExpressionStatement,
+    SyntaxKind.ForInStatement,
+    SyntaxKind.ForOfStatement,
+    SyntaxKind.ForStatement,
+    SyntaxKind.FunctionDeclaration,
+    SyntaxKind.IfStatement,
+    SyntaxKind.ImportDeclaration,
+    SyntaxKind.ImportEqualsDeclaration,
+    SyntaxKind.InterfaceDeclaration,
+    SyntaxKind.LabeledStatement,
+    SyntaxKind.ModuleBlock,
+    SyntaxKind.ModuleDeclaration,
+    SyntaxKind.NotEmittedStatement,
+    SyntaxKind.ReturnStatement,
+    SyntaxKind.SwitchStatement,
+    SyntaxKind.ThrowStatement,
+    SyntaxKind.TryStatement,
+    SyntaxKind.TypeAliasDeclaration,
+    SyntaxKind.VariableStatement,
+    SyntaxKind.WhileStatement,
+    SyntaxKind.WithStatement,
+]);
+const indexes = new WeakMap();
+/**
+ * The function whose declaration starts at, or within `LINE_TOLERANCE` lines
+ * of, the given line: the closest, then the smallest, then the first in the
+ * file. A function starting after the line is passed over when a statement
+ * that opens on the line or after it, on a line before the function's, does
+ * not contain the function. Undefined when no function is left.
+ *
+ * These are `TypeInferrer.findFunctionByLine`'s rules, which says why each is
+ * there; this is where they are computed.
+ */
+export function functionAtLine(sourceFile, line) {
+    if (!Number.isFinite(line))
+        return undefined;
+    const index = indexOf(sourceFile.compilerNode);
+    /** Statements opening inside the forward window. */
+    const windowStatements = [];
+    for (let at = Math.ceil(line); at <= line + LINE_TOLERANCE; at++) {
+        const opening = index.statementsByLine.get(at);
+        if (opening)
+            windowStatements.push(...opening);
+    }
+    const separatedFromAnchor = (fn) => windowStatements.some((statement) => statement.line < fn.line && !(statement.start <= fn.start && statement.end >= fn.end));
+    let best;
+    for (let at = Math.ceil(line - LINE_TOLERANCE); at <= line + LINE_TOLERANCE; at++) {
+        for (const fn of index.functionsByLine.get(at) ?? []) {
+            if (fn.line > line && separatedFromAnchor(fn))
+                continue;
+            if (best === undefined || isBetter(fn, best, line))
+                best = fn;
+        }
+    }
+    return best ? wrapped(sourceFile, best) : undefined;
+}
+/** Closer to the line, then smaller, then earlier in the file. */
+function isBetter(fn, best, line) {
+    const delta = Math.abs(fn.line - line);
+    const bestDelta = Math.abs(best.line - line);
+    if (delta !== bestDelta)
+        return delta < bestDelta;
+    const size = fn.end - fn.start;
+    const bestSize = best.end - best.start;
+    if (size !== bestSize)
+        return size < bestSize;
+    return fn.order < best.order;
+}
+function indexOf(file) {
+    let index = indexes.get(file);
+    if (!index) {
+        index = buildIndex(file);
+        indexes.set(file, index);
+    }
+    return index;
+}
+function buildIndex(file) {
+    // Lines as ts-morph's `getStartLineNumber` counts them, which is what the
+    // scanner's line numbers were matched against.
+    const lineAt = lineIndex(file.text);
+    const functionsByLine = new Map();
+    const statementsByLine = new Map();
+    let order = 0;
+    const visit = (node) => {
+        const isFunction = FUNCTION_KINDS.has(node.kind);
+        const isStatement = STATEMENT_KINDS.has(node.kind);
+        if (isFunction || isStatement) {
+            const start = node.getStart(file);
+            const extent = { start, end: node.end, line: lineAt(start) };
+            if (isFunction) {
+                pushAt(functionsByLine, extent.line, { ...extent, node, order: order++ });
+            }
+            if (isStatement) {
+                pushAt(statementsByLine, extent.line, extent);
+            }
+        }
+        ts.forEachChild(node, visit);
+    };
+    ts.forEachChild(file, visit);
+    return { functionsByLine, statementsByLine };
+}
+function pushAt(byLine, line, entry) {
+    const entries = byLine.get(line);
+    if (entries)
+        entries.push(entry);
+    else
+        byLine.set(line, [entry]);
+}
+/**
+ * The ts-morph node for an indexed function. Only this one is wrapped: the
+ * deepest node at the function's first character is the function or sits
+ * inside it, so its ancestors lead there, and the rest of the file's nodes are
+ * never given wrappers they would keep for the life of the project.
+ */
+function wrapped(sourceFile, fn) {
+    let node = sourceFile.getDescendantAtPos(fn.start);
+    while (node && node.compilerNode !== fn.node) {
+        node = node.getParent();
+    }
+    // An invariant, not a case: no shape is known where the climb misses. If
+    // one exists, the answer is still the function the index chose.
+    node ??= sourceFile.getFirstDescendant((descendant) => descendant.compilerNode === fn.node);
+    return node;
+}

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

@@ -10,5 +10,10 @@
  * - stdout is ONLY for JSON responses
  * - stderr is for logging
  * - Process stays alive between requests (warm standby)
+ * - One request at a time. A handler that runs the compiler blocks the event
+ *   loop until it returns, so a request sent meanwhile waits in the pipe, and
+ *   nothing can cancel the one that is running. The scanner kills a process
+ *   that goes silent past its deadline; a long handler stays alive by writing
+ *   `progress` frames as it finishes units of work (writeProgress).
  */
 export {};

package/sidecar/dist/src/index.js

@@ -10,6 +10,11 @@
  * - stdout is ONLY for JSON responses
  * - stderr is for logging
  * - Process stays alive between requests (warm standby)
+ * - One request at a time. A handler that runs the compiler blocks the event
+ *   loop until it returns, so a request sent meanwhile waits in the pipe, and
+ *   nothing can cancel the one that is running. The scanner kills a process
+ *   that goes silent past its deadline; a long handler stays alive by writing
+ *   `progress` frames as it finishes units of work (writeProgress).
  */
 import * as path from 'node:path';
 import * as readline from 'node:readline';
@@ -21,6 +26,8 @@ import { DefinitionResolver } from './definition-resolver.js';
 import { captureStub, findDisqualifyingTopTypes, jsonWireDeclarations, runCheck, } from './capture/index.js';
 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';
 // ===========================================================================
 // Module-level state
 // ===========================================================================
@@ -32,6 +39,13 @@ let initTimeMs = null;
  * the service's files (carrick#1604).
  */
 let components = new Map();
+/**
+ * Reads a capture stub's own declaration tree and nothing of the init'd
+ * project, so it is not one of the project's components: taking it from them
+ * would build the service's whole program to answer about the stub
+ * (carrick#1927).
+ */
+const definitionResolver = new DefinitionResolver();
 /**
  * Get the project-backed components, building the project if this is the
  * first request that needs it.
@@ -61,7 +75,6 @@ function projectComponents(key = '') {
         built = {
             typeBundler: new TypeBundler({ project, repoRoot }),
             typeInferrer,
-            definitionResolver: new DefinitionResolver({ project }),
             // Locates calls exactly as `infer` does, so it rewrites the node the
             // consumer's published type came from (carrick#1491).
             // The walk is typed against the capture bundle's compiler copy and
@@ -168,7 +181,11 @@ function handleBundle(request) {
         log(`Bundling ${request.symbols.length} symbol(s)`);
         // A symbol named by a path is bundled from the program of the project
         // that owns that file (carrick#1604).
-        const results = [...byProject(request.symbols, (symbol) => symbol.source_file)].map(([key, symbols]) => projectComponents(key).typeBundler.bundle(symbols));
+        const results = [...byProject(request.symbols, (symbol) => symbol.source_file)].map(([key, symbols]) => {
+            const { typeBundler } = projectComponents(key);
+            writeProgress(request.request_id, 'bundle', 'program ready');
+            return typeBundler.bundle(symbols);
+        });
         const result = results.length === 1 ? results[0] : mergeBundles(results);
         if (!result.success) {
             return {
@@ -208,6 +225,10 @@ function handleBundle(request) {
 function handleCaptureV2(request) {
     try {
         log(`capture_v2 for service '${request.service_name}' (${request.anchors.length} anchor(s))`);
+        // A frame for each stage as the capture reaches it, and within a stage
+        // (one report per anchor) at most one per interval.
+        let stage;
+        const withinStage = atMostEvery(PROGRESS_INTERVAL_MS, (phase, message) => writeProgress(request.request_id, phase, message));
         const result = captureStub({
             repoRoot: request.repo_root,
             serviceName: request.service_name,
@@ -215,6 +236,12 @@ function handleCaptureV2(request) {
             outDir: request.out_dir,
             tsconfigPath: request.tsconfig_path,
             scanRoot: request.scan_root,
+            onProgress: (phase, message) => {
+                if (phase === stage)
+                    return withinStage(phase, message);
+                stage = phase;
+                writeProgress(request.request_id, phase, message);
+            },
         });
         return {
             request_id: request.request_id,
@@ -284,7 +311,13 @@ async function handleCheckV2Async(request) {
 function handleInfer(request) {
     try {
         log(`Inferring ${request.requests.length} type(s)`);
-        const results = [...byProject(request.requests, (item) => item.file_path)].map(([key, items]) => projectComponents(key).typeInferrer.infer(items, request.extraction_config));
+        // 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]) => projectComponents(key).typeInferrer.infer(items, request.extraction_config, () => {
+            done += 1;
+            report();
+        }));
         const result = results.length === 1
             ? results[0]
             : (() => {
@@ -300,6 +333,9 @@ function handleInfer(request) {
             request_id: request.request_id,
             status: result.success ? 'success' : 'error',
             inferred_types: result.inferred_types,
+            // 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,
         };
     }
@@ -329,11 +365,19 @@ function handleRetypeCheck(request) {
         const groups = byProject(request.items.map((item, index) => ({ item, index })), ({ item }) => item.file_path);
         const deadline = performance.now() + budget;
         const outcomes = new Array(request.items.length);
+        // One count for the request, whichever programs its items span, reported
+        // as `infer` reports its batch (carrick#1914, carrick#1945).
+        let judged = 0;
+        const report = atMostEvery(PROGRESS_INTERVAL_MS, () => writeProgress(request.request_id, 'retype', `${judged} of ${request.items.length}`));
+        const onJudged = () => {
+            judged += 1;
+            report();
+        };
         for (const [key, entries] of groups) {
             // One budget for the request, whichever programs it spans.
             const remaining = groups.size === 1 ? budget : Math.max(0, deadline - performance.now());
             projectComponents(key)
-                .retyper.run(entries.map(({ item }) => item), remaining)
+                .retyper.run(entries.map(({ item }) => item), remaining, onJudged)
                 .forEach((outcome, position) => {
                 outcomes[entries[position].index] = outcome;
             });
@@ -388,6 +432,8 @@ function handleVerifyLibraryClaims(request) {
     const started = performance.now();
     try {
         const { claimsVerifier } = projectComponents();
+        // The verifier's budget starts now, and so does the scanner's wait.
+        writeProgress(request.request_id, 'verify_library_claims', 'program ready');
         const fromDir = path.resolve(projectLoader.getRepoRoot(), request.from_dir);
         log(`Verifying ${request.checks.length} library claim(s) from ${fromDir}`);
         const { semantics, modules } = claimsVerifier.run(fromDir, request.checks, request.budget_ms ?? SEMANTICS_BUDGET_MS);
@@ -428,12 +474,13 @@ function handleListLibrarySurface(request) {
 }
 /**
  * Handle the 'resolve_definitions' action - resolve surface aliases from a
- * v2 capture stub package's declaration tree.
+ * v2 capture stub package's declaration tree. Stateless, as `capture_v2` is:
+ * it needs no init and builds no project but the stub's own.
  */
 function handleResolveDefinitions(request) {
     try {
         log(`Resolving ${request.aliases.length} type alias(es) from ${request.stub_dir}`);
-        const results = projectComponents().definitionResolver.resolveFromStub(request.stub_dir, request.aliases);
+        const results = definitionResolver.resolveFromStub(request.stub_dir, request.aliases);
         return {
             request_id: request.request_id,
             status: 'success',
@@ -530,9 +577,15 @@ function writeResponse(response) {
     process.stdout.write(json + '\n');
 }
 /**
- * Write a non-terminal progress/keepalive frame (async install protocol).
- * Distinct `status: 'progress'` so clients skip it and wait for the terminal
- * success/error frame.
+ * Write a non-terminal progress frame. Distinct `status: 'progress'` so
+ * clients skip it and wait for the terminal success/error frame; the scanner
+ * restarts its deadline for the request on each one (carrick#1914).
+ *
+ * A synchronous handler calls this between units of its work, with the event
+ * loop blocked. The frame still leaves at once: a write this small to a pipe
+ * with room in it completes inside the call, and the reader on the other end
+ * drains the pipe on its own thread, so there is room. It is written through
+ * the same stream as every answer, so a frame can never land inside one.
  */
 function writeProgress(requestId, phase, message) {
     process.stdout.write(JSON.stringify({ request_id: requestId, status: 'progress', phase, message }) + '\n');

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

@@ -0,0 +1,54 @@
+/**
+ * Which requests of an `infer` batch were slow, and at what (carrick#1985).
+ *
+ * A pass can send thousands of requests and spend most of its time in a few
+ * of them. The inferrer times every request; this module turns those timings
+ * into what the batch's answer carries: how many there were and what they
+ * add up to, the slowest few by name, the request that printed the longest
+ * type, and the requests that were the first asked of their file, apart.
+ *
+ * A request's time is also told apart by what it went on: the compiler call
+ * that computes the type, and the print of that type to text. The two have
+ * different remedies, and a printed length alone cannot say which one a slow
+ * request was: a type of four characters can take seconds to compute, and a
+ * type of a million can take half a second to print.
+ *
+ * It measures and names. It changes no answer and holds no type text.
+ */
+import type { InferSlotTiming, InferTiming } from './types.js';
+/**
+ * How many of its slowest requests a batch's answer names.
+ *
+ * Enough for a reader adding batches up to say what the slowest hundredth of
+ * a whole pass took: a pass's slowest requests are among its batches'
+ * slowest, and the last one a batch names is the most any it left out can
+ * have taken.
+ */
+export declare const SLOWEST_SLOTS = 25;
+/** How long something that started at `startedMs` has taken by `nowMs`. */
+export declare function elapsedMs(startedMs: number, nowMs: number): number;
+/**
+ * The parts of a request's time that are told apart: `type` is the compiler
+ * call that computes a type, `print` is the print of a type to text.
+ */
+export type TimedPhase = 'type' | 'print';
+/**
+ * Run `work`, and count how long it took as `phase`.
+ *
+ * The count is the process's, not a request's: whoever wants one request's
+ * share reads `phaseClock` before the request and after it. One request runs
+ * at a time, so the difference is that request's and nobody else's.
+ */
+export declare function timedPhase<T>(phase: TimedPhase, work: () => T): T;
+/** What each phase has come to so far, in milliseconds. */
+export declare function phaseClock(): Readonly<Record<TimedPhase, number>>;
+/**
+ * What a batch's answer says of the time its requests took. `slots` holds one
+ * timing per request, in the order the batch was done with them.
+ */
+export declare function inferTiming(slots: readonly InferSlotTiming[]): InferTiming;
+/**
+ * One timing for a request several projects answered, each with its own:
+ * the counts and the times added up, and the slowest of all of them.
+ */
+export declare function mergeInferTimings(parts: readonly InferTiming[]): InferTiming;

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

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

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

@@ -0,0 +1,9 @@
+/**
+ * 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
+ * `getStartLineNumber` makes. A lone carriage return or a Unicode line
+ * separator ends a line for the compiler and not here.
+ *
+ * The text is read once; each lookup after that is a binary search.
+ */
+export declare function lineIndex(text: string): (pos: number) => number;

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

@@ -0,0 +1,26 @@
+/**
+ * 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
+ * `getStartLineNumber` makes. A lone carriage return or a Unicode line
+ * separator ends a line for the compiler and not here.
+ *
+ * The text is read once; each lookup after that is a binary search.
+ */
+export function lineIndex(text) {
+    const starts = [0];
+    for (let i = 0; i < text.length; i++)
+        if (text[i] === '\n')
+            starts.push(i + 1);
+    return (pos) => {
+        let lo = 0;
+        let hi = starts.length - 1;
+        while (lo < hi) {
+            const mid = (lo + hi + 1) >> 1;
+            if (starts[mid] <= pos)
+                lo = mid;
+            else
+                hi = mid - 1;
+        }
+        return lo + 1;
+    };
+}

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

@@ -0,0 +1,22 @@
+/**
+ * Pacing for the `progress` frames a long request writes (carrick#1914).
+ */
+/**
+ * The least time between two progress frames of one request.
+ *
+ * The scanner's deadline for a request is how long the sidecar may stay
+ * silent about it, so a frame has to say that a unit of work finished, and
+ * has to be far more frequent than that deadline. It does not have to follow
+ * every unit: a batch can finish thousands in a second.
+ */
+export declare const PROGRESS_INTERVAL_MS = 1500;
+/**
+ * `report`, held to one call per `intervalMs`: the first call goes through at
+ * once, and a call made sooner than `intervalMs` after the last one that went
+ * through is dropped.
+ *
+ * It is called by the work, between units, and never by a timer. A handler
+ * that stops finishing units stops reporting, which is what the reader on the
+ * other end is waiting to notice.
+ */
+export declare function atMostEvery<Args extends unknown[]>(intervalMs: number, report: (...args: Args) => void, now?: () => number): (...args: Args) => void;

package/sidecar/dist/src/progress.js

@@ -0,0 +1,31 @@
+/**
+ * Pacing for the `progress` frames a long request writes (carrick#1914).
+ */
+/**
+ * The least time between two progress frames of one request.
+ *
+ * The scanner's deadline for a request is how long the sidecar may stay
+ * silent about it, so a frame has to say that a unit of work finished, and
+ * has to be far more frequent than that deadline. It does not have to follow
+ * every unit: a batch can finish thousands in a second.
+ */
+export const PROGRESS_INTERVAL_MS = 1500;
+/**
+ * `report`, held to one call per `intervalMs`: the first call goes through at
+ * once, and a call made sooner than `intervalMs` after the last one that went
+ * through is dropped.
+ *
+ * It is called by the work, between units, and never by a timer. A handler
+ * that stops finishing units stops reporting, which is what the reader on the
+ * other end is waiting to notice.
+ */
+export function atMostEvery(intervalMs, report, now = () => performance.now()) {
+    let last = Number.NEGATIVE_INFINITY;
+    return (...args) => {
+        const at = now();
+        if (at - last < intervalMs)
+            return;
+        last = at;
+        report(...args);
+    };
+}

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

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