carrick 0.3.86 → 0.3.88

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

@@ -33,6 +33,7 @@ import ts from 'typescript';
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { collectSpecifiers, isRelative, packageNameOf } from './specifiers.js';
+import { repairDanglingImports } from './repair-dangling.js';
 import { findDisqualifyingTopTypes, provenanceOf, } from './deep-walk.js';
 export function selfCheckStub(args) {
     const typesDir = path.join(args.stubDir, 'types');
@@ -56,7 +57,18 @@ export function selfCheckStub(args) {
         linked = true;
     }
     try {
-        return runSelfCheck(args, treeFiles);
+        const first = runSelfCheck(args, treeFiles);
+        // carrick#1397: an emitted declaration that imports a module the checkout
+        // does not have makes every alias reaching that file unpublishable, however
+        // much of it resolved. Repair the file — drop the import, write `unknown`
+        // where its names were used — and check the tree again. The second pass is
+        // the verdict: it reads the repaired text, and a name the rewrite did not
+        // reach comes back as a `Cannot find name` diagnostic that
+        // `repairedNameFailures` folds back into the same dangling specifier.
+        const repaired = repairDanglingImports(first.internalFailuresByFile);
+        if (repaired.size === 0)
+            return first.records;
+        return runSelfCheck(args, treeFiles, repaired).records;
     }
     finally {
         // unlinkSync, not rmSync: the link target is a directory and rmSync
@@ -65,7 +77,7 @@ export function selfCheckStub(args) {
             fs.unlinkSync(linkPath);
     }
 }
-function runSelfCheck(args, treeFiles) {
+function runSelfCheck(args, treeFiles, repaired) {
     const options = {
         noEmit: true,
         strict: true,
@@ -102,14 +114,25 @@ function runSelfCheck(args, treeFiles) {
         return entry;
     };
     for (const d of diagnostics) {
-        if ((d.code !== 2307 && d.code !== 2792) || !d.file)
+        if (!d.file)
             continue;
+        const abs = path.resolve(d.file.fileName);
         const msg = ts.flattenDiagnosticMessageText(d.messageText, ' ');
+        // A name the repair did not reach: the import that bound it is gone, so
+        // the module is no longer reported missing and only this diagnostic is
+        // left to say the tree is incomplete. Blamed on the specifier that bound
+        // the name, which is the sentence a reader can act on (carrick#1397).
+        const orphaned = repairedNameFailure(repaired, abs, d, msg);
+        if (orphaned) {
+            bucketIn(failuresByFile, abs).internal.add(orphaned);
+            continue;
+        }
+        if (d.code !== 2307 && d.code !== 2792)
+            continue;
         const m = /Cannot find module '([^']+)'/.exec(msg);
         if (!m)
             continue;
         const spec = m[1];
-        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
@@ -158,7 +181,40 @@ function runSelfCheck(args, treeFiles) {
                 surfaceFailuresByAlias,
             }));
     }
