carrick 0.3.72 → 0.3.73

package/sidecar/dist/src/capture/paths-rewrite.js

@@ -7,12 +7,14 @@
  * producer's own resolution context -- `paths` cannot be fixed at check time
  * (program-global, and namespaces collide across stubs).
  *
- * Specifiers that map outside the emitted tree are left untouched: the
- * per-alias self-check classifies them as dangling internals with a recorded
- * reason, which is the honest outcome.
+ * An absolute path into an installed package becomes that package's bare
+ * specifier (installed-package.ts). Other specifiers that map outside the
+ * emitted tree are left untouched: the per-alias self-check classifies them
+ * as dangling internals with a recorded reason, which is the honest outcome.
  */
 import * as fs from 'node:fs';
 import * as path from 'node:path';
+import { installedPackageSpecifier } from './installed-package.js';
 import { isRelative, matchPathsPattern, rewriteSpecifiers, } from './specifiers.js';
 export function parsePathsPatterns(options, configPath) {
     const paths = options.paths;
@@ -55,21 +57,51 @@ function relativeSpecifier(fromFile, toFile) {
     return rel;
 }
 /**
- * Rewrite paths-mapped and absolute-internal specifiers in every emitted
- * file. Returns the number of specifiers rewritten.
+ * `import("<absolute>").Name` occurrences: the absolute specifier and the
+ * first name read off it, so an installed-package rewrite can find the entry
+ * that exports that name.
+ */
+const ABSOLUTE_IMPORT_TYPE = /(import\s*\(\s*)(["'])(\/[^"']+)\2(\s*\))(\s*\.\s*)([A-Za-z_$][\w$]*)/g;
+/**
+ * Rewrite paths-mapped, absolute-internal and absolute installed-package
+ * specifiers in every emitted file (carrick#1174 for the last: a path into
+ * `node_modules` or a runtime npm cache becomes the package's bare specifier).
  */
 export function rewriteEmittedSpecifiers(args) {
     const patterns = parsePathsPatterns(args.options, args.configPath);
     const emitted = new Set(args.files);
+    const pins = {};
+    const installs = {};
     let total = 0;
+    const installed = (spec, importedName) => {
+        const mapped = installedPackageSpecifier(spec, importedName);
+        if (!mapped)
+            return undefined;
+        installs[mapped.install.name] = mapped.install.root;
+        if (mapped.pin)
+            pins[mapped.pin.name] = mapped.pin.version;
+        return mapped.specifier;
+    };
     for (const file of args.files) {
         const absFile = path.join(args.typesDir, file);
-        const text = fs.readFileSync(absFile, 'utf8');
+        const original = fs.readFileSync(absFile, 'utf8');
+        let importTypeRewrites = 0;
+        // Import types first, while the member name is still attached to its
+        // specifier; an in-tree target is left for the general pass below.
+        const text = original.replace(ABSOLUTE_IMPORT_TYPE, (whole, open, quote, spec, close, dot, name) => {
+            if (treeFileFor(spec, args.entryDir, emitted))
+                return whole;
+            const replacement = installed(spec, name);
+            if (replacement === undefined)
+                return whole;
+            importTypeRewrites++;
+            return `${open}${quote}${replacement}${quote}${close}${dot}${name}`;
+        });
         const { text: rewritten, rewrites } = rewriteSpecifiers(text, (spec) => {
-            // Absolute internal paths (node-builder import types).
+            // Absolute paths: an emitted tree file, else an installed package.
             if (spec.startsWith('/')) {
                 const target = treeFileFor(spec, args.entryDir, emitted);
-                return target ? relativeSpecifier(file, target) : undefined;
+                return target ? relativeSpecifier(file, target) : installed(spec);
             }
             if (isRelative(spec))
                 return undefined;
@@ -91,10 +123,10 @@ export function rewriteEmittedSpecifiers(args) {
             }
             return undefined;
         });
-        if (rewrites > 0) {
+        if (rewrites + importTypeRewrites > 0) {
             fs.writeFileSync(absFile, rewritten);
-            total += rewrites;
+            total += rewrites + importTypeRewrites;
         }
     }
-    return total;
+    return { rewrites: total, pins, installs };
 }

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

@@ -142,7 +142,7 @@ function demotedRecord(anchor) {
         alias: anchor.request.alias,
         anchor_kind: anchor.request.kind,
         symbol_name: 'symbol_name' in anchor.request ? anchor.request.symbol_name : undefined,
-        source_file: 'source_file' in anchor.request ? anchor.request.source_file : '<inline>',
+        source_file: anchor.request.kind === 'literal' ? '<inline>' : anchor.request.source_file,
         anchor_origin: anchor.request.anchor_origin,
         serialization: 'structural_fallback',
         self_check: 'decayed_internal',
@@ -194,6 +194,7 @@ function checkedRecord(anchor, ctx) {
     }
     let blamedExternal;
     let internalFailure;
+    const danglingSpecifiers = new Set();
     for (const file of closure) {
         const failures = ctx.failuresByFile.get(file);
         if (!failures)
@@ -202,6 +203,8 @@ function checkedRecord(anchor, ctx) {
             blamedExternal = [...failures.externalPinned][0];
         if (!internalFailure)
             internalFailure = [...failures.internal][0];
+        for (const specifier of failures.internal)
+            danglingSpecifiers.add(specifier);
     }
     // Classification consults the closure failures REGARDLESS of the root
     // type: a dangling internal specifier means part of this alias's closure
@@ -283,7 +286,7 @@ function checkedRecord(anchor, ctx) {
         alias,
         anchor_kind: anchor.request.kind,
         symbol_name: 'symbol_name' in anchor.request ? anchor.request.symbol_name : undefined,
-        source_file: 'source_file' in anchor.request ? anchor.request.source_file : '<inline>',
+        source_file: anchor.request.kind === 'literal' ? '<inline>' : anchor.request.source_file,
         anchor_origin: anchor.request.anchor_origin,
         serialization: anchor.serialization,
         self_check: outcome,
@@ -295,8 +298,14 @@ function checkedRecord(anchor, ctx) {
         self_check_detail: anchor.abstainReason ?? detail ?? anchor.reaimNote,
         top_type_at_self_check: topType,
         ...(unexplainedDeep.length > 0
-            ? { any_provenance: unexplainedDeep.map(provenanceOf) }
+            ? {
+                any_provenance: unexplainedDeep.map((finding) => provenanceOf(finding, anchor.unresolved)),
+            }
+            : {}),
+        ...(danglingSpecifiers.size > 0
+            ? { dangling_specifiers: [...danglingSpecifiers].sort() }
             : {}),
+        ...(anchor.undeclaredNames ? { undeclared_names: anchor.undeclaredNames } : {}),
     };
 }
 /** Resolve a relative specifier from `fromAbs` to a tree file, if present. */

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