carrick 0.3.106 → 0.3.108

package/sidecar/dist/src/retype.js

@@ -26,6 +26,7 @@
  */
 import { Node, SyntaxKind, ts } from 'ts-morph';
 import { readsResponseStatus, statusesIn, SUCCEEDED, testsOnPath, } from './failure-path.js';
+import { lineIndex } from './line-index.js';
 import { fileDiagnostics } from './unwidened.js';
 /** Names appended to a file that is not ours carry this prefix. */
 const PREFIX = '__carrick_';
@@ -52,9 +53,11 @@ export 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, budgetMs) {
+    run(items, budgetMs, onJudged) {
         const deadline = performance.now() + budgetMs;
         // What each file said before any rewrite. Every rewrite is undone, so it
         // is the same for every item in the file.
@@ -63,12 +66,15 @@ export class Retyper {
             if (performance.now() >= deadline) {
                 return abstain(item, `the retype check ran out of its ${budgetMs}ms budget`);
             }
+            let outcome;
             try {
-                return this.runOne(item, before);
+                outcome = this.runOne(item, before);
             }
             catch (err) {
-                return abstain(item, `the retype check failed: ${err instanceof Error ? err.message : String(err)}`);
+                outcome = abstain(item, `the retype check failed: ${err instanceof Error ? err.message : String(err)}`);
             }
+            onJudged?.();
+            return outcome;
         });
     }
     runOne(item, before) {
@@ -842,22 +848,3 @@ function mapBack(pos, edits) {
     }
     return { kind: 'original', pos: pos - shift };
 }
-/** 1-based line of an original-file position. */
-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/type-inferrer.d.ts

@@ -63,6 +63,11 @@ export interface TypeInferrerOptions {
      */
     unwidenedBudgetMs?: number;
 }
+/**
+ * Called each time an `infer` batch is done with one of its requests,
+ * whatever that request answered: skipped, refused, failed or inferred.
+ */
+export type InferRequestDone = () => void;
 /**
  * TypeInferrer - Extracts types from source code, both explicit and inferred
  *
@@ -81,6 +86,12 @@ export declare class TypeInferrer {
      */
     private readonly readNodes;
     private readonly unwidenedBudgetMs;
+    /**
+     * The files a request has named to this inferrer, as the requests named
+     * them (carrick#1985). It lives as long as the project does, so the first
+     * request of a file is the first of the process, not of a batch.
+     */
+    private readonly filesAsked;
     constructor(options: TypeInferrerOptions);
     /**
      * What the structural printer needs to tell the user's own declarations from
@@ -94,9 +105,10 @@ export declare class TypeInferrer {
      *
      * @param requests - Array of inference requests
      * @param extractionConfig - Agent-generated extraction config for payload unwrapping
+     * @param onRequestDone - Called once per request, as the batch is done with it
      * @returns InferResult with inferred types or errors
      */
-    infer(requests: InferRequestItem[], extractionConfig?: ExtractionConfig): InferResult;
+    infer(requests: InferRequestItem[], extractionConfig?: ExtractionConfig, onRequestDone?: InferRequestDone): InferResult;
     /**
      * carrick#1836: list on `result` the declarations behind the names its text
      * prints that the request's file cannot resolve (`PrintedTypes.namesIn`).
@@ -187,6 +199,61 @@ export declare class TypeInferrer {
      */
     private resolveParamTarget;
     private inferResponseBody;
