carrick 0.3.133 → 0.3.135

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[];

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

@@ -0,0 +1,100 @@
+/**
+ * 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 { SyntaxKind } from 'ts-morph';
+import { lineIndex } from './line-index.js';
+const internals = (sourceFile) => sourceFile;
+const indexes = new WeakMap();
+let builds = 0;
+/** How many file indexes have been built: tests read it to prove reuse. */
+export function nodeIndexBuilds() {
+    return builds;
+}
+function indexOf(sourceFile) {
+    const key = sourceFile.compilerNode;
+    let index = indexes.get(key);
+    if (!index) {
+        index = buildIndex(sourceFile);
+        indexes.set(key, index);
+    }
+    return index;
+}
+function buildIndex(sourceFile) {
+    builds += 1;
+    const file = sourceFile.compilerNode;
+    const lineAt = lineIndex(file.text);
+    const all = [];
+    const calls = [];
+    const byLine = new Map();
+    for (const node of internals(sourceFile)._getCompilerDescendantsIterator()) {
+        const start = node.getStart(file);
+        const entry = {
+            node,
+            kind: node.kind,
+            start,
+            end: node.end,
+            line: lineAt(start),
+            order: all.length,
+        };
+        all.push(entry);
+        if (entry.kind === SyntaxKind.CallExpression)
+            calls.push(entry);
+        const onLine = byLine.get(entry.line);
+        if (onLine)
+            onLine.push(entry);
+        else
+            byLine.set(entry.line, [entry]);
+    }
+    return { all, calls, byLine };
+}
+/** The ts-morph node for an indexed one. */
+export function wrap(sourceFile, entry) {
+    return internals(sourceFile)._getNodeFromCompilerNode(entry.node);
+}
+/** Every descendant, in `getDescendants()` order. */
+export function descendantsOf(sourceFile) {
+    return indexOf(sourceFile).all;
+}
+/**
+ * The call expressions, in `getDescendantsOfKind(SyntaxKind.CallExpression)`
+ * order.
+ */
+export function callsOf(sourceFile) {
+    return indexOf(sourceFile).calls;
+}
+/** The descendants that start on `line`, in walk order. */
+export function descendantsOnLine(sourceFile, line) {
+    return indexOf(sourceFile).byLine.get(line) ?? [];
+}
+/**
+ * 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 function descendantsOnLines(sourceFile, first, last) {
+    const { byLine } = indexOf(sourceFile);
+    const found = [];
+    for (let line = Math.ceil(first); line <= last; line++) {
+        const onLine = byLine.get(line);
+        if (onLine)
+            found.push(...onLine);
+    }
+    return found.sort((a, b) => a.order - b.order);
+}

package/sidecar/dist/src/project-loader.d.ts

@@ -171,6 +171,17 @@ export declare class ProjectLoader {
      * @throws Error if load() has not succeeded, or if the build fails
      */
     getProject(): Project;
+    /**
+     * Whether the project behind a key from `projectKeyFor` has been built,
+     * without building it (carrick#2843).
+     */
+    isBuilt(key: string): boolean;
+    /**
+     * Whether the project resolves through a module graph read outside the
+     * compiler (Deno, carrick#1260). What such a program reads is not all in
+     * its source files (carrick#2843).
+     */
+    resolvesThroughModuleGraph(): boolean;
     /**
      * The default project when a request has built it, and `undefined` before
      * that, without building it (carrick#2027).

package/sidecar/dist/src/project-loader.js

@@ -487,6 +487,21 @@ export class ProjectLoader {
         }
         return this.project;
     }
+    /**
+     * Whether the project behind a key from `projectKeyFor` has been built,
+     * without building it (carrick#2843).
+     */
+    isBuilt(key) {
+        return key === '' ? this.project !== null : this.ownerProjects.has(key);
+    }
+    /**
+     * Whether the project resolves through a module graph read outside the
+     * compiler (Deno, carrick#1260). What such a program reads is not all in
+     * its source files (carrick#2843).
+     */
+    resolvesThroughModuleGraph() {
+        return this.denoProject !== undefined;
+    }
     /**
      * The default project when a request has built it, and `undefined` before
      * that, without building it (carrick#2027).

package/sidecar/dist/src/result-candidates.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Which parts of a call's return could hold the response body the call
+ * resolves to (carrick#2817). The compiler decides one case, that the
+ * caller supplies the whole return as a type argument (`whole_decided`); for
+ * every other return it only lists the candidates: the members that carry a
+ * type parameter of the signature, and the parse methods. Choosing among them
+ * is the store picker's job, and `holdsResult` judges the choice.
+ *
+ * Rule R, per signature `S` with type parameters `P`:
+ * 1. `A` is the awaited return of `S`. While `A` is a type parameter of `S`
+ *    whose default is not `unknown` or `any`, take the default (awaited), at
+ *    most four hops: a default of `unknown`/`any` is the caller-supplies-it
+ *    case.
+ * 2. `whole_decided`: `A` is a type parameter of `S` with no constraint.
+ * 3. `members`: across the branches of `A` (a conditional's true and false
+ *    types, a union's constituents without `undefined`/`null`/`void`; depth at
+ *    most four), every property with no call signature whose declared type
+ *    mentions a type parameter in `P`.
+ * 4. `parse`: properties of `S`'s raw return or of a branch of `A` that can
+ *    be called with no required argument and whose awaited return is a bare,
+ *    unconstrained type parameter of that method's own signature.
+ * A signature that returns nothing (void, undefined, never) has no candidates.
+ */
+import { ts } from 'ts-morph';
+import type { ResultShape, SurfaceResultCandidates } from './types.js';
+export declare function resultCandidatesOf(checker: ts.TypeChecker, signature: ts.Signature): SurfaceResultCandidates | undefined;
+/** Whether `shape` names one of `candidates`. `whole` is always one; a decided whole is the only one. */
+export declare function holdsResult(candidates: SurfaceResultCandidates, shape: ResultShape): boolean;

