carrick 0.3.99 → 0.3.101

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

@@ -374,10 +374,157 @@ export interface VerifyClientSemanticsRequest extends BaseRequest {
     /** Checks not reached in time come back `unchecked` with reason `budget`. */
     budget_ms?: number;
 }
+/**
+ * Where one part of a library call sits: argument `arg` (0-based), or, with
+ * `key`, the property `key` of the object passed there (carrick#1616).
+ */
+export interface ClaimSlot {
+    arg: number;
+    key?: string;
+}
+/**
+ * A name the call does not carry: the one the maker's `name` slot bound to
+ * the instance (`maker`), or the one the scope member bound (`scope`).
+ */
+export interface BoundName {
+    bound: 'maker' | 'scope';
+}
+/** The closed role list; the role alone picks the checks a claim needs. */
+export type LibraryRole = 'http_client' | 'graphql_client' | 'broker' | 'in_process_bus' | 'socket' | 'server_framework' | 'none';
+/** What an `op` claim does on the wire. */
+export type LibraryOp = 'request' | 'send' | 'receive' | 'execute';
+/** Which receivers an op, scope or reserved name is claimed on. */
+export type ClaimOn = 'export' | 'instance' | 'both';
+/**
+ * Whether a string-accepting key of an options type is the name (design D2).
+ * Which key is the name is the picker's answer; the verifier checks only that
+ * every string-accepting key at the call is accounted for.
+ */
+export type KeyLabel = 'name' | 'not_name';
+/** Where a name means something. Carried for the scanner; the verifier never reads it. */
+export interface NameScope {
+    scope: 'global' | 'service';
+    namespace: string | null;
+}
+/**
+ * One claim element, in the shape the store answers (contract on
+ * carrick#1564, comment 5937606126, sections 2 and 3, as amendment 2,
+ * comment 5939543981, changes it), tagged by `kind`. `picker` and
+ * `name_scope` are carried and never read.
+ *
+ * `on` and `of` say which receivers an op, scope or reserved name applies
+ * to, and an element carries at most one of them: `of` is exactly one
+ * receiver, by its receiver id (`instance:new`, `instance:connect>scope:channel`);
+ * `on` is the export, every instance of every maker, or both.
+ */
+export type LibraryClaim = {
+    /** How an instance is made: `member(...)` (`call`) or `new member(...)`; `member` null is the export itself. */
+    kind: 'make';
+    form: 'call' | 'new';
+    member: string | null;
+    /** An HTTP base URL, or a broker's address. */
+    base?: ClaimSlot;
+    /** A prefix every name the instance sends gets. */
+    prefix?: ClaimSlot;
+    /** A definition's id or a queue's name: bound to every op that names `{ bound: 'maker' }`. */
+    name?: ClaimSlot;
+    handler?: ClaimSlot;
+    key_labels?: Record<string, KeyLabel>;
+    name_scope?: NameScope;
+    picker?: string;
+} | {
+    /** A member that returns a receiver bound to a name (a channel, room or queue). */
+    kind: 'scope';
+    member: string;
+    name: ClaimSlot;
+    path?: string[];
+    on?: ClaimOn;
+    of?: string;
+    key_labels?: Record<string, KeyLabel>;
+    name_scope?: NameScope;
+    picker?: string;
+} | {
+    kind: 'op';
+    op: LibraryOp;
+    /** null: the receiver itself (after `path`) is called. */
+    member: string | null;
+    /** The members walked from the receiver to the object `member` sits on (`client.tasks.trigger`). */
+    path?: string[];
+    on?: ClaimOn;
+    /** The one receiver the op acts on, by its receiver id. */
+    of?: string;
+    name?: ClaimSlot | BoundName;
+    payload?: ClaimSlot;
+    handler?: ClaimSlot;
+    ack?: ClaimSlot;
+    key_labels?: Record<string, KeyLabel>;
+    name_scope?: NameScope;
+    picker?: string;
+    /** HTTP: an options object sits at `arg` (no `key`). */
+    options?: ClaimSlot;
+    /** HTTP: the method the member always sends. */
+    method?: string;
+    /** HTTP: where the method sits. */
+    method_key?: ClaimSlot;
+} | {
+    /** A name the library emits itself, spelled in one of `member`'s parameters. */
+    kind: 'reserved';
+    member: string;
+    name: string;
+    path?: string[];
+    on?: ClaimOn;
+    of?: string;
+    picker?: string;
+};
+/**
+ * One claim to check against the package's own declarations, on one receiver.
+ * The receiver is `export`, `instance:<member>` (what `export.member(...)`
+ * returns), `instance:()` (what calling the export returns), `instance:new`
+ * (what `new export(...)` builds) or `instance:new:<member>` (what
+ * `new export.member(...)` builds), optionally followed by
+ * `>scope:<path.member>` (what that scope member returns). The unit is
+ * `(claim_id, receiver)`.
+ */
+export interface LibraryCheck {
+    claim_id: string;
+    /** The module specifier as the service imports it (`pkg` or `pkg/sub`). */
+    package: string;
+    export: string;
+    role: LibraryRole;
+    receiver: string;
+    claim: LibraryClaim;
+}
+/**
+ * Check library claims of every role against each package's own
+ * declarations (carrick#1616). `verify_client_semantics` answers HTTP claims
+ * through the same verifier.
+ */
+export interface VerifyLibraryClaimsRequest extends BaseRequest {
+    action: 'verify_library_claims';
+    from_dir: string;
+    checks: LibraryCheck[];
+    /** Checks not reached in time come back `unchecked` with reason `budget`; null or absent is the default. */
+    budget_ms?: number | null;
+}
+/**
+ * List each package's declared surface the way the verifier reads it
+ * (carrick#1660): the input a model picks claims from, and the full-surface
+ * hash the shared library store keys its answers on.
+ */
+export interface ListLibrarySurfaceRequest extends BaseRequest {
+    action: 'list_library_surface';
+    from_dir: string;
+    /** Module specifiers: a package, its subpaths, or a runtime module (`node:events`). */
+    packages: string[];
+    /** Entries kept per package (exports, receivers, members, signatures, parameters and keys each count one); default 1000. */
+    max_entries?: number;
+    /** Per package, the only exports to list (the ones the service imports); absent lists every value export. */
+    exports?: Record<string, string[]>;
+}
 /**
  * Union type for all possible sidecar requests
  */
