carrick 0.3.72 → 0.3.75

package/sidecar/dist/src/capture/unresolved.d.ts

@@ -0,0 +1,28 @@
+/**
+ * What an anchor's source program could not resolve (carrick#1164).
+ *
+ * The node builder and declaration emit both print TypeScript's
+ * unresolved-reference placeholder as the keyword `any`. After that the stub
+ * text cannot say whether an `any` member was written by the author or left
+ * behind by an import that did not resolve on the scanned checkout — a
+ * dependency that was not installed, a generated module that was never
+ * generated. The self-check reads only that text, so it used to label both
+ * `declared`, and a reader told "declared that way in the source" stops
+ * looking where the fix is to install or generate the missing module.
+ *
+ * The source program still holds the placeholder, so the capture records the
+ * placeholder's member paths at anchor time, together with the module
+ * specifiers the anchor's file can reach that did not resolve, and the
+ * self-check labels the matching findings. Seam: node builtins + `typescript`.
+ */
+import ts from 'typescript';
+import { type UnresolvedAtAnchor } from './deep-walk.js';
+/**
+ * The unresolved placeholders inside `type` (read at `location` in `sourceFile`),
+ * or `undefined` when it has none — the common case, which costs one walk.
+ *
+ * `pathPrefix` maps the anchor type's member paths onto the paths of the alias
+ * the surface declares when the two differ: a symbol anchor restoring array
+ * depth prints `import('./m').Row[]`, whose members sit under `<0>`.
+ */
+export declare function unresolvedAtAnchor(program: ts.Program, sourceFile: ts.SourceFile, type: ts.Type, location: ts.Node, pathPrefix?: string): UnresolvedAtAnchor | undefined;

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

