carrick 0.3.104 → 0.3.105

package/sidecar/dist/src/capture/deep-walk.js

@@ -14,6 +14,7 @@
  * wherever it is reported.
  */
 import ts from 'typescript';
+import { memberPath } from './member-name.js';
 /** Cap on findings reported per alias. The FIRST one is what the check phase
  * pre-gates on, so verdicts never depend on this number; the rest are there to
  * tell a reader which fields are `any` (carrick#376), and a type with more
@@ -73,7 +74,7 @@ export function findUnresolvedPlaceholders(root, program, checker, location) {
 }
 /** TypeScript's unresolved-reference placeholder: `TypeFlags.Any` with the
  * internal `intrinsicName === 'error'` (stable since TS 1.x; see `anchors.ts`). */
-function isErrorPlaceholder(t) {
+export function isErrorPlaceholder(t) {
     return ((t.flags & ts.TypeFlags.Any) !== 0 &&
         t.intrinsicName === 'error');
 }
@@ -230,7 +231,7 @@ function walkTopTypes(root, program, checker, location, flagOf) {
                 continue;
             }
             const propType = checker.getTypeOfSymbolAtLocation(prop, location);
-            walk(propType, path === '' ? prop.getName() : `${path}.${prop.getName()}`, depth + 1);
+            walk(propType, memberPath(path, prop, checker), depth + 1);
             if (exhausted)
                 return;
         }
@@ -276,8 +277,8 @@ function disqualifyingFlag(t) {
     }
     return t.flags & ts.TypeFlags.Unknown ? 'unknown' : undefined;
 }
-/** How many unresolved specifiers a detail names before it counts the rest. */
-const MAX_NAMED_SPECIFIERS = 3;
+/** How many specifiers or names a detail lists before it counts the rest. */
+const MAX_NAMED_IN_DETAIL = 3;
 /**
  * Turn a deep finding into the published provenance entry (carrick#376).
  *
@@ -321,12 +322,51 @@ function unresolvedDetail(specifiers) {
     const lead = "the type at this position did not resolve on the scanned checkout, so the compiler printed a placeholder 'any' rather than a declared type";
     if (specifiers.length === 0)
         return lead;
-    const named = specifiers
-        .slice(0, MAX_NAMED_SPECIFIERS)
-        .map((specifier) => `'${specifier}'`)
+    return `${lead}; unresolved imports reachable from the anchor: ${quotedList(specifiers)}`;
+}
+/**
+ * The entry for one position at which the emitted tree holds the
+ * unresolved-reference placeholder (carrick#1446): `path` is `''` for the
+ * alias's own type. `names` are the identifiers the self-check could not find
+ * in this alias's statement and the files it reaches.
+ *
+ * The cause is `unresolved_import`, the word a reader already has for "a
+ * reference here did not resolve"; the detail says where it failed to.
+ */
+export function unresolvedInTreeProvenance(path, names) {
+    const where = path === '' ? 'this type' : 'the type at this position';
+    const lead = `${where} does not resolve in the declarations the capture emitted, so the ` +
+        "compiler reads it as 'any' although the printed text shows the name it could not follow";
+    return {
+        path,
+        kind: 'any',
+        reason: 'unresolved_import',
+        detail: names.length === 0
+            ? lead
+            : `${lead}; names those declarations cannot find: ${quotedList(names)}`,
+    };
+}
+/**
+ * The root entry for a literal anchor demoted because its text names a module
+ * whose declaration emit was skipped (carrick#1446, carrick#1165): that text is
+ * what the index serves for it, and nothing in the emitted tree declares what
+ * it imports.
+ */
+export function unemittedModuleProvenance() {
+    return {
+        path: '',
+        kind: 'any',
+        reason: 'unresolved_import',
+        detail: 'this type names a module whose declarations the capture could not emit, so it ' +
+            "does not resolve in the declarations the capture emitted and the compiler reads it as 'any'",
+    };
+}
+/** `'a', 'b', 'c' and 2 more`. */
+function quotedList(items) {
+    const named = items
+        .slice(0, MAX_NAMED_IN_DETAIL)
+        .map((item) => `'${item}'`)
         .join(', ');
-    const more = specifiers.length > MAX_NAMED_SPECIFIERS
-        ? ` and ${specifiers.length - MAX_NAMED_SPECIFIERS} more`
-        : '';
-    return `${lead}; unresolved imports reachable from the anchor: ${named}${more}`;
+    const more = items.length > MAX_NAMED_IN_DETAIL ? ` and ${items.length - MAX_NAMED_IN_DETAIL} more` : '';
+    return `${named}${more}`;
 }