-    return records;
+    const internalFailuresByFile = new Map();
+    for (const [file, failures] of failuresByFile) {
+        // The surface's own failures are a literal anchor's pasted text
+        // (carrick#1361), not a declaration with an import to drop.
+        if (file === surfaceAbs || failures.internal.size === 0)
+            continue;
+        // A file already repaired has had its turn: repairing it again would chase
+        // its own leftover diagnostics.
+        if (repaired?.has(file))
+            continue;
+        internalFailuresByFile.set(file, failures.internal);
+    }
+    return { records, internalFailuresByFile };
+}
+/**
+ * The specifier to blame for a `Cannot find name` diagnostic in a file this
+ * capture repaired, when the name is one the dropped import bound.
+ *
+ * The rewrite writes `unknown` at every type position it can reach; a use it
+ * cannot — and there should be none, since a position where `unknown` is not a
+ * type leaves the whole file untouched — would otherwise read as a clean tree,
+ * because the module that is missing is no longer imported to be reported.
+ * Fail closed: the alias keeps the refusal it had before the repair.
+ */
+function repairedNameFailure(repaired, file, diagnostic, message) {
+    if (!repaired || diagnostic.code !== 2304)
+        return undefined;
+    const entry = repaired.get(file);
+    if (!entry)
+        return undefined;
+    const named = /Cannot find name '([^']+)'/.exec(message);
+    if (!named || !entry.names.includes(named[1]))
+        return undefined;
+    return entry.specifiers[0];
 }
 /**
  * Position -> the alias whose `export type` statement span covers it, for

package/sidecar/dist/src/definition-resolver.d.ts

@@ -12,6 +12,13 @@
  *  - `expanded`: the fully *structural* form, with every named member type
  *    inlined to its member structure, recursively.
  *
+ * An alias whose own type did not resolve produces neither: the tree is read
+ * with nothing installed, so a reference that leaves it lands on TypeScript's
+ * unresolved-reference placeholder, which the compiler prints as the reference
+ * text rather than as `any` (see `isUnresolvedReference`). Both forms are then
+ * the top type, which is what every downstream rule about an empty answer is
+ * written to refuse.
+ *
  * `type.getText(node, NoTruncation)` does NOT inline named members — the
  * compiler prints a referenced type by its symbol name when that symbol is in
  * scope (`total: Money`, not `total: { amountCents: number; currency: string }`).

package/sidecar/dist/src/definition-resolver.js

@@ -12,6 +12,13 @@
  *  - `expanded`: the fully *structural* form, with every named member type
  *    inlined to its member structure, recursively.
  *
+ * An alias whose own type did not resolve produces neither: the tree is read
+ * with nothing installed, so a reference that leaves it lands on TypeScript's
+ * unresolved-reference placeholder, which the compiler prints as the reference
+ * text rather than as `any` (see `isUnresolvedReference`). Both forms are then
+ * the top type, which is what every downstream rule about an empty answer is
+ * written to refuse.
+ *
  * `type.getText(node, NoTruncation)` does NOT inline named members — the
  * compiler prints a referenced type by its symbol name when that symbol is in
  * scope (`total: Money`, not `total: { amountCents: number; currency: string }`).
@@ -26,7 +33,7 @@
 import * as path from 'node:path';
 import * as fs from 'node:fs';
 import { Project, Node } from 'ts-morph';
-import { expandTypeStructural } from './type-structural-expander.js';
+import { expandTypeStructural, } from './type-structural-expander.js';
 export class DefinitionResolver {
     project;
     constructor(options) {
@@ -71,7 +78,10 @@ export class DefinitionResolver {
             }
             const results = [];
             for (const alias of aliases) {
-                const result = this.resolveAlias(surface, alias);
+                const result = this.resolveAlias(surface, alias, {
+                    program: stubProject.getProgram().compilerObject,
+                    repoRoot: stubDir,
+                });
                 if (result) {
                     results.push(result);
                 }
@@ -89,7 +99,7 @@ export class DefinitionResolver {
     /**
      * Resolve a single alias: the original text and the structural form.
      */