+    /**
+     * The handler a module exports on `line`: a function that opens on exactly
+     * that line, exported at the top of its module, where no call on the line
+     * registers a route (carrick#807).
+     *
+     * That is the anchor of a route its module's place in the project states:
+     * the row's line is the handler's own export, and the module's exports are
+     * how the framework finds it. Each condition keeps another kind of row out:
+     *
+     *  - the line has to be the function's first, with no tolerance. A model
+     *    row that names no site of its own can sit on any line of a handler,
+     *    and the nearest function to such a line is whatever is declared
+     *    beside it;
+     *  - a method of a class is a controller's handler, whose rows are
+     *    anchored on what a model located before the method's own return;
+     *  - a line that registers a route has a registration to read.
+     */
+    private handlerDeclaredAtLine;
+    /**
+     * `handlerDeclaredAtLine` without its registration test, for a caller that
+     * has already looked for a registration on the line.
+     */
+    private exportedFunctionOpeningOn;
+    /**
+     * The response of a handler the request's line declares, for a request
+     * that also located an expression inside it (carrick#807).
+     *
+     * The handler's own return is read first, exactly as a `function_return`
+     * request at the line reads it, and that reading stands: a body it
+     * recovered, and a decision it made not to publish one. The located
+     * expression is consulted in one case only. Where the handler returns a
+     * call nothing resolves (its library is not installed), the return walk
+     * reads no argument the source does not annotate, because it cannot tell a
+     * response sender from a query. A located payload that is an ARGUMENT of
+     * such a returned call says which it is, so the same walk runs again with
+     * that callee taken as a sender: every success body the handler returns
+     * through it, error branches dropped as before. The located expression's
+     * own type is never what is published here.
+     *
+     * Returns `undefined` when the located expression is something the return
+     * walk never looked at, so it is left to the readings below:
+     *  - the handler returns nothing (`void`): it sends through a parameter;
+     *  - the handler returns transport the walk read no body out of, and the
+     *    located expression is not part of what it returns. A body built before
+     *    the response is returned (`const res = send(body); ...; return res`)
+     *    is one. Named on a send that states an error or redirect status, it is
+     *    no success body and the row abstains.
+     */
+    private responseOfDeclaredHandler;
+    /**
+     * The call inside one of `returned` that the located expression is, or is
+     * an argument of: the send a located payload was handed to. `undefined`
+     * when the located expression is not part of what the handler returns.
+     */
+    private returnedSendHolding;
     /**
      * True when a located call's own result is the route's payload, so the
      * transitional drill into its first argument must not run (carrick#1732).
@@ -291,6 +358,14 @@ export declare class TypeInferrer {
      * else, and is not reported.
      */
     private statedBodyAtRead;
+    /**
+     * The type node `statedBodyAtRead` reads, for a caller that wants the
+     * annotation itself: a consumer's response read reports its root, and a
+     * handler's request read prints it (carrick#807). One reading of "stated at
+     * the read" for both, so the two cannot disagree about which annotation
+     * belongs to a read.
+     */
+    private typeNodeStatedAtRead;
     /**
      * A stated type with `any` or `unknown` written anywhere in it (`unknown`,
      * `Record<string, unknown>`, `{ items: any[] }`) leaves a position open: it
@@ -350,12 +425,54 @@ export declare class TypeInferrer {
      */
     private resultCarrierPayload;
     /**
-     * `Future<T>` -> `T` for a promise-like of the source's own making, read off
-     * the await protocol rather than a name: a `then` whose first parameter is a
-     * callback, whose own first parameter is the value awaiting it yields.
-     * `Promise` and `PromiseLike` are peeled by `unwrapPromiseType` before this.
+     * The shape test of `resultCarrierPayload`: the carrier `type` is, once a
+     * promise-like around it is peeled, and the type arguments a branch of it
+     * holds as a member. `undefined` when `type` is not a carrier.
+     */
+    private resultCarrierArguments;
+    /**
+     * The decided abstain of a call whose result carries transport the
+     * service's wrapper rules verify and read no payload out of (carrick#1841,
+     * carrick#1843): `unknown` with `machinery_envelope` at the root and no
+     * anchor. The root reason is what keeps the capture's own locator from
+     * re-reading the raw call (`inference_decided_no_contract`,
+     * engine/type_compat_v2.rs).
+     */
+    private transportAbstain;
+    /**
+     * `Future<T>` -> `T` for a thenable, read off the await protocol rather
+     * than a name: a `then` whose first parameter is a callback, whose own
+     * first parameter is the value awaiting it yields. `Promise` and
+     * `PromiseLike` are peeled by `unwrapPromiseType` before this.
+     *
+     * The callback is read through `null` and `undefined` (carrick#1877). A
+     * `then` of the source's own making declares `(value: T) => void`; the
+     * platform's declares `onfulfilled?: ((value: T) => ...) | null`, and that
+     * is the `then` a subclass of `Promise` inherits. Read as written, an
+     * optional, nullable callback has no call signature, and the subclass was
+     * not seen as a thenable at all.
+     *
+     * A `then` that cannot be called, or whose first parameter is no callback,
+     * is no protocol, and the type is returned as it is.
+     *
+     * The compiler's own awaited type arbitrates. This walk reads the first
+     * signature of `then`; the language reads all of them. Where awaiting the
+     * type and awaiting what this walk found are not the same thing to the
+     * compiler (an overloaded `then` whose first signature is not the one
+     * `await` takes), the walk did not read the protocol, and the type is
+     * returned as it is rather than published as a guess.
      */
     private unwrapThenableType;