@@ -0,0 +1,107 @@
+/**
+ * What an anchor's source program could not resolve (carrick#1164).
+ *
+ * The node builder and declaration emit both print TypeScript's
+ * unresolved-reference placeholder as the keyword `any`. After that the stub
+ * text cannot say whether an `any` member was written by the author or left
+ * behind by an import that did not resolve on the scanned checkout — a
+ * dependency that was not installed, a generated module that was never
+ * generated. The self-check reads only that text, so it used to label both
+ * `declared`, and a reader told "declared that way in the source" stops
+ * looking where the fix is to install or generate the missing module.
+ *
+ * The source program still holds the placeholder, so the capture records the
+ * placeholder's member paths at anchor time, together with the module
+ * specifiers the anchor's file can reach that did not resolve, and the
+ * self-check labels the matching findings. Seam: node builtins + `typescript`.
+ */
+import ts from 'typescript';
+import { findUnresolvedPlaceholders } from './deep-walk.js';
+/** Files the specifier walk visits from one anchor before it stops. */
+const MAX_REACHABLE_FILES = 256;
+/** Per-program memo: source file name -> unresolved specifiers it reaches. */
+const reachableCache = new WeakMap();
+/**
+ * The unresolved placeholders inside `type` (read at `location` in `sourceFile`),
+ * or `undefined` when it has none — the common case, which costs one walk.
+ *
+ * `pathPrefix` maps the anchor type's member paths onto the paths of the alias
+ * the surface declares when the two differ: a symbol anchor restoring array
+ * depth prints `import('./m').Row[]`, whose members sit under `<0>`.
+ */
+export function unresolvedAtAnchor(program, sourceFile, type, location, pathPrefix = '') {
+    const checker = program.getTypeChecker();
+    const paths = findUnresolvedPlaceholders(type, program, checker, location).map((path) => prefixPath(pathPrefix, path));
+    if (paths.length === 0)
+        return undefined;
+    return { paths, specifiers: unresolvedSpecifiersReachableFrom(program, sourceFile) };
+}
+/** Join a walk path under a prefix in the walk's own notation. */
+function prefixPath(prefix, path) {
+    if (prefix === '')
+        return path;
+    if (path === '')
+        return prefix;
+    return /^[<[(]/.test(path) ? `${prefix}${path}` : `${prefix}.${path}`;
+}
+/**
+ * Module specifiers, as written, that do not resolve from `sourceFile` or from
+ * any source module it imports, breadth-first so the nearest come first, with
+ * relative specifiers ahead of package names. Installed packages and the
+ * default library are not descended into.
+ */
+function unresolvedSpecifiersReachableFrom(program, sourceFile) {
+    let cache = reachableCache.get(program);
+    if (!cache) {
+        cache = new Map();
+        reachableCache.set(program, cache);
+    }
+    const cached = cache.get(sourceFile.fileName);
+    if (cached)
+        return cached;
+    const checker = program.getTypeChecker();
+    const unresolved = new Set();
+    const visited = new Set([sourceFile.fileName]);
+    const queue = [sourceFile];
+    while (queue.length > 0 && visited.size <= MAX_REACHABLE_FILES) {
+        const file = queue.shift();
+        for (const literal of moduleSpecifiersOf(file)) {
+            const module = checker.getSymbolAtLocation(literal);
+            if (!module) {
+                unresolved.add(literal.text);
+                continue;
+            }
+            // An ambient `declare module 'x'` resolves to a module declaration, not
+            // a file: resolved, with nothing further to walk.
+            const target = module.declarations?.find(ts.isSourceFile);
+            if (!target ||
+                visited.has(target.fileName) ||
+                program.isSourceFileDefaultLibrary(target) ||
+                program.isSourceFileFromExternalLibrary(target)) {
+                continue;
+            }
+            visited.add(target.fileName);
+            queue.push(target);
+        }
+    }
+    const ordered = [...unresolved].sort((a, b) => Number(!a.startsWith('.')) - Number(!b.startsWith('.')));
+    cache.set(sourceFile.fileName, ordered);
+    return ordered;
+}
+/** The string-literal module specifiers of a file's imports and re-exports. */
+function moduleSpecifiersOf(file) {
+    const out = [];
+    for (const statement of file.statements) {
+        let specifier;
+        if (ts.isImportDeclaration(statement) || ts.isExportDeclaration(statement)) {
+            specifier = statement.moduleSpecifier;
+        }
+        else if (ts.isImportEqualsDeclaration(statement) &&
+            ts.isExternalModuleReference(statement.moduleReference)) {
+            specifier = statement.moduleReference.expression;
+        }
+        if (specifier && ts.isStringLiteral(specifier))
+            out.push(specifier);
+    }
+    return out;
+}

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

@@ -135,6 +135,57 @@ export declare class TypeInferrer {
      */
     private resolveParamTarget;
     private inferResponseBody;
+    /**
+     * The wire representation a request's printed type takes. A route response
+     * is serialised as JSON by every sender this layer reads a payload out of,
+     * so it prints `toJSON()` results rather than the objects that declare them
+     * (carrick#1163). Everything else prints the declared type.
+     */
+    private wireFormatFor;
+    /** An inferred type for a payload read out of response sends. */
+    private inferredFromRecoveredPayload;
+    /**
+     * carrick#1161: type a route response from every send in the handler the
+     * locator anchors, rather than from the one send it names.
+     *
+     * The analyzer reports one response expression per row, and on a handler
+     * that guards before it succeeds that is the guard's body. So the located
+     * expression selects the HANDLER: the function that contains it, on a row
+     * whose line is a route registration. Its returned sends are enumerated
+     * (conditional branches split), each is classified by the status it states
+     * (`responseSiteStatus`), the error and redirect branches are dropped, and
+     * the success bodies are joined exactly as the payload walk joins return
+     * statements.
+     *
+     * Returns `undefined` when this does not apply, which leaves the caller's
+     * own reading of the located expression untouched:
+     *  - the row's line is not a route registration;
+     *  - the located expression is neither a send nor the argument of one;
+     *  - that send is not one the handler returns;
+     *  - it is a success send and the only one that survives, so the join would
+     *    be the located body anyway;
+     *  - no joined body is the located one (a text body beside JSON ones).
+     *
+     * When the located send is an error or redirect branch and no success body
+     * survives, the route sends no body a contract can describe: an explicit
+     * `unknown` with its reason, so no later locator re-run reads the error body
+     * or the redirect location back in.
+     */
+    private inferFromResponseSites;
+    /**
+     * True when `candidate` is a response send: a call or `new` whose result is
+     * transport machinery (by the extraction config's verified rule or the
+     * structural check), or whose callee this handler's own returns prove is a
+     * serialiser (`calleesProvenSerialiser`, which holds on a bare checkout).
+     */
+    private isResponseSend;
+    /**
+     * The send `node` is an argument of, looking through the wrappers that do
+     * not change a payload (parentheses, `as`, `satisfies`, `!`, `await`) and a
+     * `JSON.stringify` around the body. `undefined` when the parent call is not
+     * a send or `node` is its callee.
+     */
+    private sendReceivingArgument;
     private inferCallResult;
     private inferVariable;
     private inferExpression;
@@ -524,24 +575,45 @@ export declare class TypeInferrer {
      */
     private statesResponseInit;
     /**
-     * True when an argument states a >= 400 status: an options object carrying
-     * `status`/`statusCode`, or a bare status code (`send(body, 404)`).
+     * What a response send states about its HTTP status (carrick#1161).
      *
-     * Read from the AST first: `{ status: 400 }` in an argument position widens
-     * to `{ status: number }`, so the literal only survives syntactically. The
-     * type check behind it catches `as const` and hoisted option objects.
+     * Read in order, and the first that states anything decides:
+     *
+     *  1. an argument past the body that carries a status: a numeric literal
+     *     (`send(body, 404)`), an options object (`{ status: 401 }`), or any
+     *     expression whose TYPE is a status literal or a union of them
+     *     (`let code: 400 | 500`). A numeric argument whose type is a plain
+     *     `number` states a status the source does not fix, which is
+     *     `variable`: the branch fails open into the union and is logged.
+     *  2. the send call's own RESULT type, when a member of it is typed as a
+     *     status literal. A framework that types its sends records the status
+     *     there, and a redirect helper's default `302` is only visible there.
+     *     A result whose status member spans success and error codes (the
+     *     default of a typed `json(body, status?)`) says nothing either way.
+     *
+     * A status in the FIRST argument is a field of the body and is never read.
+     * No method or framework name is consulted anywhere.
      */
-    private statesErrorStatus;
+    private responseSiteStatus;
     /**
-     * The HTTP status an argument states, or `undefined`.
+     * The HTTP status codes an argument states, `'variable'` when it is a
+     * status-shaped value the source does not fix, or `undefined` when it says
+     * nothing about a status.
      *
      * Read from the AST first: `{ status: 400 }` in an argument position widens
      * to `{ status: number }`, so the literal only survives syntactically. The
-     * type check behind it catches `as const` and hoisted option objects. Only
-     * values in the HTTP range count — an arbitrary number named `status` on a
-     * domain object (`{ status: 2 }`) states nothing about transport.
+     * type read behind it catches `as const`, hoisted option objects and
+     * literal-typed variables. Only values in the HTTP range count: an
+     * arbitrary number named `status` on a domain object (`{ status: 2 }`)
+     * states nothing about transport.
+     */
+    private statedStatusCodes;
+    /**
+     * Status codes a send call's result type records: the members (of the
+     * result, or of each part of an intersection result) typed as a status
+     * literal or a union of them. `undefined` when none is.
      */
-    private statedStatusCode;
+    private sendResultStatusCodes;
     /**
      * Peel the wrappers that do not change an expression's payload: parentheses
      * and `await`. Unlike `unwrapExpressionNode` this KEEPS `as`/`satisfies`,
@@ -937,6 +1009,31 @@ export declare class TypeInferrer {
      * question (`schemaContract`), not this walk's.
      */
     private middlewareBodySchemaValues;
+    /**
+     * The contract of the schema a handler validates an untyped body read with
+     * (carrick#1166), or null.
+     *
+     * `read` is the located expression: the read call, or the binding that holds
+     * it. Every call in the enclosing function that takes that value as an
+     * argument is a candidate, and the schema is the call's receiver
+     * (`Schema.safeParse(body)`) or one of its other arguments
+     * (`parse(Schema, body)`). A candidate counts only when it declares schema
+     * types (`schemaOutputType` / `schemaInputType`), so a logger or a service
+     * call the body is also handed to is never read as a contract. No method or
+     * library name is matched.
+     */
+    private schemaConsumingRead;
+    /**
+     * The part a validated read names when that part is not a body, or
+     * `undefined` (carrick#1166).
+     *
+     * The read is a call whose only argument is a string literal, and the
+     * registration carries a validator middleware binding that same literal.
+     * The part names match through the source's own literal, so no framework
+     * vocabulary is assumed beyond `REQUEST_BODY_PARTS`, which already decides
+     * what a body is for the middleware anchor.
+     */
+    private nonBodyValidatedPart;
     /**
      * The request contract behind a VALIDATED READ: a call inside a registered
      * handler whose type is exactly the parsed output of a body schema the