carrick 0.3.85 → 0.3.87

package/sidecar/dist/src/type-inferrer.js

@@ -18,9 +18,8 @@
  * function's return type.
  */
 import { Node, SyntaxKind, ts, } from 'ts-morph';
-import * as fs from 'node:fs';
-import * as path from 'node:path';
 import { validateInferRequestItem } from './validators.js';
+import { isExternalOrigin } from './origin.js';
 import { expandTypeStructural, } from './type-structural-expander.js';
 /**
  * TS/lib globals and primitives that must never be emitted as a deterministic
@@ -152,75 +151,6 @@ const RESPONSE_INIT_MEMBER_NAMES = new Set([
     'statusText',
     'headers',
 ]);
-/**
- * True when a declaration's source file is runtime/library origin rather than
- * user source. Four answers, in order:
- *
- *  1. The runtime declarations Carrick materialises for a non-Node runtime
- *     under `.carrick/deno/` (carrick#1017), and the remote (JSR, `https:`)
- *     modules it copies beside them. Carrick's own artefact layout, not a
- *     guess about anyone else's.
- *  2. A TypeScript default library (`lib.dom.d.ts`, ...), as the program
- *     classifies it; on a bare checkout the DOM `Response` resolves from here.
- *  3. An install under a `node_modules` segment, however it entered the
- *     program (an import, or a root the loader registered).
- *  4. A file the PROGRAM'S RESOLVER marked as an external library import.
- *     This is the graph-backed answer for a project whose resolution does not
- *     go through `node_modules` (carrick#1264): Deno serves an npm dependency's
- *     types from its own cache, a path with no `node_modules` segment, and
- *     `DenoProject.resolve` hands the compiler `isExternalLibraryImport` from
- *     the graph, which the compiler records on the file. Nothing crosses the
- *     capture seam; both programs are built with that host. One exclusion: a
- *     workspace package reached through a `node_modules` symlink is also
- *     marked external by the compiler but is the user's own source, so a file
- *     inside the checkout (the nearest `.git` above the service root) that
- *     carries no `node_modules` segment stays user source.
- *
- * Lockstep mirror of `isExternalOrigin` in `capture/machinery.ts` (the capture
- * seam forbids sharing a module); `machinery-indicator-mirror.test.ts` guards
- * the pair on a real program.
- */
-export function isExternalOrigin(program, sourceFile, repoRoot) {
-    const file = sourceFile.fileName.replace(/\\/g, '/');
-    if (file.includes('/.carrick/deno/')) {
-        return true;
-    }
-    if (program.isSourceFileDefaultLibrary(sourceFile)) {
-        return true;
-    }
-    if (file.includes('/node_modules/')) {
-        return true;
-    }
-    return program.isSourceFileFromExternalLibrary(sourceFile) && !isInsideCheckout(file, repoRoot);
-}
-const checkoutRoots = new Map();
-/** The checkout the service root sits in: the nearest ancestor holding a
- * `.git` entry (a directory, or the file a worktree carries), else the service
- * root itself. */
-function checkoutRootOf(repoRoot) {
-    const key = path.resolve(repoRoot);
-    const cached = checkoutRoots.get(key);
-    if (cached)
-        return cached;
-    let dir = key;
-    let root = key;
-    for (;;) {
-        if (fs.existsSync(path.join(dir, '.git'))) {
-            root = dir;
-            break;
-        }
-        const parent = path.dirname(dir);
-        if (parent === dir)
-            break;
-        dir = parent;
-    }
-    checkoutRoots.set(key, root);
-    return root;
-}
-function isInsideCheckout(file, repoRoot) {
-    const root = checkoutRootOf(repoRoot).replace(/\\/g, '/');
-    return file === root || file.startsWith(root.endsWith('/') ? root : root + '/');
-}
 /**
  * How far the response-helper recovery (carrick#631) descends through nested
  * calls looking for the payload argument. `cors(request, json(payload))` needs
@@ -304,6 +234,18 @@ export class TypeInferrer {
         this.packageOf = options.packageOf;
         this.repoRoot = options.repoRoot;
     }
+    /**
+     * What the structural printer needs to tell the user's own declarations from
+     * the runtime's and its packages' — the same program and service root this
+     * class asks `isExternalOrigin` about machinery, so the two layers cannot
+     * classify one declaration two ways.
+     */
+    expandOrigin() {
+        return {
+            program: this.project.getProgram().compilerObject,
+            repoRoot: this.repoRoot,
+        };
+    }
     /**
      * Infer types for the given requests
      *
@@ -2610,7 +2552,7 @@ export class TypeInferrer {
         const fallback = typeNode.getText();
         try {
             const annotationType = this.unwrapPromiseType(typeNode.getType());
-            const expanded = expandTypeStructural(annotationType, new Set(), 0, undefined, wire);
+            const expanded = expandTypeStructural(annotationType, this.expandOrigin(), { wire });
             // Only prefer the structural form when expansion actually inlined an
             // object shape; otherwise keep the annotation text (e.g. a bare
             // primitive or a library type the expander leaves by name). A wire
@@ -2618,7 +2560,7 @@ export class TypeInferrer {
             // `Date` annotation sends a string (carrick#1163).
             if (expanded.startsWith('{'))
                 return expanded;
-            return wire === 'json' && expanded !== expandTypeStructural(annotationType)
+            return wire === 'json' && expanded !== expandTypeStructural(annotationType, this.expandOrigin())
                 ? expanded
                 : fallback;
         }
@@ -2644,12 +2586,12 @@ export class TypeInferrer {
      */
     expandResolvedTypeStructural(type, fallback, wire = 'declared') {
         try {
-            const expanded = expandTypeStructural(type, new Set(), 0, undefined, wire);
+            const expanded = expandTypeStructural(type, this.expandOrigin(), { wire });
             // A wire print that differs from the declared one is the answer even
             // without an inlined object: a bare `Date` payload sends a string.
             if (wire === 'json' &&
                 !expanded.includes('{') &&
-                expanded !== expandTypeStructural(type)) {
+                expanded !== expandTypeStructural(type, this.expandOrigin())) {
                 return expanded;
             }
             // Prefer the expanded form whenever an object got inlined, not only when
@@ -3029,7 +2971,16 @@ export 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
@@ -3058,7 +3009,7 @@ export class TypeInferrer {
                 statesInit = true;
                 continue;
             }
-            if (name === 'status' && Array.isArray(this.statedStatusCodes(value))) {
+            if (name === 'status' && this.statedStatusCodes(value) !== undefined) {
                 statesInit = true;
             }
         }
@@ -4509,7 +4460,9 @@ export class TypeInferrer {
         const overrides = { types, applied: new Set(), at };
         let text;
         try {
-            text = expandTypeStructural(this.unwrapPromiseType(input), new Set(), 0, overrides);
+            text = expandTypeStructural(this.unwrapPromiseType(input), this.expandOrigin(), {
+                overrides,
+            });
         }
         catch {
             return null;

package/sidecar/dist/src/type-structural-expander.d.ts

@@ -28,7 +28,7 @@
  * `type-inferrer.ts` (consumer-side inference), so both paths emit the same
  * structural form rather than a dangling name.
  */
-import { type Node, type Type } from 'ts-morph';
+import { type Node, type Type, ts } from 'ts-morph';
 /**
  * Bound on the structural-expansion recursion. Deep enough for every realistic
  * request/response shape; a backstop against pathological/recursive types the
@@ -73,17 +73,49 @@ export interface MemberOverrides {
  * signature, never from a list of type names.
  */
 export type WireFormat = 'declared' | 'json';
+/**
+ * The program the walked type belongs to, and the service root inside it.
+ *
+ * Required, not optional, because the walk cannot decide from a type alone
+ * whether a declaration is the user's source or something the runtime
+ * installed: a path test answers that only where resolution goes through
+ * `node_modules`, and a runtime that serves an npm dependency's types out of
+ * its own cache leaves no such segment in the path (carrick#1264). The program
+ * carries the resolver's own verdict, so it is what `isExternalOrigin` is
+ * asked — the same instrument the inference path uses, so the two layers
+ * cannot disagree about which types to inline.
+ */
+export interface ExpandOrigin {
+    readonly program: ts.Program;
+    readonly repoRoot: string;
+}
+/** Everything `expandTypeStructural` takes besides the type and its origin. */
+export interface ExpandOptions {
+    /** Substitutions at named member positions; see `MemberOverrides`. */
+    readonly overrides?: MemberOverrides;
+    /** Which representation to print; see `WireFormat`. */
+    readonly wire?: WireFormat;
+    /**
+     * Where in the recursion the walk starts. Production callers never set it —
+     * depth is walk state — but the `MAX_EXPANSION_DEPTH` backstop is reachable
+     * from a shallow type only by starting the walk at the bound, which is how
+     * its union ordering is tested.
+     */
+    readonly depth?: number;
+}
 /**
  * Recursively render a `Type` as fully-inlined structural text.
  *
  * Named object/interface types are expanded to their member structure;
  * primitives, literals, library types (`Date`, `Promise`, tuples, …) and
- * functions stay by name. The `seen` set (object type ids on the current
- * branch) breaks reference cycles; `depth` is a hard backstop. `overrides`
- * substitutes a type at named member positions (`MemberOverrides`); without
- * it the print is unchanged. `wire` picks the representation (`WireFormat`).
+ * functions stay by name — `origin` is what decides which is which. A cycle
+ * set (object type ids on the current branch) breaks reference cycles and
+ * `MAX_EXPANSION_DEPTH` is a hard backstop; both are walk state, not caller
+ * state. `overrides` substitutes a type at named member positions
+ * (`MemberOverrides`); without it the print is unchanged. `wire` picks the
+ * representation (`WireFormat`).
  */
-export declare function expandTypeStructural(type: Type, seen?: Set<number>, depth?: number, overrides?: MemberOverrides, wire?: WireFormat): string;
+export declare function expandTypeStructural(type: Type, origin: ExpandOrigin, options?: ExpandOptions): string;
 /**
  * The type `JSON.stringify` serialises in place of a value of `type`: the
  * return type of the value's own `toJSON()`, or `undefined` when it declares

package/sidecar/dist/src/type-structural-expander.js

@@ -30,6 +30,7 @@
  */
 import { ts } from 'ts-morph';
 import { canonicalizeUnionsInText, foldBooleanLiterals, } from './type-text-canonicalizer.js';
+import { isExternalOrigin } from './origin.js';
 /**
  * Bound on the structural-expansion recursion. Deep enough for every realistic
  * request/response shape; a backstop against pathological/recursive types the
@@ -62,13 +63,16 @@ function childCursor(cursor, segment) {
  *
  * Named object/interface types are expanded to their member structure;
  * primitives, literals, library types (`Date`, `Promise`, tuples, …) and
- * functions stay by name. The `seen` set (object type ids on the current
- * branch) breaks reference cycles; `depth` is a hard backstop. `overrides`
- * substitutes a type at named member positions (`MemberOverrides`); without
- * it the print is unchanged. `wire` picks the representation (`WireFormat`).
+ * functions stay by name — `origin` is what decides which is which. A cycle
+ * set (object type ids on the current branch) breaks reference cycles and
+ * `MAX_EXPANSION_DEPTH` is a hard backstop; both are walk state, not caller
+ * state. `overrides` substitutes a type at named member positions
+ * (`MemberOverrides`); without it the print is unchanged. `wire` picks the
+ * representation (`WireFormat`).
  */
-export function expandTypeStructural(type, seen = new Set(), depth = 0, overrides, wire = 'declared') {
-    return expandAt(type, seen, depth, overrides ? { overrides, position: '' } : undefined, wire);
+export function expandTypeStructural(type, origin, options = {}) {
+    const { overrides, wire = 'declared', depth = 0 } = options;
+    return expandAt(type, new Set(), depth, overrides ? { overrides, position: '' } : undefined, wire, origin);
 }
 /**
  * The type `JSON.stringify` serialises in place of a value of `type`: the
@@ -88,7 +92,7 @@ export function jsonWireType(type) {
     const declaration = member.getValueDeclaration() ?? member.getDeclarations()[0];
     const memberType = declaration
         ? member.getTypeAtLocation(declaration)
-        : member.getDeclaredType();
+        : memberTypeWithoutDeclaration(member, type);
     const signature = memberType.getCallSignatures()[0];
     if (!signature)
         return undefined;
@@ -101,7 +105,7 @@ export function jsonWireType(type) {
         return undefined;
     return serialised;
 }
-function expandAt(type, seen, depth, at, wire) {
+function expandAt(type, seen, depth, at, wire, origin) {
     if (depth > MAX_EXPANSION_DEPTH)
         return backstopText(type);
     let cursor = at;
@@ -109,7 +113,7 @@ function expandAt(type, seen, depth, at, wire) {
         const replacement = cursor.overrides.types.get(cursor.position);
         if (replacement) {
             cursor.overrides.applied.add(cursor.position);
-            return expandAt(replacement, seen, depth, undefined, wire);
+            return expandAt(replacement, seen, depth, undefined, wire, origin);
         }
         // Nothing to substitute below here: print exactly as without overrides.
         if (!hasOverrideBelow(cursor))
@@ -133,10 +137,10 @@ function expandAt(type, seen, depth, at, wire) {
     }
     // Unions / intersections: expand each member, in canonical order.
     if (type.isUnion()) {
-        return canonicalMembers(type.getUnionTypes(), seen, depth, cursor, wire).join(' | ');
+        return canonicalMembers(type.getUnionTypes(), seen, depth, cursor, wire, origin).join(' | ');
     }
     if (type.isIntersection()) {
-        return canonicalMembers(type.getIntersectionTypes(), seen, depth, cursor, wire).join(' & ');
+        return canonicalMembers(type.getIntersectionTypes(), seen, depth, cursor, wire, origin).join(' & ');
     }
     // Tuples are array-like but must keep their `[a, b]` shape, not be walked
     // as objects (which explodes into `Array.prototype`). Handle before arrays.
@@ -147,7 +151,7 @@ function expandAt(type, seen, depth, at, wire) {
         const element = type.getArrayElementType();
         if (!element)
             return namedText(type);
-        const inner = expandAt(element, seen, depth + 1, childCursor(cursor, '<0>'), wire);
+        const inner = expandAt(element, seen, depth + 1, childCursor(cursor, '<0>'), wire, origin);
         // Parenthesise a union/intersection element so `(A | B)[]` doesn't misparse
         // as `A | B[]`. Decide from the TYPE, not the string: a single object
         // literal like `{ a: A | B }` is NOT a union and must not be parenthesised,
@@ -160,12 +164,12 @@ function expandAt(type, seen, depth, at, wire) {
     if (wire === 'json') {
         const serialised = jsonWireType(type);
         if (serialised)
-            return expandAt(serialised, seen, depth + 1, undefined, wire);
+            return expandAt(serialised, seen, depth + 1, undefined, wire, origin);
     }
     // Library / built-in types (Date, Promise, RegExp, …): keep by name, unless
     // a member below has to be substituted — a schema library declares its
     // inferred object types itself, and they are only walkable, not by-name.
-    if (!cursor && isLibraryType(type)) {
+    if (!cursor && isLibraryType(type, origin)) {
         return namedText(type);
     }
     // Callable/constructable object types (functions): keep by name; their
@@ -182,7 +186,7 @@ function expandAt(type, seen, depth, at, wire) {
         const props = type.getProperties();
         if (props.length === 0)
             return namedText(type);
-        const parts = props.map((prop) => expandProperty(prop, nextSeen, depth, cursor, wire));
+        const parts = props.map((prop) => expandProperty(prop, type, nextSeen, depth, cursor, wire, origin));
         return `{ ${parts.join('; ')}; }`;
     }
     return namedText(type);
@@ -241,8 +245,8 @@ function backstopText(type) {
  * Ties can only happen between two members that render identically, in which
  * case the joined output is the same whichever way round they go.
  */
-function canonicalMembers(members, seen, depth, cursor, wire) {
-    return orderMembers(members, (member) => expandAt(member, seen, depth + 1, cursor, wire));
+function canonicalMembers(members, seen, depth, cursor, wire, origin) {
+    return orderMembers(members, (member) => expandAt(member, seen, depth + 1, cursor, wire, origin));
 }
 /**
  * The canonical order itself, over whatever text `render` gives each member.
@@ -263,7 +267,7 @@ function orderMembers(members, render) {
     return rendered.map((entry) => entry.text);
 }
 /** Render a single property as `name[?]: <expanded>`. */
-function expandProperty(prop, seen, depth, at, wire) {
+function expandProperty(prop, owner, seen, depth, at, wire, origin) {
     const optional = (prop.getFlags() & ts.SymbolFlags.Optional) !== 0;
     const propDecl = prop.getDeclarations()[0];
     // Render the key from the declaration's name node so quoted/computed keys
@@ -274,7 +278,7 @@ function expandProperty(prop, seen, depth, at, wire) {
         ? prop.getTypeAtLocation(at.overrides.at)
         : propDecl
             ? prop.getTypeAtLocation(propDecl)
-            : prop.getDeclaredType();
+            : memberTypeWithoutDeclaration(prop, owner);
     // A substituted member takes the override's TYPE but keeps this key's
     // optionality, and is looked up before the `undefined` strip below so an
     // override that carries `| undefined` strips like any other optional key.
@@ -295,13 +299,36 @@ function expandProperty(prop, seen, depth, at, wire) {
             propType = nonUndefined[0];
         }
         else if (nonUndefined.length > 1) {
-            const inner = canonicalMembers(nonUndefined, seen, depth, cursor, wire).join(' | ');
+            const inner = canonicalMembers(nonUndefined, seen, depth, cursor, wire, origin).join(' | ');
             return `${name}?: ${inner}`;
         }
     }
-    const inner = expandAt(propType, seen, depth + 1, cursor, wire);
+    const inner = expandAt(propType, seen, depth + 1, cursor, wire, origin);
     return `${name}${optional ? '?' : ''}: ${inner}`;
 }
+/**
+ * The type of a member the CHECKER synthesised, which has no declaration of
+ * its own to be read at (carrick#1433).
+ *
+ * A mapped type's members — what a query builder's projection, a
+ * `GetPayload<…>`-style generic or any homomorphic mapping produces — carry no
+ * declaration node. `Symbol.getDeclaredType()` answers `any` for such a symbol
+ * (it is the DECLARED type of a type symbol, and a value member declares
+ * none), so the printed contract lost every field the compiler had resolved:
+ * `{ id: string; createdAt: Date }` printed as `{ id: any; createdAt: any }`
+ * and the row was demoted for carrying a top type.
+ *
+ * The member is read at the owning type's own declaration instead — the mapped
+ * type node the checker instantiated. A synthesised member's type does not
+ * depend on the location it is read at (only narrowing and `this` do, and it
+ * has neither), so this is the instantiated member type; it is the same answer
+ * the caller's own node gives. With no declaration anywhere to read at, the
+ * declared type is still the only thing left to ask for.
+ */
+function memberTypeWithoutDeclaration(prop, owner) {
+    const ownerDecl = (owner.getSymbol() ?? owner.getAliasSymbol())?.getDeclarations()?.[0];
+    return ownerDecl ? prop.getTypeAtLocation(ownerDecl) : prop.getDeclaredType();
+}
 /**
  * The property key as valid TS text. Uses the declaration's name node so a
  * quoted (`'x-y'`) or computed (`[Symbol.iterator]`) key keeps its syntax;
@@ -320,24 +347,26 @@ function isTuple(type) {
     return ((target.objectFlags ?? 0) & ts.ObjectFlags.Tuple) !== 0;
 }
 /**
- * True for types declared in `node_modules` or a TS `lib.*.d.ts` (Date,
- * Promise, RegExp, …). These stay by name rather than being inlined.
+ * True for types the runtime or an installed package declares (Date, Promise,
+ * RegExp, a framework's own types, …). These stay by name rather than being
+ * inlined.
+ *
+ * Asked of the program (`isExternalOrigin`), not of the path: where resolution
+ * does not go through `node_modules` — a runtime serving an npm dependency's
+ * types from its own cache — a path test recognises nothing, and the walk
+ * inlines a library's internals as if they were the user's contract. An
+ * interface that extends `Array<T>` then prints as the whole array prototype,
+ * whose signatures carry `thisArg?: any`, and the row is demoted for a top
+ * type that is not in the contract at all (carrick#1264).
  */
-function isLibraryType(type) {
+function isLibraryType(type, origin) {
     const symbol = type.getSymbol() ?? type.getAliasSymbol();
     if (!symbol)
         return false;
     const decls = symbol.getDeclarations();
     if (decls.length === 0)
         return false;
-    return decls.some((decl) => {
-        const sf = decl.getSourceFile();
-        if (sf.isInNodeModules())
-            return true;
-        return (sf.isDeclarationFile() &&
-            // Normalize separators so a Windows `\\` path still matches lib.*.d.ts.
-            /(^|\/)lib\.[^/]*\.d\.ts$/.test(sf.getFilePath().replace(/\\/g, '/')));
-    });
+    return decls.some((decl) => isExternalOrigin(origin.program, decl.getSourceFile().compilerNode, origin.repoRoot));
 }
 /**
  * Non-expanded text for a type. Passes `undefined` as the enclosing node so

package/templates/skills/carrick-census.md

@@ -53,6 +53,11 @@ Report these numbers before the list, per query where the field is per query:
 - `hidden_by_threshold` where the answer carries it: how many rows the floor
   removed, and `best` where it names the closest of them. A count above zero is
   the case for one more search at a lower `similarity_threshold`;
+- `hidden_by_lexical_floor` where the answer carries it: how many rows matched a
+  word of the query but too little of its word weight to rank, and `best` where
+  it names the nearest of them, with the weight it reached against the bar it
+  had to clear. A lower `similarity_threshold` does not reach these rows. The
+  search that does names the identifier or the rare term itself;
 - `total_without_intent`, which is index-wide: functions carrying no intent
   text, which the search ranked on their name, signature and body tokens
   alone, so a query that names one finds it and a query that describes what

package/templates/skills/carrick-impact.md

@@ -57,10 +57,17 @@ For each consumer service the step above listed:
 check_compatibility({{SCOPE}}, consumer_service: "<consumer>", producer_service: "<producer>", path: "<path>")
 ```
 
-Pass `path`. Without it a large producer returns hundreds of rows. Read
-`type_verdicts` (`compatible`, `incompatible`, `unresolved`, `not_compared`) and
-the `issues` rows for this operation. A `not_compared` pair has no stored
-verdict, which is never agreement.
+Pass `path`. Without it a large producer returns hundreds of rows.
+
+Read `status` before the buckets: `compatible`, `incompatible`,
+`partially_checked`, or `unresolved` where the check compared nothing, with
+`pairs_compared` and `pairs_uncompared` saying how much of the pair it reached.
+A `status` of `unresolved` is not a pass. It means the answer holds no evidence
+either way, and `type_verdicts` says where the gap is.
+
+Then read `type_verdicts` (`compatible`, `incompatible`, `unresolved`,
+`not_compared`) and the `issues` rows for this operation. A `not_compared` pair
+has no stored verdict, which is never agreement.
 
 ## 4. A file you have already edited