carrick 0.3.53

package/sidecar/dist/src/index.js

@@ -0,0 +1,564 @@
+/**
+ * Main entry point for the type-sidecar
+ *
+ * This module implements a message loop that:
+ * 1. Listens on stdin for JSON requests
+ * 2. Processes each request (init, bundle, emit_surface, infer, build_workspace, check_compatibility, health, shutdown)
+ * 3. Writes JSON responses to stdout
+ *
+ * IMPORTANT:
+ * - stdout is ONLY for JSON responses
+ * - stderr is for logging
+ * - Process stays alive between requests (warm standby)
+ */
+import * as readline from 'node:readline';
+import { parseRequest } from './validators.js';
+import { ProjectLoader } from './project-loader.js';
+import { TypeBundler, SurfaceEmitter } from './bundler.js';
+import { TypeInferrer } from './type-inferrer.js';
+import { MonorepoBuilder } from './monorepo-builder.js';
+import { DefinitionResolver } from './definition-resolver.js';
+import { captureStub, runCheck } from './capture/index.js';
+// ===========================================================================
+// Module-level state
+// ===========================================================================
+let projectLoader = null;
+let monorepoBuilder = null;
+let initTimeMs = null;
+let components = null;
+/**
+ * Get the project-backed components, building the project if this is the
+ * first request that needs it.
+ *
+ * @throws if init has not run, or if the project cannot be built
+ */
+function projectComponents() {
+    if (!projectLoader?.isInitialized()) {
+        throw new Error('Sidecar not initialized. Call init first.');
+    }
+    if (!components) {
+        const project = projectLoader.getProject();
+        const repoRoot = projectLoader.getRepoRoot();
+        components = {
+            typeBundler: new TypeBundler({ project, repoRoot }),
+            surfaceEmitter: new SurfaceEmitter({ project, repoRoot }),
+            typeInferrer: new TypeInferrer({ project }),
+            definitionResolver: new DefinitionResolver({ project }),
+        };
+    }
+    return components;
+}
+// ===========================================================================
+// Request Handlers
+// ===========================================================================
+/**
+ * Handle the 'init' action - initialize the TypeScript project
+ */
+function handleInit(request) {
+    const startTime = performance.now();
+    try {
+        log(`Initializing with repo_root: ${request.repo_root}`);
+        // Re-init re-scopes the sidecar to another root: drop everything built
+        // over the previous project before resolving the new one.
+        components = null;
+        projectLoader = new ProjectLoader({
+            repoRoot: request.repo_root,
+            tsconfigPath: request.tsconfig_path,
+            tsconfigSnapshot: request.tsconfig_snapshot,
+            pinnedDependencies: request.pinned_dependencies,
+        });
+        const result = projectLoader.load();
+        if (!result.success) {
+            return {
+                request_id: request.request_id,
+                status: 'error',
+                errors: [result.error || 'Unknown initialization error'],
+                init_time_ms: result.initTimeMs,
+            };
+        }
+        // The project and everything that reads it are built by the first request
+        // that needs them, so readiness costs the same on a bare checkout as on
+        // one with its dependencies installed (carrick#749).
+        // Initialize monorepo builder (doesn't need project)
+        monorepoBuilder = new MonorepoBuilder();
+        initTimeMs = result.initTimeMs || Math.round(performance.now() - startTime);
+        log(`Initialization complete in ${initTimeMs}ms`);
+        return {
+            request_id: request.request_id,
+            status: 'ready',
+            init_time_ms: initTimeMs,
+        };
+    }
+    catch (err) {
+        const error = err instanceof Error ? err.message : String(err);
+        logError(`Initialization failed: ${error}`);
+        return {
+            request_id: request.request_id,
+            status: 'error',
+            errors: [error],
+            init_time_ms: Math.round(performance.now() - startTime),
+        };
+    }
+}
+/**
+ * Handle the 'bundle' action - bundle explicit types (legacy)
+ */
+function handleBundle(request) {
+    try {
+        log(`Bundling ${request.symbols.length} symbol(s)`);
+        const result = projectComponents().typeBundler.bundle(request.symbols);
+        if (!result.success) {
+            return {
+                request_id: request.request_id,
+                status: 'error',
+                dts_content: result.dts_content,
+                manifest: result.manifest,
+                symbol_failures: result.symbol_failures,
+                errors: result.errors,
+            };
+        }
+        return {
+            request_id: request.request_id,
+            status: 'success',
+            dts_content: result.dts_content,
+            manifest: result.manifest,
+            symbol_failures: result.symbol_failures,
+        };
+    }
+    catch (err) {
+        const error = err instanceof Error ? err.message : String(err);
+        logError(`Bundle failed: ${error}`);
+        return {
+            request_id: request.request_id,
+            status: 'error',
+            errors: [error],
+        };
+    }
+}
+/**
+ * Handle the 'emit_surface' action - emit a surface .d.ts with rewritten specifiers
+ */
+function handleEmitSurface(request) {
+    try {
+        log(`Emitting surface for repo '${request.repo_name}' with ${request.payloads.length} payload(s)`);
+        const result = projectComponents().surfaceEmitter.emit(request.repo_name, request.payloads, request.output_path);
+        if (!result.success) {
+            return {
+                request_id: request.request_id,
+                status: 'error',
+                errors: result.errors,
+            };
+        }
+        return {
+            request_id: request.request_id,
+            status: 'success',
+            output_path: result.output_path,
+            surface_content: result.surface_content,
+            manifest: result.manifest,
+        };
+    }
+    catch (err) {
+        const error = err instanceof Error ? err.message : String(err);
+        logError(`Surface emission failed: ${error}`);
+        return {
+            request_id: request.request_id,
+            status: 'error',
+            errors: [error],
+        };
+    }
+}
+/**
+ * Handle the 'capture_v2' action - v2 "tsc as serializer" capture.
+ * Stateless by design: unlike bundle/infer it needs no init'd ts-morph
+ * project, only the repo's own tsconfig — this is the point of v2. The
+ * capture bundle behind this action is the seam ("seam, not split"): this
+ * dispatcher call is the only non-type reach-in.
+ */
+function handleCaptureV2(request) {
+    try {
+        log(`capture_v2 for service '${request.service_name}' (${request.anchors.length} anchor(s))`);
+        const result = captureStub({
+            repoRoot: request.repo_root,
+            serviceName: request.service_name,
+            anchors: request.anchors,
+            outDir: request.out_dir,
+            tsconfigPath: request.tsconfig_path,
+        });
+        return {
+            request_id: request.request_id,
+            status: result.success ? 'success' : 'error',
+            result,
+            errors: result.errors.length > 0 ? result.errors : undefined,
+        };
+    }
+    catch (err) {
+        const error = err instanceof Error ? err.message : String(err);
+        logError(`capture_v2 failed: ${error}`);
+        return {
+            request_id: request.request_id,
+            status: 'error',
+            errors: [error],
+        };
+    }
+}
+/**
+ * Handle the 'check_v2' action - v2 "tsc as judge" compatibility check.
+ *
+ * Async by necessity: the vendored pnpm install can exceed the Rust client's
+ * read deadline, and running it off the event loop (spawn, not execSync) keeps
+ * the sidecar responsive. Emits `status: 'progress'` keepalive frames during
+ * install/check and one terminal `success`/`error` frame. Writes its own
+ * frames, so processLine hands off and does not write a response for it.
+ */
+async function handleCheckV2Async(request) {
+    let phase = 'assembling';
+    const keepalive = setInterval(() => {
+        writeProgress(request.request_id, phase, `check ${phase}`);
+    }, 1500);
+    keepalive.unref();
+    try {
+        log(`check_v2: ${request.stubs.length} stub(s), ${request.pairs.length} pair(s)`);
+        const result = await runCheck({
+            stubs: request.stubs,
+            pairs: request.pairs,
+            workspaceRoot: request.workspace_root,
+            cleanup: request.keep_workspace !== true,
+        }, (p) => {
+            phase = p;
+        });
+        clearInterval(keepalive);
+        const response = {
+            request_id: request.request_id,
+            status: result.success ? 'success' : 'error',
+            result,
+            errors: result.errors.length > 0 ? result.errors : undefined,
+        };
+        writeResponse(response);
+    }
+    catch (err) {
+        clearInterval(keepalive);
+        const error = err instanceof Error ? err.message : String(err);
+        logError(`check_v2 failed: ${error}`);
+        writeResponse({
+            request_id: request.request_id,
+            status: 'error',
+            errors: [error],
+        });
+    }
+}
+/**
+ * Handle the 'infer' action - infer implicit types
+ */
+function handleInfer(request) {
+    try {
+        log(`Inferring ${request.requests.length} type(s)`);
+        const result = projectComponents().typeInferrer.infer(request.requests, request.extraction_config);
+        return {
+            request_id: request.request_id,
+            status: result.success ? 'success' : 'error',
+            inferred_types: result.inferred_types,
+            errors: result.errors,
+        };
+    }
+    catch (err) {
+        const error = err instanceof Error ? err.message : String(err);
+        logError(`Inference failed: ${error}`);
+        return {
+            request_id: request.request_id,
+            status: 'error',
+            errors: [error],
+        };
+    }
+}
+/**
+ * Handle the 'build_workspace' action - build synthetic monorepo workspace
+ */
+function handleBuildWorkspace(request) {
+    // MonorepoBuilder doesn't require project initialization
+    if (!monorepoBuilder) {
+        monorepoBuilder = new MonorepoBuilder();
+    }
+    try {
+        log(`Building synthetic workspace with ${request.repos.length} repo(s)`);
+        const result = monorepoBuilder.build(request.repos, request.workspace_root);
+        if (!result.success) {
+            return {
+                request_id: request.request_id,
+                status: 'error',
+                errors: result.errors,
+            };
+        }
+        return {
+            request_id: request.request_id,
+            status: 'success',
+            workspace_path: result.workspace_path,
+            stub_packages: result.stub_packages,
+            checker_path: result.checker_path,
+        };
+    }
+    catch (err) {
+        const error = err instanceof Error ? err.message : String(err);
+        logError(`Workspace build failed: ${error}`);
+        return {
+            request_id: request.request_id,
+            status: 'error',
+            errors: [error],
+        };
+    }
+}
+/**
+ * Handle the 'check_compatibility' action - run type compatibility checks
+ */
+function handleCheckCompatibility(request) {
+    if (!monorepoBuilder) {
+        monorepoBuilder = new MonorepoBuilder();
+    }
+    try {
+        log(`Running compatibility checks: ${request.checks.length} check(s)`);
+        const result = monorepoBuilder.checkCompatibility(request.workspace_root, request.checks);
+        if (!result.success) {
+            return {
+                request_id: request.request_id,
+                status: 'error',
+                errors: result.errors,
+            };
+        }
+        return {
+            request_id: request.request_id,
+            status: 'success',
+            results: result.results,
+            diagnostics: result.diagnostics,
+        };
+    }
+    catch (err) {
+        const error = err instanceof Error ? err.message : String(err);
+        logError(`Compatibility check failed: ${error}`);
+        return {
+            request_id: request.request_id,
+            status: 'error',
+            errors: [error],
+        };
+    }
+}
+/**
+ * Handle the 'resolve_definitions' action - resolve surface aliases from a
+ * v2 capture stub package's declaration tree.
+ */
+function handleResolveDefinitions(request) {
+    try {
+        log(`Resolving ${request.aliases.length} type alias(es) from ${request.stub_dir}`);
+        const results = projectComponents().definitionResolver.resolveFromStub(request.stub_dir, request.aliases);
+        return {
+            request_id: request.request_id,
+            status: 'success',
+            definitions: results.map((r) => ({
+                type_alias: r.type_alias,
+                definition: r.definition,
+                expanded: r.expanded,
+            })),
+        };
+    }
+    catch (err) {
+        const error = err instanceof Error ? err.message : String(err);
+        logError(`Definition resolution failed: ${error}`);
+        return {
+            request_id: request.request_id,
+            status: 'error',
+            errors: [error],
+        };
+    }
+}
+/**
+ * Handle the 'health' action - report initialization status
+ */
+function handleHealth(request) {
+    const isReady = projectLoader?.isInitialized() ?? false;
+    return {
+        request_id: request.request_id,
+        status: isReady ? 'ready' : 'not_ready',
+        init_time_ms: initTimeMs ?? undefined,
+    };
+}
+/**
+ * Handle the 'shutdown' action - exit gracefully
+ */
+function handleShutdown(request) {
+    log('Shutdown requested');
+    // Schedule exit after response is sent
+    setImmediate(() => {
+        log('Exiting');
+        process.exit(0);
+    });
+    return {
+        request_id: request.request_id,
+        status: 'success',
+    };
+}
+// ===========================================================================
+// Request Router
+// ===========================================================================
+/**
+ * Route a request to the appropriate handler
+ */
+function handleRequest(request) {
+    switch (request.action) {
+        case 'init':
+            return handleInit(request);
+        case 'bundle':
+            return handleBundle(request);
+        case 'emit_surface':
+            return handleEmitSurface(request);
+        case 'capture_v2':
+            return handleCaptureV2(request);
+        case 'infer':
+            return handleInfer(request);
+        case 'build_workspace':
+            return handleBuildWorkspace(request);
+        case 'check_compatibility':
+            return handleCheckCompatibility(request);
+        case 'resolve_definitions':
+            return handleResolveDefinitions(request);
+        case 'health':
+            return handleHealth(request);
+        case 'shutdown':
+            return handleShutdown(request);
+        default:
+            // TypeScript should catch this, but just in case
+            return {
+                request_id: request.request_id || 'unknown',
+                status: 'error',
+                errors: [`Unknown action: ${request.action}`],
+            };
+    }
+}
+// ===========================================================================
+// Response Writer
+// ===========================================================================
+/**
+ * Write a JSON response to stdout
+ */
+function writeResponse(response) {
+    const json = JSON.stringify(response);
+    process.stdout.write(json + '\n');
+}
+/**
+ * Write a non-terminal progress/keepalive frame (async install protocol).
+ * Distinct `status: 'progress'` so clients skip it and wait for the terminal
+ * success/error frame.
+ */
+function writeProgress(requestId, phase, message) {
+    process.stdout.write(JSON.stringify({ request_id: requestId, status: 'progress', phase, message }) + '\n');
+}
+/**
+ * Write an error response for an invalid request
+ */
+function writeErrorResponse(requestId, error) {
+    const response = {
+        request_id: requestId,
+        status: 'error',
+        errors: [error],
+    };
+    writeResponse(response);
+}
+// ===========================================================================
+// Logging (to stderr only)
+// ===========================================================================
+function log(message) {
+    console.error(`[sidecar] ${message}`);
+}
+function logError(message) {
+    console.error(`[sidecar:error] ${message}`);
+}
+// ===========================================================================
+// Main Entry Point
+// ===========================================================================
+/**
+ * Process a single line of input
+ */
+function processLine(line) {
+    // Skip empty lines
+    const trimmed = line.trim();
+    if (!trimmed)
+        return;
+    // Parse JSON
+    let json;
+    try {
+        json = JSON.parse(trimmed);
+    }
+    catch (err) {
+        logError(`Invalid JSON: ${trimmed}`);
+        writeErrorResponse('unknown', `Invalid JSON: ${err instanceof Error ? err.message : String(err)}`);
+        return;
+    }
+    // Validate request
+    const parseResult = parseRequest(json);
+    if (!parseResult.success) {
+        logError(`Invalid request: ${parseResult.error}`);
+        writeErrorResponse(json?.request_id || 'unknown', parseResult.error);
+        return;
+    }
+    // check_v2 runs async (spawned pnpm install + tsc) and writes its own
+    // progress + terminal frames; hand off and return.
+    if (parseResult.request.action === 'check_v2') {
+        void handleCheckV2Async(parseResult.request);
+        return;
+    }
+    // Handle request
+    const response = handleRequest(parseResult.request);
+    writeResponse(response);
+}
+/**
+ * Start the message loop
+ */
+function main() {
+    log('Process started');
+    const rl = readline.createInterface({
+        input: process.stdin,
+        output: process.stdout,
+        terminal: false,
+    });
+    rl.on('line', processLine);
+    rl.on('close', () => {
+        log('stdin closed, exiting');
+        process.exit(0);
+    });
+    // Handle process signals
+    process.on('SIGINT', () => {
+        log('SIGINT received, exiting');
+        process.exit(0);
+    });
+    process.on('SIGTERM', () => {
+        log('SIGTERM received, exiting');
+        process.exit(0);
+    });
+    // Fail fast on uncaught errors. Continuing after one means serving later
+    // requests from a possibly corrupted state and returning garbage types
+    // with a success status; exiting surfaces as ProcessDied on the Rust side,
+    // which degrades cleanly (scan continues, type_extraction_status records
+    // the loss).
+    process.on('uncaughtException', (err) => {
+        logError(`Uncaught exception (exiting): ${err.message}`);
+        logError(err.stack || '');
+        process.exit(1);
+    });
+    process.on('unhandledRejection', (reason) => {
+        // This log is the last diagnostic before exit, so it must be actionable:
+        // a bare interpolation renders non-Error reasons as [object Object].
+        let detail;
+        if (reason instanceof Error) {
+            detail = reason.stack || reason.message;
+        }
+        else {
+            try {
+                detail = JSON.stringify(reason) ?? String(reason);
+            }
+            catch {
+                detail = String(reason);
+            }
+        }
+        logError(`Unhandled rejection (exiting): ${detail}`);
+        process.exit(1);
+    });
+}
+// Start the sidecar
+main();