package/sidecar/dist/src/capture/guarded-fs.d.ts

@@ -42,7 +42,11 @@ export declare class WriteGuard {
     private readonly files;
     private readonly protect;
     private constructor();
-    /** A guard over `roots`. Throws when a root equals or contains a protected tree. */
+    /**
+     * A guard over `roots`. Throws when a root equals or contains a protected
+     * tree, or when a directory root lies inside one anywhere but beneath a
+     * `.carrick` directory (carrick#1768).
+     */
     static of(roots: WriteRoots): WriteGuard;
     /**
      * A new, empty directory under `parent` (the OS temp dir by default) and a

package/sidecar/dist/src/capture/guarded-fs.js

@@ -40,7 +40,11 @@ export class WriteGuard {
         this.files = files;
         this.protect = protect;
     }
-    /** A guard over `roots`. Throws when a root equals or contains a protected tree. */
+    /**
+     * A guard over `roots`. Throws when a root equals or contains a protected
+     * tree, or when a directory root lies inside one anywhere but beneath a
+     * `.carrick` directory (carrick#1768).
+     */
     static of(roots) {
         const protect = (roots.protect ?? []).map(landing);
         const dirs = (roots.dirs ?? []).map(landing);
@@ -51,6 +55,16 @@ export class WriteGuard {
                 throw new WriteRefused(`refused write root ${root}: it is or contains the scanned tree ${covered}`);
             }
         }
+        // Inside a scanned tree, a directory root is Carrick's only beneath a
+        // `.carrick` directory. Anywhere else it is the repo's own (a sibling
+        // service, say), and a stub dir is emptied before it is written. A file
+        // root is exempt: the surface entry has to sit inside rootDir.
+        for (const root of dirs) {
+            const inside = protect.find((tree) => within(tree, root) && !carrickOwned(tree, root));
+            if (inside !== undefined) {
+                throw new WriteRefused(`refused write root ${root}: it lies inside the scanned tree ${inside}, outside a .carrick directory`);
+            }
+        }
         return new WriteGuard(dirs, files, protect);
     }
     /**
@@ -133,6 +147,14 @@ function within(root, p) {
     const rel = path.relative(root, p);
     return rel === '' || (rel !== '..' && !rel.startsWith(`..${path.sep}`) && !path.isAbsolute(rel));
 }
+/**
+ * Whether `root`, inside `tree`, lies beneath a `.carrick` directory between
+ * the two. `.carrick` itself is not enough: it holds the workspace's proposal,
+ * jobs and scan logs. Both are resolved paths.
+ */
+function carrickOwned(tree, root) {
+    return path.relative(tree, root).split(path.sep).slice(0, -1).includes('.carrick');
+}
 function isDirectory(p) {
     try {
         return fs.statSync(p).isDirectory();

package/sidecar/dist/src/capture/index.js

@@ -145,10 +145,13 @@ export function captureStub(opts) {
     // Everything this capture writes, it writes through `guard` (carrick#1748):
     // the stub dir, the staging dir, and the surface entry. A stub dir is
     // emptied before it is written, so one that is or holds the repo is refused
-    // before anything is touched.
+    // before anything is touched. The scan root is protected too: a stub dir
+    // in a sibling service of the same repo is refused unless it sits beneath
+    // a `.carrick` directory (carrick#1768).
     let guard;
     try {
-        guard = WriteGuard.of({ dirs: [stubDir], protect: [repoRoot] });
+        const protect = opts.scanRoot === undefined ? [repoRoot] : [repoRoot, path.resolve(opts.scanRoot)];
+        guard = WriteGuard.of({ dirs: [stubDir], protect });
     }
     catch (err) {
         return fail(stubDir, packageName, [err instanceof Error ? err.message : String(err)]);
@@ -563,6 +566,7 @@ function demoteDanglingAliases(args) {
             serialization: 'structural_fallback',
             failureReason: `declaration emit was skipped for module '${dangling}'; ` +
                 'alias demoted to keep the partially emitted tree usable',
+            namesUnemittedModule: true,
         };
     });
     if (surfaceKey !== undefined && demoted.size > 0) {

package/sidecar/dist/src/capture/member-name.d.ts

@@ -0,0 +1,20 @@
+/**
+ * A member's place in a path, written the same way on every scan
+ * (carrick#1766).
+ *
+ * A member keyed by a unique symbol (`[Symbol.iterator]`, or a user's
+ * `const KEY: unique symbol`) has no name of its own. The checker escapes it as
+ * `__@<description>@<symbol id>`, and the id counts the symbols the process
+ * made before this one, so it differs between two scans of one tree and a
+ * stored sentence naming it changed on every scan. The checker prints such a
+ * member from its key instead, `[Symbol.iterator]`, which is how the source
+ * writes it.
+ *
+ * Every other member keeps `getName()`. A string key that starts with `__` is
+ * escaped with one more underscore, so it never reads as symbol-keyed here, and
+ * `symbolToString` would quote a key such as `content-type`, changing text that
+ * is already stable.
+ */
+import ts from 'typescript';
+/** `parent.name`, or `parent[KEY]` for a member keyed by a unique symbol. */
+export declare function memberPath(parent: string, member: ts.Symbol, checker: ts.TypeChecker): string;

package/sidecar/dist/src/capture/member-name.js

@@ -0,0 +1,24 @@
+/**
+ * A member's place in a path, written the same way on every scan
+ * (carrick#1766).
+ *
+ * A member keyed by a unique symbol (`[Symbol.iterator]`, or a user's
+ * `const KEY: unique symbol`) has no name of its own. The checker escapes it as
+ * `__@<description>@<symbol id>`, and the id counts the symbols the process
+ * made before this one, so it differs between two scans of one tree and a
+ * stored sentence naming it changed on every scan. The checker prints such a
+ * member from its key instead, `[Symbol.iterator]`, which is how the source
+ * writes it.
+ *
+ * Every other member keeps `getName()`. A string key that starts with `__` is
+ * escaped with one more underscore, so it never reads as symbol-keyed here, and
+ * `symbolToString` would quote a key such as `content-type`, changing text that
+ * is already stable.
+ */
+/** `parent.name`, or `parent[KEY]` for a member keyed by a unique symbol. */
+export function memberPath(parent, member, checker) {
+    if (!member.escapedName.startsWith('__@')) {
+        return parent === '' ? member.getName() : `${parent}.${member.getName()}`;
+    }
+    return `${parent}${checker.symbolToString(member)}`;
+}

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);
         }
@@ -254,12 +261,23 @@ 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()] }
+            : {}),
     };
 }
 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 +288,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 +322,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 +338,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 +441,13 @@ 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())),
