@spine-event-engine/proto-tools 2.0.0-snapshot.2

package/dist/src/generation/generator.d.ts

@@ -0,0 +1,195 @@
+import type { SpawnSyncReturns } from "node:child_process";
+import { type ManifestFileOperations } from "../io/atomic-manifest.js";
+import type { ModelSourceView } from "./source-view.js";
+/**
+ * Bounded seams used to test failure handling while retaining real Buf integration.
+ */
+export interface GenerationOperations {
+    /**
+     * Canonical live model root used only by the root transaction bootstrap.
+     */
+    readonly livePackageRoot?: string;
+    /**
+     * Executes Buf for the staged model sources.
+     *
+     * @param moduleRoot The temporary Buf module root.
+     * @param output The temporary generated-output directory.
+     * @param owned The package-relative Proto paths to generate.
+     * @param packageName The owning model package name.
+     * @param runner The optional subprocess runner.
+     */
+    readonly runBuf?: (moduleRoot: string, output: string, owned: readonly string[], packageName: string, runner?: SubprocessRunner) => void;
+    /**
+     * Executes interface companion generation after primary Buf generation succeeds.
+     *
+     * @param moduleRoot The temporary Buf module root.
+     * @param output The temporary generated-output directory.
+     * @param owned The package-relative Proto paths to generate.
+     * @param packageName The owning model package name.
+     * @param sourceView The bounded authored-source and staged-output compiler view.
+     * @param runner The optional subprocess runner.
+     */
+    readonly runInterfacePhase?: (moduleRoot: string, output: string, owned: readonly string[], packageName: string, sourceView: ModelSourceView, runner?: SubprocessRunner) => void;
+    /**
+     * Updates generated imports that belong to direct model dependencies.
+     *
+     * @param output The generated-output directory.
+     * @param owners The package that owns each Proto path.
+     * @param currentPackage The model package being generated.
+     */
+    readonly rewriteImports?: (output: string, owners: Readonly<Record<string, {
+        readonly packageName: string;
+        readonly generatedExport: string;
+    }>>, currentPackage: string) => void;
+    /**
+     * Writes the generated module descriptor.
+     *
+     * @param output The generated-output directory.
+     * @param exportName The generated module export name.
+     * @param packageName The owning model package name.
+     * @param dependencies The direct model-module dependencies.
+     */
+    readonly writeModule?: (output: string, exportName: string, packageName: string, dependencies: readonly {
+        readonly name: string;
+        readonly moduleExport: string;
+    }[]) => void;
+    /**
+     * Applies a filesystem rename during publication, backup, or rollback.
+     *
+     * @param from The current source path.
+     * @param to The destination path.
+     */
+    readonly rename?: (from: string, to: string) => void;
+    /**
+     * Overrides manifest publication filesystem operations for tests.
+     */
+    readonly manifestOperations?: Partial<ManifestFileOperations>;
+    /**
+     * Runs a subprocess for Buf generation or validation.
+     */
+    readonly runProcess?: SubprocessRunner;
+    /**
+     * Overrides generation-claim filesystem operations for tests.
+     */
+    readonly lockOperations?: Partial<GenerationLockOperations>;
+}
+/**
+ * Bounded lock seams for deterministic ownership and cleanup tests.
+ */
+export interface GenerationLockOperations {
+    /**
+     * Creates a lock file with its owner content.
+     *
+     * @param path The unique lock-file path.
+     * @param content The serialized owner metadata.
+     */
+    readonly create: (path: string, content: string) => void;
+    /**
+     * Lists the entries in a package directory.
+     *
+     * @param directory The package directory to inspect.
+     * @returns The directory entry names.
+     */
+    readonly list: (directory: string) => readonly string[];
+    /**
+     * Reads the content of a lock file.
+     *
+     * @param path The lock-file path.
+     * @returns The serialized owner metadata.
+     */
+    readonly read: (path: string) => string;
+    /**
+     * Reads a regular lock through a no-follow descriptor with stable identity.
+     *
+     * @param path The lock-file path.
+     * @returns The owner content and opened-file identity.
+     */
+    readonly snapshot?: (path: string) => ClaimSnapshot;
+    /**
+     * Inspects the kind of a lock-file entry.
+     *
+     * @param path The lock-file path.
+     * @returns Whether the entry is regular, symbolic, or another kind.
+     */
+    readonly inspect: (path: string) => "regular" | "symlink" | "other";
+    /**
+     * Removes a lock file.
+     *
+     * @param path The lock-file path.
+     */
+    readonly remove: (path: string) => void;
+    /**
+     * Updates a claim path by atomically moving it within its package directory.
+     *
+     * @param from The current claim path.
+     * @param to The same-directory quarantine path.
+     */
+    readonly move?: (from: string, to: string) => void;
+    /**
+     * Determines whether a lock owner is still running.
+     *
+     * @param pid The candidate process identifier.
+     * @returns The liveness result for the candidate process.
+     */
+    readonly liveness: (pid: number) => ClaimLiveness;
+}
+/**
+ * Result of a bounded generation-claim liveness probe.
+ */
+export type ClaimLiveness = "alive" | "dead" | "indeterminate";
+/**
+ * Executes the packaged Buf executable in a synchronous subprocess.
+ *
+ * @param command The executable path.
+ * @param arguments_ The command-line arguments.
+ * @param options The working-directory, encoding, timeout, and buffer options.
+ * @returns The synchronous subprocess result.
+ */
+export type SubprocessRunner = (command: string, arguments_: readonly string[], options: {
+    readonly cwd: string;
+    readonly encoding: "utf8";
+    readonly timeout: number;
+    readonly maxBuffer: number;
+}) => SpawnSyncReturns<string>;
+/**
+ * Bounded seams for atomic application-registry publication failures.
+ */
+export interface CompositionOperations {
+    /**
+     * Overrides registry publication filesystem operations for tests.
+     */
+    readonly registryOperations?: Partial<ManifestFileOperations>;
+}
+interface ClaimSnapshot {
+    readonly content: string;
+    readonly identity: string;
+}
+/**
+ * Generates and composes deterministic Protobuf package artifacts.
+ */
+export declare const ProtoGeneration: Readonly<{
+    /**
+     * Generates a model package's Protobuf-ES sources and module descriptor.
+     *
+     * @param packageRoot The root of the model package to generate.
+     * @param operations Optional bounded filesystem and process seams for tests.
+     */
+    generate(packageRoot: string, operations?: GenerationOperations): void;
+    /**
+     * Determines the liveness of a generation-claim owner.
+     *
+     * @param pid The process identifier to probe.
+     * @param probe The optional signal-zero probe to run.
+     * @returns Whether the claim owner is alive, dead, or indeterminate.
+     */
+    claimLiveness(pid: number, probe?: (candidate: number) => unknown): ClaimLiveness;
+    /**
+     * Composes an application's deterministic model registry.
+     *
+     * @param packageRoot The root of the application package to compose.
+     * @param operations Optional bounded manifest publication seams for tests.
+     */
+    compose(packageRoot: string, operations?: CompositionOperations): void;
+}>;
+export {};
+//# sourceMappingURL=generator.d.ts.map

package/dist/src/generation/generator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"generator.d.ts","sourceRoot":"","sources":["../../../src/generation/generator.ts"],"names":[],"mappings":"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"}