+    /** The value `then`'s first signature hands its callback, read until it stops changing. */
+    private firstThenValue;
+    /**
+     * What `await` yields for `type` where the names do not say: `type` is,
+     * once `Promise` and `PromiseLike` are peeled, a thenable by the protocol
+     * (a subclass of `Promise`, a class with a `then` of its own). `undefined`
+     * where the names say it all or `type` is no thenable, so a caller keeps
+     * the reading it had (carrick#1877).
+     */
+    private awaitedBeyondPromise;
     /**
      * The platform's error shape, in full: `name` and `message` strings AND a
      * `stack`, which is what the `Error` interface declares and every subclass
@@ -456,7 +573,17 @@ export declare class TypeInferrer {
      */
     private castsOfUnreadParameter;
     /**
-     * The zero-argument whole-body read that takes `identifier` as its receiver,
+     * The zero-argument whole-body read taken in place on the value `callExpr`
+     * yields, or `undefined` (carrick#1851): `(await fetch(url)).text()`. The
+     * receiver is the call itself, through the wrappers that leave a value as
+     * it is (parentheses, `await`, `!`), so it is the same read
+     * `bodyReadOnReceiver` finds on a binding of that value. A call that is not
+     * awaited first is read the same way: a request that is a promise and reads
+     * its own body (`send(url).json()`) yields the body from that read too.
+     */
+    private bodyReadOnCallValue;
+    /**
+     * The zero-argument whole-body read that takes `receiver` as its receiver,
      * `res.json()` or `res.text()`, or `undefined`. A text read is a body read
      * like a json one (carrick#1842): without it, `return res.text()` left the
      * walk on the response binding and published the transport object.
@@ -518,12 +645,27 @@ export declare class TypeInferrer {
      * Try to unwrap a type using a single ExtractionRule.
      */
     private tryUnwrapWithRule;
+    /**
+     * The names `type` goes by, own symbol first (carrick#1843).
+     *
+     * `type Task<A> = __Task<A>` has the class's symbol and arguments, and the
+     * alias's beside them. `type Reply<T> = { ... }` has the anonymous `__type`
+     * with no arguments of its own. `type Outcome<A, E> = Done<A, E> |
+     * Failed<A, E>` has no symbol of its own at all. In each, the alias and its
+     * arguments are what a rule naming `Task`, `Reply` or `Outcome` describes.
+     */
+    private wrapperReadings;
     /**
      * Extract the payload type from a matched wrapper. Returns null when the
      * rule matched the wrapper but no payload is recoverable from generics or
      * property paths — the caller decides what a payload-less match means
      * (verified machinery collapses to `unknown` after every rule has run;
      * a name-only match leaves the type untouched).
+     *
+     * `payloadGenericIndex` counts the arguments of `reading`, the name the
+     * rule matched (carrick#1843): an alias is free to order its parameters
+     * differently from the type it stands for, so the same index into the
+     * other list is a different argument.
      */
     private extractPayloadFromWrapper;
     /**
@@ -819,9 +961,22 @@ export declare class TypeInferrer {
      *
      * Under `statedOnly` the annotation is the ONLY thing that counts, so an
      * unresolvable callee's arguments never become a contract by accident.
+     *
+     * `asSent` judges the object in the form it is sent in, which is what an
+     * ARGUMENT handed to a sender is asked; see `typeIsObjectShaped`.
      */
     private nodeCarriesPayloadContract;
-    /** Object, array-of-object, or a union/intersection containing one. */
+    /**
+     * Object, array-of-object, or a union/intersection containing one.
+     *
+     * With `asSent` the object is judged in the form it is SENT in
+     * (carrick#1163): a value that declares `toJSON()` travels as what that
+     * returns. A `URL` or a `Date` is therefore the string it serialises to,
+     * the bare primitive this rule already refuses, and `redirect(new URL(path,
+     * base))` hands over a location exactly as `redirect("/next")` does
+     * (carrick#807). A value whose JSON form is itself an object is a body like
+     * any other.
+     */
     private typeIsObjectShaped;
     /**
      * The `satisfies X` / `as X` / `<X>` annotation node on an expression, when
@@ -920,11 +1075,19 @@ export declare class TypeInferrer {
     /**
      * Declaration file (absolute path) of the anchor symbol
      * `primaryTypeSymbol` reports for this type, or `undefined` when the type
-     * has no user-facing anchor or no source declaration. The scanner's
-     * pub/sub two-anchor arbitration (carrick#413) uses this to re-aim a
-     * demoted explicit bundle request: the bundler resolves a `SymbolRequest`
-     * only against declarations IN its `source_file`, so the request must
-     * point at the file that actually declares the tsc-witnessed payload type.
+     * has no user-facing anchor or no source declaration. Every path that
+     * reports the symbol reports this beside it (carrick#1819): it is where a
+     * reader finds the type an anchor names. The scanner's pub/sub two-anchor
+     * arbitration (carrick#413) also uses it to re-aim a demoted explicit
+     * bundle request: the bundler resolves a `SymbolRequest` only against
+     * declarations IN its `source_file`, so the request must point at the file
+     * that actually declares the tsc-witnessed payload type.
+     *
+     * The declarations read are those of the type's own symbol, so a name
+     * imported through a barrel reports the file that declares it, and a name
+     * two files declare reports the one this type resolves to. A declaration in
+     * an installed package or a TypeScript lib is reported as it is found, as
+     * an absolute path; what a reader is shown for it is the scanner's call.
      *
      * Only declaration kinds the bundler's `validateSymbols` can resolve
      * (interface, type alias, class, enum, function, variable) count. A
@@ -1194,6 +1357,46 @@ export declare class TypeInferrer {
      * Returns null (not a spurious type) for a genuinely payload-less handler.
      */
     private inferRequestReadFromHandler;
