carrick 0.3.72 → 0.3.73

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

@@ -35,6 +35,7 @@ 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 { selfCheckStub } from './self-check.js';
 import { collectSpecifiers, isRelative, packageNameOf } from './specifiers.js';
 import { DenoProject, findDenoConfig } from './deno-project.js';
@@ -304,13 +305,14 @@ export function captureStub(opts) {
     catch (err) {
         return fail(stubDir, packageName, [err instanceof Error ? err.message : String(err)]);
     }
-    const specifierRewrites = denoRewrites + rewriteEmittedSpecifiers({
+    const rewritten = rewriteEmittedSpecifiers({
         typesDir,
         files: emittedFiles,
         options: parsed.options,
         configPath,
         entryDir,
     });
+    const specifierRewrites = denoRewrites + rewritten.rewrites;
     // ---- Pin external deps: installed node_modules first, lockfile fallback ----
     // Externals are collected AFTER the rewrite pass: a rewritten paths
     // specifier is internal, not a dependency.
@@ -335,13 +337,20 @@ export function captureStub(opts) {
     const lockVersions = lockfileVersions(repoRoot);
     for (const name of Object.keys(deno?.pinned ?? {}))
         externalSpecs.add(name);
+    // A package an absolute specifier was rewritten into carries the version
+    // installed at that path (#1174); it may be a transitive the repo root
+    // neither installs by name nor locks.
+    for (const name of Object.keys(rewritten.pins))
+        externalSpecs.add(name);
     const pinned = {};
     const unpinned = [];
     for (const name of [...externalSpecs].sort()) {
-        const version = deno?.pinned[name] ?? installed.get(name) ?? lockVersions.get(name);
+        const version = deno?.pinned[name] ?? rewritten.pins[name] ?? installed.get(name) ?? lockVersions.get(name);
         if (version)
             pinned[name] = version;
-        else
+        // A runtime name whose declarations come from a rewritten `@types/*`
+        // package resolves through that pin.
+        else if (!rewritten.pins[typesPackageOf(name)])
             unpinned.push(name);
     }
     const dependencyRoot = deno?.config.workspaceRoot ?? repoRoot;
@@ -369,7 +378,9 @@ export function captureStub(opts) {
         pinned,
         bareCheckout,
         repoRoot: dependencyRoot,
-        compilerHost: deno ? options => deno.host(options) : undefined,
+        compilerHost: deno || Object.keys(rewritten.installs).length > 0
+            ? (options) => withInstalledPackages(options, rewritten.installs, deno ? deno.host(options) : undefined)
+            : undefined,
     });
     const fidelity = computeFidelity(aliases);
     fs.writeFileSync(path.join(stubDir, 'carrick-manifest.json'), JSON.stringify({
@@ -478,8 +489,7 @@ function resolveAnchors(opts, parsed, ctx, deno) {
     try {
         const anchorSources = [
             ...new Set(opts.anchors
-                .filter((a) => a.kind !== 'literal')
-                .map((a) => path.join(ctx.repoRoot, a.source_file))),
+                .flatMap((a) => (a.source_file ? [path.join(ctx.repoRoot, a.source_file)] : []))),
         ].filter((f) => fs.existsSync(f));
         const options = {
             ...parsed.options,

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

@@ -0,0 +1,58 @@
+/**
+ * Map an absolute path into an installed package onto the specifier a
+ * consumer of that package would write (carrick#1174).
+ *
+ * The v1 printer and the node builder name an out-of-scope type by the
+ * absolute path of its declaration file when no bare specifier reaches it
+ * from where they print. Inside a capture stub that path is both private (the
+ * checkout root, or the home directory of a runtime's npm cache) and dead:
+ * the check workspace resolves packages from the stub's pinned dependencies,
+ * never from the scanning machine's disk.
+ *
+ * The replacement is decided against the package itself, installed alone at
+ * `node_modules/<name>`, which is exactly what the check workspace sees:
+ *  1. an `exports` entry (or, without `exports`, the types entry or the file's
+ *     subpath) that resolves to the same file under bundler resolution;
+ *  2. failing that, an exported entry whose module exports the imported name
+ *     from that same file (a type in an unexported file, re-exported by the
+ *     package root);
+ *  3. failing both, the subpath as written, so the self-check reports the
+ *     specifier as unresolvable rather than the stub leaking the path.
+ *
+ * Seam: node builtins, `typescript`, and this bundle only.
+ */
+import ts from 'typescript';
+export interface InstalledPackageSpecifier {
+    /** Bare specifier: public package name plus subpath, e.g. `pkg/sub`. */
+    specifier: string;
+    /** The package's own name and real install directory (never written out). */
+    install: {
+        name: string;
+        root: string;
+    };
+    /** The package the path landed in and its installed version, when published. */
+    pin?: {
+        name: string;
+        version: string;
+    };
+}
+/**
+ * The `@types/*` package that serves a bare name's declarations, for callers
+ * deciding whether a runtime name is covered by a pinned types package.
+ */
+export declare function typesPackageOf(name: 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
+ * self-check compiles the stub against the producer's `node_modules`, which
+ * does not name a transitive package at its root; the check workspace does,
+ * because the stub pins it. Without this the self-check would fail a
+ * specifier the check resolves.
+ */
+export declare function withInstalledPackages(options: ts.CompilerOptions, installs: Record<string, string>, base?: ts.CompilerHost): ts.CompilerHost;
+/**
+ * The bare specifier for an absolute path into an installed package, or
+ * undefined when the path does not land in one. `importedName` is the first
+ * name read off the import (`import("...").Name`), when the text has one.
+ */
+export declare function installedPackageSpecifier(absoluteSpecifier: string, importedName?: string): InstalledPackageSpecifier | undefined;

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

@@ -0,0 +1,311 @@
+/**
+ * Map an absolute path into an installed package onto the specifier a
+ * consumer of that package would write (carrick#1174).
+ *
+ * The v1 printer and the node builder name an out-of-scope type by the
+ * absolute path of its declaration file when no bare specifier reaches it
+ * from where they print. Inside a capture stub that path is both private (the
+ * checkout root, or the home directory of a runtime's npm cache) and dead:
+ * the check workspace resolves packages from the stub's pinned dependencies,
+ * never from the scanning machine's disk.
+ *
+ * The replacement is decided against the package itself, installed alone at
+ * `node_modules/<name>`, which is exactly what the check workspace sees:
+ *  1. an `exports` entry (or, without `exports`, the types entry or the file's
+ *     subpath) that resolves to the same file under bundler resolution;
+ *  2. failing that, an exported entry whose module exports the imported name
+ *     from that same file (a type in an unexported file, re-exported by the
+ *     package root);
+ *  3. failing both, the subpath as written, so the self-check reports the
+ *     specifier as unresolvable rather than the stub leaking the path.
+ *
+ * Seam: node builtins, `typescript`, and this bundle only.
+ */
+import ts from 'typescript';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { isPublishedSemver } from './lockfile.js';
+const DECLARATION_SUFFIXES = ['', '.d.ts', '.d.mts', '.d.cts', '.ts', '.mts', '.cts', '/index.d.ts'];
+const RESOLUTION_OPTIONS = {
+    module: ts.ModuleKind.ESNext,
+    moduleResolution: ts.ModuleResolutionKind.Bundler,
+    target: ts.ScriptTarget.ESNext,
+    noEmit: true,
+    skipLibCheck: true,
+    types: [],
+};
+/** DefinitelyTyped packages are imported by the runtime name (TS6137). */
+function publicNameOf(name) {
+    if (!name.startsWith('@types/'))
+        return name;
+    const bare = name.slice('@types/'.length);
+    const scoped = /^([^_]+)__(.+)$/.exec(bare);
+    return scoped ? `@${scoped[1]}/${scoped[2]}` : bare;
+}
+/**
+ * The `@types/*` package that serves a bare name's declarations, for callers
+ * deciding whether a runtime name is covered by a pinned types package.
+ */
+export function typesPackageOf(name) {
+    const scoped = /^@([^/]+)\/(.+)$/.exec(name);
+    return scoped ? `@types/${scoped[1]}__${scoped[2]}` : `@types/${name}`;
+}
+function toPosix(p) {
+    return p.split(path.sep).join('/');
+}
+function readManifest(dir) {
+    try {
+        const parsed = JSON.parse(fs.readFileSync(path.join(dir, 'package.json'), 'utf8'));
+        if (typeof parsed?.name === 'string' && typeof parsed?.version === 'string') {
+            return parsed;
+        }
+    }
+    catch {
+        // Absent or unreadable: not a package root.
+    }
+    return undefined;
+}
+/**
+ * An installed package root is a directory named by its package, either at
+ * `node_modules/<name>` (flat and isolated stores alike) or at
+ * `<name>/<version>` (a runtime's npm cache). A nested `package.json` that only
+ * sets a module type, or a workspace member, is neither.
+ */
+function isInstalledRoot(dir, manifest) {
+    const posix = toPosix(dir);
+    return (posix.endsWith(`/node_modules/${manifest.name}`) ||
+        posix.endsWith(`/${manifest.name}/${manifest.version}`));
+}
+function packageRootOf(file) {
+    let dir = path.dirname(file);
+    while (true) {
+        const manifest = readManifest(dir);
+        if (manifest && isInstalledRoot(dir, manifest))
+            return { root: dir, manifest };
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            return undefined;
+        dir = parent;
+    }
+}
+function existingFile(spec) {
+    for (const suffix of DECLARATION_SUFFIXES) {
+        const candidate = spec + suffix;
+        try {
+            if (fs.statSync(candidate).isFile())
+                return fs.realpathSync(candidate);
+        }
+        catch {
+            // try the next suffix
+        }
+    }
+    return undefined;
+}
+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. */
+function exportTargets(value) {
+    if (typeof value === 'string')
+        return [value];
+    if (Array.isArray(value))
+        return value.flatMap(exportTargets);
+    if (value && typeof value === 'object')
+        return Object.values(value).flatMap(exportTargets);
+    return [];
+}
+/** Candidate subpaths (`''` or `/sub`) that could name `subpath` of the package. */
+function candidateSubpaths(manifest, subpath) {
+    const target = withoutExtension(subpath);
+    const candidates = [];
+    const exportsField = manifest.exports;
+    if (exportsField !== undefined && exportsField !== null) {
+        const entries = typeof exportsField === 'object' &&
+            !Array.isArray(exportsField) &&
+            Object.keys(exportsField).some((key) => key.startsWith('.'))
+            ? Object.entries(exportsField)
+            : [['.', exportsField]];
+        for (const [key, value] of entries) {
+            if (!key.startsWith('.'))
+                continue;
+            for (const raw of exportTargets(value)) {
+                const exported = withoutExtension(raw.replace(/^\.\//, ''));
+                if (!key.includes('*')) {
+                    if (exported === target)
+                        candidates.push(key === '.' ? '' : key.slice(1));
+                    continue;
+                }
+                const [before, after] = exported.split('*');
+                if (after === undefined || !target.startsWith(before) || !target.endsWith(after))
+                    continue;
+                const star = target.slice(before.length, target.length - after.length);
+                candidates.push(key.slice(1).replace('*', star));
+            }
+        }
+        return [...new Set(candidates)];
+    }
+    const entry = manifest.types ?? manifest.typings ?? manifest.main ?? 'index';
+    if (withoutExtension(entry.replace(/^\.\//, '')) === target)
+        candidates.push('');
+    candidates.push(`/${target.replace(/\/index$/, '')}`);
+    return [...new Set(candidates)];
+}
+/**
+ * Resolve `specifier` as the check workspace would: the package installed
+ * alone at `node_modules/<name>` beside the importing file. Returns the real
+ * path of the file it lands on.
+ */
+function resolveAgainstInstall(specifier, root, packageName) {
+    const virtualRoot = path.join(path.parse(root).root, '__carrick_specifier_probe__');
+    const virtualPackage = path.join(virtualRoot, 'node_modules', ...packageName.split('/'));
+    const actual = (file) => {
+        if (file === virtualPackage || file.startsWith(virtualPackage + path.sep)) {
+            return path.join(root, file.slice(virtualPackage.length));
+        }
+        return undefined;
+    };
+    const isVirtualAncestor = (dir) => dir === virtualRoot || (virtualPackage + path.sep).startsWith(dir + path.sep);
+    const host = {
+        fileExists: (file) => {
+            const real = actual(file);
+            return real !== undefined && ts.sys.fileExists(real);
+        },
+        readFile: (file) => {
+            const real = actual(file);
+            return real === undefined ? undefined : ts.sys.readFile(real);
+        },
+        directoryExists: (dir) => {
+            if (isVirtualAncestor(dir))
+                return true;
+            const real = actual(dir);
+            return real !== undefined && ts.sys.directoryExists(real);
+        },
+        realpath: (file) => actual(file) ?? file,
+        getCurrentDirectory: () => virtualRoot,
+    };
+    const resolved = ts.resolveModuleName(specifier, path.join(virtualRoot, 'probe.ts'), RESOLUTION_OPTIONS, host).resolvedModule;
+    if (!resolved)
+        return undefined;
+    try {
+        const resolvedFileName = fs.realpathSync(actual(resolved.resolvedFileName) ?? resolved.resolvedFileName);
+        return { ...resolved, resolvedFileName, isExternalLibraryImport: true };
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * A compiler host that also resolves the packages an absolute specifier was
+ * rewritten into, each from its own install directory. The capture's
+ * self-check compiles the stub against the producer's `node_modules`, which
+ * does not name a transitive package at its root; the check workspace does,
+ * because the stub pins it. Without this the self-check would fail a
+ * specifier the check resolves.
+ */
+export function withInstalledPackages(options, installs, base = ts.createCompilerHost(options)) {
+    if (Object.keys(installs).length === 0)
+        return base;
+    const fallback = base.resolveModuleNames?.bind(base);
+    base.resolveModuleNames = (names, containingFile, reused, redirected, compilerOptions, containingSourceFile) => names.map((name, index) => {
+        const resolved = fallback
+            ? fallback([name], containingFile, reused?.slice(index, index + 1), redirected, compilerOptions, containingSourceFile)[0]
+            : ts.resolveModuleName(name, containingFile, compilerOptions, base).resolvedModule;
+        if (resolved || name.startsWith('.') || name.startsWith('/'))
+            return resolved;
+        const packageName = packageNameOfSpecifier(name);
+        for (const owner of [packageName, typesPackageOf(packageName)]) {
+            const root = installs[owner];
+            if (root) {
+                const fromInstall = resolveAgainstInstall(name, root, owner);
+                if (fromInstall)
+                    return fromInstall;
+            }
+        }
+        return undefined;
+    });
+    return base;
+}
+function packageNameOfSpecifier(spec) {
+    const parts = spec.split('/');
+    return spec.startsWith('@') ? parts.slice(0, 2).join('/') : parts[0];
+}
+/** Entry subpaths of a package that a consumer can import. */
+function entrySubpaths(manifest) {
+    const exportsField = manifest.exports;
+    if (exportsField === undefined || exportsField === null)
+        return [''];
+    if (typeof exportsField === 'object' &&
+        !Array.isArray(exportsField) &&
+        Object.keys(exportsField).some((key) => key.startsWith('.'))) {
+        return Object.keys(exportsField)
+            .filter((key) => key.startsWith('.') && !key.includes('*'))
+            .map((key) => (key === '.' ? '' : key.slice(1)));
+    }
+    return [''];
+}
+const moduleExportsCache = new Map();
+/** Exported names of `entryFile`, each with the real files declaring it. */
+function exportsOf(entryFile) {
+    const cached = moduleExportsCache.get(entryFile);
+    if (cached)
+        return cached;
+    const exported = new Map();
+    const program = ts.createProgram([entryFile], RESOLUTION_OPTIONS);
+    const checker = program.getTypeChecker();
+    const source = program.getSourceFile(entryFile);
+    const moduleSymbol = source && checker.getSymbolAtLocation(source);
+    for (const symbol of moduleSymbol ? checker.getExportsOfModule(moduleSymbol) : []) {
+        const target = symbol.flags & ts.SymbolFlags.Alias ? checker.getAliasedSymbol(symbol) : symbol;
+        const files = new Set();
+        for (const declaration of target.declarations ?? []) {
+            try {
+                files.add(fs.realpathSync(declaration.getSourceFile().fileName));
+            }
+            catch {
+                // declaration outside the real file system: ignore
+            }
+        }
+        exported.set(symbol.getName(), files);
+    }
+    moduleExportsCache.set(entryFile, exported);
+    return exported;
+}
+/**
+ * The bare specifier for an absolute path into an installed package, or
+ * undefined when the path does not land in one. `importedName` is the first
+ * name read off the import (`import("...").Name`), when the text has one.
+ */
+export function installedPackageSpecifier(absoluteSpecifier, importedName) {
+    const file = existingFile(absoluteSpecifier);
+    if (!file)
+        return undefined;
+    const owner = packageRootOf(file);
+    if (!owner)
+        return undefined;
+    const root = fs.realpathSync(owner.root);
+    const { manifest } = owner;
+    const publicName = publicNameOf(manifest.name);
+    const pin = isPublishedSemver(manifest.version)
+        ? { name: manifest.name, version: manifest.version }
+        : undefined;
+    const subpath = toPosix(path.relative(root, file));
+    const install = { name: manifest.name, root };
+    const withPin = (specifier) => pin ? { specifier, install, pin } : { specifier, install };
+    const candidates = candidateSubpaths(manifest, subpath);
+    for (const candidate of candidates) {
+        if (resolveAgainstInstall(publicName + candidate, root, manifest.name)?.resolvedFileName === file) {
+            return withPin(publicName + candidate);
+        }
+    }
+    if (importedName) {
+        for (const entry of entrySubpaths(manifest)) {
+            const entryFile = resolveAgainstInstall(publicName + entry, root, manifest.name)?.resolvedFileName;
+            if (!entryFile)
+                continue;
+            if (exportsOf(entryFile).get(importedName)?.has(file)) {
+                return withPin(publicName + entry);
+            }
+        }
+    }
+    return withPin(publicName + (candidates[0] ?? `/${withoutExtension(subpath)}`));
+}

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

@@ -19,6 +19,14 @@
  * stays UNPINNED (fail-closed abstain): a wrong pin fails or corrupts the
  * synthetic-workspace typecheck, no pin merely abstains.
  */
+/**
+ * Published-semver gate for node_modules pins. Rejects anything a registry
+ * install could not satisfy: workspace/link protocol leakage
+ * (`workspace:*`, `link:...`) and yarn-berry's `0.0.0-use.local` local
+ * sentinel. A rejected version means "unpinned" (fail-closed abstain
+ * downstream), never a pin that would fail the synthetic-workspace install.
+ */
+export declare function isPublishedSemver(version: string): boolean;
 /**
  * Resolve exact versions from the repo's installed node_modules by reading
  * `node_modules/<pkg>/package.json` for each referenced external. On an

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

@@ -155,7 +155,7 @@ function pnpmLockfileVersions(lockPath) {
  * sentinel. A rejected version means "unpinned" (fail-closed abstain
  * downstream), never a pin that would fail the synthetic-workspace install.
  */
-function isPublishedSemver(version) {
+export function isPublishedSemver(version) {
     return (/^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/.test(version) &&
         !version.startsWith('0.0.0-use.'));
 }

package/sidecar/dist/src/capture/node-builder.d.ts

@@ -28,6 +28,11 @@ export interface NodeBuilderPrintResult {
     inaccessible: string[];
     /** Failure description when text is absent. */
     failure?: string;
+    /**
+     * Names the print refers to that do not resolve at the destination in the
+     * producer's program (carrick#1165). Present only when there are some.
+     */
+    undeclaredNames?: string[];
 }
 /**
  * Print `type` as a type node anchored at `destination` (a declaration inside
@@ -35,3 +40,25 @@ export interface NodeBuilderPrintResult {
  * any referenced symbol is not plainly accessible from the destination.
  */
 export declare function printTypeForDestination(program: ts.Program, type: ts.Type, destination: ts.Node): NodeBuilderPrintResult;
+/**
+ * Bare names in a printed type node that nothing in the producer's program
+ * declares (carrick#1165).
+ *
+ * The builder names an out-of-scope declaration through `import("...")`, and
+ * the tracker demotes a symbol it cannot reach, so a bare reference is meant
+ * to be in scope where the alias is declared. The one way it is not: the
+ * builder REUSES a source annotation as written (`parcel: Row`) when the
+ * annotation's import did not resolve. There is then no symbol to track, and
+ * the surface names an identifier nothing declares. Literal anchor text, which
+ * the v1 walk printed, can name a type the same way.
+ *
+ * A name is listed only when it neither resolves at the destination (every
+ * lib, runtime and `@types` global does) nor has a declaration anywhere in the
+ * program. The second test matters on a healthy checkout: the v1 walk prints
+ * an enum member (`Status.Open`) or a recursive reference by name, and that
+ * name is declared in the project though not in scope at the surface. An
+ * import binding is not a declaration, so a name whose only source is an
+ * import that did not resolve is still listed. Type parameters the print
+ * itself declares (generic signatures, mapped and `infer` types) are excluded.
+ */
+export declare function undeclaredNamesIn(node: ts.TypeNode, program: ts.Program, destination: ts.Node): string[];

package/sidecar/dist/src/capture/node-builder.js

@@ -119,5 +119,111 @@ export function printTypeForDestination(program, type, destination) {
     }
     const printer = ts.createPrinter({ removeComments: true });
     const text = printer.printNode(ts.EmitHint.Unspecified, node, destination.getSourceFile());
-    return { text, inaccessible };
+    const undeclaredNames = undeclaredNamesIn(node, program, destination);
+    return { text, inaccessible, ...(undeclaredNames.length > 0 ? { undeclaredNames } : {}) };
+}
+/**
+ * Bare names in a printed type node that nothing in the producer's program
+ * declares (carrick#1165).
+ *
+ * The builder names an out-of-scope declaration through `import("...")`, and
+ * the tracker demotes a symbol it cannot reach, so a bare reference is meant
+ * to be in scope where the alias is declared. The one way it is not: the
+ * builder REUSES a source annotation as written (`parcel: Row`) when the
+ * annotation's import did not resolve. There is then no symbol to track, and
+ * the surface names an identifier nothing declares. Literal anchor text, which
+ * the v1 walk printed, can name a type the same way.
+ *
+ * A name is listed only when it neither resolves at the destination (every
+ * lib, runtime and `@types` global does) nor has a declaration anywhere in the
+ * program. The second test matters on a healthy checkout: the v1 walk prints
+ * an enum member (`Status.Open`) or a recursive reference by name, and that
+ * name is declared in the project though not in scope at the surface. An
+ * import binding is not a declaration, so a name whose only source is an
+ * import that did not resolve is still listed. Type parameters the print
+ * itself declares (generic signatures, mapped and `infer` types) are excluded.
+ */
+export function undeclaredNamesIn(node, program, destination) {
+    const checker = program.getTypeChecker();
+    const typeParameters = new Set();
+    const leftmost = (name) => ts.isIdentifier(name) ? name : leftmost(name.left);
+    const references = [];
+    const visit = (current) => {
+        if (ts.isTypeParameterDeclaration(current)) {
+            typeParameters.add(current.name.text);
+        }
+        else if (ts.isTypeReferenceNode(current)) {
+            references.push({ name: leftmost(current.typeName).text, space: 'types' });
+        }
+        else if (ts.isTypeQueryNode(current)) {
+            references.push({ name: leftmost(current.exprName).text, space: 'values' });
+        }
+        ts.forEachChild(current, visit);
+    };
+    visit(node);
+    const undeclared = new Set();
+    for (const { name, space } of references) {
+        if (typeParameters.has(name) || undeclared.has(name))
+            continue;
+        const meaning = (space === 'types' ? ts.SymbolFlags.Type : ts.SymbolFlags.Value) |
+            ts.SymbolFlags.Namespace |
+            ts.SymbolFlags.Alias;
+        if (checker.resolveName(name, destination, meaning, false))
+            continue;
+        if (declaredNamesOf(program)[space].has(name))
+            continue;
+        undeclared.add(name);
+    }
+    return [...undeclared].sort();
+}
+const declaredNamesCache = new WeakMap();
+/**
+ * Every name a declaration in the program introduces, split by the space it
+ * can be referenced from: at any depth of a source file and at any namespace
+ * depth of a declaration file. Import bindings are left out on purpose (see
+ * `undeclaredNamesIn`). Built once per program.
+ */
+function declaredNamesOf(program) {
+    const cached = declaredNamesCache.get(program);
+    if (cached)
+        return cached;
+    const names = { types: new Set(), values: new Set() };
+    const record = (name, types, values) => {
+        if (!name || !ts.isIdentifier(name))
+            return;
+        if (types)
+            names.types.add(name.text);
+        if (values)
+            names.values.add(name.text);
+    };
+    const visit = (current, deep) => {
+        if (ts.isInterfaceDeclaration(current) || ts.isTypeAliasDeclaration(current)) {
+            record(current.name, true, false);
+        }
+        else if (ts.isClassDeclaration(current) ||
+            ts.isEnumDeclaration(current) ||
+            ts.isModuleDeclaration(current)) {
+            // A namespace can qualify a type reference (`Ns.Row`) and a query.
+            record(current.name, true, true);
+        }
+        else if (ts.isFunctionDeclaration(current) || ts.isVariableDeclaration(current)) {
+            record(current.name, false, true);
+        }
+        // A declaration file has no bodies to hide a declaration in, so its
+        // statement lists (and namespace blocks) are the whole story; a lib or
+        // package file is walked no deeper than that.
+        if (deep ||
+            ts.isSourceFile(current) ||
+            ts.isModuleDeclaration(current) ||
+            ts.isModuleBlock(current) ||
+            ts.isVariableStatement(current) ||
+            ts.isVariableDeclarationList(current)) {
+            ts.forEachChild(current, (child) => visit(child, deep));
+        }
+    };
+    for (const sourceFile of program.getSourceFiles()) {
+        visit(sourceFile, !sourceFile.isDeclarationFile);
+    }
+    declaredNamesCache.set(program, names);
+    return names;
 }

package/sidecar/dist/src/capture/paths-rewrite.d.ts

@@ -7,9 +7,10 @@
  * producer's own resolution context -- `paths` cannot be fixed at check time
  * (program-global, and namespaces collide across stubs).
  *
- * Specifiers that map outside the emitted tree are left untouched: the
- * per-alias self-check classifies them as dangling internals with a recorded
- * reason, which is the honest outcome.
+ * An absolute path into an installed package becomes that package's bare
+ * specifier (installed-package.ts). Other specifiers that map outside the
+ * emitted tree are left untouched: the per-alias self-check classifies them
+ * as dangling internals with a recorded reason, which is the honest outcome.
  */
 import ts from 'typescript';
 import { type PathsPattern } from './specifiers.js';
@@ -27,8 +28,24 @@ export interface RewriteArgs {
     entryDir: string;
 }
 export declare function parsePathsPatterns(options: ts.CompilerOptions, configPath: string): PathsPattern[];
+export interface RewriteResult {
+    /** Specifiers rewritten across every emitted file. */
+    rewrites: number;
+    /**
+     * Installed packages an absolute specifier was rewritten into, with their
+     * installed versions: the stub must pin them for the bare specifier to
+     * resolve at check time.
+     */
+    pins: Record<string, string>;
+    /**
+     * The same packages' real install directories, for the self-check's
+     * resolution only. Absolute paths: never written into the stub.
+     */
+    installs: Record<string, string>;
+}
 /**
- * Rewrite paths-mapped and absolute-internal specifiers in every emitted
- * file. Returns the number of specifiers rewritten.
+ * Rewrite paths-mapped, absolute-internal and absolute installed-package
+ * specifiers in every emitted file (carrick#1174 for the last: a path into
+ * `node_modules` or a runtime npm cache becomes the package's bare specifier).
  */
-export declare function rewriteEmittedSpecifiers(args: RewriteArgs): number;
+export declare function rewriteEmittedSpecifiers(args: RewriteArgs): RewriteResult;