carrick 0.3.97 → 0.3.98

package/sidecar/dist/src/index.js

@@ -11,6 +11,7 @@
  * - stderr is for logging
  * - Process stays alive between requests (warm standby)
  */
+import * as path from 'node:path';
 import * as readline from 'node:readline';
 import { parseRequest } from './validators.js';
 import { ProjectLoader } from './project-loader.js';
@@ -20,6 +21,7 @@ import { MonorepoBuilder } from './monorepo-builder.js';
 import { DefinitionResolver } from './definition-resolver.js';
 import { captureStub, findDisqualifyingTopTypes, jsonWireDeclarations, runCheck, } from './capture/index.js';
 import { Retyper } from './retype.js';
+import { ClientSemanticsVerifier } from './client-semantics.js';
 // ===========================================================================
 // Module-level state
 // ===========================================================================
@@ -66,6 +68,7 @@ function projectComponents() {
             // (`npm/carrick/package.json`) resolves `typescript ^5.8.0` unpinned,
             // so an install can pair ts-morph's copy with a newer 5.x.
             retyper: new Retyper(project, typeInferrer, jsonWireDeclarations, findDisqualifyingTopTypes),
+            semanticsVerifier: new ClientSemanticsVerifier(project),
         };
     }
     return components;
@@ -313,6 +316,36 @@ function handleRetypeCheck(request) {
         return { request_id: request.request_id, status: 'error', errors: [error] };
     }
 }
+/**
+ * How long one verify_client_semantics request may spend before the checks it
+ * has not reached come back `unchecked` with reason `budget`. The first request
+ * on a service may pay the program build, which counts against it; the checks
+ * themselves are cheap. Well inside the scanner's 900s read deadline.
+ */
+const SEMANTICS_BUDGET_MS = 600_000;
+/**
+ * Handle the 'verify_client_semantics' action - check library-semantics
+ * claims against each package's type declarations (carrick#1564)
+ */
+function handleVerifyClientSemantics(request) {
+    try {
+        const { semanticsVerifier } = projectComponents();
+        const fromDir = path.resolve(projectLoader.getRepoRoot(), request.from_dir);
+        log(`Verifying ${request.checks.length} client-semantics claim(s) from ${fromDir}`);
+        const { semantics, modules } = semanticsVerifier.run(fromDir, request.checks, request.budget_ms ?? SEMANTICS_BUDGET_MS);
+        return {
+            request_id: request.request_id,
+            status: 'success',
+            semantics,
+            semantics_modules: modules,
+        };
+    }
+    catch (err) {
+        const error = err instanceof Error ? err.message : String(err);
+        logError(`Client-semantics check failed: ${error}`);
+        return { request_id: request.request_id, status: 'error', errors: [error] };
+    }
+}
 /**
  * Handle the 'build_workspace' action - build synthetic monorepo workspace
  */
