carrick 0.3.109 → 0.3.110

package/sidecar/dist/src/capture/status-table.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Response tables keyed by HTTP status code (carrick#1841).
+ *
+ * An object type whose every key is a status code (`{ 200: Item; 404: Problem
+ * }`, or a range key such as `2XX`) is not a body: it is a table of the bodies
+ * each status carries. What a caller receives on success is the union of its
+ * 2xx values. The producer side reads the same rule off a schema object
+ * literal (`successStatusEntry` in the inferrer); this module reads it off a
+ * TYPE, through the compiler's own API, so the inferrer, the v1 bundle and
+ * the capture all decide a table the same way.
+ *
+ * Nothing here names a library or a generator. The shape is the HTTP status
+ * vocabulary, which is the language of the wire, not of any one client.
+ */
+import ts from 'typescript';
+/** `value` when it is an integer in the HTTP status range, else `undefined`. */
+export declare function httpStatus(value: unknown): number | undefined;
+/** One verdict for a set of status codes, or `mixed` when they disagree. */
+export declare function classifyStatusCodes(codes: number[]): 'success' | 'error' | 'redirect' | 'mixed';
+/**
+ * The status code a response-table KEY names: `200`, or a range key (`2XX`,
+ * `2xx`) read as the bottom of its range. Quotes around the key are ignored.
+ * `undefined` for any other key.
+ */
+export declare function statusKeyCode(name: string): number | undefined;
+/** One row of a response table: the key as written and the status it names. */
+export interface StatusTableEntry {
+    symbol: ts.Symbol;
+    /** The key as the type declares it (`200`, `2XX`). */
+    key: string;
+    code: number;
+}
+/**
+ * The rows of `type` when it is a response table: a plain object type with at
+ * least one property, every key a status code, no index signature and no call
+ * or construct signature. `undefined` for anything else, so a payload that
+ * happens to hold one numeric key among others is never read as a table.
+ */
+export declare function statusTableOf(checker: ts.TypeChecker, type: ts.Type): StatusTableEntry[] | undefined;
+/** The rows of a table that answer a success: 2xx, in the order declared. */
+export declare function successEntries(entries: StatusTableEntry[]): StatusTableEntry[];
+/**
+ * Whether a body type states nothing: `void`, `undefined`, `never`, or a union
+ * made only of them. A `204: void` row is such a body.
+ */
+export declare function statesNoBody(type: ts.Type): boolean;
+/**
+ * What a response table's success rows carry, read for a consumer:
+ *  - `body`: the 2xx rows' value types, at least one of which states a body;
+ *  - `no_body`: the table has no 2xx row, or every 2xx row states nothing.
+ * `undefined` when `type` is not a response table.
+ */
+export declare function statusTableBody(checker: ts.TypeChecker, type: ts.Type, at: ts.Node): {
+    kind: 'body';
+    entries: StatusTableEntry[];
+    types: ts.Type[];
+} | {
+    kind: 'no_body';
+    entries: StatusTableEntry[];
+} | undefined;
+/** The members of a union, or the type itself: what a set comparison reads. */
+export declare function constituents(type: ts.Type): ts.Type[];

package/sidecar/dist/src/capture/status-table.js

@@ -0,0 +1,104 @@
+/**
+ * Response tables keyed by HTTP status code (carrick#1841).
+ *
+ * An object type whose every key is a status code (`{ 200: Item; 404: Problem
+ * }`, or a range key such as `2XX`) is not a body: it is a table of the bodies
+ * each status carries. What a caller receives on success is the union of its
+ * 2xx values. The producer side reads the same rule off a schema object
+ * literal (`successStatusEntry` in the inferrer); this module reads it off a
+ * TYPE, through the compiler's own API, so the inferrer, the v1 bundle and
+ * the capture all decide a table the same way.
+ *
+ * Nothing here names a library or a generator. The shape is the HTTP status
+ * vocabulary, which is the language of the wire, not of any one client.
+ */
+import ts from 'typescript';
+/** `value` when it is an integer in the HTTP status range, else `undefined`. */
+export function httpStatus(value) {
+    return typeof value === 'number' && Number.isInteger(value) && value >= 100 && value <= 599
+        ? value
+        : undefined;
+}
+/** One verdict for a set of status codes, or `mixed` when they disagree. */
+export function classifyStatusCodes(codes) {
+    if (codes.every((code) => code >= 400))
+        return 'error';
+    if (codes.every((code) => code >= 300 && code < 400))
+        return 'redirect';
+    if (codes.every((code) => code < 300))
+        return 'success';
+    return 'mixed';
+}
+/**
+ * The status code a response-table KEY names: `200`, or a range key (`2XX`,
+ * `2xx`) read as the bottom of its range. Quotes around the key are ignored.
+ * `undefined` for any other key.
+ */
+export function statusKeyCode(name) {
+    const key = name.replace(/['"`]/g, '').trim();
+    if (/^\d{3}$/.test(key))
+        return httpStatus(Number(key));
+    if (/^[1-5]xx$/i.test(key))
+        return Number(key[0]) * 100;
+    return undefined;
+}
+/**
+ * The rows of `type` when it is a response table: a plain object type with at
+ * least one property, every key a status code, no index signature and no call
+ * or construct signature. `undefined` for anything else, so a payload that
+ * happens to hold one numeric key among others is never read as a table.
+ */
+export function statusTableOf(checker, type) {
+    if (!(type.flags & ts.TypeFlags.Object))
+        return undefined;
+    if (type.getCallSignatures().length > 0 || type.getConstructSignatures().length > 0) {
+        return undefined;
+    }
+    if (checker.getIndexInfosOfType(type).length > 0)
+        return undefined;
+    const properties = checker.getPropertiesOfType(type);
+    if (properties.length === 0)
+        return undefined;
+    const entries = [];
+    for (const symbol of properties) {
+        const key = symbol.getName();
+        const code = statusKeyCode(key);
+        if (code === undefined)
+            return undefined;
+        entries.push({ symbol, key, code });
+    }
+    return entries;
+}
+/** The rows of a table that answer a success: 2xx, in the order declared. */
+export function successEntries(entries) {
+    return entries.filter((entry) => entry.code >= 200 && entry.code <= 299);
+}
+/**
+ * Whether a body type states nothing: `void`, `undefined`, `never`, or a union
+ * made only of them. A `204: void` row is such a body.
+ */
+export function statesNoBody(type) {
+    const members = type.isUnion() ? type.types : [type];
+    return members.every((member) => (member.flags & (ts.TypeFlags.Void | ts.TypeFlags.Undefined | ts.TypeFlags.Never)) !== 0);
+}
+/**
+ * What a response table's success rows carry, read for a consumer:
+ *  - `body`: the 2xx rows' value types, at least one of which states a body;
+ *  - `no_body`: the table has no 2xx row, or every 2xx row states nothing.
+ * `undefined` when `type` is not a response table.
+ */
+export function statusTableBody(checker, type, at) {
+    const entries = statusTableOf(checker, type);
+    if (!entries)
+        return undefined;
+    const success = successEntries(entries);
+    const types = success.map((entry) => checker.getTypeOfSymbolAtLocation(entry.symbol, at));
+    if (success.length === 0 || types.every((body) => statesNoBody(body))) {
+        return { kind: 'no_body', entries };
+    }
+    return { kind: 'body', entries: success, types };
+}
+/** The members of a union, or the type itself: what a set comparison reads. */
+export function constituents(type) {
+    return type.isUnion() ? type.types : [type];
+}

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

@@ -27,7 +27,7 @@
  * 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';
+import { Node, type CaseOrDefaultClause, type SwitchStatement } 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. */
@@ -60,8 +60,48 @@ export declare function reachedOnlyOnFailure(node: Node, boundary: Node, isRespo
  * 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.
+ * response's `ok` or `status` is not listed. A `switch` is not read here:
+ * `retype.ts` finds one by its own climb.
  */
 export declare function testsOnPath(node: Node, boundary: Node | undefined, isResponse: (node: Node) => boolean): SideTaken[];
+/**
+ * One test on the path to a node, as the side the node is on. `test` is the
+ * statement or expression that tests, so two nodes under the same test share
+ * it.
+ *
+ *  - `branch`: an `if` or a conditional expression, and whether the node is
+ *    on its true side: the branch the node sits in or, for an earlier `if` in
+ *    an enclosing block one of whose branches cannot complete, the side that
+ *    did not leave.
+ *  - `clause`: the node sits in this clause of a `switch`.
+ *  - `after-switch`: the node follows a `switch` in an enclosing block.
+ */
+export type PathStep = {
+    kind: 'branch';
+    test: Node;
+    condition: Node;
+    whenTrue: boolean;
+} | {
+    kind: 'clause';
+    test: SwitchStatement;
+    clause: CaseOrDefaultClause;
+} | {
+    kind: 'after-switch';
+    test: SwitchStatement;
+};
+/**
+ * Every test on the path from `node` up to `boundary` (the whole file when it
+ * is `undefined`), whatever it reads, innermost first. `testsOnPath` reads
+ * the branches as statuses; `response-modes.ts` reads branches and switches
+ * as values of a request field (carrick#2054).
+ */
+export declare function stepsOnPath(node: Node, boundary: Node | undefined): PathStep[];
 /** `node` reads the response's `ok` or `status`, itself or anywhere inside it. */
 export declare function readsResponseStatus(node: Node, isResponse: (node: Node) => boolean): boolean;
+/**
+ * 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.
+ */
+export declare function cannotComplete(statement: Node): boolean;

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

@@ -64,30 +64,51 @@ export function reachedOnlyOnFailure(node, boundary, isResponse) {
  * 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.
+ * response's `ok` or `status` is not listed. A `switch` is not read here:
+ * `retype.ts` finds one by its own climb.
  */
 export function testsOnPath(node, boundary, isResponse) {
     const sides = [];
-    const take = (test, whenTrue) => {
+    for (const step of stepsOnPath(node, boundary)) {
+        if (step.kind !== 'branch')
+            continue;
+        const test = readTest(step.condition, isResponse);
         if (test === UNRELATED)
-            return;
-        sides.push({ admits: whenTrue ? test.whenTrue : test.whenFalse, inexact: test.inexact });
-    };
+            continue;
+        sides.push({ admits: step.whenTrue ? test.whenTrue : test.whenFalse, inexact: test.inexact });
+    }
+    return sides;
+}
+/**
+ * Every test on the path from `node` up to `boundary` (the whole file when it
+ * is `undefined`), whatever it reads, innermost first. `testsOnPath` reads
+ * the branches as statuses; `response-modes.ts` reads branches and switches
+ * as values of a request field (carrick#2054).
+ */
+export function stepsOnPath(node, boundary) {
+    const steps = [];
+    const branch = (test, condition, whenTrue) => steps.push({ kind: 'branch', test, condition, whenTrue });
     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);
+                branch(parent, parent.getExpression(), true);
             }
             else if (child === parent.getElseStatement()) {
-                take(readTest(parent.getExpression(), isResponse), false);
+                branch(parent, parent.getExpression(), false);
             }
         }
         else if (Node.isConditionalExpression(parent)) {
             if (child === parent.getWhenTrue()) {
-                take(readTest(parent.getCondition(), isResponse), true);
+                branch(parent, parent.getCondition(), true);
             }
             else if (child === parent.getWhenFalse()) {
-                take(readTest(parent.getCondition(), isResponse), false);
+                branch(parent, parent.getCondition(), false);
+            }
+        }
+        else if (Node.isCaseClause(parent) || Node.isDefaultClause(parent)) {
+            const statement = parent.getParent()?.getParent();
+            if (statement && Node.isSwitchStatement(statement)) {
+                steps.push({ kind: 'clause', test: statement, clause: parent });
             }
         }
         if (Node.isBlock(parent) ||
@@ -97,21 +118,25 @@ export function testsOnPath(node, boundary, isResponse) {
             for (const statement of parent.getStatements()) {
                 if (statement === child)
                     break;
+                if (Node.isSwitchStatement(statement)) {
+                    steps.push({ kind: 'after-switch', test: statement });
+                    continue;
+                }
                 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);
+                    branch(statement, statement.getExpression(), false);
                 }
                 else if (elseLeaves && !thenLeaves) {
-                    take(readTest(statement.getExpression(), isResponse), true);
+                    branch(statement, statement.getExpression(), true);
                 }
             }
         }
     }
-    return sides;
+    return steps;
 }
 /** The statuses `condition` lets through when it is true and when it is false. */
 function readTest(condition, isResponse) {
@@ -216,7 +241,7 @@ export function readsResponseStatus(node, isResponse) {
  * `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) {
+export function cannotComplete(statement) {
     if (Node.isReturnStatement(statement) ||
         Node.isThrowStatement(statement) ||
         Node.isBreakStatement(statement) ||

package/sidecar/dist/src/library-claims.js

@@ -2584,6 +2584,8 @@ class DeclarationReader {
      * repository checked out under a `node_modules` ancestor, is not installed.
      * An install hoisted above the service root (`../../node_modules/pkg`) and
      * a pnpm store (`node_modules/.pnpm/pkg@1/node_modules/pkg`) are.
+     * Mirrored by `installedPackageDirectory` in capture/, which the capture
+     * seam keeps from being shared.
      */
     installedPackage(fileName) {
         const segments = path.relative(this.root, this.realpath(fileName)).split(path.sep);

package/sidecar/dist/src/line-index.d.ts

@@ -1,3 +1,4 @@
+import type { Node } from 'ts-morph';
 /**
  * The 1-based line of a position in a text, counted by line feeds alone: one
  * more than the `\n`s before the position. That is the count ts-morph's
@@ -7,3 +8,11 @@
  * The text is read once; each lookup after that is a binary search.
  */
 export declare function lineIndex(text: string): (pos: number) => number;
+/**
+ * `node.getStartLineNumber()` from a per-file index. ts-morph counts the
+ * file's line feeds from position 0 on every call, so a walk that asks of
+ * every node of a file pays the file's size once per node (carrick#1935).
+ */
+export declare function startLineOf(node: Node): number;
+/** `node.getEndLineNumber()` from the same per-file index. */
+export declare function endLineOf(node: Node): number;

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

@@ -24,3 +24,27 @@ export function lineIndex(text) {
         return lo + 1;
     };
 }
+const fileLineIndexes = new WeakMap();
+function lineAtIn(node, pos) {
+    // Keyed on the compiler node: a manipulation (`replaceWithText`, a retype)
+    // gives the file a new one, so the index is built again from the new text.
+    const key = node.getSourceFile().compilerNode;
+    let lineAt = fileLineIndexes.get(key);
+    if (!lineAt) {
+        lineAt = lineIndex(key.text);
+        fileLineIndexes.set(key, lineAt);
+    }
+    return lineAt(pos);
+}
+/**
+ * `node.getStartLineNumber()` from a per-file index. ts-morph counts the
+ * file's line feeds from position 0 on every call, so a walk that asks of
+ * every node of a file pays the file's size once per node (carrick#1935).
+ */
+export function startLineOf(node) {
+    return lineAtIn(node, node.getStart());
+}
+/** `node.getEndLineNumber()` from the same per-file index. */
+export function endLineOf(node) {
+    return lineAtIn(node, node.getEnd());
+}

package/sidecar/dist/src/response-modes.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Which incoming-message field picks each member of a response union (carrick#2054).
+ *
+ * A handler that sends `{ x }` when `?mode=a` and `{ y }` otherwise publishes
+ * `{ x } | { y }`. A call that states `mode=a` receives only `{ x }`, and a
+ * call that states nothing may receive either. The union alone cannot say
+ * which, so this reads it from the handler: for each success body the union
+ * joined, the tests on its path that compare a value read from the incoming message
+ * with a string literal.
+ *
+ * The reading, in order:
+ *
+ *  - A test counts only when it separates two of the joined bodies: one on
+ *    each side of it, or, for an earlier `if` that cannot complete, one in
+ *    its branch and one after it. A validation guard whose branch only sends
+ *    an error separates nothing the join kept, and is ignored.
+ *  - A counted test is a message read when a value it tests is read from a
+ *    parameter of a function enclosing the send (`messageRead`). A test that
+ *    reads nothing from the incoming message (server state, a local count) is ignored,
+ *    so a body under it is under no test of the field and stays in every case.
+ *  - `===`, `==`, `!==` and `!=` against a string literal, with `!` flipping
+ *    the test, and `switch` labels, are read as values. Any other test of a
+ *    message read leaves its field read with its values unread.
+ *  - `reads` lists every message read among the counted tests. `cases` is
+ *    read only for one placed field whose tests were all read: one case per
+ *    literal compared, plus "any other value" (`value: null`) when a body
+ *    admits one, each the union of the bodies it admits.
+ *  - When every case is the same union, the route has no modes.
+ *
+ * The published union is not changed by any of this.
+ */
+import { Node, type Symbol as TsSymbol } from 'ts-morph';
+/**
+ * Where in the incoming message a field is read from. Only the HTTP sources
+ * are read so far; another protocol (a socket message, a pub/sub payload)
+ * adds its own source here.
+ */
+export type MessageSource = 'query' | 'body' | 'unplaced';
+/** One incoming-message field a response union depends on. */
+export interface ResponseModeRead {
+    /**
+     * `query`: read with `.get(...)` on the default lib's `URLSearchParams`.
+     * `body`: a top-level property of the awaited result of a zero-argument
+     * `json()` the default lib or an installed library declares. `unplaced`:
+     * anything else (a header, a path parameter, the method, a framework's own
+     * accessor, a `json()` the repo declares).
+     */
+    location: MessageSource;
+    field: string;
+}
+/** The union a stated value of the field receives. */
+export interface ResponseModeCase {
+    /** The value; `null` for any value no other case names. */
+    value: string | null;
+    type_string: string;
+}
+export interface ResponseModes {
+    /** Every message field the union depends on, sorted by location, then field. */
+    reads: ResponseModeRead[];
+    /**
+     * Present only when `reads` is one placed field and every test of it was
+     * read. Sorted by value, the `null` case last.
+     */
+    cases?: ResponseModeCase[];
+}
+/** One success body the union joined, in source order. */
+export interface JoinedBody {
+    node: Node;
+    type_string: string;
+}
+/**
+ * The modes of the union joined from `bodies`, or `undefined` when no message
+ * read separates them. `join` builds a union text from member texts with the
+ * rules the published union is built with. `isLibOrExternal` says whether a
+ * symbol is declared by a TypeScript lib or an installed library.
+ */
+export declare function readResponseModes(bodies: JoinedBody[], join: (texts: string[]) => string, isLibOrExternal: (symbol: TsSymbol | undefined) => boolean): ResponseModes | undefined;