carrick 0.3.133 → 0.3.134

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

@@ -61,6 +61,31 @@ export function carriesHeapLimitLine(stderr) {
         .some((line) => line.includes(HEAP_OUT_OF_MEMORY) &&
         !HARD_SIZE_LIMITS.some((limit) => line.includes(limit)));
 }
+/**
+ * Whether the native compiler (TypeScript 7, a Go program) died out of
+ * memory. The Go runtime prints `fatal error: runtime: out of memory` and
+ * exits 2; V8's line above never appears, and a heap cap passed through
+ * `NODE_OPTIONS` reaches only the launcher, not the compiler.
+ */
+export function carriesNativeOutOfMemoryLine(output) {
+    return output.split('\n').some((line) => line.includes('fatal error: runtime: out of memory'));
+}
+/**
+ * Whether a diagnostic is about the compiler's configuration rather than a
+ * file it checked: one placed in the tsconfig the judge wrote, or "no inputs"
+ * (TS18003). Keyed on the file, not on the TS5xxx option range: some of those
+ * codes sit in a source file (TS5097, an import ending in `.ts`) and poison
+ * only the stub that holds it.
+ */
+export function isConfigDiagnostic(d) {
+    return path.posix.basename(d.file) === 'tsconfig.json' || d.code === 18003;
+}
+/** Why the compiler ended abnormally, when its output names a known cause. */
+export function abnormalCause(output) {
+    if (carriesNativeOutOfMemoryLine(output))
+        return 'the type checker ran out of memory';
+    return undefined;
+}
 /** V8's default old-space ceiling on a 64-bit host, in MB. */
 const V8_DEFAULT_HEAP_CEILING_MB = 4096;
 /**
@@ -119,9 +144,16 @@ function sidecarRoot() {
  * which is the caller's "not found" signal and the most useful thing to name.
  */
 export function resolveVendoredBin(name, from = sidecarRoot()) {
-    const local = path.join(from, 'node_modules', '.bin', name);
+    return resolveVendored(path.join('.bin', name), from);
+}
+/**
+ * The first `node_modules/<rel>` at or above `from`, the same walk as
+ * {@link resolveVendoredBin}; the sidecar-local path when none exists.
+ */
+export function resolveVendored(rel, from = sidecarRoot()) {
+    const local = path.join(from, 'node_modules', rel);
     for (let dir = from;; dir = path.dirname(dir)) {
-        const candidate = path.join(dir, 'node_modules', '.bin', name);
+        const candidate = path.join(dir, 'node_modules', rel);
         if (fs.existsSync(candidate))
             return candidate;
         if (path.dirname(dir) === dir)
@@ -131,6 +163,58 @@ export function resolveVendoredBin(name, from = sidecarRoot()) {
 function binPath(name) {
     return resolveVendoredBin(name);
 }
+/**
+ * The package that brings the judge's compiler: TypeScript 7 under an alias
+ * beside the TypeScript 6 that capture and inference read through ts-morph.
+ * Its platform package holds the native executable the judge runs. Both
+ * packages declare a `tsc` bin, so `node_modules/.bin/tsc` may be either; the
+ * judge never reads it.
+ */
+export const JUDGE_COMPILER_PACKAGE = 'typescript-native';
+/**
+ * The judge's tsc: the host's native executable, from the platform package
+ * the compiler installs as an optional dependency (`@typescript/
+ * typescript-<platform>-<arch>`), found by the same walk as the bins. Where it
+ * is not installed (an install that omits optional dependencies, such as the
+ * cloud runner's, or a pnpm store the walk does not reach), TypeScript 6's own
+ * tsc, which ships for ts-morph anyway. The two read every probe the same
+ * (measured on 1,018 real probes; the one wording difference moves only a
+ * verdict's `codes`), so the fallback changes no verdict, only the time.
+ */
+export function judgeTscPath(from = sidecarRoot(), platform = process.platform, arch = process.arch) {
+    const exe = platform === 'win32' ? 'tsc.exe' : 'tsc';
+    const native = path.join('@typescript', `typescript-${platform}-${arch}`, 'lib', exe);
+    const found = resolveVendored(native, from);
+    if (fs.existsSync(found))
+        return found;
+    return resolveVendored(path.join('typescript', 'bin', 'tsc'), from);
+}
+/** Which compiler a tsc path is, in words, for the run log and the result. */
+export function judgeLabel(tscPath) {
+    const version = compilerVersion(tscPath);
+    const parts = tscPath.split(/[\\/]/);
+    if (parts.some((p) => p.startsWith('typescript-') && p !== JUDGE_COMPILER_PACKAGE)) {
+        return `TypeScript ${version} (native)`;
+    }
+    if (parts.includes('typescript') && parts[parts.length - 2] === 'bin') {
+        return `TypeScript ${version} (native compiler not installed)`;
+    }
+    return `a stand-in compiler at ${tscPath}`;
+}
+/** The version of the compiler a tsc path belongs to, read from the package
+ * that holds it; the compiler-API version for a stand-in with no package. */
+function compilerVersion(tscPath) {
+    try {
+        const manifest = JSON.parse(fs.readFileSync(path.join(path.dirname(tscPath), '..', 'package.json'), 'utf8'));
+        const compiler = manifest.name === 'typescript' || manifest.name?.startsWith('@typescript/typescript-');
+        if (compiler && manifest.version)
+            return manifest.version;
+    }
+    catch {
+        // A stand-in compiler (tests) sits in no package.
+    }
+    return ts.version;
+}
 function unverifiableAll(plans, gate, diagnostic) {
     return plans.map((plan) => ({
         pair_id: plan.pairId,
@@ -155,8 +239,9 @@ export async function runCheck(opts, onProgress) {
     const progress = onProgress ?? (() => { });
     const cleanup = opts.cleanup !== false;
     const pnpmPath = opts.pnpmPath ?? binPath('pnpm');
-    const tscPath = opts.tscPath ?? binPath('tsc');
-    const tsVersion = ts.version;
+    const tscPath = opts.tscPath ?? judgeTscPath();
+    const tsVersion = compilerVersion(tscPath);
+    const judge = judgeLabel(tscPath);
     // Isolation is non-negotiable: without the vendored pnpm we would fall back
     // to a flat npm install that manufactures nominal false-incompatibles. Fail
     // explicitly instead (design Check step 2).
@@ -169,6 +254,7 @@ export async function runCheck(opts, onProgress) {
             isolation: 'unavailable',
             install_ok: false,
             ts_version: tsVersion,
+            judge,
             verdicts: sortVerdicts([
                 ...unverifiableAll(probing, 'isolation:unavailable', 'type isolation unavailable (pnpm missing); compatibility cannot be verified.'),
                 ...preGated,
@@ -248,13 +334,14 @@ export async function runCheck(opts, onProgress) {
             isolation: 'pnpm',
             install_ok: false,
             ts_version: tsVersion,
+            judge,
             verdicts,
             degraded_services: degraded,
             errors,
         };
     }
     // ---- Judge (async, off the event loop) ----------------------------------
-    progress('checking', 'type-checking probes');
+    progress('checking', `type-checking probes (judge: ${judge})`);
     const heap = childHeap(process.execArgv, process.env.NODE_OPTIONS, process.memoryUsage().rss / (1024 * 1024));
     const tsc = await runProcess(tscPath, ['--noEmit', '--pretty', 'false', '-p', path.join(ws.probesRel, 'tsconfig.json')], ws.workspaceDir, { ...process.env, NODE_OPTIONS: heap.nodeOptions });
     const diagnostics = parseTscOutput(tsc.stdout + '\n' + tsc.stderr);
@@ -267,8 +354,20 @@ export async function runCheck(opts, onProgress) {
     // `code === 0` guard.
     // A compiler a signal ended never finished, so a pair with no diagnostic
     // was never cleared, whatever it printed first (carrick#2209).
-    if (tsc.signal !== null || (tsc.code !== 0 && diagnostics.length === 0)) {
-        const excerpt = scrubPaths((tsc.stderr || tsc.stdout).trim().slice(0, 2000), scrubCtx);
+    //
+    // A diagnostic about the configuration (a tsconfig the compiler refuses,
+    // an option it does not know) is printed WITH a position, in the tsconfig,
+    // and belongs to no pair: TypeScript 7 refuses an option and checks
+    // nothing, so without this every pair read compatible. Such a run checked
+    // no pair, whatever else it printed.
+    const configError = diagnostics.find(isConfigDiagnostic);
+    if (tsc.signal !== null ||
+        (tsc.code !== 0 && diagnostics.length === 0) ||
+        configError !== undefined) {
+        const excerpt = scrubPaths((configError
+            ? `${configError.file}(${configError.line},${configError.col}): error TS${configError.code}: ${configError.message}`
+            : (tsc.stderr || tsc.stdout).trim()).slice(0, 2000), scrubCtx);
+        const cause = abnormalCause(tsc.stderr + '\n' + tsc.stdout);
         errors.push(`tsc terminated abnormally (exit code ${tsc.code ?? 'null'}) ` +
             `with no parseable diagnostics${excerpt ? `: ${excerpt}` : ''}`);
         for (const s of opts.stubs) {
@@ -278,8 +377,9 @@ export async function runCheck(opts, onProgress) {
             });
         }
         const verdicts = sortVerdicts([
-            ...unverifiableAll(probing, 'tsc:abnormal-termination', `the type checker terminated abnormally (exit code ${tsc.code ?? 'null'}); ` +
-                'compatibility cannot be verified.' +
+            ...unverifiableAll(probing, 'tsc:abnormal-termination', `the type checker terminated abnormally (exit code ${tsc.code ?? 'null'})` +
+                (cause ? ` because ${cause}` : '') +
+                '; compatibility cannot be verified.' +
                 (excerpt ? ` Compiler output: ${excerpt}` : '')),
             ...preGated,
             ...unresolved,
@@ -290,7 +390,7 @@ export async function runCheck(opts, onProgress) {
         const compilerEnd = {
             exit_code: tsc.code,
             signal: tsc.signal,
-            heap_limit: carriesHeapLimitLine(tsc.stderr),
+            heap_limit: carriesHeapLimitLine(tsc.stderr) || carriesNativeOutOfMemoryLine(tsc.stderr + '\n' + tsc.stdout),
             heap_cap_mb: heap.heapCapMb,
         };
         if (cleanup)
@@ -301,6 +401,7 @@ export async function runCheck(opts, onProgress) {
             isolation: 'pnpm',
             install_ok: true,
             ts_version: tsVersion,
+            judge,
             verdicts,
             degraded_services: dedupeDegraded(degraded),
             errors,
@@ -359,6 +460,7 @@ export async function runCheck(opts, onProgress) {
         isolation: 'pnpm',
         install_ok: true,
         ts_version: tsVersion,
+        judge,
         verdicts,
         degraded_services: dedupeDegraded(degraded),
         errors,

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

@@ -35,6 +35,11 @@ export interface InstalledPackageSpecifier {
         name: string;
         version: string;
     };
+    /**
+     * The name the entry exports the declaration under, set only when it differs
+     * from the name the path's declaration carries (`export { O as OmitKeys }`).
+     */
+    exportName?: string;
 }
 /**
  * The `@types/*` package that serves a bare name's declarations, for callers

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

@@ -245,29 +245,78 @@ function entrySubpaths(manifest) {
     }
     return [''];
 }
+/**
+ * Declaration keys (`file\0declaredName`) of what `file` exports as `name`.
+ * A chunk can declare a type under its public name and export it under a
+ * short one (`export { type OmitKeyof as O }`), so the name read off the
+ * import is not the name the declaration carries.
+ */
+function declarationKeysOfExport(file, name) {
+    const program = ts.createProgram([file], RESOLUTION_OPTIONS);
+    const checker = program.getTypeChecker();
+    const source = program.getSourceFile(file);
+    const moduleSymbol = source && checker.getSymbolAtLocation(source);
+    const symbol = moduleSymbol && checker.getExportsOfModule(moduleSymbol).find((s) => s.getName() === name);
+    if (!symbol)
+        return [];
+    let target = symbol;
+    for (let hops = 0; target.flags & ts.SymbolFlags.Alias && hops < 16; hops++) {
+        const next = checker.getAliasedSymbol(target);
+        if (next === target)
+            break;
+        target = next;
+    }
+    const keys = [];
+    for (const declaration of target.declarations ?? []) {
+        try {
+            keys.push(`${fs.realpathSync(declaration.getSourceFile().fileName)}\0${target.getName()}`);
+        }
+        catch {
+            // declaration outside the real file system: ignore
+        }
+    }
+    return keys;
+}
 const moduleExportsCache = new Map();
-/** Exported names of `entryFile`, each with the real files declaring it. */
+/**
+ * Exports of `entryFile`: by exported name (with the real files declaring it)
+ * and by declaration identity (the file and the name the declaration carries
+ * there, whatever name the entry exports it under).
+ */
 function exportsOf(entryFile) {
     const cached = moduleExportsCache.get(entryFile);
     if (cached)
         return cached;
-    const exported = new Map();
+    const exported = { byName: new Map(), byDeclaration: 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;
+        let target = symbol;
+        // Follow the alias chain until it stops (an entry can re-export a re-export).
+        for (let hops = 0; target.flags & ts.SymbolFlags.Alias && hops < 16; hops++) {
+            const next = checker.getAliasedSymbol(target);
+            if (next === target)
+                break;
+            target = next;
+        }
         const files = new Set();
         for (const declaration of target.declarations ?? []) {
             try {
-                files.add(fs.realpathSync(declaration.getSourceFile().fileName));
+                const real = fs.realpathSync(declaration.getSourceFile().fileName);
+                files.add(real);
+                const key = `${real}\0${target.getName()}`;
+                // The first export of a declaration wins; its own name wins over a rename.
+                if (!exported.byDeclaration.has(key) || symbol.getName() === target.getName()) {
+                    exported.byDeclaration.set(key, symbol.getName());
+                }
             }
             catch {
                 // declaration outside the real file system: ignore
             }
         }
-        exported.set(symbol.getName(), files);
+        exported.byName.set(symbol.getName(), files);
     }
     moduleExportsCache.set(entryFile, exported);
     return exported;
@@ -304,9 +353,18 @@ export function installedPackageSpecifier(absoluteSpecifier, importedName) {
             const entryFile = resolveAgainstInstall(publicName + entry, root, manifest.name)?.resolvedFileName;
             if (!entryFile)
                 continue;
-            if (exportsOf(entryFile).get(importedName)?.has(file)) {
+            const entryExports = exportsOf(entryFile);
+            if (entryExports.byName.get(importedName)?.has(file)) {
                 return withPin(publicName + entry);
             }
+            // The entry may export the declaration under another name.
+            const renamed = entryExports.byDeclaration.get(`${file}\0${importedName}`) ??
+                declarationKeysOfExport(file, importedName)
+                    .map((key) => entryExports.byDeclaration.get(key))
+                    .find((name) => name !== undefined);
+            if (renamed !== undefined) {
+                return { ...withPin(publicName + entry), exportName: renamed };
+            }
         }
     }
     return withPin(publicName + (candidates[0] ?? `/${withoutExtension(subpath)}`));

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

@@ -82,7 +82,7 @@ export function rewriteEmittedSpecifiers(args) {
         installs[mapped.install.name] = mapped.install.root;
         if (mapped.pin)
             pins[mapped.pin.name] = mapped.pin.version;
-        return mapped.specifier;
+        return { specifier: mapped.specifier, exportName: mapped.exportName };
     };
     for (const file of args.files) {
         const absFile = path.join(args.typesDir, file);
@@ -97,13 +97,13 @@ export function rewriteEmittedSpecifiers(args) {
             if (replacement === undefined)
                 return whole;
             importTypeRewrites++;
-            return `${open}${quote}${replacement}${quote}${close}${dot}${name}`;
+            return `${open}${quote}${replacement.specifier}${quote}${close}${dot}${replacement.exportName ?? name}`;
         });
         const { text: rewritten, rewrites } = rewriteSpecifiers(text, (spec) => {
             // Absolute paths: an emitted tree file, else an installed package.
             if (spec.startsWith('/')) {
                 const target = treeFileFor(spec, args.entryDir, emitted, args.outside);
-                return target ? relativeSpecifier(file, target) : installed(spec);
+                return target ? relativeSpecifier(file, target) : installed(spec)?.specifier;
             }
             if (isRelative(spec))
                 return undefined;

package/sidecar/dist/src/capture/result-label.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Reading a labelled call's result (carrick#2818).
+ *
+ * A request library's call rarely returns the response body itself: the body
+ * sits in a member of what comes back (`data`), behind a parse method
+ * (`json()`), or is the whole value. The library store labels which, per
+ * operation, and the scanner sends the label on the consumer's infer anchor.
+ * This reads the labelled part of the located call's type, so the contract the
+ * consumer states is the body and never the library's envelope.
+ *
+ * The label is one of:
+ *  - `{ whole: true }`: the awaited type;
+ *  - `{ member: [m] }`: `m` on every non-nullish constituent of the awaited
+ *    type, `undefined` and `null` removed from what is read;
+ *  - `{ parse: p }`: the awaited return of calling `p()`, read off the type as
+ *    the call returns it (a promise-like with a `json()` method is a thenable,
+ *    and awaiting it first would drop the method).
+ *
+ * A label the type cannot satisfy abstains with `result_member_missing`.
+ */
+import ts from 'typescript';
+/** The wire form of a result label. Exactly one key is set. */
+export type ResultLabel = {
+    whole: true;
+} | {
+    member: [string];
+} | {
+    parse: string;
+};
+export type ResultRead = {
+    type: ts.Type;
+} | {
+    abstain: string;
+};
+/** The constituents of a union, or the type alone. */
+export declare function constituentsOf(type: ts.Type): readonly ts.Type[];
+/**
+ * Read `label` off a call's type. `raw` is the type as the call returns it and
+ * `awaited` the type after the transport unwrap; `at` is the node properties
+ * are instantiated at.
+ */
+export declare function readResultLabel(checker: ts.TypeChecker, raw: ts.Type, awaited: ts.Type, label: ResultLabel, at: ts.Node): ResultRead;

package/sidecar/dist/src/capture/result-label.js

@@ -0,0 +1,91 @@
+/**
+ * Reading a labelled call's result (carrick#2818).
+ *
+ * A request library's call rarely returns the response body itself: the body
+ * sits in a member of what comes back (`data`), behind a parse method
+ * (`json()`), or is the whole value. The library store labels which, per
+ * operation, and the scanner sends the label on the consumer's infer anchor.
+ * This reads the labelled part of the located call's type, so the contract the
+ * consumer states is the body and never the library's envelope.
+ *
+ * The label is one of:
+ *  - `{ whole: true }`: the awaited type;
+ *  - `{ member: [m] }`: `m` on every non-nullish constituent of the awaited
+ *    type, `undefined` and `null` removed from what is read;
+ *  - `{ parse: p }`: the awaited return of calling `p()`, read off the type as
+ *    the call returns it (a promise-like with a `json()` method is a thenable,
+ *    and awaiting it first would drop the method).
+ *
+ * A label the type cannot satisfy abstains with `result_member_missing`.
+ */
+import ts from 'typescript';
+const NULLISH = ts.TypeFlags.Undefined | ts.TypeFlags.Null | ts.TypeFlags.Void;
+/** The constituents of a union, or the type alone. */
+export function constituentsOf(type) {
+    return type.isUnion() ? type.types : [type];
+}
+function missing(what) {
+    return { abstain: `result_member_missing: ${what}` };
+}
+/**
+ * Read `label` off a call's type. `raw` is the type as the call returns it and
+ * `awaited` the type after the transport unwrap; `at` is the node properties
+ * are instantiated at.
+ */
+export function readResultLabel(checker, raw, awaited, label, at) {
+    if ('whole' in label)
+        return { type: awaited };
+    if ('member' in label)
+        return readMember(checker, awaited, label.member[0], at);
+    return readParse(checker, raw, awaited, label.parse, at);
+}
+function readMember(checker, awaited, name, at) {
+    const read = [];
+    for (const constituent of constituentsOf(awaited)) {
+        if (constituent.flags & NULLISH)
+            continue;
+        const property = checker.getPropertyOfType(constituent, name);
+        if (!property)
+            return missing(`the labelled member '${name}' is not on every constituent`);
+        const held = checker.getTypeOfSymbolAtLocation(property, at);
+        for (const part of constituentsOf(held)) {
+            if (!(part.flags & NULLISH))
+                read.push(part);
+        }
+    }
+    if (read.length === 0)
+        return missing(`the labelled member '${name}' holds no value`);
+    if (read.length === 1)
+        return { type: read[0] };
+    const union = checker.getUnionType;
+    // Without the checker's own union the members cannot be joined honestly;
+    // abstaining beats publishing the first of them.
+    if (!union)
+        return missing(`the labelled member '${name}' holds several types`);
+    return { type: union.call(checker, read) };
+}
+function readParse(checker, raw, awaited, name, at) {
+    // The method is looked up on the call's own type first: it is the thenable
+    // that carries `json()`, and its awaited value does not.
+    for (const holder of [raw, awaited]) {
+        const method = checker.getPropertyOfType(holder, name);
+        if (!method)
+            continue;
+        const signature = checker
+            .getSignaturesOfType(checker.getTypeOfSymbolAtLocation(method, at), ts.SignatureKind.Call)
+            .find((candidate) => candidate.parameters.every((p) => isOptional(p)));
+        if (!signature)
+            continue;
+        const returned = checker.getReturnTypeOfSignature(signature);
+        return { type: checker.getAwaitedType(returned) ?? returned };
+    }
+    return missing(`the labelled parse method '${name}' is not callable with no arguments`);
+}
+function isOptional(parameter) {
+    const declaration = parameter.valueDeclaration;
+    return (!!declaration &&
+        ts.isParameter(declaration) &&
+        (declaration.questionToken !== undefined ||
+            declaration.initializer !== undefined ||
+            declaration.dotDotDotToken !== undefined));
+}

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

@@ -232,6 +232,17 @@ function runSelfCheck(args, treeFiles, repaired) {
  * because the module that is missing is no longer imported to be reported.
  * Fail closed: the alias keeps the refusal it had before the repair.
  */
+/**
+ * Detail for a pinned external that does not resolve on an installed checkout.
+ * A subpath on the specifier means the rewrite found no entry of the package
+ * exporting a declaration from that file, so it named the file itself.
+ */
+function unresolvedExternalDetail(spec) {
+    const pkg = packageNameOf(spec);
+    const subpath = spec.slice(pkg.length + 1);
+    const base = `unresolved pinned external '${spec}' on an installed checkout`;
+    return subpath ? `${base}: no entry of '${pkg}' exports a declaration from '${subpath}'` : base;
+}
 function repairedNameFailure(repaired, file, diagnostic, message) {
     if (!repaired || diagnostic.code !== 2304)
         return undefined;
@@ -432,7 +443,7 @@ function checkedRecord(anchor, ctx) {
             }
             else {
                 outcome = 'decayed_internal';
-                detail = `unresolved pinned external '${blamedExternal}' on an installed checkout`;
+                detail = unresolvedExternalDetail(blamedExternal);
             }
         }
         else {
@@ -452,7 +463,7 @@ function checkedRecord(anchor, ctx) {
         }
         else {
             outcome = 'decayed_internal';
-            detail = `unresolved pinned external '${blamedExternal}' on an installed checkout`;
+            detail = unresolvedExternalDetail(blamedExternal);
         }
     }
     return {