package/sidecar/dist/src/result-candidates.js

@@ -0,0 +1,209 @@
+/**
+ * Which parts of a call's return could hold the response body the call
+ * resolves to (carrick#2817). The compiler decides one case, that the
+ * caller supplies the whole return as a type argument (`whole_decided`); for
+ * every other return it only lists the candidates: the members that carry a
+ * type parameter of the signature, and the parse methods. Choosing among them
+ * is the store picker's job, and `holdsResult` judges the choice.
+ *
+ * Rule R, per signature `S` with type parameters `P`:
+ * 1. `A` is the awaited return of `S`. While `A` is a type parameter of `S`
+ *    whose default is not `unknown` or `any`, take the default (awaited), at
+ *    most four hops: a default of `unknown`/`any` is the caller-supplies-it
+ *    case.
+ * 2. `whole_decided`: `A` is a type parameter of `S` with no constraint.
+ * 3. `members`: across the branches of `A` (a conditional's true and false
+ *    types, a union's constituents without `undefined`/`null`/`void`; depth at
+ *    most four), every property with no call signature whose declared type
+ *    mentions a type parameter in `P`.
+ * 4. `parse`: properties of `S`'s raw return or of a branch of `A` that can
+ *    be called with no required argument and whose awaited return is a bare,
+ *    unconstrained type parameter of that method's own signature.
+ * A signature that returns nothing (void, undefined, never) has no candidates.
+ */
+import { ts } from 'ts-morph';
+const MAX_DEPTH = 4;
+const NOTHING = ts.TypeFlags.Void | ts.TypeFlags.Undefined | ts.TypeFlags.Never;
+const NULLISH = ts.TypeFlags.Undefined | ts.TypeFlags.Null | ts.TypeFlags.Void;
+const OPEN = ts.TypeFlags.Any | ts.TypeFlags.Unknown;
+const isTypeParameter = (type) => (type.flags & ts.TypeFlags.TypeParameter) !== 0;
+const byCodeUnit = (a, b) => (a < b ? -1 : a > b ? 1 : 0);
+export function resultCandidatesOf(checker, signature) {
+    const reader = new ResultReader(checker);
+    return reader.candidates(signature);
+}
+/** Whether `shape` names one of `candidates`. `whole` is always one; a decided whole is the only one. */
+export function holdsResult(candidates, shape) {
+    if ('whole' in shape)
+        return true;
+    if (candidates.whole_decided)
+        return false;
+    if ('member' in shape)
+        return candidates.members.includes(shape.member[0]);
+    return candidates.parse.includes(shape.parse);
+}
+class ResultReader {
+    checker;
+    constructor(checker) {
+        this.checker = checker;
+    }
+    candidates(signature) {
+        const raw = this.checker.getReturnTypeOfSignature(signature);
+        if (raw.flags & NOTHING)
+            return undefined;
+        const params = new Set(signature.getTypeParameters() ?? []);
+        let awaited = this.awaited(raw);
+        for (let hop = 0; hop < MAX_DEPTH && isTypeParameter(awaited) && params.has(awaited); hop++) {
+            const fallback = this.checker.getDefaultFromTypeParameter(awaited);
+            if (fallback === undefined || fallback.flags & OPEN)
+                break;
+            awaited = this.awaited(fallback);
+        }
+        if (awaited.flags & NOTHING)
+            return undefined;
+        if (isTypeParameter(awaited) && params.has(awaited) && this.unconstrained(awaited)) {
+            return { whole_decided: true, members: [], parse: [] };
+        }
+        const leaves = [];
+        this.leavesOf(awaited, params, 0, leaves);
+        const members = new Set();
+        for (const leaf of leaves) {
+            if (!(leaf.type.flags & (ts.TypeFlags.Object | ts.TypeFlags.Intersection)))
+                continue;
+            for (const property of this.checker.getPropertiesOfType(leaf.type)) {
+                const type = this.checker.getTypeOfSymbol(property);
+                if (this.checker.getNonNullableType(type).getCallSignatures().length > 0)
+                    continue;
+                if (this.mentions(type, leaf.params, 0, new Set()))
+                    members.add(property.getName());
+            }
+        }
+        const parse = new Set();
+        for (const holder of [raw, ...leaves.map(leaf => leaf.type)]) {
+            if (!(holder.flags & (ts.TypeFlags.Object | ts.TypeFlags.Intersection)))
+                continue;
+            for (const property of this.checker.getPropertiesOfType(holder)) {
+                const type = this.checker.getNonNullableType(this.checker.getTypeOfSymbol(property));
+                if (type.getCallSignatures().some(method => this.parses(method)))
+                    parse.add(property.getName());
+            }
+        }
+        return { whole_decided: false, members: [...members].sort(byCodeUnit), parse: [...parse].sort(byCodeUnit) };
+    }
+    /**
+     * `type` with a promise unwrapped. The checker spells an open parameter's
+     * awaited type `Awaited<T>`; that is read as `T`. A union and a conditional
+     * are left to `leavesOf`, which awaits each arm.
+     */
+    awaited(type, depth = 0) {
+        if (depth > MAX_DEPTH)
+            return type;
+        if (type.aliasSymbol?.getName() === 'Awaited' && type.aliasTypeArguments?.length === 1) {
+            return this.awaited(type.aliasTypeArguments[0], depth + 1);
+        }
+        if (type.flags & (ts.TypeFlags.TypeParameter | ts.TypeFlags.Union | ts.TypeFlags.Conditional))
+            return type;
+        const unwrapped = this.checker.getAwaitedType(type);
+        return unwrapped === undefined || unwrapped === type ? type : this.awaited(unwrapped, depth + 1);
+    }
+    unconstrained(parameter) {
+        const constraint = this.checker.getBaseConstraintOfType(parameter);
+        return constraint === undefined || (constraint.flags & OPEN) !== 0;
+    }
+    /**
+     * The branches of `type`: a union's parts without nullish ones, a
+     * conditional's two arms, each awaited. `params` are the type parameters a
+     * branch counts as carrying a value of: an arm of a generic alias is written
+     * in the alias's own parameters, so the alias parameters applied to
+     * something that mentions `params` join `params` for that arm.
+     */
+    leavesOf(type, params, depth, into) {
+        if (depth > MAX_DEPTH)
+            return;
+        const current = this.awaited(type);
+        if (current.flags & ts.TypeFlags.Union) {
+            for (const part of current.types) {
+                if (!(part.flags & NULLISH))
+                    this.leavesOf(part, params, depth + 1, into);
+            }
+            return;
+        }
+        if (current.flags & ts.TypeFlags.Conditional) {
+            const node = current.root.node;
+            const armParams = this.aliasParams(current, params);
+            for (const arm of [node.trueType, node.falseType]) {
+                this.leavesOf(this.checker.getTypeFromTypeNode(arm), armParams, depth + 1, into);
+            }
+            return;
+        }
+        if (current.flags & NOTHING)
+            return;
+        into.push({ type: current, params });
+    }
+    /**
+     * `params`, plus each type parameter of the alias `type` is an application
+     * of whose argument mentions one of `params`. The arms of a conditional
+     * written in an alias name those parameters, not the arguments.
+     */
+    aliasParams(type, params) {
+        const declaration = type.aliasSymbol?.declarations?.find(ts.isTypeAliasDeclaration);
+        const args = type.aliasTypeArguments;
+        if (declaration === undefined || args === undefined)
+            return params;
+        const joined = new Set(params);
+        (declaration.typeParameters ?? []).forEach((node, index) => {
+            if (index < args.length && this.mentions(args[index], params, 0, new Set())) {
+                joined.add(this.checker.getTypeAtLocation(node));
+            }
+        });
+        return joined;
+    }
+    /** A parse method: no required argument, and it returns a bare unconstrained parameter of its own. */
+    parses(method) {
+        const own = method.getTypeParameters() ?? [];
+        if (own.length === 0)
+            return false;
+        const required = method.getParameters().some(parameter => {
+            const declaration = parameter.valueDeclaration;
+            if (declaration === undefined || !ts.isParameter(declaration))
+                return true;
+            return declaration.questionToken === undefined && declaration.initializer === undefined && declaration.dotDotDotToken === undefined;
+        });
+        if (required)
+            return false;
+        const returned = this.awaited(this.checker.getReturnTypeOfSignature(method));
+        return isTypeParameter(returned) && own.includes(returned) && this.unconstrained(returned);
+    }
+    /** Whether `type` names one of `params` anywhere a value of it could be read through. */
+    mentions(type, params, depth, seen) {
+        if (params.has(type))
+            return true;
+        if (depth > MAX_DEPTH || seen.has(type))
+            return false;
+        seen.add(type);
+        const next = (part) => this.mentions(part, params, depth + 1, seen);
+        if (type.aliasTypeArguments?.some(next))
+            return true;
+        if (type.isUnionOrIntersection())
+            return type.types.some(next);
+        if (type.flags & ts.TypeFlags.IndexedAccess) {
+            const access = type;
+            return next(access.objectType) || next(access.indexType);
+        }
+        if (type.flags & ts.TypeFlags.Index)
+            return next(type.type);
+        if (type.flags & ts.TypeFlags.Conditional) {
+            const conditional = type;
+            return next(conditional.checkType) || next(conditional.extendsType);
+        }
+        if (!(type.flags & ts.TypeFlags.Object))
+            return false;
+        const object = type;
+        if (object.objectFlags & ts.ObjectFlags.Reference && this.checker.getTypeArguments(object).some(next)) {
+            return true;
+        }
+        if (this.checker.isArrayType(type) || this.checker.isTupleType(type))
+            return false;
+        return this.checker.getPropertiesOfType(type).some(property => next(this.checker.getTypeOfSymbol(property)));
+    }
+}