+            }
+            : {}),
     };
 }
 /** Resolve a relative specifier from `fromAbs` to a tree file, if present. */

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

@@ -0,0 +1,36 @@
+/**
+ * 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.
+ *
+ * That is deliberately stricter than the retype check's reading of a status
+ * test (`okWhenTrue` in retype.ts), which 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';
+/**
+ * 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;

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

@@ -0,0 +1,212 @@
+/**
+ * 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.
+ *
+ * That is deliberately stricter than the retype check's reading of a status
+ * test (`okWhenTrue` in retype.ts), which 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. */
+const SUCCEEDED = (status) => status >= 200 && status <= 299;
+const UNDECIDED = { whenTrue: EVERY_STATUS, whenFalse: EVERY_STATUS };
+/**
+ * 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) {
+    let admitted = EVERY_STATUS;
+    let narrowed = false;
+    const narrow = (by) => {
+        if (by === EVERY_STATUS)
+            return;
+        const before = admitted;
+        admitted = (status) => before(status) && by(status);
+        narrowed = true;
+    };
+    for (let child = node, parent = node.getParent(); parent && parent !== boundary; child = parent, parent = parent.getParent()) {
+        if (Node.isIfStatement(parent)) {
+            if (child === parent.getThenStatement()) {
+                narrow(readTest(parent.getExpression(), isResponse).whenTrue);
+            }
+            else if (child === parent.getElseStatement()) {
+                narrow(readTest(parent.getExpression(), isResponse).whenFalse);
+            }
+        }
+        else if (Node.isConditionalExpression(parent)) {
+            if (child === parent.getWhenTrue()) {
+                narrow(readTest(parent.getCondition(), isResponse).whenTrue);
+            }
+            else if (child === parent.getWhenFalse()) {
+                narrow(readTest(parent.getCondition(), isResponse).whenFalse);
+            }
+        }
+        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) {
+                    narrow(readTest(statement.getExpression(), isResponse).whenFalse);
+                }
+                else if (elseLeaves && !thenLeaves) {
+                    narrow(readTest(statement.getExpression(), isResponse).whenTrue);
+                }
+            }
+        }
+    }
+    if (!narrowed)
+        return false;
+    let reachable = false;
+    for (let status = FIRST_STATUS; status <= LAST_STATUS; status++) {
+        if (!admitted(status))
+            continue;
+        if (SUCCEEDED(status))
+            return false;
+        reachable = true;
+    }
+    return reachable;
+}
+/** 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);
+        return { whenTrue: inner.whenFalse, whenFalse: inner.whenTrue };
+    }
+    if (isMemberOfResponse(test, 'ok', isResponse)) {
+        return { whenTrue: SUCCEEDED, whenFalse: (status) => !SUCCEEDED(status) };
+    }
+    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 === UNDECIDED && right === UNDECIDED)
+                return UNDECIDED;
+            return operator === SyntaxKind.AmpersandAmpersandToken
+                ? {
+                    whenTrue: (status) => left.whenTrue(status) && right.whenTrue(status),
+                    whenFalse: (status) => left.whenFalse(status) || right.whenFalse(status),
+                }
+                : {
+                    whenTrue: (status) => left.whenTrue(status) || right.whenTrue(status),
+                    whenFalse: (status) => left.whenFalse(status) && right.whenFalse(status),
+                };
+        }
+        const compared = statusComparison(test.getLeft(), operator, test.getRight(), isResponse);
+        if (compared) {
+            return { whenTrue: compared, whenFalse: (status) => !compared(status) };
+        }
+    }
+    return UNDECIDED;
+}
+/**
+ * `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()));
+}
+/**
+ * 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/retype.js

@@ -735,11 +735,23 @@ function branchSide(condition, whenTrue, isResponse) {
         return ok;
     return ok === whenTrue ? 'success' : 'failure';
 }
+/**
+ * The success statuses whose response carries no content (RFC 9110: 204 No
+ * Content, 205 Reset Content).
+ */
+const NO_CONTENT_STATUSES = new Set([204, 205]);
 /**
  * Whether `condition` being true means the response succeeded: `res.ok`,
  * `res.status === 200`, `res.status !== 200`, `res.status >= 400` and their
  * negations. Any other test of the response is `'unclear'`; a condition that does not
  * test the response is `undefined`.
+ *
+ * An equality or inequality with a no-content status is `undefined` too
+ * (carrick#1813). The retype only runs against a producer that publishes a
+ * response body, and that body never arrives with a 204 or 205, so
+ * `if (res.status === 204) return null` only takes away a status the body
+ * cannot come with. The read after it sits where a read no test decides
+ * sits, not on the error path.
  */
 function okWhenTrue(condition, isResponse) {
     let e = condition;
@@ -759,13 +771,14 @@ function okWhenTrue(condition, isResponse) {
             : undefined;
         if (value !== undefined) {
             const success = value >= 200 && value < 300;
+            const noContent = NO_CONTENT_STATUSES.has(value);
             switch (op) {
                 case SyntaxKind.EqualsEqualsEqualsToken:
                 case SyntaxKind.EqualsEqualsToken:
-                    return success;
+                    return noContent ? undefined : success;
                 case SyntaxKind.ExclamationEqualsEqualsToken:
                 case SyntaxKind.ExclamationEqualsToken:
-                    return !success;
+                    return noContent ? undefined : !success;
                 case SyntaxKind.GreaterThanEqualsToken:
                     if (value >= 300)
                         return false;

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

@@ -434,6 +434,8 @@ export declare class TypeInferrer {
     private bodyReadOnReceiver;
     private collectDefUseNodes;
     private expressionUsesNames;
+    /** `expr` is a use of a tracked name, or contains one. */
+    private usesTrackedNames;
     private isIdentifierUsage;
     private isInFunctionScope;
     /**