@@ -463,6 +496,8 @@ function handleRequest(request) {
             return handleResolveDefinitions(request);
         case 'retype_check':
             return handleRetypeCheck(request);
+        case 'verify_client_semantics':
+            return handleVerifyClientSemantics(request);
         case 'health':
             return handleHealth(request);
         case 'shutdown':

package/sidecar/dist/src/types.d.ts

@@ -320,10 +320,64 @@ export interface RetypeCheckRequest extends BaseRequest {
     /** Time the request may spend; items it does not reach abstain. */
     budget_ms?: number;
 }
+/**
+ * One library-semantics claim to check against the package's own type
+ * declarations, on one receiver (carrick#1564). The unit of verification is
+ * the pair `(claim_id, receiver)`.
+ */
+export interface SemanticsCheck {
+    claim_id: string;
+    /** Module specifier, resolved from the request's `from_dir`. */
+    package: string;
+    /** `"default"` or a named export. */
+    export: string;
+    /** `"export"` or `"instance:<factory member>"`. */
+    receiver: string;
+    claim: {
+        kind: 'factory';
+        member: string;
+        base_url_key: string;
+    } | {
+        kind: 'verb';
+        member: string;
+        method: string;
+    } | {
+        kind: 'verb_body';
+        member: string;
+        args: 'path_body' | 'path_options';
+        body_key?: string;
+    } | {
+        kind: 'request';
+        member: string | null;
+        args: 'config' | 'path_options';
+        url_key?: string;
+        method_key: string;
+    } | {
+        kind: 'request_body';
+        member: string | null;
+        args: 'config' | 'path_options';
+        url_key?: string;
+        method_key: string;
+        body_key: string;
+    };
+}
+/**
+ * Check library-semantics claims against each package's type declarations.
+ * Needs `init`: module resolution runs under the service's compiler options,
+ * in the service's program.
+ */
+export interface VerifyClientSemanticsRequest extends BaseRequest {
+    action: 'verify_client_semantics';
+    /** Absolute service root; module resolution starts here. */
+    from_dir: string;
+    checks: SemanticsCheck[];
+    /** Checks not reached in time come back `unchecked` with reason `budget`. */
+    budget_ms?: number;
+}
 /**
  * Union type for all possible sidecar requests
  */
-export type SidecarRequest = RetypeCheckRequest | InitRequest | BundleRequest | EmitSurfaceRequest | CaptureV2Request | CheckV2Request | InferRequest | BuildWorkspaceRequest | CheckCompatibilityRequest | ResolveDefinitionsRequest | HealthRequest | ShutdownRequest;
+export type SidecarRequest = RetypeCheckRequest | VerifyClientSemanticsRequest | InitRequest | BundleRequest | EmitSurfaceRequest | CaptureV2Request | CheckV2Request | InferRequest | BuildWorkspaceRequest | CheckCompatibilityRequest | ResolveDefinitionsRequest | HealthRequest | ShutdownRequest;
 /**
  * Request for a specific symbol to be bundled
  */
@@ -532,10 +586,37 @@ export interface RetypeCheckResponse extends BaseResponse {
     outcomes?: RetypeOutcome[];
     errors?: string[];
 }
+/**
+ * The verdict on one `(claim_id, receiver)` pair.
+ *
+ * - `verified`: the declarations satisfy the claim.
+ * - `failed`: the declarations resolved and contradict it.
+ * - `unchecked`: the declarations could not be read.
+ */
+export interface SemanticsResult {
+    claim_id: string;
+    receiver: string;
+    verdict: 'verified' | 'failed' | 'unchecked';
+    /** Absent exactly when verified. */
+    reason?: string;
+}
+/** How one package of the request resolved, for logs. */
+export interface SemanticsModule {
+    package: string;
+    resolved_file?: string;
+    installed_version?: string;
+    reason?: string;
+}
+export interface VerifyClientSemanticsResponse extends BaseResponse {
+    /** Exactly one per check, in request order. */
+    semantics?: SemanticsResult[];
+    semantics_modules?: SemanticsModule[];
+    errors?: string[];
+}
 /**
  * Union type for all possible sidecar responses
  */
-export type SidecarResponse = RetypeCheckResponse | InitResponse | BundleResponse | EmitSurfaceResponse | CaptureV2Response | CheckV2Response | InferResponse | BuildWorkspaceResponse | CheckCompatibilityResponse | ResolveDefinitionsResponse | HealthResponse | ShutdownResponse | ErrorResponse;
+export type SidecarResponse = RetypeCheckResponse | VerifyClientSemanticsResponse | InitResponse | BundleResponse | EmitSurfaceResponse | CaptureV2Response | CheckV2Response | InferResponse | BuildWorkspaceResponse | CheckCompatibilityResponse | ResolveDefinitionsResponse | HealthResponse | ShutdownResponse | ErrorResponse;
 /**
  * An entry in the type manifest
  */

package/sidecar/dist/src/validators.d.ts

@@ -1201,6 +1201,238 @@ export declare const RetypeCheckRequestSchema: z.ZodObject<{
     }[];
     budget_ms?: number | undefined;
 }>;