package/sidecar/dist/src/type-inferrer.d.ts

@@ -208,6 +208,18 @@ export declare class TypeInferrer {
      * Get or add a source file to the project
      */
     private getSourceFile;
+    /**
+     * carrick#2824: a located response expression that sits in ANOTHER route's
+     * handler is not this row's. A model can locate `response` at a line that
+     * belongs to the next registration in the same module; reading that node
+     * publishes the other route's reply. Returns the request with its locator
+     * dropped, so it is answered by the registration on its own line, when:
+     *  1. a registration R sits on the request's line;
+     *  2. the located node is outside R and outside R's handler;
+     *  3. some ancestor of the node is a registration whose handler contains it.
+     * Anything else is returned unchanged. Matches on node shape, no names.
+     */
+    private withoutForeignLocator;
     private inferFunctionReturn;
     /**
      * Build a `function_return` inferred type from an already-resolved function
@@ -446,6 +458,15 @@ export declare class TypeInferrer {
      * returns is a better statement of that body than the read (carrick#1382).
      */
     private receivingCallOf;
+    /**
+     * A call's result read through the library store's label (carrick#2818):
+     * `whole` is the awaited type, `member` is that member of every non-nullish
+     * constituent of it, and `parse` is the awaited return of that method as the
+     * call returns it (a thenable's own `json()` is not on what it resolves to).
+     * A part the type lacks is a decided abstain, so the capture's own re-read
+     * of the raw call does not publish the envelope in its place.
+     */
+    private labelledCallResult;
     private inferCallResult;
     /**
      * The terminal of a call's def-use walk is a zero-argument `.text()` read of
@@ -970,6 +991,12 @@ export declare class TypeInferrer {
      * arguments are what a rule naming `Task`, `Reply` or `Outcome` describes.
      */
     private wrapperReadings;
+    /**
+     * The type of `type`'s member `name` at `node`, or `undefined` when the type
+     * has no such member. The one property read the payload-property rules and
+     * the library store's result label (carrick#2818) share.
+     */
+    private readMemberType;
     /**
      * Extract the payload type from a matched wrapper. Returns null when the
      * rule matched the wrapper but no payload is recoverable from generics or