package/sidecar/dist/src/monorepo-builder.d.ts

@@ -0,0 +1,129 @@
+/**
+ * Monorepo Builder - Builds synthetic monorepo workspaces for type compatibility checking
+ *
+ * This module implements the "Synthetic Monorepo (Stub Snapshot)" architecture:
+ * - Creates a workspace with stub packages for each repo
+ * - Each stub package has its own isolated node_modules with pinned dependencies
+ * - Generates path mappings so @carrick/{repoName}/{spec} resolves correctly
+ * - Creates a checker package that imports surfaces and asserts type compatibility
+ *
+ * Key design decisions:
+ * - Uses pnpm for better isolation between packages
+ * - Does NOT copy full repos - only uses captured artifacts
+ * - Deterministic: uses pinned dependency snapshots
+ */
+import type { RepoMetadata, WorkspaceBuildResult, CompatibilityCheck, CompatibilityCheckResult } from './types.js';
+/**
+ * MonorepoBuilder - Creates synthetic workspaces for cross-repo type checking
+ *
+ * Usage:
+ *   const builder = new MonorepoBuilder();
+ *   const result = builder.build(repos);
+ *   const checkResult = builder.checkCompatibility(workspacePath, checks);
+ */
+export declare class MonorepoBuilder {
+    /**
+     * Build the synthetic monorepo workspace
+     *
+     * @param repos - Metadata for each repository to include
+     * @param workspaceRoot - Root directory for the workspace (defaults to .carrick/workspace)
+     * @returns WorkspaceBuildResult
+     */
+    build(repos: RepoMetadata[], workspaceRoot?: string): WorkspaceBuildResult;
+    /**
+     * Run type compatibility checks in the workspace
+     *
+     * @param workspaceRoot - Path to the workspace root
+     * @param checks - Compatibility checks to run
+     * @returns CompatibilityCheckResult
+     */
+    checkCompatibility(workspaceRoot: string, checks: CompatibilityCheck[]): CompatibilityCheckResult;
+    /**
+     * Ensure a clean directory exists at the given path
+     */
+    private ensureCleanDirectory;
+    /**
+     * Create the root package.json for the workspace
+     */
+    private createRootPackageJson;
+    /**
+     * Create pnpm-workspace.yaml
+     */
+    private createPnpmWorkspaceYaml;
+    /**
+     * Create .npmrc to prevent hoisting that would blur package boundaries
+     */
+    private createNpmrc;
+    /**
+     * Create a stub package for a repository
+     *
+     * @returns Path to the created package
+     */
+    private createStubPackage;
+    /**
+     * Create package.json for a stub package
+     */
+    private createStubPackageJson;
+    /**
+     * Create tsconfig.json for a stub package from the snapshot
+     */
+    private createStubTsconfig;
+    /**
+     * Create the surface.d.ts file
+     */
+    private createSurfaceFile;
+    /**
+     * Create a placeholder surface file
+     */
+    private createPlaceholderSurface;
+    /**
+     * Get default tsconfig snapshot
+     */
+    private getDefaultTsconfigSnapshot;
+    /**
+     * Create the checker package that runs type compatibility checks
+     *
+     * @returns Path to the checker package
+     */
+    private createCheckerPackage;
+    /**
+     * Create package.json for the checker package
+     */
+    private createCheckerPackageJson;
+    /**
+     * Create tsconfig.json for the checker package with path mappings
+     */
+    private createCheckerTsconfig;
+    /**
+     * Create initial checks.ts file
+     */
+    private createInitialChecksFile;
+    /**
+     * Install dependencies using pnpm
+     */
+    private installDependencies;
+    /**
+     * Fallback: Install dependencies using npm
+     */
+    private installWithNpm;
+    /**
+     * Generate the checks.ts file with type assertions
+     */
+    private generateCheckFile;
+    /**
+     * Create a unique import name for a repo/alias combination
+     */
+    private makeImportName;
+    /**
+     * Run TypeScript type checking on the checker package
+     *
+     * @returns Object with success status and any error output
+     */
+    private runTypeCheck;
+    /**
+     * Parse the result of a type check for a specific compatibility check
+     */
+    private parseCheckResult;
+    private log;
+    private logError;
+}