+export declare const VerifyClientSemanticsRequestSchema: z.ZodObject<{
+    request_id: z.ZodString;
+} & {
+    action: z.ZodLiteral<"verify_client_semantics">;
+    from_dir: z.ZodString;
+    checks: z.ZodArray<z.ZodObject<{
+        claim_id: z.ZodString;
+        package: z.ZodString;
+        export: z.ZodString;
+        receiver: z.ZodString;
+        claim: z.ZodDiscriminatedUnion<"kind", [z.ZodObject<{
+            kind: z.ZodLiteral<"factory">;
+            member: z.ZodString;
+            base_url_key: z.ZodString;
+        }, "strip", z.ZodTypeAny, {
+            kind: "factory";
+            member: string;
+            base_url_key: string;
+        }, {
+            kind: "factory";
+            member: string;
+            base_url_key: string;
+        }>, z.ZodObject<{
+            kind: z.ZodLiteral<"verb">;
+            member: z.ZodString;
+            method: z.ZodString;
+        }, "strip", z.ZodTypeAny, {
+            kind: "verb";
+            member: string;
+            method: string;
+        }, {
+            kind: "verb";
+            member: string;
+            method: string;
+        }>, z.ZodObject<{
+            kind: z.ZodLiteral<"verb_body">;
+            member: z.ZodString;
+            args: z.ZodEnum<["path_body", "path_options"]>;
+            body_key: z.ZodOptional<z.ZodString>;
+        }, "strip", z.ZodTypeAny, {
+            kind: "verb_body";
+            member: string;
+            args: "path_body" | "path_options";
+            body_key?: string | undefined;
+        }, {
+            kind: "verb_body";
+            member: string;
+            args: "path_body" | "path_options";
+            body_key?: string | undefined;
+        }>, z.ZodObject<{
+            kind: z.ZodLiteral<"request">;
+            member: z.ZodNullable<z.ZodString>;
+            args: z.ZodEnum<["config", "path_options"]>;
+            url_key: z.ZodOptional<z.ZodString>;
+            method_key: z.ZodString;
+        }, "strip", z.ZodTypeAny, {
+            kind: "request";
+            member: string | null;
+            args: "path_options" | "config";
+            method_key: string;
+            url_key?: string | undefined;
+        }, {
+            kind: "request";
+            member: string | null;
+            args: "path_options" | "config";
+            method_key: string;
+            url_key?: string | undefined;
+        }>, z.ZodObject<{
+            kind: z.ZodLiteral<"request_body">;
+            member: z.ZodNullable<z.ZodString>;
+            args: z.ZodEnum<["config", "path_options"]>;
+            url_key: z.ZodOptional<z.ZodString>;
+            method_key: z.ZodString;
+            body_key: z.ZodString;
+        }, "strip", z.ZodTypeAny, {
+            kind: "request_body";
+            member: string | null;
+            args: "path_options" | "config";
+            body_key: string;
+            method_key: string;
+            url_key?: string | undefined;
+        }, {
+            kind: "request_body";
+            member: string | null;
+            args: "path_options" | "config";
+            body_key: string;
+            method_key: string;
+            url_key?: string | undefined;
+        }>]>;
+    }, "strip", z.ZodTypeAny, {
+        export: string;
+        claim: {
+            kind: "factory";
+            member: string;
+            base_url_key: string;
+        } | {
+            kind: "verb";
+            member: string;
+            method: string;
+        } | {
+            kind: "verb_body";
+            member: string;
+            args: "path_body" | "path_options";
+            body_key?: string | undefined;
+        } | {
+            kind: "request";
+            member: string | null;
+            args: "path_options" | "config";
+            method_key: string;
+            url_key?: string | undefined;
+        } | {
+            kind: "request_body";
+            member: string | null;
+            args: "path_options" | "config";
+            body_key: string;
+            method_key: string;
+            url_key?: string | undefined;
+        };
+        claim_id: string;
+        package: string;
+        receiver: string;
+    }, {
+        export: string;
+        claim: {
+            kind: "factory";
+            member: string;
+            base_url_key: string;
+        } | {
+            kind: "verb";
+            member: string;
+            method: string;
+        } | {
+            kind: "verb_body";
+            member: string;
+            args: "path_body" | "path_options";
+            body_key?: string | undefined;
+        } | {
+            kind: "request";
+            member: string | null;
+            args: "path_options" | "config";
+            method_key: string;
+            url_key?: string | undefined;
+        } | {
+            kind: "request_body";
+            member: string | null;
+            args: "path_options" | "config";
+            body_key: string;
+            method_key: string;
+            url_key?: string | undefined;
+        };
+        claim_id: string;
+        package: string;
+        receiver: string;
+    }>, "many">;
+    budget_ms: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    request_id: string;
+    action: "verify_client_semantics";
+    checks: {
+        export: string;
+        claim: {
+            kind: "factory";
+            member: string;
+            base_url_key: string;
+        } | {
+            kind: "verb";
+            member: string;
+            method: string;
+        } | {
+            kind: "verb_body";
+            member: string;
+            args: "path_body" | "path_options";
+            body_key?: string | undefined;
+        } | {
+            kind: "request";
+            member: string | null;
+            args: "path_options" | "config";
+            method_key: string;
+            url_key?: string | undefined;
+        } | {
+            kind: "request_body";
+            member: string | null;
+            args: "path_options" | "config";
+            body_key: string;
+            method_key: string;
+            url_key?: string | undefined;
+        };
+        claim_id: string;
+        package: string;
+        receiver: string;
+    }[];
+    from_dir: string;
+    budget_ms?: number | undefined;
+}, {
+    request_id: string;
+    action: "verify_client_semantics";
+    checks: {
+        export: string;
+        claim: {
+            kind: "factory";
+            member: string;
+            base_url_key: string;
+        } | {
+            kind: "verb";
+            member: string;
+            method: string;
+        } | {
+            kind: "verb_body";
+            member: string;
+            args: "path_body" | "path_options";
+            body_key?: string | undefined;
+        } | {
+            kind: "request";
+            member: string | null;
+            args: "path_options" | "config";
+            method_key: string;
+            url_key?: string | undefined;
+        } | {
+            kind: "request_body";
+            member: string | null;
+            args: "path_options" | "config";
+            body_key: string;
+            method_key: string;
+            url_key?: string | undefined;
+        };
+        claim_id: string;
+        package: string;
+        receiver: string;
+    }[];
+    from_dir: string;
+    budget_ms?: number | undefined;
+}>;
 /**
  * The main sidecar request schema - a discriminated union on the 'action' field
  */
