carrick 0.3.104 → 0.3.106

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

@@ -34,7 +34,7 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { collectSpecifiers, isRelative, packageNameOf } from './specifiers.js';
 import { repairDanglingImports } from './repair-dangling.js';
-import { findDisqualifyingTopTypes, provenanceOf, } from './deep-walk.js';
+import { findDisqualifyingTopTypes, findUnresolvedPlaceholders, isErrorPlaceholder, provenanceOf, unemittedModuleProvenance, unresolvedInTreeProvenance, } from './deep-walk.js';
 export function selfCheckStub(args) {
     const typesDir = path.join(args.stubDir, 'types');
     const treeFiles = [];
@@ -104,6 +104,7 @@ function runSelfCheck(args, treeFiles, repaired) {
     const emptyFailures = () => ({
         externalPinned: new Set(),
         internal: new Set(),
+        unfoundNames: new Set(),
     });
     const bucketIn = (map, key) => {
         let entry = map.get(key);
@@ -113,11 +114,24 @@ function runSelfCheck(args, treeFiles, repaired) {
         }
         return entry;
     };
+    // A surface diagnostic outside every alias statement (a file-level import,
+    // a reference directive) is attributable to no alias and keeps the
+    // service-wide file bucket: soundness over precision, the same fallback
+    // check-poison.ts makes.
+    const bucketFor = (abs, start) => {
+        const owner = abs === surfaceAbs ? aliasAtSurfacePosition(start) : undefined;
+        return owner ? bucketIn(surfaceFailuresByAlias, owner) : bucketIn(failuresByFile, abs);
+    };
     for (const d of diagnostics) {
         if (!d.file)
             continue;
         const abs = path.resolve(d.file.fileName);
         const msg = ts.flattenDiagnosticMessageText(d.messageText, ' ');
+        // A name the compiler cannot find is the placeholder's cause wherever a
+        // type uses it; the record names it beside those positions (carrick#1446).
+        const unfound = /Cannot find (?:name|namespace) '([^']+)'/.exec(msg);
+        if (unfound)
+            bucketFor(abs, d.start).unfoundNames.add(unfound[1]);
         // A name the repair did not reach: the import that bound it is gone, so
         // the module is no longer reported missing and only this diagnostic is
         // left to say the tree is incomplete. Blamed on the specifier that bound
@@ -133,14 +147,7 @@ function runSelfCheck(args, treeFiles, repaired) {
         if (!m)
             continue;
         const spec = m[1];
-        // A surface diagnostic outside every alias statement (a file-level import,
-        // a reference directive) is attributable to no alias and keeps the
-        // service-wide file bucket: soundness over precision, the same fallback
-        // check-poison.ts makes.
-        const owner = abs === surfaceAbs ? aliasAtSurfacePosition(d.start) : undefined;
-        const bucket = owner
-            ? bucketIn(surfaceFailuresByAlias, owner)
-            : bucketIn(failuresByFile, abs);
+        const bucket = bucketFor(abs, d.start);
         if (!isRelative(spec) && args.pinned[packageNameOf(spec)]) {
             bucket.externalPinned.add(spec);
         }
@@ -240,6 +247,13 @@ function buildSurfaceSpanIndex(surfaceSource) {
         return spans.find((span) => position >= span.start && position <= span.end)?.alias;
     };
 }
+/**
+ * carrick#1842: a literal anchor whose text is a body read as raw text passes
+ * that mark to its record, where the check phase reads it.
+ */
+function rawTextMark(request) {
+    return request.kind === 'literal' && request.raw_text_read ? { raw_text_read: true } : {};
+}
 /** An alias that never reached a capture-native tier: the failure reason was
  * recorded at demotion time; the surface line is `unknown` by construction. */
 function demotedRecord(anchor) {
@@ -254,12 +268,24 @@ function demotedRecord(anchor) {
         self_check_detail: anchor.failureReason,
         capture_failure_reason: anchor.failureReason,
         top_type_at_self_check: true,
+        // A literal's text is what the index serves for it, and a module it
+        // names never reached the tree (carrick#1446). A symbol anchor's served
+        // declaration comes from elsewhere, so its demotion says nothing about it.
+        ...(anchor.request.kind === 'literal' && anchor.namesUnemittedModule
+            ? { unresolved_in_tree: [unemittedModuleProvenance()] }
+            : {}),
+        ...rawTextMark(anchor.request),
     };
 }
 function checkedRecord(anchor, ctx) {
     const alias = anchor.request.alias;
     let topType = true;
     let deepFindings = [];
+    // Where the alias's type holds the unresolved-reference placeholder in this
+    // tree (carrick#1446): `''` for its own type. The deep walk leaves the
+    // placeholder out because the check heals a pinned external; what the index
+    // publishes is this tree, so the record says where it does not resolve.
+    let unresolvedPaths = [];
     const seeds = [];
     if (ctx.surfaceSource) {
         for (const stmt of ctx.surfaceSource.statements) {
@@ -270,6 +296,10 @@ function checkedRecord(anchor, ctx) {
                 (type.flags & (ts.TypeFlags.Any | ts.TypeFlags.Unknown | ts.TypeFlags.Never)) !== 0;
             if (!topType) {
                 deepFindings = findDisqualifyingTopTypes(type, ctx.program, ctx.checker, stmt.name);
+                unresolvedPaths = findUnresolvedPlaceholders(type, ctx.program, ctx.checker, stmt.name);
+            }
+            else if (isErrorPlaceholder(type)) {
+                unresolvedPaths = [''];
             }
             // Seed the closure with the alias's own import-type targets.
             const visit = (node) => {
@@ -300,6 +330,7 @@ function checkedRecord(anchor, ctx) {
     let blamedExternal;
     let internalFailure;
     const danglingSpecifiers = new Set();
+    const unfoundNames = new Set();
     // This alias's own surface statement, then the closure's files. The surface
     // file bucket now holds only the diagnostics no alias statement covers.
     const closureFailures = [
@@ -315,6 +346,8 @@ function checkedRecord(anchor, ctx) {
             internalFailure = [...failures.internal][0];
         for (const specifier of failures.internal)
             danglingSpecifiers.add(specifier);
+        for (const name of failures.unfoundNames)
+            unfoundNames.add(name);
     }
     // Classification consults the closure failures REGARDLESS of the root
     // type: a dangling internal specifier means part of this alias's closure
@@ -416,6 +449,14 @@ function checkedRecord(anchor, ctx) {
             ? { dangling_specifiers: [...danglingSpecifiers].sort() }
             : {}),
         ...(anchor.undeclaredNames ? { undeclared_names: anchor.undeclaredNames } : {}),
+        ...(unresolvedPaths.length > 0
+            ? {
+                unresolved_in_tree: [...unresolvedPaths]
+                    .sort()
+                    .map((p) => unresolvedInTreeProvenance(p, [...unfoundNames].sort())),
+            }
+            : {}),
+        ...rawTextMark(anchor.request),
     };
 }
 /** Resolve a relative specifier from `fromAbs` to a tree file, if present. */

package/sidecar/dist/src/capture/service-config.d.ts

@@ -17,3 +17,5 @@
  */
 /** Absolute path of the config that types the service, or undefined for none. */
 export declare function findServiceTsconfig(serviceRoot: string, scanRoot?: string): string | undefined;
+/** The path with every symlink resolved; the path as given when it does not exist. */
+export declare function realPath(p: string): string;

package/sidecar/dist/src/capture/service-config.js

@@ -47,7 +47,7 @@ export function findServiceTsconfig(serviceRoot, scanRoot) {
     return undefined;
 }
 /** The path with every symlink resolved; the path as given when it does not exist. */
-function realPath(p) {
+export function realPath(p) {
     try {
         return fs.realpathSync(p);
     }

package/sidecar/dist/src/failure-path.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Whether the source reaches a node only when an HTTP response FAILED
+ * (carrick#1796).
+ *
+ * A consumer reads the success body on one path and the error text or the
+ * error body on another. Only the first is the call's response contract, so
+ * the def-use walk behind a `call_result` row must not take a read from the
+ * second. Which path a read is on is told by the source's own tests of the
+ * response, read two ways:
+ *
+ *  - the read sits in a branch of a test: `if (!res.ok) { ... }`, the `else`
+ *    of `if (res.ok)`, either arm of a conditional expression;
+ *  - the read follows an `if` whose other branch cannot complete, so the rest
+ *    of the block runs only on the side that did not leave:
+ *    `if (res.ok) { return ... } const text = await res.text()`.
+ *
+ * A test is read as the set of statuses it lets through. `ok` is true for
+ * 200-299 and false for every other status; a comparison of the status with a
+ * number lets through what it admits; `!`, `&&` and `||` combine the sets, and
+ * any other condition lets everything through. A node is on the failure path
+ * only when NO status in 200-299 can reach it.
+ *
+ * The retype check (retype.ts) reads the same tests through `testsOnPath` and
+ * keeps its own policy on top: it also reads the false side of
+ * `res.status === 200` as the failure path, so it can find a success read to
+ * judge. Here a decided failure REMOVES a read, so the reading has to be sound
+ * the other way round: after `if (res.status === 204) return null`, 200 still
+ * gets through, and the json read that follows is the payload.
+ */
+import { Node } from 'ts-morph';
+/** A set of HTTP statuses, as the predicate that admits them. */
+export type Statuses = (status: number) => boolean;
+/** The statuses `ok` is true for. */
+export declare const SUCCEEDED: Statuses;
+/** The statuses from 100 to 599 that `statuses` admits, in order. */
+export declare function statusesIn(statuses: Statuses): number[];
+/** One test of the response on the path to a node, as the side the node is on. */
+export interface SideTaken {
+    /** Every status that can take this side, and maybe more (see `inexact`). */
+    admits: Statuses;
+    /**
+     * The test reads the response's `ok` or `status` in a form this reading
+     * cannot follow (`res.status === OK`, `codes.includes(res.status)`), or
+     * combines it with a condition that is not about the response
+     * (`res.ok && fresh`). `admits` then lets through more statuses than the
+     * side does: still sound for "no success status reaches the node", but no
+     * longer only the statuses the source singled out.
+     */
+    inexact: boolean;
+}
+/**
+ * True when the source reaches `node` only after the response named by
+ * `isResponse` failed. The walk climbs from `node` to `boundary` (the function
+ * the call sits in) and never looks at a test outside it.
+ */
+export declare function reachedOnlyOnFailure(node: Node, boundary: Node, isResponse: (node: Node) => boolean): boolean;
+/**
+ * Each test of the response on the path from `node` up to `boundary` (the
+ * whole file when it is `undefined`), as the side `node` is on: a branch of
+ * an `if` or a conditional expression it sits in, or an earlier `if` in an
+ * enclosing block one of whose branches cannot complete, which leaves the
+ * rest of the block to the other side. A test that does not read the
+ * response's `ok` or `status` is not listed.
+ */
+export declare function testsOnPath(node: Node, boundary: Node | undefined, isResponse: (node: Node) => boolean): SideTaken[];
+/** `node` reads the response's `ok` or `status`, itself or anywhere inside it. */
+export declare function readsResponseStatus(node: Node, isResponse: (node: Node) => boolean): boolean;

package/sidecar/dist/src/failure-path.js

@@ -0,0 +1,236 @@
+/**
+ * Whether the source reaches a node only when an HTTP response FAILED
+ * (carrick#1796).
+ *
+ * A consumer reads the success body on one path and the error text or the
+ * error body on another. Only the first is the call's response contract, so
+ * the def-use walk behind a `call_result` row must not take a read from the
+ * second. Which path a read is on is told by the source's own tests of the
+ * response, read two ways:
+ *
+ *  - the read sits in a branch of a test: `if (!res.ok) { ... }`, the `else`
+ *    of `if (res.ok)`, either arm of a conditional expression;
+ *  - the read follows an `if` whose other branch cannot complete, so the rest
+ *    of the block runs only on the side that did not leave:
+ *    `if (res.ok) { return ... } const text = await res.text()`.
+ *
+ * A test is read as the set of statuses it lets through. `ok` is true for
+ * 200-299 and false for every other status; a comparison of the status with a
+ * number lets through what it admits; `!`, `&&` and `||` combine the sets, and
+ * any other condition lets everything through. A node is on the failure path
+ * only when NO status in 200-299 can reach it.
+ *
+ * The retype check (retype.ts) reads the same tests through `testsOnPath` and
+ * keeps its own policy on top: it also reads the false side of
+ * `res.status === 200` as the failure path, so it can find a success read to
+ * judge. Here a decided failure REMOVES a read, so the reading has to be sound
+ * the other way round: after `if (res.status === 204) return null`, 200 still
+ * gets through, and the json read that follows is the payload.
+ */
+import { Node, SyntaxKind } from 'ts-morph';
+const FIRST_STATUS = 100;
+const LAST_STATUS = 599;
+const EVERY_STATUS = () => true;
+/** The statuses `ok` is true for. */
+export const SUCCEEDED = (status) => status >= 200 && status <= 299;
+/** The statuses from 100 to 599 that `statuses` admits, in order. */
+export function statusesIn(statuses) {
+    const admitted = [];
+    for (let status = FIRST_STATUS; status <= LAST_STATUS; status++) {
+        if (statuses(status))
+            admitted.push(status);
+    }
+    return admitted;
+}
+/** A condition that does not read the response's `ok` or `status`. */
+const UNRELATED = { whenTrue: EVERY_STATUS, whenFalse: EVERY_STATUS, inexact: false };
+/** A condition that reads the response's status in a form this reading cannot follow. */
+const UNREAD = { whenTrue: EVERY_STATUS, whenFalse: EVERY_STATUS, inexact: true };
+/**
+ * True when the source reaches `node` only after the response named by
+ * `isResponse` failed. The walk climbs from `node` to `boundary` (the function
+ * the call sits in) and never looks at a test outside it.
+ */
+export function reachedOnlyOnFailure(node, boundary, isResponse) {
+    const sides = testsOnPath(node, boundary, isResponse);
+    if (sides.length === 0)
+        return false;
+    const reaching = statusesIn((status) => sides.every((side) => side.admits(status)));
+    return reaching.length > 0 && !reaching.some(SUCCEEDED);
+}
+/**
+ * Each test of the response on the path from `node` up to `boundary` (the
+ * whole file when it is `undefined`), as the side `node` is on: a branch of
+ * an `if` or a conditional expression it sits in, or an earlier `if` in an
+ * enclosing block one of whose branches cannot complete, which leaves the
+ * rest of the block to the other side. A test that does not read the
+ * response's `ok` or `status` is not listed.
+ */
+export function testsOnPath(node, boundary, isResponse) {
+    const sides = [];
+    const take = (test, whenTrue) => {
+        if (test === UNRELATED)
+            return;
+        sides.push({ admits: whenTrue ? test.whenTrue : test.whenFalse, inexact: test.inexact });
+    };
+    for (let child = node, parent = node.getParent(); parent && parent !== boundary; child = parent, parent = parent.getParent()) {
+        if (Node.isIfStatement(parent)) {
+            if (child === parent.getThenStatement()) {
+                take(readTest(parent.getExpression(), isResponse), true);
+            }
+            else if (child === parent.getElseStatement()) {
+                take(readTest(parent.getExpression(), isResponse), false);
+            }
+        }
+        else if (Node.isConditionalExpression(parent)) {
+            if (child === parent.getWhenTrue()) {
+                take(readTest(parent.getCondition(), isResponse), true);
+            }
+            else if (child === parent.getWhenFalse()) {
+                take(readTest(parent.getCondition(), isResponse), false);
+            }
+        }
+        if (Node.isBlock(parent) ||
+            Node.isSourceFile(parent) ||
+            Node.isCaseClause(parent) ||
+            Node.isDefaultClause(parent)) {
+            for (const statement of parent.getStatements()) {
+                if (statement === child)
+                    break;
+                if (!Node.isIfStatement(statement))
+                    continue;
+                const otherwise = statement.getElseStatement();
+                const thenLeaves = cannotComplete(statement.getThenStatement());
+                const elseLeaves = otherwise !== undefined && cannotComplete(otherwise);
+                if (thenLeaves && !elseLeaves) {
+                    take(readTest(statement.getExpression(), isResponse), false);
+                }
+                else if (elseLeaves && !thenLeaves) {
+                    take(readTest(statement.getExpression(), isResponse), true);
+                }
+            }
+        }
+    }
+    return sides;
+}
+/** The statuses `condition` lets through when it is true and when it is false. */
+function readTest(condition, isResponse) {
+    let test = condition;
+    while (Node.isParenthesizedExpression(test))
+        test = test.getExpression();
+    if (Node.isPrefixUnaryExpression(test) &&
+        test.getOperatorToken() === SyntaxKind.ExclamationToken) {
+        const inner = readTest(test.getOperand(), isResponse);
+        if (inner === UNRELATED || inner === UNREAD)
+            return inner;
+        return { whenTrue: inner.whenFalse, whenFalse: inner.whenTrue, inexact: inner.inexact };
+    }
+    if (isMemberOfResponse(test, 'ok', isResponse)) {
+        return { whenTrue: SUCCEEDED, whenFalse: (status) => !SUCCEEDED(status), inexact: false };
+    }
+    if (Node.isBinaryExpression(test)) {
+        const operator = test.getOperatorToken().getKind();
+        if (operator === SyntaxKind.AmpersandAmpersandToken ||
+            operator === SyntaxKind.BarBarToken) {
+            const left = readTest(test.getLeft(), isResponse);
+            const right = readTest(test.getRight(), isResponse);
+            if (left === UNRELATED && right === UNRELATED)
+                return UNRELATED;
+            const inexact = left.inexact || right.inexact || left === UNRELATED || right === UNRELATED;
+            return operator === SyntaxKind.AmpersandAmpersandToken
+                ? {
+                    whenTrue: (status) => left.whenTrue(status) && right.whenTrue(status),
+                    whenFalse: (status) => left.whenFalse(status) || right.whenFalse(status),
+                    inexact,
+                }
+                : {
+                    whenTrue: (status) => left.whenTrue(status) || right.whenTrue(status),
+                    whenFalse: (status) => left.whenFalse(status) && right.whenFalse(status),
+                    inexact,
+                };
+        }
+        const compared = statusComparison(test.getLeft(), operator, test.getRight(), isResponse);
+        if (compared) {
+            return { whenTrue: compared, whenFalse: (status) => !compared(status), inexact: false };
+        }
+    }
+    return readsResponseStatus(test, isResponse) ? UNREAD : UNRELATED;
+}
+/**
+ * `res.status <op> N` or `N <op> res.status`, as the statuses it is true for;
+ * `undefined` when the comparison is not one of the response's status with a
+ * number.
+ */
+function statusComparison(left, operator, right, isResponse) {
+    let op = operator;
+    let value;
+    if (isMemberOfResponse(left, 'status', isResponse) && Node.isNumericLiteral(right)) {
+        value = right.getLiteralValue();
+    }
+    else if (isMemberOfResponse(right, 'status', isResponse) && Node.isNumericLiteral(left)) {
+        value = left.getLiteralValue();
+        op = MIRRORED[op] ?? op;
+    }
+    else {
+        return undefined;
+    }
+    switch (op) {
+        case SyntaxKind.EqualsEqualsEqualsToken:
+        case SyntaxKind.EqualsEqualsToken:
+            return (status) => status === value;
+        case SyntaxKind.ExclamationEqualsEqualsToken:
+        case SyntaxKind.ExclamationEqualsToken:
+            return (status) => status !== value;
+        case SyntaxKind.LessThanToken:
+            return (status) => status < value;
+        case SyntaxKind.LessThanEqualsToken:
+            return (status) => status <= value;
+        case SyntaxKind.GreaterThanToken:
+            return (status) => status > value;
+        case SyntaxKind.GreaterThanEqualsToken:
+            return (status) => status >= value;
+        default:
+            return undefined;
+    }
+}
+/** `400 <= res.status` reads as `res.status >= 400`. */
+const MIRRORED = {
+    [SyntaxKind.LessThanToken]: SyntaxKind.GreaterThanToken,
+    [SyntaxKind.LessThanEqualsToken]: SyntaxKind.GreaterThanEqualsToken,
+    [SyntaxKind.GreaterThanToken]: SyntaxKind.LessThanToken,
+    [SyntaxKind.GreaterThanEqualsToken]: SyntaxKind.LessThanEqualsToken,
+};
+function isMemberOfResponse(node, name, isResponse) {
+    return (Node.isPropertyAccessExpression(node) &&
+        node.getName() === name &&
+        isResponse(node.getExpression()));
+}
+/** `node` reads the response's `ok` or `status`, itself or anywhere inside it. */
+export function readsResponseStatus(node, isResponse) {
+    return [node, ...node.getDescendantsOfKind(SyntaxKind.PropertyAccessExpression)].some((inner) => isMemberOfResponse(inner, 'ok', isResponse) ||
+        isMemberOfResponse(inner, 'status', isResponse));
+}
+/**
+ * A statement that never runs on into the statement after it: it returns,
+ * throws, breaks or continues, or every path through it does. A loop, a
+ * `switch` or a `try` is read as one that can complete, which only ever
+ * leaves a read on the path it was on.
+ */
+function cannotComplete(statement) {
+    if (Node.isReturnStatement(statement) ||
+        Node.isThrowStatement(statement) ||
+        Node.isBreakStatement(statement) ||
+        Node.isContinueStatement(statement)) {
+        return true;
+    }
+    if (Node.isBlock(statement)) {
+        return statement.getStatements().some((inner) => cannotComplete(inner));
+    }
+    if (Node.isIfStatement(statement)) {
+        const otherwise = statement.getElseStatement();
+        return (otherwise !== undefined &&
+            cannotComplete(statement.getThenStatement()) &&
+            cannotComplete(otherwise));
+    }
+    return false;
+}

package/sidecar/dist/src/printed-names.d.ts

@@ -0,0 +1,43 @@
+/**
+ * carrick#1836: what each bare name in an inference's printed text meant.
+ *
+ * The structural printer (`type-structural-expander.ts`) hands some subtrees
+ * back to the compiler's own print with no enclosing declaration, and that
+ * print writes every named type by its bare name: a database client's row,
+ * which is a library's mapped type, prints `{ status: EntityStatus; ... }`.
+ * The file a request names often never imports `EntityStatus`, so the text
+ * names nothing where it is read (TS2304), and the member reads `any` in the
+ * capture's surface.
+ *
+ * The compiler knew the symbol when it printed the name, and only then. So
+ * every type print made while an inference runs is noted (`notePrintedType`),
+ * and when it ends (`PrintedTypes.namesIn`) the names its text prints that the
+ * request's file cannot resolve are looked up in those prints: the node
+ * builder gives each name it writes the symbol it wrote it for. Each such
+ * symbol is recorded as the module that declares it and its export path
+ * there. A name printed for two declarations is recorded twice, and the
+ * reader of the record decides what an ambiguous name means.
+ *
+ * Only the prints whose text writes such a name are read back, and only when
+ * the inference's text has one, so an inference whose names all resolve costs
+ * no more than keeping the list.
+ */
+import { ts, type Node, type Type } from 'ts-morph';
+import type { PrintedName } from './types.js';
+/**
+ * Note a type the compiler printed as `text`, so the inference running now can
+ * tell what the names in that print meant. Does nothing outside a recording.
+ */
+export declare function notePrintedType(type: Type, enclosing: Node | undefined, text: string): void;
+/** The type prints one inference made. */
+export declare class PrintedTypes {
+    private readonly prints;
+    /** Run `read`, noting every type it prints. */
+    during<T>(read: () => T): T;
+    /**
+     * The declarations behind each name `texts` print that `source` does not
+     * resolve, sorted, one entry per distinct declaration. `checker` must be
+     * the one the prints were made with: call this before the program changes.
+     */
+    namesIn(texts: readonly string[], source: ts.SourceFile, checker: ts.TypeChecker): PrintedName[];
+}