carrick 0.3.72 → 0.3.75

package/sidecar/dist/src/capture/check-probe.d.ts

@@ -43,7 +43,7 @@ export declare function fnv1a(input: string): string;
  * path, so it is byte-stable across runs. */
 export declare function pairId(spec: CheckPairSpec): string;
 /** Names each gate line so a TS2344 can be attributed to a specific side+kind. */
-export type GateName = 'sent:any' | 'sent:unknown' | 'sent:never' | 'expected:any' | 'expected:unknown' | 'expected:never';
+export type GateName = 'sent:any' | 'sent:unknown' | 'sent:never' | 'sent:void' | 'sent:form' | 'expected:any' | 'expected:unknown' | 'expected:never' | 'expected:void';
 export interface ProbePlan {
     pairId: string;
     spec: CheckPairSpec;

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

@@ -95,6 +95,22 @@ export function buildProbe(spec, packageOf) {
     gateLines.set(push(`type _G_expected_any = Assert<Not<IsAny<Expected>>>;`), 'expected:any');
     gateLines.set(push(`type _G_expected_unknown = Assert<Not<IsUnknown<Expected>>>;`), 'expected:unknown');
     gateLines.set(push(`type _G_expected_never = Assert<Not<IsNever<Expected>>>;`), 'expected:never');
+    // carrick#1162: `void`/`undefined` is what a call site that reads no body
+    // types its response as (a wrapper returning `Promise<void>`). It states no
+    // contract, so no counterparty shape can be judged against it.
+    // `any` is excluded first: `[any] extends [void]` holds, and an `any` side
+    // must keep its own top-type reason, never read as "reads no body".
+    push(`type IsVoid<T> = 0 extends 1 & T ? false : [T] extends [never] ? false : [T] extends [void] ? true : false;`);
+    gateLines.set(push(`type _G_sent_void = Assert<Not<IsVoid<Sent>>>;`), 'sent:void');
+    gateLines.set(push(`type _G_expected_void = Assert<Not<IsVoid<Expected>>>;`), 'expected:void');
+    // carrick#1162: a form-encoded request body (the platform `FormData` or
+    // `URLSearchParams`) carries its fields as runtime appends, which no type
+    // records, so a field-by-field comparison against a declared shape reads
+    // every such body as missing all of its fields.
+    if (spec.protocol === 'http' && spec.type_kind === 'request') {
+        push(`type IsFormBody<T> = 0 extends 1 & T ? false : [T] extends [never] ? false : [T] extends [FormData | URLSearchParams] ? true : false;`);
+        gateLines.set(push(`type _G_sent_form = Assert<Not<IsFormBody<Sent>>>;`), 'sent:form');
+    }
     push(`declare const sent: Sent;`);
     let assignmentLine;
     if (spec.protocol === 'graphql') {

package/sidecar/dist/src/capture/deep-walk.d.ts

@@ -44,19 +44,46 @@ export type DeepTopType = Pick<TypeProvenance, 'kind' | 'path'>;
  *    void` safely accepts a stricter counterparty), so it is not a masked
  *    mismatch and demoting it would over-demote a sound shape;
  *  - TypeScript's unresolved-reference `error` placeholder (`intrinsicName ===
- *    'error'`) is excluded (see `flagOf`): it heals when the check installs the
+ *    'error'`) is excluded (see `disqualifyingFlag`): it heals when the check installs the
  *    pinned external, so it is a healable decay, not an author-baked `any`.
  * A type the walk cannot cheaply finish is NOT flagged — over-demoting a
  * legitimately fully-resolved type is the failure mode this guard must not have.
  */
 export declare function findDisqualifyingTopTypes(root: ts.Type, program: ts.Program, checker: ts.TypeChecker, location: ts.Node): DeepTopType[];
+/**
+ * Member paths at which `root` holds TypeScript's unresolved-reference
+ * placeholder (the `error` intrinsic) rather than a type (carrick#1164).
+ *
+ * Run on the SOURCE program, where a member typed through an import that did
+ * not resolve still carries the placeholder. Once printed into the stub the
+ * placeholder is the keyword `any`, indistinguishable from an author's `any`,
+ * so this is the only point at which the two causes can be told apart. Same
+ * walk, same budget and the same path notation as the self-check's walk over
+ * the emitted text, so a path found here names the member a self-check finding
+ * names. A walk that runs out of budget reports what it found before it did.
+ */
+export declare function findUnresolvedPlaceholders(root: ts.Type, program: ts.Program, checker: ts.TypeChecker, location: ts.Node): string[];
+/** What an anchor's SOURCE program could not resolve (carrick#1164). */
+export interface UnresolvedAtAnchor {
+    /** Member paths holding the unresolved-reference placeholder. */
+    paths: readonly string[];
+    /**
+     * Module specifiers, as the source wrote them, that did not resolve from the
+     * anchor's file or a module it reaches. Internal specifiers first. May be
+     * empty: a name the program never declared leaves the same placeholder.
+     */
+    specifiers: readonly string[];
+}
 /**
  * Turn a deep finding into the published provenance entry (carrick#376).
  *
  * The self-check reads EMITTED declaration text, so a top type it finds is
- * text: whatever produced it — an author annotation, or an emitter that
- * printed a value it could not resolve — no install re-resolves it. That is
- * `declared`, and saying so is more useful than the bare `any` a reader gets
- * today. The one other cause it can distinguish is its own budget.
+ * text: an author annotation and an emitter that printed an unresolved value
+ * both read `any` there. The anchor's source program can still tell them apart
+ * (`findUnresolvedPlaceholders`), and when it recorded the finding's path as a
+ * placeholder the cause is `unresolved_import`: a dependency or a generated
+ * module was missing on the scanned checkout, which installing or generating
+ * it fixes (carrick#1164). Anything else at that position is `declared`. The
+ * one other cause the walk itself can distinguish is its own budget.
  */
-export declare function provenanceOf(finding: DeepTopType): TypeProvenance;
+export declare function provenanceOf(finding: DeepTopType, unresolved?: UnresolvedAtAnchor): TypeProvenance;

package/sidecar/dist/src/capture/deep-walk.js

@@ -43,12 +43,38 @@ const MAX_DEEP_FINDINGS = 32;
  *    void` safely accepts a stricter counterparty), so it is not a masked
  *    mismatch and demoting it would over-demote a sound shape;
  *  - TypeScript's unresolved-reference `error` placeholder (`intrinsicName ===
- *    'error'`) is excluded (see `flagOf`): it heals when the check installs the
+ *    'error'`) is excluded (see `disqualifyingFlag`): it heals when the check installs the
  *    pinned external, so it is a healable decay, not an author-baked `any`.
  * A type the walk cannot cheaply finish is NOT flagged — over-demoting a
  * legitimately fully-resolved type is the failure mode this guard must not have.
  */
 export function findDisqualifyingTopTypes(root, program, checker, location) {
+    return walkTopTypes(root, program, checker, location, disqualifyingFlag);
+}
+/**
+ * Member paths at which `root` holds TypeScript's unresolved-reference
+ * placeholder (the `error` intrinsic) rather than a type (carrick#1164).
+ *
+ * Run on the SOURCE program, where a member typed through an import that did
+ * not resolve still carries the placeholder. Once printed into the stub the
+ * placeholder is the keyword `any`, indistinguishable from an author's `any`,
+ * so this is the only point at which the two causes can be told apart. Same
+ * walk, same budget and the same path notation as the self-check's walk over
+ * the emitted text, so a path found here names the member a self-check finding
+ * names. A walk that runs out of budget reports what it found before it did.
+ */
+export function findUnresolvedPlaceholders(root, program, checker, location) {
+    return walkTopTypes(root, program, checker, location, (t) => isErrorPlaceholder(t) ? 'any' : undefined)
+        .filter((finding) => finding.kind !== 'budget_exhausted')
+        .map((finding) => finding.path);
+}
+/** TypeScript's unresolved-reference placeholder: `TypeFlags.Any` with the
+ * internal `intrinsicName === 'error'` (stable since TS 1.x; see `anchors.ts`). */
+function isErrorPlaceholder(t) {
+    return ((t.flags & ts.TypeFlags.Any) !== 0 &&
+        t.intrinsicName === 'error');
+}
+function walkTopTypes(root, program, checker, location, flagOf) {
     // Cover v1's inline-expander reach with margin so this structural walk is a
     // genuine superset of v1's text-scan disqualifier AT DEPTH: anything v1 could
     // expand-and-flag as `any`/`unknown`, this walk reaches too. v1's expander
@@ -63,28 +89,6 @@ export function findDisqualifyingTopTypes(root, program, checker, location) {
     const MAX_VISITED = 4096;
     const seen = new Set();
     let visited = 0;
-    const flagOf = (t) => {
-        if (t.flags & ts.TypeFlags.Any) {
-            // TypeScript's unresolved-reference placeholder (e.g. `import('ext').Foo`
-            // on a bare checkout) carries `TypeFlags.Any` but `intrinsicName ===
-            // 'error'` — NOT an author-baked `any`. It resolves to the real type once
-            // the check phase installs the pinned external, so it must not count as a
-            // disqualifier: treating it as `any` would demote a healable external
-            // reference. Genuine author `any` carries `intrinsicName === 'any'`.
-            // (`intrinsicName` is internal but stable since TS 1.x — same standing as
-            // its use in anchors.ts.)
-            //
-            // The `error` placeholder also stands in for NON-healable causes (TS2304
-            // undefined name, TS2315 wrong-arity generic, a dangling internal
-            // specifier). Excluding those here is not a hole: each emits a diagnostic
-            // in the alias's own closure, so the closure-failure classification
-            // (`internalFailure` -> decayed_internal) or the check-phase POISON rule
-            // — NOT this deep walk — is their backstop, and both fail closed.
-            const name = t.intrinsicName;
-            return name === 'error' ? undefined : 'any';
-        }
-        return t.flags & ts.TypeFlags.Unknown ? 'unknown' : undefined;
-    };
     // Findings accumulate rather than short-circuiting: the FIRST is what the
     // check phase pre-gates on (so the verdict is identical to the
     // stop-at-first walk this replaces), and the rest answer "which fields are
@@ -216,16 +220,44 @@ export function findDisqualifyingTopTypes(root, program, checker, location) {
     rest.sort((a, b) => a.path.localeCompare(b.path));
     return [head, ...rest];
 }
+/** The disqualifier the self-check and the check phase gate on (see
+ * `findDisqualifyingTopTypes`). */
+function disqualifyingFlag(t) {
+    if (t.flags & ts.TypeFlags.Any) {
+        // TypeScript's unresolved-reference placeholder (e.g. `import('ext').Foo`
+        // on a bare checkout) carries `TypeFlags.Any` but `intrinsicName ===
+        // 'error'` — NOT an author-baked `any`. It resolves to the real type once
+        // the check phase installs the pinned external, so it must not count as a
+        // disqualifier: treating it as `any` would demote a healable external
+        // reference. Genuine author `any` carries `intrinsicName === 'any'`.
+        // (`intrinsicName` is internal but stable since TS 1.x — same standing as
+        // its use in anchors.ts.)
+        //
+        // The `error` placeholder also stands in for NON-healable causes (TS2304
+        // undefined name, TS2315 wrong-arity generic, a dangling internal
+        // specifier). Excluding those here is not a hole: each emits a diagnostic
+        // in the alias's own closure, so the closure-failure classification
+        // (`internalFailure` -> decayed_internal) or the check-phase POISON rule
+        // — NOT this deep walk — is their backstop, and both fail closed.
+        return isErrorPlaceholder(t) ? undefined : 'any';
+    }
+    return t.flags & ts.TypeFlags.Unknown ? 'unknown' : undefined;
+}
+/** How many unresolved specifiers a detail names before it counts the rest. */
+const MAX_NAMED_SPECIFIERS = 3;
 /**
  * Turn a deep finding into the published provenance entry (carrick#376).
  *
  * The self-check reads EMITTED declaration text, so a top type it finds is
- * text: whatever produced it — an author annotation, or an emitter that
- * printed a value it could not resolve — no install re-resolves it. That is
- * `declared`, and saying so is more useful than the bare `any` a reader gets
- * today. The one other cause it can distinguish is its own budget.
+ * text: an author annotation and an emitter that printed an unresolved value
+ * both read `any` there. The anchor's source program can still tell them apart
+ * (`findUnresolvedPlaceholders`), and when it recorded the finding's path as a
+ * placeholder the cause is `unresolved_import`: a dependency or a generated
+ * module was missing on the scanned checkout, which installing or generating
+ * it fixes (carrick#1164). Anything else at that position is `declared`. The
+ * one other cause the walk itself can distinguish is its own budget.
  */
-export function provenanceOf(finding) {
+export function provenanceOf(finding, unresolved) {
     if (finding.kind === 'budget_exhausted') {
         return {
             path: finding.path,
@@ -234,6 +266,14 @@ export function provenanceOf(finding) {
             detail: 'the type is too deep or wide to verify within the capture budget here, so it is reported unverified rather than assumed clean',
         };
     }
+    if (finding.kind === 'any' && unresolved?.paths.includes(finding.path)) {
+        return {
+            path: finding.path,
+            kind: finding.kind,
+            reason: 'unresolved_import',
+            detail: unresolvedDetail(unresolved.specifiers),
+        };
+    }
     return {
         path: finding.path,
         kind: finding.kind,
@@ -241,3 +281,16 @@ export function provenanceOf(finding) {
         detail: `the captured declaration states '${finding.kind}' at this position, so no counterparty shape can disagree with it`,
     };
 }
+function unresolvedDetail(specifiers) {
+    const lead = "the type at this position did not resolve on the scanned checkout, so the compiler printed a placeholder 'any' rather than a declared type";
+    if (specifiers.length === 0)
+        return lead;
+    const named = specifiers
+        .slice(0, MAX_NAMED_SPECIFIERS)
+        .map((specifier) => `'${specifier}'`)
+        .join(', ');
+    const more = specifiers.length > MAX_NAMED_SPECIFIERS
+        ? ` and ${specifiers.length - MAX_NAMED_SPECIFIERS} more`
+        : '';
+    return `${lead}; unresolved imports reachable from the anchor: ${named}${more}`;
+}

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;