carrick 0.3.106 → 0.3.108

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

@@ -34,13 +34,13 @@ import { entryRelativeSpecifier, resolveAnchor } from './anchors.js';
 import { findAugmentationFiles } from './augmentations.js';
 import { installedVersions, lockfileVersions } from './lockfile.js';
 import { rewriteEmittedSpecifiers } from './paths-rewrite.js';
-import { typesPackageOf, withInstalledPackages } from './installed-package.js';
+import { installedPackageSpecifier, typesPackageOf, withInstalledPackages } from './installed-package.js';
 import { selfCheckStub } from './self-check.js';
 import { collectSpecifiers, isRelative, packageNameOf } from './specifiers.js';
 import { DenoProject, findDenoConfig } from './deno-project.js';
 import { emitsAlike, ProjectGraph } from './project-references.js';
 import { findServiceTsconfig } from './service-config.js';
-import { placeEmittedTree } from './outside-root.js';
+import { placeEmittedTree, surfaceModuleInTree } from './outside-root.js';
 import { WriteGuard } from './guarded-fs.js';
 export { DenoProject, findDenoConfig } from './deno-project.js';
 export { serviceConfigPath } from './project-references.js';
@@ -256,7 +256,8 @@ export function captureStub(opts) {
     }
     // ---- Phase A: analysis program over placeholder entry + anchor sources ----
     let resolved;
