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

package/README.md

@@ -1,33 +1,34 @@
 # Protobuf tooling for Spine applications
 
-This package generates TypeScript from application Proto models and
-assembles those models into an application registry. Those models can define
-commands, events, and state used by Aggregates or Projections. It runs at build
-time, not inside a server process.
+Use this build-time package to generate TypeScript from application Proto
+models, assemble model registries, and generate handler registries. Models can
+define commands, events, and state used by Aggregates or Projections; this tool
+does not run inside a server process.
 
-## Generate interface artifacts
+This is an experimental snapshot. Install the snapshot explicitly while its CLI
+and generated-output contract continue to evolve:
 
-`pnpm proto:generate` discovers `ts_type` options and emits model-local
-`generated/interfaces/*.ts` artifacts. Generated `TaskEvent` is a complete
-generated declaration; generated `TaskAssignmentEvent` binds the token to an
-authored interface in the same model module. Do not edit output: rerun the
-generator instead.
+```sh
+pnpm add -D @spine-event-engine/proto-tools@snapshot
+```
 
-For detailed contracts intended for coding agents, see the
-[REFERENCE.md documentation for agents](REFERENCE.md).
+For configuration, manifest, and generated-output details, read the
+[reference](REFERENCE.md).
 
-## 💡 Why use it?
+## 💡 Who should use it?
 
-- ✅ Generates Protobuf-ES code for application models.
-- ✅ Creates one importable `ProtoModule` per model package.
-- ✅ Follows dependencies between model packages deterministically.
-- ✅ Generates typed rejection helpers and handler registries.
+- ✅ Authors of Node.js/pnpm Spine model packages and application packages.
+- ✅ Teams with canonical `.proto` sources, the `spine-proto` CLI, and the
+  required Protobuf compiler/plugins available to their workspace.
+- ❌ Runtime application code; import the generated model module and registry
+  instead of invoking this CLI from a server.
 
-## 🚀 Create a model package
+## 🚀 Generate and compile one model
 
-A model package contains canonical `.proto` files, generated code, and one exported
-`ProtoModule`. Use separate model packages for independently developed bounded
-contexts; a small application may use one combined model package.
+Start in a Node.js/pnpm workspace with the CLI installed, a model package, and
+the Protobuf compiler/plugin toolchain available. A model package keeps its
+canonical `.proto` files under `proto/` and declares its generated locations in
+`spine-proto.json`:
 
 ```json
 {
@@ -42,17 +43,19 @@ contexts; a small application may use one combined model package.
 }
 ```
 
-Run generation from that package directory:
+From that model package directory, generate the model. The command emits
+Protobuf-ES source under `generated/`, an importable `generated/proto-module.ts`,
+and `spine-proto-manifest.json`; then compile the package.
 
 ```sh
-spine-proto generate
+pnpm exec spine-proto generate
+tsc -b
 ```
 
-Generation creates the generated Protobuf-ES sources, a `proto-module.ts`,
-typed rejection companions for rejection Proto files in the package, and a deterministic
-`spine-proto-manifest.json`. Do not edit generated output by hand.
+Do not edit generated output by hand: change the Proto source or configuration,
+then run generation again.
 
-## 🧩 Compose an application
+## 🧩 Compose an application after the first model succeeds
 
 An application lists its direct model packages and a source location for the
 generated registry.
@@ -67,36 +70,41 @@ generated registry.
 ```
 
 ```sh
