carrick 0.3.86 → 0.3.88

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