carrick 0.3.84 → 0.3.86

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

@@ -6,9 +6,9 @@
  */
 import ts from 'typescript';
 import * as path from 'node:path';
-import { printTypeForDestination, undeclaredNamesIn } from './node-builder.js';
+import { printTypeForDestination, substituteUndeclaredNames, undeclaredNamesIn, } from './node-builder.js';
 import { typeIsOrContainsMachinery } from './machinery.js';
-import { unresolvedAtAnchor } from './unresolved.js';
+import { unresolvedAtAnchor, unresolvedSpecifiersReachableFrom, } from './unresolved.js';
 /** Repo-root-relative source file -> extensionless specifier from entryDir. */
 export function entryRelativeSpecifier(entryDir, repoRoot, sourceFile) {
     const target = path
@@ -54,12 +54,25 @@ export function resolveAnchor(program, request, args) {
         // (a generated model that was never generated). The stub then self-checks
         // such a name as an error placeholder, which no walk flags. A name a
         // sibling symbol anchor imports is resolved by that import.
+        // carrick#1377: rewrite what nothing declares to `unknown` in place, so
+        // one member typed by a module the checkout does not have stops taking
+        // every member around it down with it.
+        const rewritten = siblingSpec || !args.placeholder
+            ? undefined
+            : substituteUndeclaredNamesInText(text, program, args.placeholder);
+        const aliasBody = rewritten?.text ?? text;
         const undeclaredNames = siblingSpec || !args.placeholder
             ? []
-            : undeclaredNamesInText(text, program, args.placeholder);
+            : undeclaredNamesInText(aliasBody, program, args.placeholder);
+        const unresolved = rewritten?.paths.length
+            ? {
+                paths: rewritten.paths,
+                specifiers: unresolvedSpecifiersForLiteral(program, request.source_file, args.repoRoot),
+            }
+            : undefined;
         return {
             request,
-            aliasText: siblingSpec ? `import('${siblingSpec}').${text}` : text,
+            aliasText: siblingSpec ? `import('${siblingSpec}').${text}` : aliasBody,
             // Literal anchors ARE the legacy-text tier (WP3 wiring of the design's
             // structural_fallback): hand-produced type text riding the surface.
             // The self-check still classifies decay; the fidelity metric counts
@@ -67,6 +80,7 @@ export function resolveAnchor(program, request, args) {
             // ratchetable. Demotions are distinguished by failureReason.
             serialization: 'structural_fallback',
             ...(undeclaredNames.length > 0 ? { undeclaredNames } : {}),
+            ...(unresolved ? { unresolved } : {}),
         };
     }
     const sourceAbs = path.join(args.repoRoot, request.source_file);
@@ -276,7 +290,12 @@ function finishInferAnchor(program, sourceFile, request, located, placeholder, r
     if (!printed.text) {
         return demote(printed.failure ?? 'node builder print failed');
     }
-    const unresolved = unresolvedAtAnchor(program, sourceFile, type, located);
+    const atAnchor = unresolvedAtAnchor(program, sourceFile, type, located);
+    // carrick#1377: a member the print named undeclared and this rewrote to
+    // `unknown` is an unresolved position too, whether or not the source type
+    // carried the compiler's placeholder at it (a bare name the print reused as
+    // written does not). Both lists feed the same labelling.
+    const unresolved = mergeUnresolved(atAnchor, printed.substitutedPaths, () => unresolvedSpecifiersReachableFrom(program, sourceFile));
     return {
         request,
         aliasText: printed.text,
@@ -286,13 +305,55 @@ function finishInferAnchor(program, sourceFile, request, located, placeholder, r
         ...(unresolved ? { unresolved } : {}),
     };
 }
+/**
+ * Fold substituted member positions into what the source program could not
+ * resolve. `specifiers` is a thunk: the reachable-import walk is only worth
+ * running for an anchor that actually substituted something.
+ */
+function mergeUnresolved(atAnchor, substitutedPaths, specifiers) {
+    if (!substitutedPaths || substitutedPaths.length === 0)
+        return atAnchor;
+    const paths = new Set([...(atAnchor?.paths ?? []), ...substitutedPaths]);
+    return {
+        paths: [...paths],
+        specifiers: atAnchor?.specifiers ?? specifiers(),
+    };
+}
+/**
+ * The unresolved specifiers a LITERAL anchor's source file reaches, or none
+ * when the anchor names no file (its text names a type with nothing behind it
+ * and the detail says only that).
+ */
+function unresolvedSpecifiersForLiteral(program, sourceFileRel, repoRoot) {
+    if (!sourceFileRel)
+        return [];
+    const sourceFile = program.getSourceFile(path.join(repoRoot, sourceFileRel));
+    return sourceFile ? unresolvedSpecifiersReachableFrom(program, sourceFile) : [];
+}
 /** `undeclaredNamesIn` over type text rather than a built node. */
 function undeclaredNamesInText(text, program, destination) {
+    const parsed = parseLiteralAnchor(text);
+    return parsed ? undeclaredNamesIn(parsed, program, destination) : [];
+}
+/** `substituteUndeclaredNames` over type text rather than a built node. */
+function substituteUndeclaredNamesInText(text, program, destination) {
+    const parsed = parseLiteralAnchor(text);
+    if (!parsed)
+        return undefined;
+    const rewritten = substituteUndeclaredNames(parsed, program, destination);
+    if (rewritten.substitutions.length === 0)
+        return undefined;
+    const printer = ts.createPrinter({ removeComments: true });
+    return {
+        text: printer.printNode(ts.EmitHint.Unspecified, rewritten.node, parsed.getSourceFile()),
+        paths: rewritten.substitutions.map((entry) => entry.path),
+    };
+}
+/** The type node of `type __LiteralAnchor = <text>;`, or undefined. */
+function parseLiteralAnchor(text) {
     const parsed = ts.createSourceFile('literal-anchor.ts', `type __LiteralAnchor = ${text};`, ts.ScriptTarget.Latest, true);
     const statement = parsed.statements[0];
-    if (!statement || !ts.isTypeAliasDeclaration(statement))
-        return [];
-    return undeclaredNamesIn(statement.type, program, destination);
+    return statement && ts.isTypeAliasDeclaration(statement) ? statement.type : undefined;
 }
 /**
  * True when the anchor carries a LINE and nothing else — no payload span, no

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

@@ -164,10 +164,13 @@ export type SelfCheckOutcome = 'ok' | 'allowlisted_external' | 'decayed_internal
  *  - `no_request_body`: the located request read is a validated part the
  *    route's validator binds that is not a body (a path parameter, a query), so
  *    the route states no request body contract there (carrick#1166).
+ *  - `projected_value_only`: every read of a call's result takes a member out
+ *    of it and none reads the value itself, so the site states a part of a
+ *    payload rather than the payload a caller receives (carrick#1375).
  *  - `not_recorded`: the position carries a top type and this layer has no
  *    cause for it.
  */
-export type TypeProvenanceReason = 'declared' | 'unresolved_import' | 'budget_exhausted' | 'no_payload_evidence' | 'machinery_envelope' | 'coerced_input' | 'no_success_payload' | 'no_request_body' | 'not_recorded';
+export type TypeProvenanceReason = 'declared' | 'unresolved_import' | 'budget_exhausted' | 'no_payload_evidence' | 'machinery_envelope' | 'coerced_input' | 'no_success_payload' | 'no_request_body' | 'projected_value_only' | 'not_recorded';
 /**
  * One `any`/`unknown` finding inside a captured or inferred type, with its
  * position and its cause. Sorted by `path` wherever a list is emitted, so the

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

@@ -266,7 +266,10 @@ export function provenanceOf(finding, unresolved) {
             detail: 'the type is too deep or wide to verify within the capture budget here, so it is reported unverified rather than assumed clean',
         };
     }
-    if (finding.kind === 'any' && unresolved?.paths.includes(finding.path)) {
+    // `unknown` reads here as well as `any` (carrick#1377): a reference nothing
+    // declares is rewritten to `unknown` at its own position, and a reader told
+    // the author declared it that way stops looking where the fix is.
+    if (unresolved?.paths.includes(finding.path)) {
         return {
             path: finding.path,
             kind: finding.kind,

package/sidecar/dist/src/capture/node-builder.d.ts

@@ -30,9 +30,23 @@ export interface NodeBuilderPrintResult {
     failure?: string;
     /**
      * Names the print refers to that do not resolve at the destination in the
-     * producer's program (carrick#1165). Present only when there are some.
+     * producer's program (carrick#1165). Present only when there are some —
+     * which, since carrick#1377 rewrites what it can reach, means a reference
+     * the substitution could not replace.
      */
     undeclaredNames?: string[];
+    /**
+     * Member positions the print named something undeclared at, and where that
+     * reference now reads `unknown` (carrick#1377). In the walk's own path
+     * notation, so a finding at one of them can be labelled as what it is: a
+     * module that did not resolve, not a declared top type.
+     */
+    substitutedPaths?: string[];
+}
+/** One reference replaced by `unknown`, with the member position it sat at. */
+export interface UndeclaredSubstitution {
+    name: string;
+    path: string;
 }
 /**
  * Print `type` as a type node anchored at `destination` (a declaration inside
@@ -40,6 +54,19 @@ export interface NodeBuilderPrintResult {
  * any referenced symbol is not plainly accessible from the destination.
  */
 export declare function printTypeForDestination(program: ts.Program, type: ts.Type, destination: ts.Node): NodeBuilderPrintResult;
+/**
+ * Rewrite every reference in `node` that nothing in the producer's program
+ * declares to the `unknown` keyword, and report the member position each sat
+ * at (carrick#1377).
+ *
+ * The positions use the same notation as the capture's deep walk — `sub`,
+ * `items<0>.meta`, `[index]`, `()` for a callable return — so a path found
+ * here names the same member a self-check finding at that path names.
+ */
+export declare function substituteUndeclaredNames(node: ts.TypeNode, program: ts.Program, destination: ts.Node): {
+    node: ts.TypeNode;
+    substitutions: UndeclaredSubstitution[];
+};
 /**
  * Bare names in a printed type node that nothing in the producer's program
  * declares (carrick#1165).

package/sidecar/dist/src/capture/node-builder.js

@@ -117,10 +117,96 @@ export function printTypeForDestination(program, type, destination) {
             failure: `symbols not accessible from the surface entry: ${[...new Set(inaccessible)].join(', ')}`,
         };
     }
+    // carrick#1377: a reference nothing declares makes the WHOLE answer
+    // unpublishable, so one member typed by a package the checkout does not
+    // have used to discard every member around it. Replace what it names with
+    // `unknown` in place and print that; the rest of the shape survives, and
+    // the positions are reported so the finding at each can be labelled as a
+    // module that did not resolve rather than a top type the author declared.
+    const substituted = substituteUndeclaredNames(node, program, destination);
     const printer = ts.createPrinter({ removeComments: true });
-    const text = printer.printNode(ts.EmitHint.Unspecified, node, destination.getSourceFile());
-    const undeclaredNames = undeclaredNamesIn(node, program, destination);
-    return { text, inaccessible, ...(undeclaredNames.length > 0 ? { undeclaredNames } : {}) };
+    const text = printer.printNode(ts.EmitHint.Unspecified, substituted.node, destination.getSourceFile());
+    // Asked of the REWRITTEN node: the field says what the printed answer
+    // names, so anything the substitution could not reach still fills it and
+    // still refuses publication.
+    const undeclaredNames = undeclaredNamesIn(substituted.node, program, destination);
+    const substitutedPaths = substituted.substitutions.map((entry) => entry.path);
+    return {
+        text,
+        inaccessible,
+        ...(undeclaredNames.length > 0 ? { undeclaredNames } : {}),
+        ...(substitutedPaths.length > 0 ? { substitutedPaths } : {}),
+    };
+}
+/**
+ * Rewrite every reference in `node` that nothing in the producer's program
+ * declares to the `unknown` keyword, and report the member position each sat
+ * at (carrick#1377).
+ *
+ * The positions use the same notation as the capture's deep walk — `sub`,
+ * `items<0>.meta`, `[index]`, `()` for a callable return — so a path found
+ * here names the same member a self-check finding at that path names.
+ */
+export function substituteUndeclaredNames(node, program, destination) {
+    const undeclared = new Set(undeclaredNamesIn(node, program, destination));
+    if (undeclared.size === 0) {
+        return { node, substitutions: [] };
+    }
+    const substitutions = [];
+    const leftmost = (name) => ts.isIdentifier(name) ? name : leftmost(name.left);
+    // The path is carried down the visit rather than reconstructed, because a
+    // rewritten node has no parent to walk back up from.
+    const rewrite = (current, path) => {
+        if ((ts.isTypeReferenceNode(current) && undeclared.has(leftmost(current.typeName).text)) ||
+            (ts.isTypeQueryNode(current) && undeclared.has(leftmost(current.exprName).text))) {
+            substitutions.push({
+                name: ts.isTypeReferenceNode(current)
+                    ? leftmost(current.typeName).text
+                    : leftmost(current.exprName).text,
+                path: path === '' ? '<root>' : path,
+            });
+            return ts.factory.createKeywordTypeNode(ts.SyntaxKind.UnknownKeyword);
+        }
+        return ts.visitEachChild(current, (child) => rewrite(child, childPath(current, child, path)), 
+        /* context */ undefined);
+    };
+    const rewritten = rewrite(node, '');
+    return { node: rewritten, substitutions };
+}
+/** The deep walk's path for `child` inside `parent`, extending `path`. */
+function childPath(parent, child, path) {
+    if (ts.isPropertySignature(parent) && parent.type === child) {
+        const name = ts.isIdentifier(parent.name) || ts.isStringLiteral(parent.name)
+            ? parent.name.text
+            : parent.name.getText?.() ?? '';
+        return path === '' ? name : `${path}.${name}`;
+    }
+    if (ts.isArrayTypeNode(parent) && parent.elementType === child) {
+        return `${path}<0>`;
+    }
+    if (ts.isIndexSignatureDeclaration(parent) && parent.type === child) {
+        return `${path}[index]`;
+    }
+    if ((ts.isFunctionTypeNode(parent) ||
+        ts.isMethodSignature(parent) ||
+        ts.isCallSignatureDeclaration(parent)) &&
+        parent.type === child) {
+        return `${path}()`;
+    }
+    if (ts.isTypeReferenceNode(parent) && parent.typeArguments) {
+        const index = parent.typeArguments.indexOf(child);
+        if (index >= 0)
+            return `${path}<${index}>`;
+    }
+    if (ts.isTupleTypeNode(parent)) {
+        const index = parent.elements.indexOf(child);
+        if (index >= 0)
+            return `${path}<${index}>`;
+    }
+    // A union or intersection member sits at its parent's position, as the deep
+    // walk records it; everything else (a type literal's members, a parenthesis)
+    // keeps the path it was reached with.
+    return path;
 }
 /**
  * Bare names in a printed type node that nothing in the producer's program

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

@@ -26,3 +26,10 @@ import { type UnresolvedAtAnchor } from './deep-walk.js';
  * 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;
+/**
+ * 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.
+ */
+export declare function unresolvedSpecifiersReachableFrom(program: ts.Program, sourceFile: ts.SourceFile): string[];

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

@@ -50,7 +50,7 @@ function prefixPath(prefix, path) {
  * relative specifiers ahead of package names. Installed packages and the
  * default library are not descended into.
  */
-function unresolvedSpecifiersReachableFrom(program, sourceFile) {
+export function unresolvedSpecifiersReachableFrom(program, sourceFile) {
     let cache = reachableCache.get(program);
     if (!cache) {
         cache = new Map();

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

@@ -206,17 +206,131 @@ export declare class TypeInferrer {
      */
     private isResponseSend;
     /**
-     * The send `node` is an argument of, looking through the wrappers that do
+     * The call `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.
+     * `JSON.stringify` around the body. `undefined` when `accept` rejects that
+     * call or `node` is its callee.
+     *
+     * Two readings use it: a value handed to a response send is the payload that
+     * send transmits, and a body read handed to a call that states what it
+     * returns is a better statement of that body than the read (carrick#1382).
      */
-    private sendReceivingArgument;
+    private receivingCallOf;
     private inferCallResult;
     private inferVariable;
     private inferExpression;
     private inferRequestBody;
     private resolveCallResultTerminalNode;
+    /**
+     * True when a member read on the call's result resolves to one of that
+     * result's own TYPE ARGUMENTS — the source is unwrapping a generic envelope
+     * by hand (`state.data` off a `ResourceState<Envelope>`), and the payload it
+     * carries is the instantiation, not the envelope (carrick#1375).
+     *
+     * The generic is what tells the two apart. A call that answers its payload
+     * directly is read member by member too, and its declared result IS the
+     * contract; abstaining there would throw away the type the request boundary
+     * states, which a replay over a real repo's consumer rows showed on a
+     * `{ ok: true } | { ok: false; reason: string }` result read as `sent.ok`.
+     */
+    private projectionReadsGenericPayload;
+    /**
+     * The payload a RESULT CARRIER carries, or `undefined` when `type` is not
+     * one or its success side cannot be told from its failure side
+     * (carrick#1376).
+     *
+     * A carrier is recognised by its shape, never by a name: a union of object
+     * branches, instantiated with two or more type arguments, at least one of
+     * which a branch holds as a member. `Result<T, E>`, `Either<L, R>` and a
+     * hand-rolled `{ ok: true; value: T } | { ok: false; error: E }` are all the
+     * same shape, and a promise-like around one is peeled first through the
+     * language's own await protocol. A single generic object — a resource state,
+     * a query result — is NOT a union and is left to carrick#1375, which
+     * abstains on it so a sibling site can answer.
+     *
+     * Which argument is the payload is decided twice over, and never guessed:
+     *
+     *  1. the platform's error shape. Exactly one argument that is not
+     *     error-shaped, beside at least one that is, is the success side.
+     *  2. what the source reads. Where every argument looks alike — `Pair<A,
+     *     string>` — a member read of the carrier that resolves to exactly one
+     *     of the arguments names the side this call site takes.
+     *
+     * Where neither decides, the carrier keeps its own answer and the limit is
+     * logged: a coin flip published as a contract is worse than an envelope a
+     * reader can see is an envelope.
+     */
+    private resultCarrierPayload;
+    /**
+     * `Future<T>` -> `T` for a promise-like of the source's own making, read off
+     * the await protocol rather than a name: a `then` whose first parameter is a
+     * callback, whose own first parameter is the value awaiting it yields.
+     * `Promise` and `PromiseLike` are peeled by `unwrapPromiseType` before this.
+     */
+    private unwrapThenableType;
+    /**
+     * The platform's error shape, in full: `name` and `message` strings AND a
+     * `stack`, which is what the `Error` interface declares and every subclass
+     * of it inherits.
+     *
+     * `stack` is what makes the test a test. A name and a message alone are a
+     * shape a PAYLOAD can have — a contact form declares both — and reading such
+     * a payload as the failure side would publish the other argument, which is
+     * the concrete-but-wrong answer this whole rule exists to avoid. A union is
+     * error-shaped when every member of it is.
+     */
+    private isErrorShaped;
+    /**
+     * The member read that takes `identifier` as its RECEIVER — `query` in
+     * `query.data`, `envelope` in `envelope.list[0]` — or `undefined` when the
+     * identifier names the value itself.
+     *
+     * A member CALL is not a projection: `res.text()` yields a body rather than
+     * a part of one, and what it returns stays the walk's business. The
+     * zero-argument json body read has its own branch and is taken before this
+     * is asked.
+     */
+    private projectionOnReceiver;
+    /**
+     * The call that CONSUMES this json body read and states what the body is —
+     * `parseEnvelope(await response.json())` — or `undefined` when nothing
+     * downstream of the read says more about it than the read itself does
+     * (carrick#1382).
+     *
+     * Three conditions, all shapes of the language rather than names:
+     *
+     *  - the read reaches the call as an ARGUMENT, through the wrappers that do
+     *    not change a value (`await`, parentheses, `as`, `satisfies`, `!`). A
+     *    cast with no call around it therefore keeps the read as the terminal,
+     *    so `(await res.json()) as Entry` is still read off the read itself;
+     *  - the call's own result is BOUND — declared into a variable, returned, or
+     *    assigned — so a call the source made for its side effect
+     *    (`store(await res.json())`) states nothing about the payload;
+     *  - that result is an OBJECT shape. A validator answering `boolean` or a
+     *    serialiser answering `string` describes what the caller did with the
+     *    body, not what the body is, and publishing it would be a
+     *    concrete-but-wrong contract where the honest `any` of the read is
+     *    merely unresolved.
+     */
+    private statedPayloadAroundBodyRead;
+    /**
+     * The source keeps this call's result: it initializes a declaration, is
+     * returned, is assigned, or is an arrow's expression body. A result that is
+     * kept is one the source has a use for; a discarded one is a side effect.
+     */
+    private callResultIsBound;
+    /**
+     * A shape a JSON body can be: an object, an array, or a union of them.
+     * Top types, primitives, `void` and callables are not.
+     */
+    private isObjectShape;
+    /**
+     * Every use of a tracked name inside `expr` reads a member out of the
+     * tracked value, so the expression's type describes a PART of the payload.
+     * False when the expression uses no tracked name at all, so a caller can
+     * read it as "this is a projection" rather than "this is not a use".
+     */
+    private usesNamesOnlyByProjection;
     private extractBindingFromCall;
     private extractBindingNames;
     private getPrimaryBindingNode;
@@ -594,7 +708,16 @@ export declare class TypeInferrer {
      * True when an object literal argument is response INIT rather than a body:
      * every property it declares is one the standard `ResponseInit` declares
      * (`status`, `statusText`, `headers`), and it states at least one of them as
-     * init really does — a numeric status in the HTTP range, or headers.
+     * init really does — a status in the HTTP range, or headers.
+     *
+     * The status does NOT have to be a literal code. A route that carries its
+     * outcome in a value writes `new Response(body, { status: result.status })`,
+     * where the source fixes no code and `statedStatusCodes` answers
+     * `'variable'` — status-shaped, just not pinned. Requiring a literal there
+     * left the whole init object reading as a body, so an endpoint whose payload
+     * this layer does not publish (a string body) published `{ status: number }`
+     * as its response contract instead: a wrong contract, served, where an
+     * abstention was the honest answer.
      *
      * A payload that merely has a `status` member of its own (`{ status: "ok",
      * service: "ledger" }`) declares members init does not, or states `status` as