-spine-proto compose
-spine-proto handlers
+pnpm exec spine-proto compose
+pnpm exec spine-proto handlers
 tsc -b
 ```
 
 `compose` follows declared model dependencies transitively. `handlers` creates
-the generated handler registry for decorated application classes. Run both after
-the related model or handler changes.
-
-The public CLI is `spine-proto`. Its programmatic config and manifest readers
-are for tooling that needs the same validated package contracts; application
+the generated handler registry for decorated application classes. Its emitted
+source imports the Server handler-registry contract as a type from
+`@spine-event-engine/server/spi/handler-registry`; the CLI itself has no Server
+runtime dependency. Run both after the related model or handler changes.
+The handler analyzer records `@Throws(...)` declarations as rejection outcomes;
+the generated rejection companion supplies the schema used by that metadata.
+Handler results can use native message unions, flat arrays, fixed tuples with
+optional entries, and one outer `Promise`. Concrete local/imported aliases are
+resolved too. The [handler return guide](https://github.com/SpineEventEngine/spine-ts/blob/master/docs/USER_GUIDE.md#choose-what-a-handler-returns)
+shows the allowed forms and the rules for each decorator. Regenerate handlers
+after changing a return declaration so every possible result schema is registered.
+
+The public CLI is `spine-proto`. Programmatic config and manifest readers are
+for build tooling that needs the same validated package contracts; application
 code should import generated model modules instead.
 
-```ts
-// docs-snippet-path: packages/proto-tools/src/index.ts
-import { ProtoConfig } from "@spine-event-engine/proto-tools";
-
-const config = ProtoConfig.read(".");
-void config;
-```
-
-## ⚠️ Build-time only
+## ⚠️ Cleanup and limits
 
 Run this tooling after changing Proto files or decorated handlers. Generated
 files are outputs, not source: never edit them by hand. Application runtime code
 imports the generated model module and registry; it does not invoke the CLI.
 
+Keep model-package dependencies explicit in both `package.json` and
+`spine-proto.json`. `compose` follows declared model dependencies transitively;
+it does not discover undeclared packages or create a running application.
+
 ## 🔗 Learn more
 
-- [Spine Protobuf package](../proto/README.md)
-- [Core message tools](../core/README.md)
-- [Message Board model example](../../examples/message-board/model/README.md)
+- [Spine Protobuf package](https://github.com/SpineEventEngine/spine-ts/blob/master/packages/proto/README.md)
+- [Core message tools](https://github.com/SpineEventEngine/spine-ts/blob/master/packages/core/README.md)
+- [Message Board model example](https://github.com/SpineEventEngine/spine-ts/blob/master/examples/message-board/model/README.md)
 - [Reference for coding agents](REFERENCE.md)

package/REFERENCE.md

@@ -1,5 +1,12 @@
 # @spine-event-engine/proto-tools reference
 
+## Testing entry point
+
+`@spine-event-engine/proto-tools/testing` supports compiler-focused framework
+tests that analyze or render handler registries. Direct implementation modules
+under `src/generation` remain private; only this deliberate testing subpath is
+available to package-test consumers, with test-infrastructure stability only.
+
 This reference describes the public build-time Proto tooling for coding agents.
 
 ## Interface discovery and provenance
@@ -19,11 +26,14 @@ The `spine-proto` binary is the primary public API. Run it from the package
 whose `spine-proto.json` it should read:
 
 - `spine-proto generate` accepts only model configuration and generates model
-  outputs and the manifest;
+  outputs and the manifest, including `_query.ts` companions for eligible Entity states;
 - `spine-proto compose` accepts only application configuration and writes the
   configured model registry source;
 - `spine-proto handlers` accepts an application package and writes
-  `generated/handler/generated-handler-registry.ts`.
+  `generated/handler/generated-handler-registry.ts`. The emitted module imports
+  `GeneratedHandlerRegistry` as a type from
+  `@spine-event-engine/server/spi/handler-registry`; handler analysis and
+  rendering remain tooling-owned and never load Server at CLI runtime.
 
 The package also exposes `manifestFormatVersion`, `ProtoConfig`, and
 `ProtoManifest` for build tooling that needs to read or validate the same
@@ -48,8 +58,11 @@ version, sorted Proto files in the package, generated exports, direct
 dependencies, the module export, and a generation ID. Byte-identical staged
 output reuses its committed ID; changed output receives a new opaque ID. A model
 with a top-level `*rejections.proto` also gets a
-typed same-directory rejection companion. When such a companion is produced,
-the model must directly depend on `@spine-event-engine/core`.
+typed same-directory rejection companion. An eligible Entity state gets a
+same-directory `_query.ts` companion. Either companion imports core at runtime,
+so the model must declare `@spine-event-engine/core` in its direct runtime
+`package.json` dependencies when either is generated. Models with neither
+companion do not need this dependency for generation.
 
 For a cross-model Proto import, declare the other model in both `package.json`
 and `spine-proto.json`; import the other model's canonical package path. The
@@ -66,6 +79,15 @@ sufficient because `TypeRegistry.from()` follows declared dependencies.
 `handlers` must run after a decorated handler or its generated command, event,
 or state types change. Compile the generated registry with the application.
 
+Explicit handler return annotations may resolve to one generated message, a
+union, a flat array, or a fixed tuple (including readonly, named, optional, and
+union-valued entries), optionally wrapped in one built-in `Promise`. Local and
+imported aliases must resolve to concrete generated schemas. The analyzer records
+all possible schemas in that handler's `outcomes.returned`; it does not serialize
+tuple positions or union branches. Handler-specific result rules and unsupported
+shapes are documented in the
+[server reference](https://github.com/SpineEventEngine/spine-ts/blob/master/packages/server/REFERENCE.md#handler-return-types).
+
 ## Safety and atomicity
 
 All package-relative paths must remain inside the package and may not use unsafe

package/dist/src/generation/build-time-handler-analyzer.d.ts

@@ -0,0 +1,217 @@
+import ts from "typescript";
+type GeneratedHandlerKind = "command-assignment" | "command-substitution" | "command-reaction" | "event-subscription" | "state-subscription" | "event-reaction";
+type GeneratedHandlerParameterCount = 1 | 2;
+/**
+ * Build-time analysis result for bare decorated receiver handler methods.
+ */
+export interface BuildHandlerAnalysis {
+    /**
+     * All generated Entity and standalone receiver declarations.
+     */
+    readonly receivers: readonly BuildReceiverHandlers[];
+    /**
+     * Deterministic diagnostics for unsupported handler declarations.
+     */
+    readonly diagnostics: readonly BuildHandlerDiagnostic[];
+}
+/**
+ * Build-time entity group shaped for later generated registry rendering.
+ */
+export interface BuildEntityHandlers {
+    /**
+     * Entity class declaration name.
+     */
+    readonly className: string;
+    /**
+     * Whether the class is imported from a default export.
+     */
+    readonly defaultExport?: boolean;
+    /**
+     * Marks this declaration as an Entity receiver.
+     */
+    readonly receiverKind: "entity";
+    /**
+     * Source file where the entity class is declared.
+     */
+    readonly sourceFile: string;
+    /**
+     * Importable generated schema reference for entity state.
+     */
+    readonly stateSchema: SchemaReference;
+    /**
+     * Analyzed bare-decorator handler records.
+     */
+    readonly handlers: readonly BuildHandlerRecord[];
+}
+/**
+ * Build-time standalone receiver declaration.
+ */
+export interface BuildStandaloneHandlers {
+    /**
+     * Marks this declaration as a standalone receiver.
+     */
+    readonly receiverKind: "standalone";
+    /**
+     * Standalone receiver class declaration name.
+     */
+    readonly className: string;
+    /**
+     * Indicates that the receiver class is a default export.
+     */
+    readonly defaultExport?: boolean;
+    /**
+     * Source file that declares the standalone receiver class.
+     */
+    readonly sourceFile: string;
+    /**
+     * Analyzed decorated handler records in declaration order.
+     */
+    readonly handlers: readonly BuildHandlerRecord[];
+}
+/**
+ * One generated receiver declaration.
+ */
+export type BuildReceiverHandlers = BuildEntityHandlers | BuildStandaloneHandlers;
+/**
+ * Importable generated schema reference used by later source rendering.
+ */
+export interface SchemaReference {
+    /**
+     * Module specifier exactly as declared by analyzed source.
+     */
+    readonly moduleSpecifier: string;
+    /**
+     * Generated schema export name in that module.
+     */
+    readonly exportName: string;
+}
+/**
+ * Build-time handler record before generated source rendering.
+ */
+export interface BuildHandlerRecord {
+    /**
+     * Handler role inferred from the bare decorator.
+     */
+    readonly kind: GeneratedHandlerKind;
+    /**
+     * String method name selected by the generated metadata.
+     */
+    readonly methodName: string;
+    /**
+     * Generated schema accepted by the first handler parameter.
+     */
+    readonly input: BuildHandlerInput;
+    /**
+     * Generated schemas returned normally or declared as thrown rejections.
+     */
+    readonly outcomes: BuildHandlerOutcomes;
+    /**
+     * Public method arity: `handler(signal)` or `handler(signal, context)`.
+     */
+    readonly parameterCount: GeneratedHandlerParameterCount;
+}
+/**
+ * Input metadata for one generated handler.
+ */
+export interface BuildHandlerInput {
+    /**
+     * Generated schema accepted by the handler.
+     */
+    readonly schema: SchemaReference;
+    /**
+     * Origin required for an Event input.
+     */
+    readonly origin: "domestic" | "external";
+    /**
+     * Optional generated Event field filter.
+     */
+    readonly where?: BuildWhereOptions;
+}
+/**
+ * Normal and declared rejection outcomes for one generated handler.
+ */
+export interface BuildHandlerOutcomes {
+    /**
+     * Generated schemas returned normally by the handler.
+     */
+    readonly returned: readonly SchemaReference[];
+    /**
+     * Generated rejection schemas that the handler may throw.
+     */
+    readonly thrown: readonly SchemaReference[];
+}
+/**
+ * Build-time representation of one `@Where` declaration.
+ */
+export interface BuildWhereOptions {
+    /**
+     * Proto source-name path selected by the declaration.
+     */
+    readonly eventField: string;
+    /**
+     * Declared field value in Stringifier text form.
+     */
+    readonly equals: string;
+}
+/**
+ * Stable diagnostic codes emitted by build-time handler analysis.
+ */
+export type BuildHandlerDiagnosticCode = "FRAMEWORK_ENVELOPE_RETURN" | "INVALID_EMITTED_SCHEMA" | "INVALID_HANDLER_NAME" | "INVALID_HANDLER_CONTEXT" | "INVALID_HANDLER_VISIBILITY" | "INVALID_PARAMETER_COUNT" | "INVALID_SIGNAL_TYPE" | "INVALID_EXTERNAL_ORIGIN" | "EXTERNAL_COMMAND_RECEIVER" | "INVALID_SUBSCRIBE_RETURN" | "INVALID_THROWS" | "INVALID_WHERE" | "MISSING_EMITTED_SCHEMAS" | "MISSING_ENTITY_STATE_SCHEMA" | "MISSING_RETURN_TYPE" | "MISSING_SIGNAL_TYPE" | "NON_EXPORTED_RECEIVER_CLASS" | "SCHEMA_BEARING_DECORATOR" | "TYPESCRIPT_SYNTAX_ERROR" | "UNSUPPORTED_ASSIGN_HANDLER" | "UNSUPPORTED_COMMAND_HANDLER" | "UNSUPPORTED_RETURN_TYPE";
+/**
+ * One build-time analyzer diagnostic.
+ */
+export interface BuildHandlerDiagnostic {
+    /**
+     * Stable machine-readable diagnostic code.
+     */
+    readonly code: BuildHandlerDiagnosticCode;
+    /**
+     * Source file where the diagnostic was found.
+     */
+    readonly sourceFile: string;
+    /**
+     * One-based source line.
+     */
+    readonly line: number;
+    /**
+     * One-based source column.
+     */
+    readonly column: number;
+    /**
+     * Human-readable diagnostic message.
+     */
+    readonly message: string;
+    /**
+     * Entity class name when available.
+     */
+    readonly className?: string;
+    /**
+     * Handler method name when available.
+     */
+    readonly methodName?: string;
+}
+/**
+ * Inspects configured TypeScript source files for bare Spine handler decorators.
+ */
+export interface BuildHandlerAnalyzer {
+    /**
+     * Inspects source files and returns receiver handler records with deterministic diagnostics.
+     *
+     * @param program TypeScript program that owns the source files and diagnostics.
+     * @param sourceFiles Application source files to inspect; defaults to program files.
+     * @returns Receiver handler records and deterministic diagnostics.
+     */
+    analyze(program: ts.Program, sourceFiles?: readonly ts.SourceFile[]): BuildHandlerAnalysis;
+}
+/**
+ * Provides build-time analysis for bare Spine handler decorators.
+ */
+export declare const BuildHandlerAnalyzer: BuildHandlerAnalyzer;
+/**
+ * Finds the package identity that owns an analyzed source file.
+ */
+export declare const PackageIdentity: Readonly<{
+    nameFor(sourceFile: string): string | undefined;
+}>;
+export {};
+//# sourceMappingURL=build-time-handler-analyzer.d.ts.map

package/dist/src/generation/build-time-handler-analyzer.d.ts.map

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