-export type SidecarRequest = RetypeCheckRequest | VerifyClientSemanticsRequest | InitRequest | BundleRequest | EmitSurfaceRequest | CaptureV2Request | CheckV2Request | InferRequest | BuildWorkspaceRequest | CheckCompatibilityRequest | ResolveDefinitionsRequest | HealthRequest | ShutdownRequest;
+export type SidecarRequest = RetypeCheckRequest | VerifyClientSemanticsRequest | VerifyLibraryClaimsRequest | ListLibrarySurfaceRequest | InitRequest | BundleRequest | EmitSurfaceRequest | CaptureV2Request | CheckV2Request | InferRequest | BuildWorkspaceRequest | CheckCompatibilityRequest | ResolveDefinitionsRequest | HealthRequest | ShutdownRequest;
 /**
  * Request for a specific symbol to be bundled
  */
@@ -613,10 +760,85 @@ export interface VerifyClientSemanticsResponse extends BaseResponse {
     semantics_modules?: SemanticsModule[];
     errors?: string[];
 }
+/** Library-claim verdicts (carrick#1616): the same objects, under the contract's names. */
+export interface VerifyLibraryClaimsResponse extends BaseResponse {
+    /** Exactly one per check, in request order. */
+    verdicts?: SemanticsResult[];
+    modules?: SemanticsModule[];
+    /** Wall time of the verification, program build included. */
+    duration_ms?: number;
+    errors?: string[];
+}
+/** What one parameter position takes, read with the verifier's predicates. */
+export interface SurfaceParam {
+    name: string;
+    optional: boolean;
+    rest: boolean;
+    /** The parameter's type as the declarations print it, truncated. */
+    type: string;
+    accepts_string: boolean;
+    /** A function type with a declared signature. */
+    function: boolean;
+    /** Declared keys, when it is an object type. */
+    keys?: SurfaceKey[];
+    /** String literals the slot spells (an overload's literal, a `keyof` map's keys). */
+    literals?: string[];
+}
+export interface SurfaceKey {
+    name: string;
+    /** Declared optional (`key?:`). */
+    optional: boolean;
+    accepts_string: boolean;
+    function: boolean;
+}
+export interface SurfaceSignature {
+    params: SurfaceParam[];
+    returns: string;
+}
+export interface SurfaceMember {
+    name: string;
+    /** Declared by the receiver's home packages (not only inherited from another package). */
+    own: boolean;
+    signatures: SurfaceSignature[];
+}
+/** One receiver the verifier can read claims on, in its receiver grammar, with what it declares. */
+export interface SurfaceReceiver {
+    receiver: string;
+    call?: SurfaceSignature[];
+    construct?: SurfaceSignature[];
+    members: SurfaceMember[];
+}
+export interface SurfaceExport {
+    export: string;
+    receivers: SurfaceReceiver[];
+}
+/** One specifier's surface. */
+export interface LibrarySurface {
+    package: string;
+    resolved_file?: string;
+    installed_version?: string;
+    /** Why nothing was listed (the verifier's module reasons). */
+    reason?: string;
+    /** Entries dropped by `max_entries`. */
+    truncated: number;
+    exports: SurfaceExport[];
+}
+export interface ListLibrarySurfaceResponse extends BaseResponse {
+    /** One per requested specifier, in request order. */
+    surfaces?: LibrarySurface[];
+    /**
+     * The full-surface hash: sha256 of the JSON array of `[package, exports]`
+     * for every surface that listed at least one export, sorted by `package`.
+     * Type text names the request's directory as `<root>`, so the same
+     * packages hash the same wherever they are installed.
+     */
+    surface_sha256?: string;
+    errors?: string[];
+}
 /**
  * Union type for all possible sidecar responses
  */
-export type SidecarResponse = RetypeCheckResponse | VerifyClientSemanticsResponse | InitResponse | BundleResponse | EmitSurfaceResponse | CaptureV2Response | CheckV2Response | InferResponse | BuildWorkspaceResponse | CheckCompatibilityResponse | ResolveDefinitionsResponse | HealthResponse | ShutdownResponse | ErrorResponse;
+export type SidecarResponse = RetypeCheckResponse | VerifyClientSemanticsResponse | VerifyLibraryClaimsResponse | ListLibrarySurfaceResponse | InitResponse | BundleResponse | EmitSurfaceResponse | CaptureV2Response | CheckV2Response | InferResponse | BuildWorkspaceResponse | CheckCompatibilityResponse | ResolveDefinitionsResponse | HealthResponse | ShutdownResponse | ErrorResponse;
 /**
  * An entry in the type manifest
  */