-    resolveAlias(sourceFile, alias) {
+    resolveAlias(sourceFile, alias, origin) {
         const decl = sourceFile.getTypeAlias(alias) ??
             sourceFile.getInterface(alias) ??
             sourceFile.getClass(alias) ??
@@ -98,6 +108,12 @@ export class DefinitionResolver {
             return null;
         try {
             const type = decl.getType();
+            // An alias whose own type did not resolve answers the top type it IS,
+            // not the reference the compiler echoes for it (carrick#1444).
+            if (isUnresolvedReference(type)) {
+                this.log(`${alias} names a type this tree cannot resolve; answering any`);
+                return { type_alias: alias, definition: 'any', expanded: 'any' };
+            }
             // As-written form: prefer the alias target's own declaration (the real
             // `interface Order {...}` in the tree) over the surface's import-type
             // line, so named shapes read naturally. Fall back to the alias line for
@@ -118,7 +134,7 @@ export class DefinitionResolver {
                 }
             }
             // Structural form — every named member inlined to its shape.
-            const expanded = expandTypeStructural(type);
+            const expanded = expandTypeStructural(type, origin);
             return { type_alias: alias, definition, expanded };
         }
         catch (err) {
@@ -133,6 +149,29 @@ export class DefinitionResolver {
         console.error(`[sidecar:definition-resolver:error] ${message}`);
     }
 }
+/**
+ * True when a type is TypeScript's unresolved-reference placeholder:
+ * `TypeFlags.Any` carrying the internal `intrinsicName === 'error'` (stable
+ * since TS 1.x). `capture/deep-walk.ts` tests the same two facts for the same
+ * reason; the seam forbids importing it from here, so the pin is that both read
+ * the flag and the intrinsic name and nothing else.
+ *
+ * The compiler prints this placeholder as the reference text it FAILED to
+ * resolve, never as `any`. That print is what makes an unresolvable alias read
+ * as a confident name: an instantiation over a dependency's internal generics
+ * has no members in it and resolves nowhere, and every scanner-side rule that
+ * refuses an empty answer asks the TEXT (`text_is_bare_top_type`), so nothing
+ * downstream can tell the difference (carrick#1444).
+ *
+ * Asked only of the alias's own type. At a member position the same echo is
+ * the producer's own vocabulary (`status: OrderStatus`) inside a shape that
+ * otherwise resolved, and replacing it with `any` would remove a name a reader
+ * can look up in the producing repo.
+ */
+function isUnresolvedReference(type) {
+    return (type.isAny() &&
+        type.compilerType.intrinsicName === 'error');
+}
 /** All .d.ts files under a directory, depth-first, deterministic order. */
 function walkDtsFiles(dir) {
     const out = [];

package/sidecar/dist/src/origin.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Where a declaration comes from: the user's own source, or the runtime and
+ * the packages it installed.
+ *
+ * One module because more than one layer asks the question — the inference
+ * path (`type-inferrer.ts`, deciding whether a type is framework machinery)
+ * and the structural printer (`type-structural-expander.ts`, deciding whether
+ * to inline a type's members or keep it by name). They must answer it the same
+ * way or one layer inlines what the other suppresses.
+ *
+ * The capture side keeps its own copy in `capture/machinery.ts`: that seam
+ * forbids importing anything but node builtins, `typescript` and its own
+ * bundle, so the two are kept in lockstep by `machinery-indicator-mirror.test.ts`
+ * rather than by sharing this module.
+ */
+import type { ts } from 'ts-morph';
+/**
+ * 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 declare function isExternalOrigin(program: ts.Program, sourceFile: ts.SourceFile, repoRoot: string): boolean;

package/sidecar/dist/src/origin.js

@@ -0,0 +1,86 @@
+/**
+ * Where a declaration comes from: the user's own source, or the runtime and
+ * the packages it installed.
+ *
+ * One module because more than one layer asks the question — the inference
+ * path (`type-inferrer.ts`, deciding whether a type is framework machinery)
+ * and the structural printer (`type-structural-expander.ts`, deciding whether
+ * to inline a type's members or keep it by name). They must answer it the same
+ * way or one layer inlines what the other suppresses.
+ *
+ * The capture side keeps its own copy in `capture/machinery.ts`: that seam
+ * forbids importing anything but node builtins, `typescript` and its own
+ * bundle, so the two are kept in lockstep by `machinery-indicator-mirror.test.ts`
+ * rather than by sharing this module.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+/**
+ * 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 + '/');
+}

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

@@ -17,7 +17,7 @@
  * (redirects, 204s), the LLM emits null and we fall back to the containing
  * function's return type.
  */
-import { Project, ts } from 'ts-morph';
+import { Project } from 'ts-morph';
 import type { InferRequestItem, InferResult, ExtractionConfig } from './types.js';
 /**
  * Strongly-discriminating member names of HTTP transport machinery — the
@@ -38,35 +38,6 @@ import type { InferRequestItem, InferResult, ExtractionConfig } from './types.js
  * test (`machinery-indicator-mirror.test.ts`) asserts the two sets stay equal.
  */
 export declare const MACHINERY_MEMBER_INDICATORS: Set<string>;
-/**
- * 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 declare function isExternalOrigin(program: ts.Program, sourceFile: ts.SourceFile, repoRoot: string): boolean;
 /**
  * Options for TypeInferrer construction
  */
@@ -99,6 +70,13 @@ export declare class TypeInferrer {
     private readonly packageOf;
     private readonly repoRoot;
     constructor(options: TypeInferrerOptions);
+    /**
+     * 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.
+     */
+    private expandOrigin;
     /**
      * Infer types for the given requests
      *

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
@@ -4518,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