carrick 0.3.103 → 0.3.105

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/index.js

@@ -125,6 +125,7 @@ function handleInit(request) {
         projectLoader = new ProjectLoader({
             repoRoot: request.repo_root,
             tsconfigPath: request.tsconfig_path,
+            scanRoot: request.scan_root,
             tsconfigSnapshot: request.tsconfig_snapshot,
             pinnedDependencies: request.pinned_dependencies,
         });
@@ -213,6 +214,7 @@ function handleCaptureV2(request) {
             anchors: request.anchors,
             outDir: request.out_dir,
             tsconfigPath: request.tsconfig_path,
+            scanRoot: request.scan_root,
         });
         return {
             request_id: request.request_id,

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

@@ -19,6 +19,12 @@ export interface ProjectLoaderOptions {
     repoRoot: string;
     /** Optional path to tsconfig.json (relative to repo root or absolute) */
     tsconfigPath?: string;
+    /**
+     * The scanned repo's root, the upper bound of the search for a tsconfig
+     * above `repoRoot` when none is named (carrick#1776). Without it only
+     * `repoRoot` is searched.
+     */
+    scanRoot?: string;
     /** Optional tsconfig snapshot (closed/merged) - preferred over tsconfigPath */
     tsconfigSnapshot?: TsconfigSnapshot;
     /** Optional pinned dependencies for this repo */
@@ -69,6 +75,7 @@ export declare class ProjectLoader {
     private readonly ownerProjects;
     private readonly repoRoot;
     private readonly tsconfigPath;
+    private readonly scanRoot;
     private readonly tsconfigSnapshot;
     private readonly pinnedDependencies;
     private initialized;
@@ -140,9 +147,10 @@ export declare class ProjectLoader {
      */
     getPinnedDependencies(): PinnedDependencySnapshot | undefined;
     /**
-     * Find the tsconfig.json file to use
+     * The tsconfig to build from: the named one when it exists, else the one
+     * `findServiceTsconfig` finds for the service, which capture also reads.
      *
-     * @returns Absolute path to tsconfig.json, or undefined if not found
+     * @returns Absolute path to the tsconfig, or undefined if not found
      */
     private findTsConfig;
     /**

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

@@ -12,7 +12,7 @@
 import { Project } from 'ts-morph';
 import * as path from 'node:path';
 import * as fs from 'node:fs';
-import { DenoProject, findDenoConfig, serviceConfigPath } from './capture/index.js';
+import { DenoProject, findDenoConfig, findServiceTsconfig, serviceConfigPath } from './capture/index.js';
 import { moduleFormatResolutionHost } from './module-format.js';
 import { ExternalImports, registerExternalImports } from './origin.js';
 /**
@@ -125,6 +125,7 @@ export class ProjectLoader {
     ownerProjects = new Map();
     repoRoot;
     tsconfigPath;
+    scanRoot;
     tsconfigSnapshot;
     pinnedDependencies;
     initialized = false;
@@ -141,6 +142,7 @@ export class ProjectLoader {
                 ? options.tsconfigPath
                 : path.resolve(this.repoRoot, options.tsconfigPath);
         }
+        this.scanRoot = options.scanRoot;
         // Store snapshot if provided
         this.tsconfigSnapshot = options.tsconfigSnapshot;
         this.pinnedDependencies = options.pinnedDependencies;
@@ -422,30 +424,19 @@ export class ProjectLoader {
         return this.pinnedDependencies;
     }
     /**
-     * Find the tsconfig.json file to use
+     * The tsconfig to build from: the named one when it exists, else the one
+     * `findServiceTsconfig` finds for the service, which capture also reads.
      *
-     * @returns Absolute path to tsconfig.json, or undefined if not found
+     * @returns Absolute path to the tsconfig, or undefined if not found
      */
     findTsConfig() {
-        // If a specific path was provided, try to use it
         if (this.tsconfigPath) {
             if (fs.existsSync(this.tsconfigPath)) {
                 return this.tsconfigPath;
             }
             this.log(`Specified tsconfig not found: ${this.tsconfigPath}`);
         }
-        // Try common tsconfig locations
-        const candidates = [
-            path.join(this.repoRoot, 'tsconfig.json'),
-            path.join(this.repoRoot, 'tsconfig.build.json'),
-            path.join(this.repoRoot, 'tsconfig.app.json'),
-        ];
-        for (const candidate of candidates) {
-            if (fs.existsSync(candidate)) {
-                return candidate;
-            }
-        }
-        return undefined;
+        return findServiceTsconfig(this.repoRoot, this.scanRoot);
     }
     /**
      * Add source files from common project locations when no tsconfig is found.

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;
     /**

package/sidecar/dist/src/type-inferrer.js

@@ -21,6 +21,7 @@ import * as path from 'node:path';
 import { Node, SyntaxKind, ts, } from 'ts-morph';
 import { validateInferRequestItem } from './validators.js';
 import { externalImportsOf, isExternalOrigin } from './origin.js';
+import { reachedOnlyOnFailure } from './failure-path.js';
 import { addedDiagnostics, applyInsertions, fileDiagnostics, literalInsertions, mapBack, mapForward, normalise, pathOf, } from './unwidened.js';
 import { expandTypeStructural, } from './type-structural-expander.js';
 /**
@@ -1813,6 +1814,16 @@ export class TypeInferrer {
             for (const expr of candidates) {
                 if (expr.getStart() <= startPos)
                     continue;
+                // carrick#1796: what the source does with the response once it has
+                // FAILED describes the failure, not the payload. `if (res.ok) {
+                // return ... } const errorText = await res.text()` published the error
+                // text as the response contract because the walk keeps the LAST whole
+                // read, and the failure path's read comes after the success path's
+                // return. A read there is neither the payload nor a part of it.
+                if (this.usesTrackedNames(expr, currentNames) &&
+                    reachedOnlyOnFailure(expr, func, (node) => this.isIdentifierUsage(node, currentNames))) {
+                    continue;
+                }
                 // carrick#1017: a comparison is `boolean` by construction, so it is
                 // never the payload a call yields. `const res = await fetch(url); if
                 // (res.status === 404) return null; return await res.json() as Entry`
@@ -2361,6 +2372,12 @@ export class TypeInferrer {
         const identifiers = expr.getDescendantsOfKind(SyntaxKind.Identifier);
         return identifiers.some((id) => this.isIdentifierUsage(id, names));
     }
+    /** `expr` is a use of a tracked name, or contains one. */
+    usesTrackedNames(expr, names) {
+        return Node.isIdentifier(expr)
+            ? this.isIdentifierUsage(expr, names)
+            : this.expressionUsesNames(expr, names);
+    }
     isIdentifierUsage(id, names) {
         if (!Node.isIdentifier(id)) {
             return false;

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

@@ -110,6 +110,12 @@ export interface InitRequest extends BaseRequest {
     action: 'init';
     repo_root: string;
     tsconfig_path?: string;
+    /**
+     * The scanned repo's root: with no tsconfig named or in `repo_root`, the
+     * nearest `tsconfig.json` above `repo_root` up to this root types the
+     * service (carrick#1776). Without it only `repo_root` is searched.
+     */
+    scan_root?: string;
     /** Optional tsconfig snapshot (closed/merged) - preferred over tsconfig_path */
     tsconfig_snapshot?: TsconfigSnapshot;
     /** Optional pinned dependencies for this repo */
@@ -141,6 +147,8 @@ export interface CaptureV2Request extends BaseRequest {
     out_dir: string;
     /** Optional explicit tsconfig path (defaults to <repo_root>/tsconfig.json) */
     tsconfig_path?: string;
+    /** The scanned repo's root, as on `init` (carrick#1776). */
+    scan_root?: string;
 }
 /**
  * Response for the capture_v2 action

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

@@ -69,6 +69,7 @@ export declare const InitRequestSchema: z.ZodObject<{
     action: z.ZodLiteral<"init">;
     repo_root: z.ZodString;
     tsconfig_path: z.ZodOptional<z.ZodString>;
+    scan_root: z.ZodOptional<z.ZodString>;
     tsconfig_snapshot: z.ZodOptional<z.ZodObject<{
         compilerOptions: z.ZodObject<{
             module: z.ZodOptional<z.ZodString>;
@@ -161,6 +162,7 @@ export declare const InitRequestSchema: z.ZodObject<{
     action: "init";
     repo_root: string;
     tsconfig_path?: string | undefined;
+    scan_root?: string | undefined;
     tsconfig_snapshot?: {
         compilerOptions: {
             module?: string | undefined;
@@ -187,6 +189,7 @@ export declare const InitRequestSchema: z.ZodObject<{
     action: "init";
     repo_root: string;
     tsconfig_path?: string | undefined;
+    scan_root?: string | undefined;
     tsconfig_snapshot?: {
         compilerOptions: {
             module?: string | undefined;
@@ -344,6 +347,7 @@ export declare const CaptureV2RequestSchema: z.ZodObject<{
     }>]>, "many">;
     out_dir: z.ZodString;
     tsconfig_path: z.ZodOptional<z.ZodString>;
+    scan_root: z.ZodOptional<z.ZodString>;
 }, "strip", z.ZodTypeAny, {
     request_id: string;
     action: "capture_v2";
@@ -381,6 +385,7 @@ export declare const CaptureV2RequestSchema: z.ZodObject<{
     })[];
     out_dir: string;
     tsconfig_path?: string | undefined;
+    scan_root?: string | undefined;
 }, {
     request_id: string;
     action: "capture_v2";
@@ -418,6 +423,7 @@ export declare const CaptureV2RequestSchema: z.ZodObject<{
     })[];
     out_dir: string;
     tsconfig_path?: string | undefined;
+    scan_root?: string | undefined;
 }>;
 export declare const CheckV2RequestSchema: z.ZodObject<{
     request_id: z.ZodString;
@@ -1810,6 +1816,7 @@ export declare const SidecarRequestSchema: z.ZodDiscriminatedUnion<"action", [z.
     action: z.ZodLiteral<"init">;
     repo_root: z.ZodString;
     tsconfig_path: z.ZodOptional<z.ZodString>;
+    scan_root: z.ZodOptional<z.ZodString>;
     tsconfig_snapshot: z.ZodOptional<z.ZodObject<{
         compilerOptions: z.ZodObject<{
             module: z.ZodOptional<z.ZodString>;
@@ -1902,6 +1909,7 @@ export declare const SidecarRequestSchema: z.ZodDiscriminatedUnion<"action", [z.
     action: "init";
     repo_root: string;
     tsconfig_path?: string | undefined;
+    scan_root?: string | undefined;
     tsconfig_snapshot?: {
         compilerOptions: {
             module?: string | undefined;
@@ -1928,6 +1936,7 @@ export declare const SidecarRequestSchema: z.ZodDiscriminatedUnion<"action", [z.
     action: "init";
     repo_root: string;
     tsconfig_path?: string | undefined;
+    scan_root?: string | undefined;
     tsconfig_snapshot?: {
         compilerOptions: {
             module?: string | undefined;
@@ -2083,6 +2092,7 @@ export declare const SidecarRequestSchema: z.ZodDiscriminatedUnion<"action", [z.
     }>]>, "many">;
     out_dir: z.ZodString;
     tsconfig_path: z.ZodOptional<z.ZodString>;
+    scan_root: z.ZodOptional<z.ZodString>;
 }, "strip", z.ZodTypeAny, {
     request_id: string;
     action: "capture_v2";
@@ -2120,6 +2130,7 @@ export declare const SidecarRequestSchema: z.ZodDiscriminatedUnion<"action", [z.
     })[];
     out_dir: string;
     tsconfig_path?: string | undefined;
+    scan_root?: string | undefined;
 }, {
     request_id: string;
     action: "capture_v2";
@@ -2157,6 +2168,7 @@ export declare const SidecarRequestSchema: z.ZodDiscriminatedUnion<"action", [z.
     })[];
     out_dir: string;
     tsconfig_path?: string | undefined;
+    scan_root?: string | undefined;
 }>, z.ZodObject<{
     request_id: z.ZodString;
 } & {

package/sidecar/dist/src/validators.js

@@ -136,6 +136,7 @@ export const InitRequestSchema = BaseRequestSchema.extend({
     action: z.literal('init'),
     repo_root: z.string().min(1, 'Repo root cannot be empty'),
     tsconfig_path: z.string().optional(),
+    scan_root: z.string().min(1).optional(),
     tsconfig_snapshot: TsconfigSnapshotSchema.optional(),
     pinned_dependencies: PinnedDependencySnapshotSchema.optional(),
 });
@@ -192,6 +193,7 @@ export const CaptureV2RequestSchema = BaseRequestSchema.extend({
     anchors: z.array(CaptureAnchorRequestSchema).min(1, 'At least one anchor is required'),
     out_dir: z.string().min(1, 'Output dir cannot be empty'),
     tsconfig_path: z.string().optional(),
+    scan_root: z.string().min(1).optional(),
 });
 const CheckStubInputSchema = z.object({
     service_name: z.string().min(1),