@@ -2312,6 +2544,237 @@ export declare const SidecarRequestSchema: z.ZodDiscriminatedUnion<"action", [z.
     budget_ms?: number | undefined;
 }>, z.ZodObject<{
     request_id: z.ZodString;
+} & {
+    action: z.ZodLiteral<"verify_client_semantics">;
+    from_dir: z.ZodString;
+    checks: z.ZodArray<z.ZodObject<{
+        claim_id: z.ZodString;
+        package: z.ZodString;
+        export: z.ZodString;
+        receiver: z.ZodString;
+        claim: z.ZodDiscriminatedUnion<"kind", [z.ZodObject<{
+            kind: z.ZodLiteral<"factory">;
+            member: z.ZodString;
+            base_url_key: z.ZodString;
+        }, "strip", z.ZodTypeAny, {
+            kind: "factory";
+            member: string;
+            base_url_key: string;
+        }, {
+            kind: "factory";
+            member: string;
+            base_url_key: string;
+        }>, z.ZodObject<{
+            kind: z.ZodLiteral<"verb">;
+            member: z.ZodString;
+            method: z.ZodString;
+        }, "strip", z.ZodTypeAny, {
+            kind: "verb";
+            member: string;
+            method: string;
+        }, {
+            kind: "verb";
+            member: string;
+            method: string;
+        }>, z.ZodObject<{
+            kind: z.ZodLiteral<"verb_body">;
+            member: z.ZodString;
+            args: z.ZodEnum<["path_body", "path_options"]>;
+            body_key: z.ZodOptional<z.ZodString>;
+        }, "strip", z.ZodTypeAny, {
+            kind: "verb_body";
+            member: string;
+            args: "path_body" | "path_options";
+            body_key?: string | undefined;
+        }, {
+            kind: "verb_body";
+            member: string;
+            args: "path_body" | "path_options";
+            body_key?: string | undefined;
+        }>, z.ZodObject<{
+            kind: z.ZodLiteral<"request">;
+            member: z.ZodNullable<z.ZodString>;
+            args: z.ZodEnum<["config", "path_options"]>;
+            url_key: z.ZodOptional<z.ZodString>;
+            method_key: z.ZodString;
+        }, "strip", z.ZodTypeAny, {
+            kind: "request";
+            member: string | null;
+            args: "path_options" | "config";
+            method_key: string;
+            url_key?: string | undefined;
+        }, {
+            kind: "request";
+            member: string | null;
+            args: "path_options" | "config";
+            method_key: string;
+            url_key?: string | undefined;
+        }>, z.ZodObject<{
+            kind: z.ZodLiteral<"request_body">;
+            member: z.ZodNullable<z.ZodString>;
+            args: z.ZodEnum<["config", "path_options"]>;
+            url_key: z.ZodOptional<z.ZodString>;
+            method_key: z.ZodString;
+            body_key: z.ZodString;
+        }, "strip", z.ZodTypeAny, {
+            kind: "request_body";
+            member: string | null;
+            args: "path_options" | "config";
+            body_key: string;
+            method_key: string;
+            url_key?: string | undefined;
+        }, {
+            kind: "request_body";
+            member: string | null;
+            args: "path_options" | "config";
+            body_key: string;
+            method_key: string;
+            url_key?: string | undefined;
+        }>]>;
+    }, "strip", z.ZodTypeAny, {
+        export: string;
+        claim: {
+            kind: "factory";
+            member: string;
+            base_url_key: string;
+        } | {
+            kind: "verb";
+            member: string;
+            method: string;
+        } | {
+            kind: "verb_body";
+            member: string;
+            args: "path_body" | "path_options";
+            body_key?: string | undefined;
+        } | {
+            kind: "request";
+            member: string | null;
+            args: "path_options" | "config";
+            method_key: string;
+            url_key?: string | undefined;
+        } | {
+            kind: "request_body";
+            member: string | null;
+            args: "path_options" | "config";
+            body_key: string;
+            method_key: string;
+            url_key?: string | undefined;
+        };
+        claim_id: string;
+        package: string;
+        receiver: string;
+    }, {
+        export: string;
+        claim: {
+            kind: "factory";
+            member: string;
+            base_url_key: string;
+        } | {
+            kind: "verb";
+            member: string;
+            method: string;
+        } | {
+            kind: "verb_body";
+            member: string;
+            args: "path_body" | "path_options";
+            body_key?: string | undefined;
+        } | {
+            kind: "request";
+            member: string | null;
+            args: "path_options" | "config";
+            method_key: string;
+            url_key?: string | undefined;
+        } | {
+            kind: "request_body";
+            member: string | null;
+            args: "path_options" | "config";
+            body_key: string;
+            method_key: string;
+            url_key?: string | undefined;
+        };
+        claim_id: string;
+        package: string;
+        receiver: string;
+    }>, "many">;
+    budget_ms: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    request_id: string;
+    action: "verify_client_semantics";
+    checks: {
+        export: string;
+        claim: {
+            kind: "factory";
+            member: string;
+            base_url_key: string;
+        } | {
+            kind: "verb";
+            member: string;
+            method: string;
+        } | {
+            kind: "verb_body";
+            member: string;
+            args: "path_body" | "path_options";
+            body_key?: string | undefined;
+        } | {
+            kind: "request";
+            member: string | null;
+            args: "path_options" | "config";
+            method_key: string;
+            url_key?: string | undefined;
+        } | {
+            kind: "request_body";
+            member: string | null;
+            args: "path_options" | "config";
+            body_key: string;
+            method_key: string;
+            url_key?: string | undefined;
+        };
+        claim_id: string;
+        package: string;
+        receiver: string;
+    }[];
+    from_dir: string;
+    budget_ms?: number | undefined;
+}, {
+    request_id: string;
+    action: "verify_client_semantics";
+    checks: {
+        export: string;
+        claim: {
+            kind: "factory";
+            member: string;
+            base_url_key: string;
+        } | {
+            kind: "verb";
+            member: string;
+            method: string;
+        } | {
+            kind: "verb_body";
+            member: string;
+            args: "path_body" | "path_options";
+            body_key?: string | undefined;
+        } | {
+            kind: "request";
+            member: string | null;
+            args: "path_options" | "config";
+            method_key: string;
+            url_key?: string | undefined;
+        } | {
+            kind: "request_body";
+            member: string | null;
+            args: "path_options" | "config";
+            body_key: string;
+            method_key: string;
+            url_key?: string | undefined;
+        };
+        claim_id: string;
+        package: string;
+        receiver: string;
+    }[];
+    from_dir: string;
+    budget_ms?: number | undefined;
+}>, z.ZodObject<{
+    request_id: z.ZodString;
 } & {
     action: z.ZodLiteral<"health">;
 }, "strip", z.ZodTypeAny, {