carrick 0.3.83 → 0.3.85

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

@@ -22,7 +22,12 @@
  * Attribution is per-alias closure: failed specifiers are blamed on an alias
  * only if they occur in a file reachable from that alias's surface statement
  * (import-type seeds, then BFS over relative imports). The spike's
- * file-granularity shortcut is gone.
+ * file-granularity shortcut is gone -- including on the SURFACE file itself,
+ * which holds every alias, so a file-granular bucket there blamed the whole
+ * service for one alias's dangling specifier (cloud#1184). A surface
+ * diagnostic is attributed by `export type` statement span, exactly as
+ * check-poison.ts contains poison; one that no statement covers keeps the
+ * service-wide bucket.
  */
 import ts from 'typescript';
 import * as fs from 'node:fs';
@@ -73,13 +78,26 @@ function runSelfCheck(args, treeFiles) {
     const program = ts.createProgram(treeFiles, options, args.compilerHost?.(options));
     const checker = program.getTypeChecker();
     const diagnostics = ts.getPreEmitDiagnostics(program);
-    // Failed module specifiers, split external-pinned vs internal, per FILE.
+    const surfaceAbs = path.resolve(args.surfaceAbsPath);
+    const surfaceSource = program.getSourceFile(surfaceAbs);
+    // The surface holds EVERY alias, and every alias's closure starts there, so
+    // a file-granular failure bucket on it blames the whole service for one
+    // alias's dangling specifier (cloud#1184). Attribute by `export type`
+    // statement span, exactly as check-poison.ts contains poison.
+    const aliasAtSurfacePosition = buildSurfaceSpanIndex(surfaceSource);
+    // Failed module specifiers, split external-pinned vs internal, per FILE —
+    // except on the surface, where they are per ALIAS.
     const failuresByFile = new Map();
-    const failuresFor = (fileName) => {
-        let entry = failuresByFile.get(fileName);
+    const surfaceFailuresByAlias = new Map();
+    const emptyFailures = () => ({
+        externalPinned: new Set(),
+        internal: new Set(),
+    });
+    const bucketIn = (map, key) => {
+        let entry = map.get(key);
         if (!entry) {
-            entry = { externalPinned: new Set(), internal: new Set() };
-            failuresByFile.set(fileName, entry);
+            entry = emptyFailures();
+            map.set(key, entry);
         }
         return entry;
     };
@@ -91,7 +109,15 @@ function runSelfCheck(args, treeFiles) {
         if (!m)
             continue;
         const spec = m[1];
-        const bucket = failuresFor(path.resolve(d.file.fileName));
+        const abs = path.resolve(d.file.fileName);
+        // A surface diagnostic outside every alias statement (a file-level import,
+        // a reference directive) is attributable to no alias and keeps the
+        // service-wide file bucket: soundness over precision, the same fallback
+        // check-poison.ts makes.
+        const owner = abs === surfaceAbs ? aliasAtSurfacePosition(d.start) : undefined;
+        const bucket = owner
+            ? bucketIn(surfaceFailuresByAlias, owner)
+            : bucketIn(failuresByFile, abs);
         if (!isRelative(spec) && args.pinned[packageNameOf(spec)]) {
             bucket.externalPinned.add(spec);
         }
@@ -113,8 +139,6 @@ function runSelfCheck(args, treeFiles) {
         }
         adjacency.set(abs, neighbors);
     }
-    const surfaceAbs = path.resolve(args.surfaceAbsPath);
-    const surfaceSource = program.getSourceFile(surfaceAbs);
     const records = [];
     for (const anchor of args.resolved) {
         // Demotions (failureReason present) never reached the surface with a
@@ -131,10 +155,35 @@ function runSelfCheck(args, treeFiles) {
                 surfaceSource,
                 adjacency,
                 failuresByFile,
+                surfaceFailuresByAlias,
             }));
     }
     return records;
 }
+/**
+ * Position -> the alias whose `export type` statement span covers it, for
+ * diagnostics reported on the surface file. `undefined` when no alias
+ * statement covers the position, or when the surface is not in the program.
+ */
+function buildSurfaceSpanIndex(surfaceSource) {
+    if (!surfaceSource)
+        return () => undefined;
+    const spans = [];
+    for (const stmt of surfaceSource.statements) {
+        if (!ts.isTypeAliasDeclaration(stmt))
+            continue;
+        spans.push({
+            alias: stmt.name.text,
+            start: stmt.getStart(surfaceSource),
+            end: stmt.getEnd(),
+        });
+    }
+    return (position) => {
+        if (position === undefined)
+            return undefined;
+        return spans.find((span) => position >= span.start && position <= span.end)?.alias;
+    };
+}
 /** An alias that never reached a capture-native tier: the failure reason was
  * recorded at demotion time; the surface line is `unknown` by construction. */
 function demotedRecord(anchor) {
@@ -195,8 +244,13 @@ function checkedRecord(anchor, ctx) {
     let blamedExternal;
     let internalFailure;
     const danglingSpecifiers = new Set();
-    for (const file of closure) {
-        const failures = ctx.failuresByFile.get(file);
+    // This alias's own surface statement, then the closure's files. The surface
+    // file bucket now holds only the diagnostics no alias statement covers.
+    const closureFailures = [
+        ctx.surfaceFailuresByAlias.get(alias),
+        ...[...closure].map((file) => ctx.failuresByFile.get(file)),
+    ];
+    for (const failures of closureFailures) {
         if (!failures)
             continue;
         if (!blamedExternal)

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;