@scriptc/compiler 0.0.5 → 0.0.7

package/dist/library/sidecar.d.ts

@@ -0,0 +1,191 @@
+import { type ScrDiagnostic } from "../diagnostics/diagnostic.js";
+import type { ContractFacts } from "../frontend/lib-contract.js";
+import type { LibraryProfile } from "./profile.js";
+/** The sidecar schema's format this emitter writes. */
+export declare const SIDECAR_FORMAT = 1;
+export type TypeRef = {
+    kind: "bool";
+} | {
+    kind: "f64";
+} | {
+    kind: "i64";
+} | {
+    kind: "bytes";
+} | {
+    kind: "void";
+} | {
+    kind: "optional";
+    inner: TypeRef;
+} | {
+    kind: "slice";
+    elem: TypeRef;
+} | {
+    kind: "node";
+    name: string;
+} | {
+    kind: "value";
+    name: string;
+} | {
+    kind: "enum";
+    name: string;
+} | {
+    kind: "union";
+    name: string;
+};
+export type PayloadDescriptor = {
+    kind: "void";
+} | {
+    kind: "bytes";
+} | {
+    kind: "number";
+    class: "f64" | "i64";
+} | {
+    kind: "number_bytes";
+    number_field: string;
+    number_class: "f64" | "i64";
+    bytes_field: string;
+} | {
+    kind: "record";
+    name: string;
+} | {
+    kind: "union";
+    name: string;
+} | {
+    kind: "enum";
+    name: string;
+} | {
+    kind: "scalar";
+    type: TypeRef;
+};
+export interface SidecarStruct {
+    name: string;
+    synthesized?: true;
+    fields: {
+        name: string;
+        type: TypeRef;
+    }[];
+}
+export interface SidecarEnum {
+    name: string;
+    members: string[];
+}
+export interface SidecarUnion {
+    name: string;
+    arms: {
+        name: string;
+        payload: TypeRef;
+    }[];
+}
+export interface SidecarHelper {
+    name: string;
+    params: TypeRef[];
+    returns: TypeRef;
+    arena: boolean;
+}
+/** The whole document, property-ordered exactly as §1 lists the fields
+ * (JSON.stringify preserves insertion order — the construction order IS
+ * the serialization order). */
+export interface SidecarDoc {
+    format: number;
+    wire_version: number;
+    abi_version: number;
+    compiler_version: string;
+    entry: string;
+    source_hash: string;
+    build_id: string;
+    types: {
+        structs: SidecarStruct[];
+        enums: SidecarEnum[];
+        unions: SidecarUnion[];
+    };
+    model: string;
+    model_helpers: SidecarHelper[];
+    model_unbound: string[];
+    msg: {
+        name: string;
+        arms: {
+            name: string;
+            payload: PayloadDescriptor;
+        }[];
+        unbound: string[];
+    };
+    init_returns_cmd: boolean;
+    update_returns_cmd: boolean;
+    has_subscriptions: boolean;
+    channels: {
+        command_msg: boolean;
+        frame_msg: boolean;
+        key_msg: boolean;
+        pinch_msg: boolean;
+        appearance_msg: string | null;
+        chrome_msg: string | null;
+        env_msgs: {
+            env: string;
+            msg: string;
+        }[];
+    };
+    abi: {
+        prefix: string;
+        exports: string[];
+        snapshot_format: number;
+    };
+    integer_slots: {
+        slot: string;
+        class: "i64";
+    }[];
+    deterministic: boolean;
+    async_free: boolean;
+}
+/** The compiler's exact release identifier — the published package
+ * version, read once from the compiler package's own package.json (this
+ * module lives two levels below the package root in src/ and dist/
+ * alike). build_id input 1 and the sidecar's `compiler_version`. */
+export declare function compilerReleaseVersion(): string;
+/** One path under the sidecar's canonical rules: compilation-root-relative
+ * POSIX, or `profile:`-namespaced when the file sits outside the root
+ * (never absolute, no `.`/`..` segments). */
+export declare function canonicalPath(rootDir: string, file: string): string;
+export interface CanonicalModule {
+    /** Compilation-root-relative POSIX path (or `profile:`-namespaced when
+     * outside the root), never absolute, no `.`/`..` segments. */
+    canonical: string;
+    bytes: Uint8Array;
+}
+/** Canonicalize + sort the module graph for hashing: root-relative POSIX
+ * paths, ascending by plain bytewise comparison of the path strings. A
+ * module outside the compilation root (the profile file's directory)
+ * cannot spell a canonical relative path, so it rides the `profile:`
+ * namespace under its basename — deterministic and absolute-path-free. */
+export declare function canonicalModuleGraph(rootDir: string, sources: ReadonlyMap<string, string>): CanonicalModule[];
+/** build_id (schema §2: compiler version, profile bytes, sorted module
+ * graph — every input length-prefixed) and source_hash (the
+ * "module-graph" contract: the sorted module graph alone, so the value is
+ * stable across compiler releases). Both 16 lowercase hex digits. */
+export declare function libraryIdentityHashes(compilerVersion: string, profileBytes: Uint8Array, modules: readonly CanonicalModule[]): {
+    buildId: string;
+    sourceHash: string;
+};
+/** The profile's canonical `abi.exports` suffix order: the identity
+ * getters first (abi_version, then build_id), the mode-provided entries
+ * (sink registration, init, collect, reset — declared ones only), then
+ * the export map in profile order. Suffix = symbol minus prefix. */
+export declare function abiExportSuffixes(profile: LibraryProfile): string[];
+export interface SidecarBuildInput {
+    profile: LibraryProfile;
+    facts: ContractFacts;
+    compilerVersion: string;
+    /** Entry module path, compilation-root-relative, POSIX separators. */
+    entry: string;
+    buildId: string;
+    sourceHash: string;
+    deterministic: boolean;
+}
+export type SidecarBuildResult = {
+    ok: true;
+    doc: SidecarDoc;
+    json: string;
+} | {
+    ok: false;
+    diagnostics: ScrDiagnostic[];
+};
+export declare function buildSidecar(input: SidecarBuildInput): SidecarBuildResult;