-    const analysisCtx = { repoRoot, entryDir: path.dirname(entryPath), entryPath, guard };
+    const progress = opts.onProgress ?? (() => { });
+    const analysisCtx = { repoRoot, entryDir: path.dirname(entryPath), entryPath, guard, progress };
     try {
         resolved = ownerGroups && emitProject
             ? resolveAnchorsByOwner(opts, ownerGroups, emitProject, analysisCtx, errors)
@@ -277,14 +278,9 @@ export function captureStub(opts) {
     }
     const scratch = WriteGuard.scratch('carrick-capture-v2-');
     const staging = scratch.dir;
-    const emitted = new Map();
-    // Input .d.ts files (ambient stubs, augmentation declarations, local
-    // hand-written declarations in the import closure) are never re-emitted by
-    // tsc; they must ship verbatim or the tree's references to them dangle.
-    const declarationSources = new Map();
-    const sourceByEmitted = new Map();
-    let emitPartial = false;
+    let written;
     try {
+        progress('emit', 'emitting declarations');
         guard.writeFile(entryPath, entryLines.join('\n') + '\n');
         const emitOptions = {
             ...parsed.options,
@@ -300,35 +296,13 @@ export function captureStub(opts) {
             outDir: staging,
             rootDir: entryDir,
         };
-        const program = ts.createProgram([entryPath, ...augmentationSources], emitOptions, deno?.host(emitOptions));
-        const emitResult = program.emit(undefined, (fileName, text, _bom, _error, sources) => {
-            emitted.set(fileName, text);
-            if (sources?.[0])
-                sourceByEmitted.set(path.relative(staging, fileName).split(path.sep).join('/'), sources[0].fileName);
-        }, undefined, 
-        /* emitOnlyDtsFiles */ true);
-        // emitSkipped is PER-PROGRAM even when only one file's declaration emit
-        // failed (e.g. TS4023 from a hand-rolled ambient stub shadowing a real
-        // package): every other file's .d.ts was still written to the callback.
-        // Fail wholesale only when nothing at all emitted; otherwise keep the
-        // emitted subset and demote exactly the aliases it cannot support.
-        if (emitResult.emitSkipped && emitted.size === 0) {
-            return fail(stubDir, packageName, ['declaration emit was skipped']);
-        }
-        emitPartial = emitResult.emitSkipped;
-        for (const d of emitResult.diagnostics) {
-            errors.push(ts.flattenDiagnosticMessageText(d.messageText, '\n'));
-        }
-        for (const sourceFile of program.getSourceFiles()) {
-            if (!sourceFile.isDeclarationFile)
-                continue;
-            const abs = path.resolve(sourceFile.fileName);
-            const rel = path.relative(entryDir, abs).split(path.sep).join('/');
-            if (rel.startsWith('..') || rel.includes('node_modules/'))
-                continue;
-            declarationSources.set(rel, sourceFile.getFullText());
-            sourceByEmitted.set(rel, abs);
-        }
+        written = emitDeclarations({
+            rootNames: [entryPath, ...augmentationSources],
+            options: emitOptions,
+            host: deno?.host(emitOptions),
+            staging,
+            entryDir,
+        });
     }
     catch (err) {
         return fail(stubDir, packageName, [err instanceof Error ? err.message : String(err)]);
@@ -338,6 +312,9 @@ export function captureStub(opts) {
             guard.unlink(entryPath);
         scratch.guard.remove(staging);
     }
+    const { emitted, declarationSources, sourceByEmitted } = written;
+    const emitPartial = written.partial;
+    errors.push(...written.diagnostics);
     // ---- Partial-emit recovery ----
     // The corpus-2 notifications-svc shape: one file's declaration emit was
     // skipped but the rest of the tree emitted fine. Keep the tree; demote any
@@ -351,7 +328,14 @@ export function captureStub(opts) {
     if (emitPartial) {
         errors.push(`declaration emit was partial: kept ${emitted.size} emitted file(s); ` +
             'aliases referencing unemitted modules are demoted to structural_fallback');
-        resolved = demoteDanglingAliases({ resolved, emitted, declarationSources, staging, surfaceDeclaration });
+        resolved = demoteDanglingAliases({
+            resolved,
+            emitted,
+            declarationSources,
+            staging,
+            entryDir,
+            surfaceDeclaration,
+        });
     }
     // ---- Relocate the emitted tree into the stub package ----
     const typesDir = path.join(stubDir, 'types');
@@ -483,6 +467,7 @@ export function captureStub(opts) {
         target: parsed.options.target !== undefined ? ts.ScriptTarget[parsed.options.target] : undefined,
     }, null, 2) + '\n');
     // ---- Capture-time self-check (per-alias closure attribution) ----
+    progress('self-check', 'checking the stub');
     const aliases = selfCheckStub({
         guard: stubGuard,
         stubDir,
@@ -520,43 +505,99 @@ export function captureStub(opts) {
     };
 }
 /**
- * Partial-emit demotion: with the set of modules that DID reach the tree
- * (emitted .d.ts plus verbatim declaration sources), demote every anchor
- * whose alias text references a relative module absent from that set, and
+ * Phase B: build the program of the final entry and emit its declarations.
+ *
+ * A function of its own so that its program dies with it (carrick#1916). The
+ * program is as large as the service, and nothing after the emit reads it:
+ * what the capture needs is the text returned here. While the emit ran inside
+ * `captureStub`, that one long function's frame went on holding the program
+ * for as long as the capture ran, so the self-check loaded its own program
+ * beside it; on a 2,345-file service that was 1,290 MB of a 2,741 MB peak.
+ *
+ * The caller builds the options and the host. A host is held by its program
+ * and holds none itself, so the caller keeping one keeps no program alive.
+ *
+ * Throws when the emit was skipped and wrote nothing.
+ */
+function emitDeclarations(args) {
+    const emitted = new Map();
+    const declarationSources = new Map();
+    const sourceByEmitted = new Map();
+    const program = ts.createProgram(args.rootNames, args.options, args.host);
+    const emitResult = program.emit(undefined, (fileName, text, _bom, _error, sources) => {
+        emitted.set(fileName, text);
+        if (sources?.[0])
+            sourceByEmitted.set(path.relative(args.staging, fileName).split(path.sep).join('/'), sources[0].fileName);
+    }, undefined, 
+    /* emitOnlyDtsFiles */ true);
+    // emitSkipped is PER-PROGRAM even when only one file's declaration emit
+    // failed (e.g. TS4023 from a hand-rolled ambient stub shadowing a real
+    // package): every other file's .d.ts was still written to the callback.
+    // Fail wholesale only when nothing at all emitted; otherwise keep the
+    // emitted subset and demote exactly the aliases it cannot support.
+    if (emitResult.emitSkipped && emitted.size === 0) {
+        throw new Error('declaration emit was skipped');
+    }
+    for (const sourceFile of program.getSourceFiles()) {
+        if (!sourceFile.isDeclarationFile)
+            continue;
+        const abs = path.resolve(sourceFile.fileName);
+        const rel = path.relative(args.entryDir, abs).split(path.sep).join('/');
+        if (rel.startsWith('..') || rel.includes('node_modules/'))
+            continue;
+        declarationSources.set(rel, sourceFile.getFullText());
+        sourceByEmitted.set(rel, abs);
+    }
+    return {
+        emitted,
+        declarationSources,
+        sourceByEmitted,
+        partial: emitResult.emitSkipped,
+        diagnostics: emitResult.diagnostics.map((d) => ts.flattenDiagnosticMessageText(d.messageText, '\n')),
+    };
+}
+/**
+ * Partial-emit demotion: demote every anchor whose alias text names, by a
+ * relative or an absolute path, a module the stub will not resolve, and
  * rewrite the demoted aliases' lines in the emitted surface to `unknown`.
+ *
+ * A path resolves when the tree holds its module (`surfaceModuleInTree`: an
+ * emitted declaration inside rootDir or outside it, or a verbatim declaration
+ * source), read from where the entry was written, not from where the surface
+ * sits in the tree. An absolute path into an installed package resolves too
+ * (carrick#1773): no emit writes that module, and the specifier rewrite turns
+ * the path into the package's bare specifier and a pin, as it does when the
+ * emit is whole. A relative path into a package is not rewritten, so it stays
+ * demoted (carrick#1857).
+ *
  * Anchors already demoted stay as they are; anchors whose text is
  * self-contained (node-builder structural prints, literal object text) are
  * untouched even when their source file failed to emit — their surface line
  * references nothing that can dangle.
  */
 function demoteDanglingAliases(args) {
-    // Extensionless, entryDir-relative POSIX module ids present in the tree.
-    const treeModules = new Set();
-    let surfaceKey;
-    for (const fileName of args.emitted.keys()) {
-        const rel = path.relative(args.staging, fileName).split(path.sep).join('/');
-        if (path.basename(rel) === args.surfaceDeclaration)
-            surfaceKey = fileName;
-        if (rel.endsWith('.d.ts'))
-            treeModules.add(rel.slice(0, -'.d.ts'.length));
-    }
-    for (const rel of args.declarationSources.keys()) {
-        if (rel.endsWith('.d.ts'))
-            treeModules.add(rel.slice(0, -'.d.ts'.length));
-    }
-    // Deno's temporary surface lives in the cache inside the emitted tree.
-    const surfaceDir = surfaceKey ? path.posix.dirname(path.relative(args.staging, surfaceKey).split(path.sep).join('/')) : '.';
-    const moduleInTree = (spec) => {
-        const id = path.posix.normalize(path.posix.join(surfaceDir, spec));
-        if (id.startsWith('..'))
-            return false;
-        return treeModules.has(id) || treeModules.has(`${id}/index`);
+    const surfaceKey = [...args.emitted.keys()].find((fileName) => path.basename(fileName) === args.surfaceDeclaration);
+    const inTree = surfaceModuleInTree({
+        emitted: args.emitted.keys(),
+        declarationSources: args.declarationSources.keys(),
+        staging: args.staging,
+        entryDir: args.entryDir,
+        surfaceDeclaration: args.surfaceDeclaration,
+    });
+    const resolves = new Map();
+    const moduleResolves = (spec) => {
+        let answer = resolves.get(spec);
+        if (answer === undefined) {
+            answer = inTree(spec) || (spec.startsWith('/') && installedPackageSpecifier(spec) !== undefined);
+            resolves.set(spec, answer);
+        }
+        return answer;
     };
     const demoted = new Set();
     const next = args.resolved.map((anchor) => {
         if (anchor.failureReason !== undefined)
             return anchor;
-        const dangling = [...collectSpecifiers(anchor.aliasText)].find((spec) => isRelative(spec) && !moduleInTree(spec));
+        const dangling = [...collectSpecifiers(anchor.aliasText)].find((spec) => isRelative(spec) && !moduleResolves(spec));
         if (dangling === undefined)
             return anchor;
         demoted.add(anchor.request.alias);
@@ -644,6 +685,7 @@ function resolveAnchors(opts, parsed, ctx, deno) {
     }
     ctx.guard.writeFile(ctx.entryPath, placeholderLines.join('\n') + '\n');
     try {
+        ctx.progress('program', 'building the program the anchors are read in');
         const anchorSources = [
             ...new Set(opts.anchors
                 .flatMap((a) => (a.source_file ? [path.join(ctx.repoRoot, a.source_file)] : []))),
@@ -653,6 +695,11 @@ function resolveAnchors(opts, parsed, ctx, deno) {
             noEmit: true,
         };
         const program = ts.createProgram([ctx.entryPath, ...anchorSources, ...(deno?.globals ?? [])], options, deno?.host(options));
+        // The checker binds every file of the program when it is first asked for,
+        // which the first anchor would otherwise do: asked for here, so that the
+        // report below says the program is whole before any anchor is read.
+        program.getTypeChecker();
+        ctx.progress('anchors', `0 of ${opts.anchors.length}`);
         const entrySource = program.getSourceFile(ctx.entryPath);
         const placeholders = new Map();
         if (entrySource) {
@@ -661,6 +708,20 @@ function resolveAnchors(opts, parsed, ctx, deno) {
                     placeholders.set(stmt.name.text, stmt);
             }
         }
+        // A module specifier as the entry resolves it, under the program's own
+        // resolution (the Deno graph's, for a Deno service). Asked once per
+        // specifier: every anchor of a module asks for the same one.
+        const entryMode = entrySource?.impliedNodeFormat;
+        const fromEntry = new Map();
+        const resolveFromEntry = (specifier) => {
+            if (!fromEntry.has(specifier)) {
+                fromEntry.set(specifier, (deno
+                    ? deno.resolve(specifier, ctx.entryPath, options)
+                    : ts.resolveModuleName(specifier, ctx.entryPath, options, ts.sys, undefined, undefined, entryMode)
+                        .resolvedModule)?.resolvedFileName);
+            }
+            return fromEntry.get(specifier);
+        };
         // A literal anchor whose text is a bare identifier resolves through a
         // sibling symbol anchor's module when one names the same symbol.
         const siblingSymbolSpecs = new Map();
@@ -668,23 +729,20 @@ function resolveAnchors(opts, parsed, ctx, deno) {
             if (anchor.kind !== 'symbol')
                 continue;
             if (!siblingSymbolSpecs.has(anchor.symbol_name)) {
-                siblingSymbolSpecs.set(anchor.symbol_name, entryRelativeSpecifier(ctx.entryDir, ctx.repoRoot, anchor.source_file));
+                siblingSymbolSpecs.set(anchor.symbol_name, entryRelativeSpecifier(ctx.entryDir, ctx.repoRoot, anchor.source_file, resolveFromEntry));
             }
         }
-        // A module specifier as the entry resolves it, under the program's own
-        // resolution (the Deno graph's, for a Deno service).
-        const entryMode = entrySource?.impliedNodeFormat;
-        const resolveFromEntry = (specifier) => (deno
-            ? deno.resolve(specifier, ctx.entryPath, options)
-            : ts.resolveModuleName(specifier, ctx.entryPath, options, ts.sys, undefined, undefined, entryMode)
-                .resolvedModule)?.resolvedFileName;
-        return opts.anchors.map((request) => resolveAnchor(program, request, {
-            repoRoot: ctx.repoRoot,
-            entryDir: ctx.entryDir,
-            placeholder: placeholders.get(request.alias),
-            siblingSymbolSpecs,
-            resolveFromEntry,
-        }));
+        return opts.anchors.map((request, index) => {
+            const anchor = resolveAnchor(program, request, {
+                repoRoot: ctx.repoRoot,
+                entryDir: ctx.entryDir,
+                placeholder: placeholders.get(request.alias),
+                siblingSymbolSpecs,
+                resolveFromEntry,
+            });
+            ctx.progress('anchors', `${index + 1} of ${opts.anchors.length}`);
+            return anchor;
+        });
     }
     finally {
         if (fs.existsSync(ctx.entryPath))

package/sidecar/dist/src/capture/installed-package.d.ts

@@ -41,6 +41,8 @@ export interface InstalledPackageSpecifier {
  * deciding whether a runtime name is covered by a pinned types package.
  */
 export declare function typesPackageOf(name: string): string;
+/** A path or specifier without its script, source or declaration extension. */
+export declare function withoutExtension(subpath: string): string;
 /**
  * A compiler host that also resolves the packages an absolute specifier was
  * rewritten into, each from its own install directory. The capture's

package/sidecar/dist/src/capture/installed-package.js

@@ -101,7 +101,8 @@ function existingFile(spec) {
     }
     return undefined;
 }
-function withoutExtension(subpath) {
+/** A path or specifier without its script, source or declaration extension. */
+export function withoutExtension(subpath) {
     return subpath.replace(/(?:\.d)?\.(?:ts|mts|cts|js|mjs|cjs|tsx|jsx)$/, '');
 }
 /** Every string target an exports value names, whatever its conditions. */

package/sidecar/dist/src/capture/outside-root.d.ts

@@ -39,3 +39,22 @@ export declare function placeEmittedTree(args: {
     entryDir: string;
     surfaceDeclaration: string;
 }): PlacedTree;
+/**
+ * A test for whether the tree holds the module a specifier in the surface
+ * entry names (carrick#1773).
+ *
+ * The specifier is read the way the placement above reads one: resolved from
+ * the surface's SOURCE-side directory, so an absolute path stays what it is
+ * and `../` leaves rootDir, then looked up among the source-side paths of the
+ * declarations the tree holds. Those are every emitted declaration, inside
+ * rootDir or placed under `OUTSIDE_DIR`, and the declaration sources shipped
+ * verbatim (`declarationSources`, relative to rootDir).
+ */
+export declare function surfaceModuleInTree(args: {
+    /** tsc's file name for each emitted declaration. */
+    emitted: Iterable<string>;
+    declarationSources: Iterable<string>;
+    staging: string;
+    entryDir: string;
+    surfaceDeclaration: string;
+}): (spec: string) => boolean;

package/sidecar/dist/src/capture/outside-root.js

@@ -15,6 +15,7 @@
  * A capture whose program stays inside rootDir is placed exactly as before.
  */
 import * as path from 'node:path';
+import { withoutExtension } from './installed-package.js';
 import { rewriteSpecifiers } from './specifiers.js';
 /** Tree directory holding declarations of sources outside rootDir. */
 export const OUTSIDE_DIR = '__outside__';
@@ -31,13 +32,12 @@ export function placeEmittedTree(args) {
     const sourceSideOf = new Map();
     const outsideFiles = [];
     for (const fileName of args.emitted.keys()) {
+        sourceSideOf.set(fileName, sourceSidePath(fileName, args.staging, args.entryDir));
         const rel = posix(path.relative(args.staging, fileName));
         if (escapes(rel)) {
             outsideFiles.push(fileName);
-            sourceSideOf.set(fileName, path.resolve(fileName));
             continue;
         }
-        sourceSideOf.set(fileName, path.join(args.entryDir, rel));
         relOf.set(fileName, path.basename(rel) === args.surfaceDeclaration ? 'surface.d.ts' : rel);
     }
     const outside = new Map();
@@ -82,6 +82,43 @@ export function placeEmittedTree(args) {
     }
     return { relOf, textOf, outside, rewrites };
 }
+/**
+ * Where tsc would have written an emitted declaration in the source tree. A
+ * file under the staging dir mirrors rootDir; one outside it arrived at its
+ * source's own path.
+ */
+function sourceSidePath(fileName, staging, entryDir) {
+    const rel = posix(path.relative(staging, fileName));
+    return escapes(rel) ? path.resolve(fileName) : path.join(entryDir, rel);
+}
+/**
+ * A test for whether the tree holds the module a specifier in the surface
+ * entry names (carrick#1773).
+ *
+ * The specifier is read the way the placement above reads one: resolved from
+ * the surface's SOURCE-side directory, so an absolute path stays what it is
+ * and `../` leaves rootDir, then looked up among the source-side paths of the
+ * declarations the tree holds. Those are every emitted declaration, inside
+ * rootDir or placed under `OUTSIDE_DIR`, and the declaration sources shipped
+ * verbatim (`declarationSources`, relative to rootDir).
+ */
+export function surfaceModuleInTree(args) {
+    const held = new Set();
+    let surfaceDir = args.entryDir;
+    for (const fileName of args.emitted) {
+        const sourceSide = sourceSidePath(fileName, args.staging, args.entryDir);
+        if (path.basename(sourceSide) === args.surfaceDeclaration)
+            surfaceDir = path.dirname(sourceSide);
+        held.add(sourceSide.replace(DECLARATION_EXT, ''));
+    }
+    for (const rel of args.declarationSources) {
+        held.add(path.join(args.entryDir, rel).replace(DECLARATION_EXT, ''));
+    }
+    return (spec) => {
+        const target = path.resolve(surfaceDir, withoutExtension(spec));
+        return held.has(target) || held.has(path.join(target, 'index'));
+    };
+}
 function posix(p) {
     return p.split(path.sep).join('/');
 }

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

@@ -32,7 +32,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 { collectSpecifiers, declarationCandidates, isDeclarationFileName, isRelative, packageNameOf, } from './specifiers.js';
 import { repairDanglingImports } from './repair-dangling.js';
 import { findDisqualifyingTopTypes, findUnresolvedPlaceholders, isErrorPlaceholder, provenanceOf, unemittedModuleProvenance, unresolvedInTreeProvenance, } from './deep-walk.js';
 export function selfCheckStub(args) {
@@ -43,7 +43,7 @@ export function selfCheckStub(args) {
             const p = path.join(dir, entry.name);
             if (entry.isDirectory())
                 walk(p);
-            else if (entry.name.endsWith('.d.ts'))
+            else if (isDeclarationFileName(entry.name))
                 treeFiles.push(p);
         }
     };
@@ -464,15 +464,5 @@ function resolveTreeSpecifier(fromAbs, spec, tree) {
     if (!isRelative(spec))
         return undefined;
     const base = path.resolve(path.dirname(fromAbs), spec);
-    const candidates = [
-        `${base}.d.ts`,
-        path.join(base, 'index.d.ts'),
-        base.endsWith('.js') ? `${base.slice(0, -3)}.d.ts` : undefined,
-        base, // already .d.ts
-    ].filter((c) => c !== undefined);
-    for (const candidate of candidates) {
-        if (tree.has(candidate))
-            return candidate;
-    }
-    return undefined;
+    return declarationCandidates(base).find((candidate) => tree.has(candidate));
 }

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

@@ -4,6 +4,20 @@
  * pattern matching for the post-emit rewrite pass.
  */
 export declare function isRelative(spec: string): boolean;
+/** A declaration file of any module format: `.d.ts`, `.d.mts`, `.d.cts`. */
+export declare function isDeclarationFileName(name: string): boolean;
+/**
+ * The declaration files a relative specifier can name in a stub's tree, in
+ * the order tried, given the path it resolves to from the file that holds it.
+ *
+ * A specifier names its module with no extension (`./a`: `a.d.ts`, or the
+ * directory's `index.d.ts`), by the file the module compiles to (`./a.js`:
+ * `a.d.ts`, `./a.mjs`: `a.d.mts`, `./a.cjs`: `a.d.cts`), or by the
+ * declaration file itself. The surface names an anchor's module the second
+ * way where the first does not resolve (carrick#1911), and so does any source
+ * written for `node16`..`nodenext`.
+ */
+export declare function declarationCandidates(resolved: string): string[];
 /** zod -> zod, @scope/pkg/sub -> @scope/pkg, pkg/sub -> pkg */
 export declare function packageNameOf(spec: string): string;
 /** Extract every module specifier mentioned in a .d.ts text: `from "x"`,

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

@@ -3,9 +3,34 @@
  * declaration text, external/internal classification, and tsconfig-`paths`
  * pattern matching for the post-emit rewrite pass.
  */
+import * as path from 'node:path';
 export function isRelative(spec) {
     return spec.startsWith('./') || spec.startsWith('../') || spec.startsWith('/');
 }
+/** A declaration file of any module format: `.d.ts`, `.d.mts`, `.d.cts`. */
+export function isDeclarationFileName(name) {
+    return /\.d\.[cm]?ts$/.test(name);
+}
+/**
+ * The declaration files a relative specifier can name in a stub's tree, in
+ * the order tried, given the path it resolves to from the file that holds it.
+ *
+ * A specifier names its module with no extension (`./a`: `a.d.ts`, or the
+ * directory's `index.d.ts`), by the file the module compiles to (`./a.js`:
+ * `a.d.ts`, `./a.mjs`: `a.d.mts`, `./a.cjs`: `a.d.cts`), or by the
+ * declaration file itself. The surface names an anchor's module the second
+ * way where the first does not resolve (carrick#1911), and so does any source
+ * written for `node16`..`nodenext`.
+ */
+export function declarationCandidates(resolved) {
+    const output = /\.([cm]?)jsx?$/.exec(resolved);
+    return [
+        `${resolved}.d.ts`,
+        path.join(resolved, 'index.d.ts'),
+        ...(output ? [`${resolved.slice(0, output.index)}.d.${output[1]}ts`] : []),
+        resolved,
+    ];
+}
 /** zod -> zod, @scope/pkg/sub -> @scope/pkg, pkg/sub -> pkg */
 export function packageNameOf(spec) {
     const parts = spec.split('/');

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

@@ -26,11 +26,12 @@
  * inference path in `type-inferrer.ts`), which walks the resolved `Type` and
  * rebuilds the inlined text.
  *
- * Each resolve call builds its own throwaway in-memory project over the stub
- * tree, so the warm sidecar's long-lived project never sees stub files and
- * cannot accumulate stale trees across requests.
+ * Each resolve call builds its own throwaway project over the stub tree and
+ * reads nothing else: not the service's project, and not whether the sidecar
+ * was ever initialised. So the request costs what the stub costs, in a process
+ * that has built nothing as in one that has (carrick#1927), and the sidecar's
+ * long-lived project never sees stub files.
  */
-import { Project } from 'ts-morph';
 export interface ResolvedDefinition {
     type_alias: string;
     /** Original declaration text as written (preserves named types) */
@@ -39,10 +40,6 @@ export interface ResolvedDefinition {
     expanded: string;
 }
 export declare class DefinitionResolver {
-    private readonly project;
-    constructor(options: {
-        project: Project;
-    });
     /**
      * Resolve surface aliases from a capture stub package directory
      * (`<stub_dir>/types/surface.d.ts` + its declaration tree).

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

@@ -26,19 +26,17 @@
  * inference path in `type-inferrer.ts`), which walks the resolved `Type` and
  * rebuilds the inlined text.
  *
- * Each resolve call builds its own throwaway in-memory project over the stub
- * tree, so the warm sidecar's long-lived project never sees stub files and
- * cannot accumulate stale trees across requests.
+ * Each resolve call builds its own throwaway project over the stub tree and
+ * reads nothing else: not the service's project, and not whether the sidecar
+ * was ever initialised. So the request costs what the stub costs, in a process
+ * that has built nothing as in one that has (carrick#1927), and the sidecar's
+ * long-lived project never sees stub files.
  */
 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';
 export class DefinitionResolver {
-    project;
-    constructor(options) {
-        this.project = options.project;
-    }
     /**
      * Resolve surface aliases from a capture stub package directory
      * (`<stub_dir>/types/surface.d.ts` + its declaration tree).

package/sidecar/dist/src/function-line-index.d.ts

@@ -0,0 +1,30 @@
+/**
+ * The function a line names, from an index built once per source file
+ * (carrick#1915).
+ *
+ * A signature request carries only the line its function starts on, and a
+ * signature pass sends one request per unannotated slot: thousands of
+ * lookups, several per function and many per file. Answering each by walking
+ * the file's every node cost the file's size per slot, and was 81% of the
+ * pass on a 2,345-file program. Here the file is walked once, over the
+ * compiler's own nodes, and each lookup reads the few entries near its line.
+ *
+ * The index belongs to the compiler's source file node, not to the file's
+ * name: replacing a file's text gives it a new node, so a file rewritten for
+ * one reading (the unwidened reading, the retype check) and then restored is
+ * indexed again each time, and never answered from positions it no longer has.
+ */
+import { type ArrowFunction, type FunctionDeclaration, type FunctionExpression, type MethodDeclaration, type SourceFile } from 'ts-morph';
+/** The declarations a line can name. */
+export type LineFunction = FunctionDeclaration | ArrowFunction | FunctionExpression | MethodDeclaration;
+/**
+ * The function whose declaration starts at, or within `LINE_TOLERANCE` lines
+ * of, the given line: the closest, then the smallest, then the first in the
+ * file. A function starting after the line is passed over when a statement
+ * that opens on the line or after it, on a line before the function's, does
+ * not contain the function. Undefined when no function is left.
+ *
+ * These are `TypeInferrer.findFunctionByLine`'s rules, which says why each is
+ * there; this is where they are computed.
+ */
+export declare function functionAtLine(sourceFile: SourceFile, line: number): LineFunction | undefined;