carrick 0.3.53

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

@@ -0,0 +1,450 @@
+/**
+ * v2 check core: "tsc as the judge"
+ * (docs/reference/type-compat-synthetic-monorepo.md, Check phase).
+ *
+ * Consumes two or more capture stub packages, assembles a scratch synthetic
+ * monorepo, installs pinned deps with the vendored pnpm (isolated linker),
+ * generates one probe per matched pair, runs the vendored `tsc` CLI, and
+ * classifies diagnostics into the four buckets. Deterministic given the stubs
+ * and pairs: verdicts are byte-stable across runs (the scrub pass removes the
+ * per-run temp path, and the pair IDs / ordering derive from the pair specs).
+ *
+ * Seam: this file imports only node builtins, `typescript` (for the version
+ * string), and the rest of this bundle. The sidecar reaches it only through
+ * ./index.js. The judge is the `tsc` CLI (no compiler API), which keeps the
+ * check phase TS7-ready by construction.
+ */
+import { spawn } from 'node:child_process';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import ts from 'typescript';
+import { buildProbe } from './check-probe.js';
+import { classifyPair, parseTscOutput, } from './check-classify.js';
+import { scrubPaths } from './check-scrub.js';
+import { assembleWorkspace, writeProbes, } from './check-workspace.js';
+import { buildPoisonIndexes } from './check-poison.js';
+import { probeDeepFindings } from './check-deep.js';
+function runProcess(command, args, cwd) {
+    return new Promise((resolve, reject) => {
+        const child = spawn(command, args, { cwd, stdio: ['ignore', 'pipe', 'pipe'] });
+        let stdout = '';
+        let stderr = '';
+        child.stdout.on('data', (d) => (stdout += d.toString()));
+        child.stderr.on('data', (d) => (stderr += d.toString()));
+        child.on('error', reject);
+        child.on('close', (code) => resolve({ code, stdout, stderr }));
+    });
+}
+/** Resolve the sidecar root (where the vendored pnpm/tsc live) from this bundle. */
+function sidecarRoot() {
+    // dist/src/capture/check.js -> up three -> sidecar root.
+    const here = path.dirname(fileURLToPath(import.meta.url));
+    return path.resolve(here, '..', '..', '..');
+}
+/**
+ * Locate a vendored executable the way node locates a package: walk up from
+ * the bundle and take the first `node_modules/.bin/<name>` that exists.
+ *
+ * Where the bins sit depends on how the sidecar arrived. A checkout and the
+ * release tarball both keep them in the sidecar's own `node_modules`, so the
+ * first candidate hits and nothing changes. An npm install never can: npm
+ * strips nested `node_modules` from a published tarball, so the sidecar ships
+ * as a plain directory inside the package and its dependencies are installed
+ * by the package that carries it — hoisted to the install root, or nested one
+ * level up when a version conflict forces it. Assuming one shape is what made
+ * an installed `carrick` degrade every pair to unverifiable (carrick#833).
+ *
+ * `from` is injectable so the layouts can be pinned by test; production always
+ * starts at the bundle. Returns the sidecar-local path when nothing exists,
+ * 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);
+    for (let dir = from;; dir = path.dirname(dir)) {
+        const candidate = path.join(dir, 'node_modules', '.bin', name);
+        if (fs.existsSync(candidate))
+            return candidate;
+        if (path.dirname(dir) === dir)
+            return local;
+    }
+}
+function binPath(name) {
+    return resolveVendoredBin(name);
+}
+function unverifiableAll(plans, gate, diagnostic) {
+    return plans.map((plan) => ({
+        pair_id: plan.pairId,
+        pair_key: plan.spec.pair_key,
+        bucket: 'unverifiable',
+        gate,
+        diagnostic,
+        codes: [],
+        resolved: false,
+        unresolved_reason: diagnostic,
+    }));
+}
+function sortVerdicts(verdicts) {
+    return [...verdicts].sort((a, b) => a.pair_id < b.pair_id ? -1 : a.pair_id > b.pair_id ? 1 : 0);
+}
+/** Run the deterministic check phase. Async: install + tsc run off the event
+ * loop so the sidecar stays responsive and can emit keepalive frames. */
+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;
+    // 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).
+    if (!fs.existsSync(pnpmPath)) {
+        const planned = planPairs(opts, (s) => `@carrick/${s}`);
+        return {
+            success: false,
+            workspace_dir: '',
+            isolation: 'unavailable',
+            install_ok: false,
+            install_error: 'vendored pnpm not found; type isolation is unavailable',
+            ts_version: tsVersion,
+            verdicts: sortVerdicts(unverifiableAll(planned, 'isolation:unavailable', 'type isolation unavailable (pnpm missing); compatibility cannot be verified.')),
+            degraded_services: opts.stubs.map((s) => ({
+                service_name: s.service_name,
+                reason: 'isolation unavailable',
+            })),
+            errors: ['vendored pnpm not found'],
+        };
+    }
+    progress('assembling', 'assembling synthetic workspace');
+    const ws = assembleWorkspace({
+        stubs: opts.stubs,
+        workspaceRoot: opts.workspaceRoot,
+    });
+    const scrubCtx = {
+        workspaceRoot: ws.workspaceDir,
+        packageLabelOf: ws.packageLabelOf,
+    };
+    // Generate probes. A pair naming a service with no stub is unverifiable.
+    const plans = [];
+    const unresolved = [];
+    for (const spec of opts.pairs) {
+        try {
+            plans.push(buildProbe(spec, ws.packageOf));
+        }
+        catch {
+            unresolved.push({
+                pair_id: '',
+                pair_key: spec.pair_key,
+                bucket: 'unverifiable',
+                gate: 'missing:stub',
+                diagnostic: 'a stub for one side of this pair was not provided; compatibility cannot be verified.',
+                codes: [],
+                resolved: false,
+                unresolved_reason: 'one side of this pair has no captured type surface',
+            });
+        }
+    }
+    // Backfill deterministic pair IDs for unresolved pairs from the spec.
+    for (const v of unresolved) {
+        const spec = opts.pairs.find((p) => p.pair_key === v.pair_key);
+        v.pair_id = fnvOfSpec(spec);
+    }
+    // Capture-time deep-decay pre-gate (adversarial-review finding 1): a
+    // member-level `any`/`unknown` recorded by the capture self-check with no
+    // failing-external explanation. The probe gates below are WHOLE-type only
+    // — `{ orderId: string; metadata: any }` sails through IsAny and the
+    // assignment compiles clean — so such pairs must never reach a probe.
+    // `any` routes to gate_caught_baked_any, `unknown` to unverifiable; both
+    // read as None downstream, never compatible.
+    const aliasRecords = readStubAliasRecords(opts.stubs);
+    const preGated = [];
+    const probing = [];
+    for (const plan of plans) {
+        const hit = deepDecayOf(plan, aliasRecords);
+        if (!hit) {
+            probing.push(plan);
+            continue;
+        }
+        preGated.push({
+            pair_id: plan.pairId,
+            pair_key: plan.spec.pair_key,
+            // `any` is a confirmed baked top type -> gate_caught_baked_any; `unknown`
+            // and `budget_exhausted` (a subtree the capture walk could not finish)
+            // are "cannot verify" -> unverifiable. All read as None downstream.
+            bucket: hit.kind === 'any' ? 'gate_caught_baked_any' : 'unverifiable',
+            gate: `capture:${hit.side}:${hit.kind}`,
+            diagnostic: hit.kind === 'budget_exhausted'
+                ? `the ${hit.side} type is too deep or wide to verify within the ` +
+                    `capture budget (at '${hit.path}'); compatibility cannot be ` +
+                    `verified — abstaining so a buried 'any' can never read compatible.`
+                : `the ${hit.side} type carries '${hit.kind}' at '${hit.path}' from ` +
+                    `capture; compatibility cannot be verified (a partially-unresolved ` +
+                    `type would let an arbitrary shape read compatible).`,
+            codes: [],
+            resolved: false,
+            unresolved_reason: hit.kind === 'budget_exhausted'
+                ? `the ${hit.side} type is too deep or wide to verify at '${hit.path}'`
+                : `the ${hit.side} type carries '${hit.kind}' at '${hit.path}'`,
+        });
+    }
+    writeProbes(ws, probing);
+    const errors = [];
+    const degraded = [];
+    // ---- Install (async, off the event loop) --------------------------------
+    progress('installing', 'installing pinned dependencies');
+    const install = await runProcess(pnpmPath, ['install'], ws.workspaceDir);
+    const installOk = install.code === 0;
+    let installError;
+    if (!installOk) {
+        installError = scrubPaths((install.stderr || install.stdout).trim().slice(0, 2000), scrubCtx);
+        for (const s of opts.stubs) {
+            degraded.push({ service_name: s.service_name, reason: 'workspace install failed' });
+        }
+        const verdicts = sortVerdicts([
+            ...unverifiableAll(probing, 'install:failed', 'workspace dependency install failed; compatibility cannot be verified.'),
+            // Capture-decay verdicts stand regardless of the install outcome.
+            ...preGated,
+            ...unresolved,
+        ]);
+        if (cleanup)
+            safeRm(ws.workspaceDir);
+        return {
+            success: false,
+            workspace_dir: cleanup ? '' : ws.workspaceDir,
+            isolation: 'pnpm',
+            install_ok: false,
+            install_error: installError,
+            ts_version: tsVersion,
+            verdicts,
+            degraded_services: degraded,
+            errors,
+        };
+    }
+    // ---- Judge (async, off the event loop) ----------------------------------
+    progress('checking', 'type-checking probes');
+    const tsc = await runProcess(tscPath, ['--noEmit', '--pretty', 'false', '-p', path.join(ws.probesRel, 'tsconfig.json')], ws.workspaceDir);
+    const diagnostics = parseTscOutput(tsc.stdout + '\n' + tsc.stderr);
+    // Abnormal tsc termination: OOM/SIGKILL (exit code null), an internal
+    // crash, or a fileless config error (e.g. TS18003, printed without a
+    // (line,col) prefix) all yield ZERO parseable diagnostics — and an empty
+    // diagnostic set must never fall through to "compatible". A non-zero exit
+    // WITH parsed diagnostics is the legitimate incompatible path (tsc exits 1
+    // on ordinary type errors) and stays untouched. Mirrors the install step's
+    // `code === 0` guard.
+    if (tsc.code !== 0 && diagnostics.length === 0) {
+        const excerpt = scrubPaths((tsc.stderr || tsc.stdout).trim().slice(0, 2000), scrubCtx);
+        errors.push(`tsc terminated abnormally (exit code ${tsc.code ?? 'null'}) ` +
+            `with no parseable diagnostics${excerpt ? `: ${excerpt}` : ''}`);
+        for (const s of opts.stubs) {
+            degraded.push({
+                service_name: s.service_name,
+                reason: 'type checker terminated abnormally',
+            });
+        }
+        const verdicts = sortVerdicts([
+            ...unverifiableAll(probing, 'tsc:abnormal-termination', 'the type checker terminated abnormally; compatibility cannot be verified.'),
+            ...preGated,
+            ...unresolved,
+        ]);
+        if (cleanup)
+            safeRm(ws.workspaceDir);
+        return {
+            success: false,
+            workspace_dir: cleanup ? '' : ws.workspaceDir,
+            isolation: 'pnpm',
+            install_ok: true,
+            ts_version: tsVersion,
+            verdicts,
+            degraded_services: dedupeDegraded(degraded),
+            errors,
+        };
+    }
+    const { probeDiagsByPair, poison, globalErrors } = attributeDiagnostics(diagnostics, ws, probing);
+    for (const e of globalErrors)
+        errors.push(scrubPaths(e, scrubCtx));
+    // Only SERVICE-WIDE poison (an unattributable stub diagnostic) degrades the
+    // whole service; contained alias-scoped poison rides its own verdicts.
+    for (const [service, scope] of poison) {
+        if (scope.all)
+            degraded.push({ service_name: service, reason: scope.reason });
+    }
+    const poisonReason = (service, alias) => {
+        const scope = poison.get(service);
+        if (!scope)
+            return undefined;
+        return scope.all || scope.aliases.has(alias) ? scope.reason : undefined;
+    };
+    // Fact-ness walk (carrick#707, R1d): the probe gates are whole-type only,
+    // so a compared pair is only a fact about two known types when neither side
+    // carries a member-level any/unknown HERE — after install, where the capture
+    // could not look (carrick#450). It sets `resolved` and nothing else; no
+    // bucket depends on it.
+    const deepByPair = probeDeepFindings(ws.probesDir, probing);
+    const verdicts = sortVerdicts([
+        ...probing.map((plan) => classifyPair({
+            plan,
+            probeDiags: probeDiagsByPair.get(plan.pairId) ?? [],
+            poisonReason,
+            scrubCtx,
+            deepFindings: deepByPair.get(plan.pairId),
+        })),
+        ...preGated,
+        ...unresolved,
+    ]);
+    const workspaceDirOut = cleanup ? '' : ws.workspaceDir;
+    if (cleanup)
+        safeRm(ws.workspaceDir);
+    return {
+        success: true,
+        workspace_dir: workspaceDirOut,
+        isolation: 'pnpm',
+        install_ok: true,
+        ts_version: tsVersion,
+        verdicts,
+        degraded_services: dedupeDegraded(degraded),
+        errors,
+    };
+}
+/**
+ * Per-service alias records from each stub's carrick-manifest.json. Absent
+ * or unparseable manifests (e.g. hand-authored stubs in tests) contribute
+ * nothing — only positively-recorded deep decay pre-gates a pair.
+ */
+function readStubAliasRecords(stubs) {
+    const byService = new Map();
+    for (const stub of stubs) {
+        try {
+            const manifest = JSON.parse(fs.readFileSync(path.join(stub.stub_dir, 'carrick-manifest.json'), 'utf8'));
+            const byAlias = new Map();
+            for (const record of manifest.aliases ?? []) {
+                if (record?.alias)
+                    byAlias.set(record.alias, record);
+            }
+            byService.set(stub.service_name, byAlias);
+        }
+        catch {
+            // No manifest: nothing to pre-gate for this stub.
+        }
+    }
+    return byService;
+}
+/** First side (producer, then consumer) whose capture recorded a deep decay. */
+function deepDecayOf(plan, aliasRecords) {
+    for (const side of ['producer', 'consumer']) {
+        const endpoint = plan.spec[side];
+        const record = aliasRecords.get(endpoint.service_name)?.get(endpoint.alias);
+        // The capture emits every deep finding it made; the FIRST is the one the
+        // pre-gate reads, exactly as when the walk stopped at the first hit.
+        const finding = record?.any_provenance?.[0];
+        if (finding) {
+            return { side, kind: finding.kind, path: finding.path };
+        }
+    }
+    return undefined;
+}
+const POISON_REASON = 'stub type tree carries its own diagnostics';
+/**
+ * Group diagnostics: per-probe (for classification), plus stub-tree poison
+ * CONTAINED to the aliases reachable from the poisoned file (#438 part 2). An
+ * unattributable stub diagnostic (an augmentation-file collision in no alias's
+ * closure) falls back to service-wide poison; everything else is scoped.
+ */
+function attributeDiagnostics(diagnostics, ws, plans) {
+    const probeFileToPair = new Map();
+    for (const plan of plans) {
+        probeFileToPair.set(`${ws.probesRel}/probes/${plan.fileName}`, plan.pairId);
+    }
+    const stubDirs = new Set(ws.stubs.map((s) => s.packageDir));
+    // Lazy: the clean path (no stub-tree diagnostic) must not walk and parse
+    // every stub `.d.ts` tree. Built on first stub-tree diagnostic, at most once.
+    let indexesMemo;
+    const getIndexes = () => (indexesMemo ??= buildPoisonIndexes(ws));
+    const probeDiagsByPair = new Map();
+    const poison = new Map();
+    const globalErrors = [];
+    const scopeFor = (service) => {
+        let scope = poison.get(service);
+        if (!scope) {
+            scope = { all: false, aliases: new Set(), reason: POISON_REASON };
+            poison.set(service, scope);
+        }
+        return scope;
+    };
+    for (const d of diagnostics) {
+        if (!d.file) {
+            globalErrors.push(`TS${d.code}: ${d.message}`);
+            continue;
+        }
+        const pairId = probeFileToPair.get(d.file);
+        if (pairId) {
+            if (!probeDiagsByPair.has(pairId))
+                probeDiagsByPair.set(pairId, []);
+            probeDiagsByPair.get(pairId).push(d);
+            continue;
+        }
+        // Stub-tree diagnostics poison that stub (its OWN sources, not deps).
+        const pkgMatch = d.file.match(/^packages\/([^/]+)\//);
+        if (pkgMatch && !d.file.includes('/node_modules/') && stubDirs.has(pkgMatch[1])) {
+            const service = ws.serviceOfPackageDir(pkgMatch[1]);
+            if (!service)
+                continue;
+            const scope = scopeFor(service);
+            const index = getIndexes().get(service);
+            if (index && d.file === index.surfaceFile) {
+                // Surface diagnostic: attribute by the alias statement span it sits in.
+                const alias = index.aliasAtSurfaceLine(d.line);
+                if (alias)
+                    scope.aliases.add(alias);
+                else
+                    scope.all = true;
+            }
+            else if (index) {
+                // Nested-file diagnostic: attribute to every alias whose closure reads
+                // it; a file in no closure (augmentation collision) falls back wide.
+                const affected = index.aliasesForFile(d.file);
+                if (affected.length > 0)
+                    for (const a of affected)
+                        scope.aliases.add(a);
+                else
+                    scope.all = true;
+            }
+            else {
+                scope.all = true;
+            }
+        }
+        // Anything else (node_modules, TS lib) is environmental: ignored for
+        // verdicts so it cannot inject nondeterministic noise.
+    }
+    return { probeDiagsByPair, poison, globalErrors };
+}
+function dedupeDegraded(list) {
+    const seen = new Map();
+    for (const d of list)
+        if (!seen.has(d.service_name))
+            seen.set(d.service_name, d);
+    return [...seen.values()].sort((a, b) => a.service_name < b.service_name ? -1 : a.service_name > b.service_name ? 1 : 0);
+}
+/** Plan pairs without a workspace (for the isolation-unavailable early exit). */
+function planPairs(opts, packageOf) {
+    const plans = [];
+    for (const spec of opts.pairs) {
+        try {
+            plans.push(buildProbe(spec, packageOf));
+        }
+        catch {
+            /* skipped in the early-exit path */
+        }
+    }
+    return plans;
+}
+function fnvOfSpec(spec) {
+    return buildProbe(spec, (s) => `@carrick/${s}`).pairId;
+}
+function safeRm(dir) {
+    try {
+        fs.rmSync(dir, { recursive: true, force: true });
+    }
+    catch {
+        /* best effort */
+    }
+}

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

@@ -0,0 +1,62 @@
+/**
+ * The structural any/unknown walk, shared by the two type surfaces that need it
+ * (carrick#448, carrick#707).
+ *
+ * Capture-time it runs over the emitted stub tree and decides whether an alias
+ * carries a member-level decay the check phase must pre-gate. Check-time it
+ * runs over the assembled probe workspace, where the pinned externals ARE
+ * installed, and decides whether a verdict is a fact about two known types or
+ * an artefact of a type nobody could see (`CheckVerdict.resolved`). The
+ * whole-type probe gates cannot answer that: `any` three members down passes
+ * every one of them.
+ *
+ * One walk, one budget, one path notation, so a finding means the same thing
+ * wherever it is reported.
+ */
+import ts from 'typescript';
+import type { TypeProvenance } from './api.js';
+/** A disqualifying finding below the root of a captured type: an author-baked
+ * `any`/`unknown`, or `budget_exhausted` — a subtree the walk could not finish
+ * within its depth/node budget, treated as unverifiable (fail closed) rather
+ * than silently clean. */
+export type DeepTopType = Pick<TypeProvenance, 'kind' | 'path'>;
+/**
+ * Depth-bounded structural walk for a disqualifying top type at ANY depth:
+ * a member, array element, index signature, type argument, or callable RETURN
+ * that resolved to `any` (bidirectionally assignable — an arbitrary
+ * counterparty shape reads compatible) or `unknown` (a failed-inference bake;
+ * carries no shape information). The check phase's probe gates are WHOLE-type
+ * only, so this walk owns the depths they cannot see. It is a genuine SUPERSET
+ * of v1's text-scan disqualifier (`contains_disqualifying_top_type`) at ALL
+ * depths/widths — so removing the `type_state == Unknown` pre-verdict (carrick
+ * #448) never turns a shape v1 would have abstained on into a false-compatible.
+ * The superset holds unconditionally because budget EXHAUSTION FAILS CLOSED
+ * (returns the `budget_exhausted` sentinel, not "clean"): a subtree too deep or
+ * wide to finish within budget is unverifiable, never silently compatible. A
+ * bigger bound would only relocate the fail-open cliff; failing closed removes
+ * it. v1's text scan is itself unbounded, so any disqualifier it would flag
+ * that lies past this walk's finite budget is still caught — as
+ * `budget_exhausted` rather than its exact kind.
+ *
+ * Cycle-safe. Two deliberate exceptions to "flag any/unknown anywhere":
+ *  - callable PARAMETER types are NOT descended (only return types): a
+ *    parameter `any` is contravariant and genuinely permissive (`(x: any) =>
+ *    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
+ *    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[];
+/**
+ * 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.
+ */
+export declare function provenanceOf(finding: DeepTopType): TypeProvenance;