carrick 0.3.70 → 0.3.73

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;

package/sidecar/dist/src/capture/paths-rewrite.js

@@ -7,12 +7,14 @@
  * 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 * as fs from 'node:fs';
 import * as path from 'node:path';
+import { installedPackageSpecifier } from './installed-package.js';
 import { isRelative, matchPathsPattern, rewriteSpecifiers, } from './specifiers.js';
 export function parsePathsPatterns(options, configPath) {
     const paths = options.paths;
@@ -55,21 +57,51 @@ function relativeSpecifier(fromFile, toFile) {
     return rel;
 }
 /**
- * Rewrite paths-mapped and absolute-internal specifiers in every emitted
- * file. Returns the number of specifiers rewritten.
+ * `import("<absolute>").Name` occurrences: the absolute specifier and the
+ * first name read off it, so an installed-package rewrite can find the entry
+ * that exports that name.
+ */
+const ABSOLUTE_IMPORT_TYPE = /(import\s*\(\s*)(["'])(\/[^"']+)\2(\s*\))(\s*\.\s*)([A-Za-z_$][\w$]*)/g;
+/**
+ * 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 function rewriteEmittedSpecifiers(args) {
     const patterns = parsePathsPatterns(args.options, args.configPath);
     const emitted = new Set(args.files);
+    const pins = {};
+    const installs = {};
     let total = 0;
+    const installed = (spec, importedName) => {
+        const mapped = installedPackageSpecifier(spec, importedName);
+        if (!mapped)
+            return undefined;
+        installs[mapped.install.name] = mapped.install.root;
+        if (mapped.pin)
+            pins[mapped.pin.name] = mapped.pin.version;
+        return mapped.specifier;
+    };
     for (const file of args.files) {
         const absFile = path.join(args.typesDir, file);
-        const text = fs.readFileSync(absFile, 'utf8');
+        const original = fs.readFileSync(absFile, 'utf8');
+        let importTypeRewrites = 0;
+        // Import types first, while the member name is still attached to its
+        // specifier; an in-tree target is left for the general pass below.
+        const text = original.replace(ABSOLUTE_IMPORT_TYPE, (whole, open, quote, spec, close, dot, name) => {
+            if (treeFileFor(spec, args.entryDir, emitted))
+                return whole;
+            const replacement = installed(spec, name);
+            if (replacement === undefined)
+                return whole;
+            importTypeRewrites++;
+            return `${open}${quote}${replacement}${quote}${close}${dot}${name}`;
+        });
         const { text: rewritten, rewrites } = rewriteSpecifiers(text, (spec) => {
-            // Absolute internal paths (node-builder import types).
+            // Absolute paths: an emitted tree file, else an installed package.
             if (spec.startsWith('/')) {
                 const target = treeFileFor(spec, args.entryDir, emitted);
-                return target ? relativeSpecifier(file, target) : undefined;
+                return target ? relativeSpecifier(file, target) : installed(spec);
             }
             if (isRelative(spec))
                 return undefined;
@@ -91,10 +123,10 @@ export function rewriteEmittedSpecifiers(args) {
             }
             return undefined;
         });
-        if (rewrites > 0) {
+        if (rewrites + importTypeRewrites > 0) {
             fs.writeFileSync(absFile, rewritten);
-            total += rewrites;
+            total += rewrites + importTypeRewrites;
         }
     }
-    return total;
+    return { rewrites: total, pins, installs };
 }

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

@@ -142,7 +142,7 @@ function demotedRecord(anchor) {
         alias: anchor.request.alias,
         anchor_kind: anchor.request.kind,
         symbol_name: 'symbol_name' in anchor.request ? anchor.request.symbol_name : undefined,
-        source_file: 'source_file' in anchor.request ? anchor.request.source_file : '<inline>',
+        source_file: anchor.request.kind === 'literal' ? '<inline>' : anchor.request.source_file,
         anchor_origin: anchor.request.anchor_origin,
         serialization: 'structural_fallback',
         self_check: 'decayed_internal',
@@ -194,6 +194,7 @@ function checkedRecord(anchor, ctx) {
     }
     let blamedExternal;
     let internalFailure;
+    const danglingSpecifiers = new Set();
     for (const file of closure) {
         const failures = ctx.failuresByFile.get(file);
         if (!failures)
@@ -202,6 +203,8 @@ function checkedRecord(anchor, ctx) {
             blamedExternal = [...failures.externalPinned][0];
         if (!internalFailure)
             internalFailure = [...failures.internal][0];
+        for (const specifier of failures.internal)
+            danglingSpecifiers.add(specifier);
     }
     // Classification consults the closure failures REGARDLESS of the root
     // type: a dangling internal specifier means part of this alias's closure
@@ -283,7 +286,7 @@ function checkedRecord(anchor, ctx) {
         alias,
         anchor_kind: anchor.request.kind,
         symbol_name: 'symbol_name' in anchor.request ? anchor.request.symbol_name : undefined,
-        source_file: 'source_file' in anchor.request ? anchor.request.source_file : '<inline>',
+        source_file: anchor.request.kind === 'literal' ? '<inline>' : anchor.request.source_file,
         anchor_origin: anchor.request.anchor_origin,
         serialization: anchor.serialization,
         self_check: outcome,
@@ -295,8 +298,14 @@ function checkedRecord(anchor, ctx) {
         self_check_detail: anchor.abstainReason ?? detail ?? anchor.reaimNote,
         top_type_at_self_check: topType,
         ...(unexplainedDeep.length > 0
-            ? { any_provenance: unexplainedDeep.map(provenanceOf) }
+            ? {
+                any_provenance: unexplainedDeep.map((finding) => provenanceOf(finding, anchor.unresolved)),
+            }
+            : {}),
+        ...(danglingSpecifiers.size > 0
+            ? { dangling_specifiers: [...danglingSpecifiers].sort() }
             : {}),
+        ...(anchor.undeclaredNames ? { undeclared_names: anchor.undeclaredNames } : {}),
     };
 }
 /** Resolve a relative specifier from `fromAbs` to a tree file, if present. */

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

@@ -0,0 +1,28 @@
+/**
+ * What an anchor's source program could not resolve (carrick#1164).
+ *
+ * The node builder and declaration emit both print TypeScript's
+ * unresolved-reference placeholder as the keyword `any`. After that the stub
+ * text cannot say whether an `any` member was written by the author or left
+ * behind by an import that did not resolve on the scanned checkout — a
+ * dependency that was not installed, a generated module that was never
+ * generated. The self-check reads only that text, so it used to label both
+ * `declared`, and a reader told "declared that way in the source" stops
+ * looking where the fix is to install or generate the missing module.
+ *
+ * The source program still holds the placeholder, so the capture records the
+ * placeholder's member paths at anchor time, together with the module
+ * specifiers the anchor's file can reach that did not resolve, and the
+ * self-check labels the matching findings. Seam: node builtins + `typescript`.
+ */
+import ts from 'typescript';
+import { type UnresolvedAtAnchor } from './deep-walk.js';
+/**
+ * The unresolved placeholders inside `type` (read at `location` in `sourceFile`),
+ * or `undefined` when it has none — the common case, which costs one walk.
+ *
+ * `pathPrefix` maps the anchor type's member paths onto the paths of the alias
+ * the surface declares when the two differ: a symbol anchor restoring array
+ * depth prints `import('./m').Row[]`, whose members sit under `<0>`.
+ */
+export declare function unresolvedAtAnchor(program: ts.Program, sourceFile: ts.SourceFile, type: ts.Type, location: ts.Node, pathPrefix?: string): UnresolvedAtAnchor | undefined;

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

@@ -0,0 +1,107 @@
+/**
+ * What an anchor's source program could not resolve (carrick#1164).
+ *
+ * The node builder and declaration emit both print TypeScript's
+ * unresolved-reference placeholder as the keyword `any`. After that the stub
+ * text cannot say whether an `any` member was written by the author or left
+ * behind by an import that did not resolve on the scanned checkout — a
+ * dependency that was not installed, a generated module that was never
+ * generated. The self-check reads only that text, so it used to label both
+ * `declared`, and a reader told "declared that way in the source" stops
+ * looking where the fix is to install or generate the missing module.
+ *
+ * The source program still holds the placeholder, so the capture records the
+ * placeholder's member paths at anchor time, together with the module
+ * specifiers the anchor's file can reach that did not resolve, and the
+ * self-check labels the matching findings. Seam: node builtins + `typescript`.
+ */
+import ts from 'typescript';
+import { findUnresolvedPlaceholders } from './deep-walk.js';
+/** Files the specifier walk visits from one anchor before it stops. */
+const MAX_REACHABLE_FILES = 256;
+/** Per-program memo: source file name -> unresolved specifiers it reaches. */
+const reachableCache = new WeakMap();
+/**
+ * The unresolved placeholders inside `type` (read at `location` in `sourceFile`),
+ * or `undefined` when it has none — the common case, which costs one walk.
+ *
+ * `pathPrefix` maps the anchor type's member paths onto the paths of the alias
+ * the surface declares when the two differ: a symbol anchor restoring array
+ * depth prints `import('./m').Row[]`, whose members sit under `<0>`.
+ */
+export function unresolvedAtAnchor(program, sourceFile, type, location, pathPrefix = '') {
+    const checker = program.getTypeChecker();
+    const paths = findUnresolvedPlaceholders(type, program, checker, location).map((path) => prefixPath(pathPrefix, path));
+    if (paths.length === 0)
+        return undefined;
+    return { paths, specifiers: unresolvedSpecifiersReachableFrom(program, sourceFile) };
+}
+/** Join a walk path under a prefix in the walk's own notation. */
+function prefixPath(prefix, path) {
+    if (prefix === '')
+        return path;
+    if (path === '')
+        return prefix;
+    return /^[<[(]/.test(path) ? `${prefix}${path}` : `${prefix}.${path}`;
+}
+/**
+ * Module specifiers, as written, that do not resolve from `sourceFile` or from
+ * any source module it imports, breadth-first so the nearest come first, with
+ * relative specifiers ahead of package names. Installed packages and the
+ * default library are not descended into.
+ */
+function unresolvedSpecifiersReachableFrom(program, sourceFile) {
+    let cache = reachableCache.get(program);
+    if (!cache) {
+        cache = new Map();
+        reachableCache.set(program, cache);
+    }
+    const cached = cache.get(sourceFile.fileName);
+    if (cached)
+        return cached;
+    const checker = program.getTypeChecker();
+    const unresolved = new Set();
+    const visited = new Set([sourceFile.fileName]);
+    const queue = [sourceFile];
+    while (queue.length > 0 && visited.size <= MAX_REACHABLE_FILES) {
+        const file = queue.shift();
+        for (const literal of moduleSpecifiersOf(file)) {
+            const module = checker.getSymbolAtLocation(literal);
+            if (!module) {
+                unresolved.add(literal.text);
+                continue;
+            }
+            // An ambient `declare module 'x'` resolves to a module declaration, not
+            // a file: resolved, with nothing further to walk.
+            const target = module.declarations?.find(ts.isSourceFile);
+            if (!target ||
+                visited.has(target.fileName) ||
+                program.isSourceFileDefaultLibrary(target) ||
+                program.isSourceFileFromExternalLibrary(target)) {
+                continue;
+            }
+            visited.add(target.fileName);
+            queue.push(target);
+        }
+    }
+    const ordered = [...unresolved].sort((a, b) => Number(!a.startsWith('.')) - Number(!b.startsWith('.')));
+    cache.set(sourceFile.fileName, ordered);
+    return ordered;
+}
+/** The string-literal module specifiers of a file's imports and re-exports. */
+function moduleSpecifiersOf(file) {
+    const out = [];
+    for (const statement of file.statements) {
+        let specifier;
+        if (ts.isImportDeclaration(statement) || ts.isExportDeclaration(statement)) {
+            specifier = statement.moduleSpecifier;
+        }
+        else if (ts.isImportEqualsDeclaration(statement) &&
+            ts.isExternalModuleReference(statement.moduleReference)) {
+            specifier = statement.moduleReference.expression;
+        }
+        if (specifier && ts.isStringLiteral(specifier))
+            out.push(specifier);
+    }
+    return out;
+}