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

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,34 @@ 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 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 public CLI is `spine-proto`. Its programmatic config and manifest readers
-are for tooling that needs the same validated package contracts; application
+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/main/packages/proto/README.md)
+- [Core message tools](https://github.com/SpineEventEngine/spine-ts/blob/main/packages/core/README.md)
+- [Message Board model example](https://github.com/SpineEventEngine/spine-ts/blob/main/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
@@ -23,7 +30,10 @@ whose `spine-proto.json` it should read:
 - `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

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

@@ -0,0 +1,158 @@
+import ts from "typescript";
+type GeneratedHandlerKind = "command-assignment" | "command-reaction" | "event-subscription" | "state-subscription" | "event-reaction";
+type GeneratedHandlerParameterCount = 1 | 2;
+/**
+ * Build-time analysis result for bare decorated entity handler methods.
+ */
+export interface BuildHandlerAnalysis {
+    /**
+     * Entity groups in source-file and class declaration order.
+     */
+    readonly entities: readonly BuildEntityHandlers[];
+    /**
+     * 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;
+    /**
+     * 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[];
+}
+/**
+ * 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 signalSchema: SchemaReference;
+    /**
+     * Generated schemas emitted by the handler return type.
+     */
+    readonly emittedSchemas: readonly SchemaReference[];
+    /**
+     * Public method arity: `handler(signal)` or `handler(signal, context)`.
+     */
+    readonly parameterCount: GeneratedHandlerParameterCount;
+    /**
+     * Origin declared on the first receptor parameter.
+     */
+    readonly origin: "domestic" | "external";
+    /**
+     * Optional statically declared Event field filter.
+     */
+    readonly where?: BuildWhereOptions;
+}
+/**
+ * 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 = "APPLY_DECORATOR" | "FRAMEWORK_ENVELOPE_RETURN" | "INVALID_EMITTED_SCHEMA" | "INVALID_HANDLER_NAME" | "INVALID_HANDLER_VISIBILITY" | "INVALID_PARAMETER_COUNT" | "INVALID_SIGNAL_TYPE" | "INVALID_EXTERNAL_ORIGIN" | "EXTERNAL_COMMAND_RECEIVER" | "INVALID_SUBSCRIBE_RETURN" | "INVALID_WHERE" | "MISSING_EMITTED_SCHEMAS" | "MISSING_ENTITY_STATE_SCHEMA" | "MISSING_RETURN_TYPE" | "MISSING_SIGNAL_TYPE" | "NON_EXPORTED_ENTITY_CLASS" | "SCHEMA_BEARING_DECORATOR" | "TYPESCRIPT_SYNTAX_ERROR" | "UNSUPPORTED_ENTITY_EXPORT" | "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 entity 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 Entity 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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"}