+    /**
+     * The call in a handler that reads the request's body off the platform
+     * request the handler was handed, or `undefined` (carrick#807).
+     *
+     * Read by shape, with no method name consulted:
+     *
+     *  - a call that takes nothing, on a member of a value whose type is request
+     *    machinery (`typeIsFrameworkMachinery`: declared by the platform or an
+     *    installed library, and carrying its body readers);
+     *  - that value is rooted at one of the handler's OWN parameters, named or
+     *    destructured. A response read off an outbound call inside the handler
+     *    (`(await upstream.json()) as Rate`) has the same shape one variable
+     *    away, and is the opposite side of a different exchange;
+     *  - and the call's result, awaited, is `any` or `unknown`: the platform's
+     *    untyped parse. A read that states its own type (`formData()`, a typed
+     *    `json<T>()`) is not this shape and is left to the readers that
+     *    already handle it.
+     *
+     * The first such call in source order: a body is read once.
+     */
+    private platformBodyReadIn;
+    /**
+     * The request contract the source states AT a body read, or null when it
+     * states none there (carrick#807).
+     *
+     * Three statements count, each of them on the read itself:
+     *
+     *  - a cast on it: `(await request.json()) as NewWidget`;
+     *  - the annotation of the binding it initialises:
+     *    `const input: NewWidget = await request.json()`;
+     *  - a schema the read, or the binding that holds it, is handed to
+     *    (`schemaConsumingRead`): the schema's input is what a caller may send.
+     *
+     * The first two are `typeNodeStatedAtRead`, the reading a consumer's
+     * response read already gets. An annotation further out is not one of them:
+     * `const saved: Saved = await save(await request.json())` types what `save`
+     * returned, and reading it as the body would publish the wrong side of the
+     * handler. Nor is a placeholder (`as unknown`, `Record<string, unknown>`).
+     */
+    private requestStatedAtBodyRead;
     /**
      * Resolve a type-annotation/type-argument node to fully-structural text,
      * dropping any `Promise<…>` wrapper (`c.req.json<T>()` returns `Promise<T>`,
@@ -1337,8 +1540,31 @@ export declare class TypeInferrer {
      * request type resolves `body` to `unknown`/`any`, which the useless-type
      * guard rejects. So a handler that declares nothing yields null and the next
      * anchor runs.
+     *
+     * The member has to be one the route's own annotation can have filled
+     * (carrick#807). The platform `Request` declares `body` too, as the byte
+     * stream every request carries, and so does each library type that extends
+     * it. That is concrete, so it passed the useless-type guard and a handler
+     * taking the platform request published a stream as its request contract,
+     * ahead of the body read inside it. A `body` a library declares with one
+     * fixed type says nothing about this route and is skipped.
      */
     private requestBodyFromHandlerParams;
+    /**
+     * True when a member is declared by a library, or by the platform, with a
+     * type that names none of its declaring type's parameters: the same type on
+     * every value, whichever route the value belongs to.
+     *
+     * `body: ReqBody` on a request type generic in its body is a slot, and the
+     * handler's annotation fills it. `readonly body: ReadableStream<Uint8Array>
+     * | null` on the platform request is not. A member the repo declares itself
+     * is never fixed in this sense: writing `body: NewWidget` on the handler's
+     * own request type is the annotation, and one declaration of the repo's
+     * among several (an intersection with the platform type) decides it. A
+     * declaration that states no type at all is left to the guards that read
+     * the type.
+     */
+    private memberIsFixedByItsLibrary;
     /**
      * Anchor (b2): the contract declared by a VALIDATOR MIDDLEWARE on the
      * registration (carrick#964).