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

package/dist/src/generation/build-time-handler-analyzer.js

@@ -0,0 +1,1158 @@
+/*
+ * Copyright 2026, CodeMatters. All rights reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except
+ * in compliance with the License. You may obtain a copy of the License at
+ *
+ * https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under the License
+ * is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
+ * or implied. See the License for the specific language governing permissions and limitations under
+ * the License.
+ */
+import { Buffer } from "node:buffer";
+import { existsSync, readFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { dirname, join, resolve } from "node:path";
+import ts from "typescript";
+/**
+ * Provides build-time analysis for bare Spine handler decorators.
+ */
+export const BuildHandlerAnalyzer = Object.freeze({
+    // prettier-ignore
+    /**
+     * 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, sourceFiles = HandlerSources.appSourceFiles(program)) {
+        PackageDependencies.load(program);
+        const entities = [];
+        const diagnostics = [];
+        for (const source of sourceFiles) {
+            const syntaxDiagnostics = program.getSyntacticDiagnostics(source);
+            if (syntaxDiagnostics.length > 0) {
+                diagnostics.push(...syntaxDiagnostics.map((diagnostic) => HandlerTypes.syntaxDiagnostic(source, diagnostic)));
+                continue;
+            }
+            const scope = {
+                program,
+                source,
+                imports: HandlerSources.buildImportState(source, program),
+                diagnostics,
+            };
+            entities.push(...HandlerSources.analyzeSource(scope));
+        }
+        return { entities, diagnostics };
+    },
+});
+const handlerDecorators = new Set(["Assign", "Command", "React", "Subscribe"]);
+const entityBaseNames = new Set(["Aggregate", "Projection", "ProcessManager"]);
+const maxAliasDepth = 50;
+// `spine.options.entity` in the frozen `spine/options.proto` contract.
+const entityOptionFieldNumber = 73903;
+let packageDependencies;
+const HandlerSources = Object.freeze({
+    appSourceFiles(program) {
+        return program.getSourceFiles().filter((source) => !source.isDeclarationFile);
+    },
+    analyzeSource(scope) {
+        const entities = [];
+        for (const statement of scope.source.statements) {
+            if (!ts.isClassDeclaration(statement) || statement.name === undefined) {
+                continue;
+            }
+            const entity = HandlerSources.analyzeClass(statement, scope);
+            if (entity !== undefined) {
+                entities.push(entity);
+            }
+        }
+        return entities;
+    },
+    analyzeClass(node, scope) {
+        const className = node.name?.text ?? "(anonymous)";
+        const exportIssue = HandlerSources.entityExportIssue(node, scope.source);
+        if (HandlerSources.hasDecoratedMethod(node, scope.imports) && exportIssue !== undefined) {
+            HandlerTypes.pushDiagnostic(scope, exportIssue.code, node.name ?? node, exportIssue.message, className);
+            return undefined;
+        }
+        const stateSchema = HandlerSources.entityStateSchema(node, scope.imports);
+        const handlers = [];
+        for (const member of node.members) {
+            if (!ts.isMethodDeclaration(member)) {
+                continue;
+            }
+            const handler = HandlerSources.analyzeMethod(member, className, stateSchema, scope);
+            if (handler !== undefined) {
+                handlers.push(handler);
+            }
+        }
+        if (stateSchema === undefined || handlers.length === 0) {
+            return undefined;
+        }
+        return { className, sourceFile: scope.source.fileName, stateSchema, handlers };
+    },
+    analyzeMethod(node, className, stateSchema, scope) {
+        const decorators = HandlerSources.methodDecorators(node, scope.imports);
+        const apply = decorators.find((decorator) => decorator.name === "Apply");
+        const handler = decorators.find(HandlerSources.isHandlerUse);
+        const whereUses = decorators.filter((decorator) => decorator.name === "Where");
+        if (apply !== undefined) {
+            HandlerTypes.pushDiagnostic(scope, "APPLY_DECORATOR", apply.node, "Generated registries do not support @Apply.", className, HandlerTypes.methodName(node));
+        }
+        if (handler === undefined) {
+            if (whereUses.length > 0) {
+                HandlerTypes.pushDiagnostic(scope, "INVALID_WHERE", whereUses[0]?.node ?? node, "@Where requires an Event-consuming @Subscribe, @React, or @Command handler.", className, HandlerTypes.methodName(node));
+            }
+            return undefined;
+        }
+        const method = HandlerTypes.methodName(node);
+        const invalid = HandlerSources.validateHandlerNode(node, handler.name, stateSchema, scope, className, method);
+        if (handler.hasArguments) {
+            HandlerTypes.pushDiagnostic(scope, "SCHEMA_BEARING_DECORATOR", handler.node, `@${handler.name}(...) is not supported in analyzed app source.`, className, method);
+            return undefined;
+        }
+        if (invalid) {
+            return undefined;
+        }
+        const origin = HandlerSources.externalOrigin(node.parameters, scope, className, method);
+        if (origin === undefined)
+            return undefined;
+        const signal = HandlerSources.schemaUseFromType(origin.type, scope.imports);
+        const signalSchema = signal?.reference;
+        const emittedSchemas = HandlerSources.emittedSchemaUses(node.type, handler.name, scope.imports)?.map((schema) => schema.reference);
+        if (signalSchema === undefined || emittedSchemas === undefined || method === undefined) {
+            return undefined;
+        }
+        const where = HandlerSources.whereDeclaration(whereUses, handler, signal?.kind, scope, className, method);
+        if (whereUses.length > 0 && where === undefined) {
+            return undefined;
+        }
+        return {
+            kind: HandlerSources.handlerKind(handler.name, signal?.kind),
+            methodName: method,
+            signalSchema,
+            emittedSchemas,
+            parameterCount: node.parameters.length,
+            origin: origin.value,
+            ...(where === undefined ? {} : { where }),
+        };
+    },
+    whereDeclaration(uses, handler, signalKind, scope, className, methodName) {
+        if (uses.length === 0)
+            return undefined;
+        const use = uses[0];
+        if (uses.length !== 1 ||
+            (handler.name !== "Subscribe" && handler.name !== "React" && handler.name !== "Command") ||
+            (signalKind !== "event" && signalKind !== "rejection") ||
+            use === undefined) {
+            HandlerTypes.pushDiagnostic(scope, "INVALID_WHERE", use?.node ?? handler.node, "@Where is allowed once on an Event-consuming @Subscribe, @React, or @Command handler.", className, methodName);
+            return undefined;
+        }
+        const expression = use.node.expression;
+        if (!ts.isCallExpression(expression) || expression.arguments.length !== 1) {
+            HandlerTypes.pushDiagnostic(scope, "INVALID_WHERE", use.node, "@Where requires one object literal.", className, methodName);
+            return undefined;
+        }
+        const options = expression.arguments[0];
+        if (options === undefined || !ts.isObjectLiteralExpression(options)) {
+            HandlerTypes.pushDiagnostic(scope, "INVALID_WHERE", expression, "@Where options must be an object literal.", className, methodName);
+            return undefined;
+        }
+        const values = new Map();
+        for (const property of options.properties) {
+            if (!ts.isPropertyAssignment(property) ||
+                (property.name.kind !== ts.SyntaxKind.Identifier &&
+                    !ts.isStringLiteralLike(property.name)) ||
+                !ts.isStringLiteralLike(property.initializer)) {
+                HandlerTypes.pushDiagnostic(scope, "INVALID_WHERE", property, "@Where accepts only eventField and equals string literals.", className, methodName);
+                return undefined;
+            }
+            const name = property.name.text;
+            if ((name !== "eventField" && name !== "equals") || values.has(name)) {
+                HandlerTypes.pushDiagnostic(scope, "INVALID_WHERE", property, "@Where accepts each of eventField and equals exactly once.", className, methodName);
+                return undefined;
+            }
+            values.set(name, property.initializer.text);
+        }
+        const eventField = values.get("eventField");
+        const equals = values.get("equals");
+        if (eventField === undefined || eventField.trim().length === 0 || equals === undefined) {
+            HandlerTypes.pushDiagnostic(scope, "INVALID_WHERE", options, "@Where requires non-empty eventField and string equals.", className, methodName);
+            return undefined;
+        }
+        return Object.freeze({ eventField, equals });
+    },
+    hasDecoratedMethod(node, imports) {
+        return node.members.some((member) => ts.isMethodDeclaration(member) &&
+            HandlerSources.methodDecorators(member, imports).length > 0);
+    },
+    entityExportIssue(node, source) {
+        if (HandlerTypes.hasModifier(node, ts.SyntaxKind.DefaultKeyword)) {
+            return {
+                code: "UNSUPPORTED_ENTITY_EXPORT",
+                message: "Decorated entity classes must use named exports, not default exports.",
+            };
+        }
+        if (HandlerTypes.hasModifier(node, ts.SyntaxKind.ExportKeyword)) {
+            return undefined;
+        }
+        if (node.name !== undefined && HandlerSources.hasNamedClassExport(node.name.text, source)) {
+            return undefined;
+        }
+        return {
+            code: "NON_EXPORTED_ENTITY_CLASS",
+            message: "Decorated entity classes must be exported for generated registry imports.",
+        };
+    },
+    hasNamedClassExport(className, source) {
+        return source.statements.some((statement) => ts.isExportDeclaration(statement) &&
+            statement.moduleSpecifier === undefined &&
+            statement.exportClause !== undefined &&
+            HandlerSources.namedExportIncludes(statement.exportClause, className));
+    },
+    namedExportIncludes(clause, className) {
+        return (ts.isNamedExports(clause) &&
+            clause.elements.some((element) => element.name.text === className &&
+                (element.propertyName === undefined || element.propertyName.text === className)));
+    },
+    validateHandlerNode(node, decorator, stateSchema, scope, className, method) {
+        return [
+            HandlerSources.validateEntityState(node, stateSchema, scope, className, method),
+            HandlerSources.validateName(node, scope, className),
+            HandlerSources.validateVisibility(node, scope, className, method),
+            HandlerSources.validateParameters(node, decorator, scope, className, method),
+            HandlerSources.validateReturn(node, decorator, scope, className, method),
+        ].some(Boolean);
+    },
+    validateEntityState(node, stateSchema, scope, className, method) {
+        if (stateSchema !== undefined) {
+            return false;
+        }
+        HandlerTypes.pushDiagnostic(scope, "MISSING_ENTITY_STATE_SCHEMA", node, "Decorated handlers must be declared on an entity class with an inferred state schema.", className, method);
+        return true;
+    },
+    validateName(node, scope, className) {
+        if (HandlerTypes.methodName(node) !== undefined) {
+            return false;
+        }
+        HandlerTypes.pushDiagnostic(scope, "INVALID_HANDLER_NAME", node.name, "Decorated handlers must use a string method name.", className);
+        return true;
+    },
+    validateVisibility(node, scope, className, method) {
+        if (!HandlerTypes.hasModifier(node, ts.SyntaxKind.StaticKeyword) &&
+            !HandlerTypes.hasModifier(node, ts.SyntaxKind.PrivateKeyword) &&
+            !HandlerTypes.hasModifier(node, ts.SyntaxKind.ProtectedKeyword)) {
+            return false;
+        }
+        HandlerTypes.pushDiagnostic(scope, "INVALID_HANDLER_VISIBILITY", node.name, "Decorated handlers must be public instance methods.", className, method);
+        return true;
+    },
+    validateParameters(node, decorator, scope, className, method) {
+        if (node.parameters.length !== 1 && node.parameters.length !== 2) {
+            HandlerTypes.pushDiagnostic(scope, "INVALID_PARAMETER_COUNT", node, "Decorated handlers must declare one or two public parameters.", className, method);
+            return true;
+        }
+        if (node.parameters[0]?.type === undefined) {
+            HandlerTypes.pushDiagnostic(scope, "MISSING_SIGNAL_TYPE", node, `@${decorator} handlers require an explicit first parameter type.`, className, method);
+            return true;
+        }
+        const origin = HandlerSources.externalOrigin(node.parameters, scope, className, method);
+        if (origin === undefined)
+            return true;
+        const signal = HandlerSources.schemaUseFromType(origin.type, scope.imports);
+        if (signal !== undefined && HandlerSources.acceptsSignalKind(decorator, signal.kind)) {
+            if (origin.value === "external" && signal.kind === "command") {
+                HandlerTypes.pushDiagnostic(scope, "EXTERNAL_COMMAND_RECEIVER", node.parameters[0].type, "Command receivers cannot declare External<Command>.", className, method);
+                return true;
+            }
+            return false;
+        }
+        HandlerTypes.pushDiagnostic(scope, "INVALID_SIGNAL_TYPE", node.parameters[0].type, `@${decorator} first parameter must be ${HandlerSources.signalMessage(decorator)}.`, className, method);
+        return true;
+    },
+    validateReturn(node, decorator, scope, className, method) {
+        if (decorator === "Subscribe") {
+            return HandlerSources.validateSubscribeReturn(node, scope, className, method);
+        }
+        if (node.type === undefined) {
+            HandlerTypes.pushDiagnostic(scope, "MISSING_RETURN_TYPE", node, `@${decorator} handlers require an explicit return type.`, className, method);
+            return true;
+        }
+        const envelope = HandlerSources.frameworkEnvelope(node.type, scope.imports);
+        if (envelope !== undefined) {
+            HandlerTypes.pushDiagnostic(scope, "FRAMEWORK_ENVELOPE_RETURN", node.type, `Handler return type must not be framework ${envelope}.`, className, method);
+            return true;
+        }
+        return HandlerSources.validateEmittedReturn(node, decorator, scope, className, method);
+    },
+    validateSubscribeReturn(node, scope, className, method) {
+        if (node.type?.kind === ts.SyntaxKind.VoidKeyword) {
+            return false;
+        }
+        HandlerTypes.pushDiagnostic(scope, "INVALID_SUBSCRIBE_RETURN", node, "@Subscribe handlers must return explicit void.", className, method);
+        return true;
+    },
+    validateEmittedReturn(node, decorator, scope, className, method) {
+        const schemas = HandlerSources.emittedSchemaUses(node.type, decorator, scope.imports);
+        if (schemas === undefined) {
+            HandlerTypes.pushDiagnostic(scope, "UNSUPPORTED_RETURN_TYPE", node.type ?? node, `@${decorator} return type must resolve to generated schema references.`, className, method);
+            return true;
+        }
+        const expected = HandlerSources.emittedSignalKind(decorator);
+        if (expected !== undefined && schemas.some((schema) => schema.kind !== expected)) {
+            HandlerTypes.pushDiagnostic(scope, "INVALID_EMITTED_SCHEMA", node.type ?? node, `@${decorator} return type must emit generated ${expected} schemas.`, className, method);
+            return true;
+        }
+        if ((decorator === "Assign" || decorator === "Command") && schemas.length === 0) {
+            HandlerTypes.pushDiagnostic(scope, "MISSING_EMITTED_SCHEMAS", node.type ?? node, `@${decorator} handlers must emit at least one schema.`, className, method);
+            return true;
+        }
+        if (decorator === "React" &&
+            schemas.length === 0 &&
+            !HandlerSources.isExplicitVoidType(node.type)) {
+            HandlerTypes.pushDiagnostic(scope, "MISSING_EMITTED_SCHEMAS", node.type ?? node, "@React handlers must emit at least one schema unless they return explicit void.", className, method);
+            return true;
+        }
+        return false;
+    },
+    methodDecorators(node, imports) {
+        return (ts.getDecorators(node) ?? []).flatMap((decorator) => {
+            const expression = ts.isCallExpression(decorator.expression)
+                ? decorator.expression.expression
+                : decorator.expression;
+            const name = HandlerSources.serverDecoratorName(expression, imports);
+            return name === undefined
+                ? []
+                : [{ hasArguments: ts.isCallExpression(decorator.expression), name, node: decorator }];
+        });
+    },
+    serverDecoratorName(expression, imports) {
+        if (ts.isIdentifier(expression)) {
+            return HandlerTypes.serverDecorator(imports.serverSymbols.get(expression.text));
+        }
+        if (ts.isPropertyAccessExpression(expression)) {
+            const namespace = HandlerTypes.expressionName(expression.expression);
+            if (namespace !== undefined && imports.serverNamespaces.has(namespace)) {
+                return HandlerTypes.serverDecorator(expression.name.text);
+            }
+        }
+        return undefined;
+    },
+    isHandlerUse(decorator) {
+        return handlerDecorators.has(decorator.name);
+    },
+    entityStateSchema(node, imports) {
+        for (const clause of node.heritageClauses ?? []) {
+            for (const type of clause.types) {
+                if (!HandlerSources.isEntityBase(type.expression, imports)) {
+                    continue;
+                }
+                const stateType = type.typeArguments?.[1];
+                const reference = stateType === undefined
+                    ? undefined
+                    : HandlerSources.schemaFromTypeQuery(stateType, imports, HandlerSources.newTypeWalk());
+                if (reference !== undefined) {
+                    return reference;
+                }
+            }
+        }
+        return undefined;
+    },
+    isEntityBase(expression, imports) {
+        if (ts.isIdentifier(expression)) {
+            return entityBaseNames.has(imports.serverSymbols.get(expression.text) ?? "");
+        }
+        if (ts.isPropertyAccessExpression(expression)) {
+            const namespace = HandlerTypes.expressionName(expression.expression);
+            return (namespace !== undefined &&
+                imports.serverNamespaces.has(namespace) &&
+                entityBaseNames.has(expression.name.text));
+        }
+        return false;
+    },
+    schemaFromTypeQuery(typeNode, imports, walk) {
+        if (!HandlerSources.consumeTypeWalk(walk)) {
+            return undefined;
+        }
+        if (ts.isParenthesizedTypeNode(typeNode)) {
+            return HandlerSources.schemaFromTypeQuery(typeNode.type, imports, walk);
+        }
+        if (ts.isTypeReferenceNode(typeNode) && ts.isIdentifier(typeNode.typeName)) {
+            const alias = imports.localTypeAliases.get(typeNode.typeName.text);
+            return alias === undefined
+                ? undefined
+                : HandlerSources.resolveAlias(typeNode.typeName.text, alias, walk, (resolved) => HandlerSources.schemaFromTypeQuery(resolved, imports, walk));
+        }
+        if (!ts.isTypeQueryNode(typeNode)) {
+            return undefined;
+        }
+        return HandlerSources.schemaFromEntityName(typeNode.exprName, imports);
+    },
+    emittedSchemaUses(typeNode, decorator, imports) {
+        if (decorator === "Subscribe") {
+            return typeNode?.kind === ts.SyntaxKind.VoidKeyword ? [] : undefined;
+        }
+        if (typeNode?.kind === ts.SyntaxKind.VoidKeyword) {
+            return [];
+        }
+        if (typeNode === undefined) {
+            return undefined;
+        }
+        return HandlerSources.schemaListFromType(typeNode, imports, HandlerSources.newTypeWalk());
+    },
+    schemaListFromType(typeNode, imports, walk) {
+        if (!HandlerSources.consumeTypeWalk(walk)) {
+            return undefined;
+        }
+        const unwrapped = HandlerSources.unwrapReadonly(typeNode);
+        if (ts.isArrayTypeNode(unwrapped)) {
+            const item = HandlerSources.schemaUseFromType(unwrapped.elementType, imports, walk);
+            return item === undefined ? undefined : [item];
+        }
+        if (ts.isTupleTypeNode(unwrapped)) {
+            return HandlerSources.schemaListFromTuple(unwrapped, imports, walk);
+        }
+        if (ts.isTypeReferenceNode(unwrapped) && HandlerSources.isArrayReferenceType(unwrapped)) {
+            const item = HandlerSources.schemaUseFromType(unwrapped.typeArguments?.[0], imports, walk);
+            return item === undefined ? undefined : [item];
+        }
+        const schema = HandlerSources.schemaUseFromType(unwrapped, imports, walk);
+        return schema === undefined ? undefined : [schema];
+    },
+    schemaListFromTuple(typeNode, imports, walk) {
+        const schemas = [];
+        for (const element of typeNode.elements) {
+            const schema = HandlerSources.schemaFromTupleElement(element, imports, walk);
+            if (schema === undefined) {
+                return undefined;
+            }
+            schemas.push(schema);
+        }
+        return schemas;
+    },
+    schemaFromTupleElement(typeNode, imports, walk) {
+        if (ts.isNamedTupleMember(typeNode)) {
+            return typeNode.questionToken === undefined && typeNode.dotDotDotToken === undefined
+                ? HandlerSources.schemaUseFromType(typeNode.type, imports, walk)
+                : undefined;
+        }
+        if (ts.isRestTypeNode(typeNode) || ts.isOptionalTypeNode(typeNode)) {
+            return undefined;
+        }
+        return HandlerSources.schemaUseFromType(typeNode, imports, walk);
+    },
+    schemaUseFromType(typeNode, imports, walk = HandlerSources.newTypeWalk()) {
+        if (typeNode === undefined) {
+            return undefined;
+        }
+        if (!HandlerSources.consumeTypeWalk(walk)) {
+            return undefined;
+        }
+        const unwrapped = HandlerSources.unwrapReadonly(typeNode);
+        if (!ts.isTypeReferenceNode(unwrapped)) {
+            return undefined;
+        }
+        if (ts.isIdentifier(unwrapped.typeName)) {
+            const alias = imports.localTypeAliases.get(unwrapped.typeName.text);
+            if (alias !== undefined) {
+                return HandlerSources.resolveAlias(unwrapped.typeName.text, alias, walk, (resolved) => HandlerSources.schemaUseFromType(resolved, imports, walk));
+            }
+            return HandlerSources.schemaUseFromSymbol(unwrapped.typeName.text, imports);
+        }
+        if (ts.isQualifiedName(unwrapped.typeName)) {
+            return HandlerSources.schemaUseFromName(unwrapped.typeName, imports);
+        }
+        return undefined;
+    },
+    schemaUseFromSymbol(name, imports) {
+        const symbol = imports.generatedSymbols.get(name);
+        if (symbol?.schemaExportName === undefined) {
+            return undefined;
+        }
+        return {
+            kind: symbol.kind,
+            reference: { moduleSpecifier: symbol.moduleSpecifier, exportName: symbol.schemaExportName },
+        };
+    },
+    schemaUseFromName(name, imports) {
+        if (!ts.isIdentifier(name.left)) {
+            return undefined;
+        }
+        const namespace = imports.generatedNamespaces.get(name.left.text);
+        const schemaName = `${name.right.text}Schema`;
+        return namespace === undefined ||
+            !HandlerTypes.hasGeneratedType(namespace.exports, name.right.text) ||
+            !namespace.exports.values.has(schemaName)
+            ? undefined
+            : {
+                kind: namespace.exports.schemaRoles.get(schemaName),
+                reference: { moduleSpecifier: namespace.moduleSpecifier, exportName: schemaName },
+            };
+    },
+    schemaFromEntityName(name, imports) {
+        if (ts.isIdentifier(name)) {
+            const symbol = imports.generatedSymbols.get(name.text);
+            return symbol?.schemaValue !== true
+                ? undefined
+                : { moduleSpecifier: symbol.moduleSpecifier, exportName: symbol.exportName };
+        }
+        if (ts.isQualifiedName(name) && ts.isIdentifier(name.left)) {
+            const namespace = imports.generatedNamespaces.get(name.left.text);
+            return namespace?.exports.values.has(name.right.text) !== true
+                ? undefined
+                : { moduleSpecifier: namespace.moduleSpecifier, exportName: name.right.text };
+        }
+        return undefined;
+    },
+    frameworkEnvelope(typeNode, imports, walk = HandlerSources.newTypeWalk()) {
+        if (!HandlerSources.consumeTypeWalk(walk)) {
+            return undefined;
+        }
+        const unwrapped = HandlerSources.unwrapReadonly(typeNode);
+        if (!ts.isTypeReferenceNode(unwrapped)) {
+            return undefined;
+        }
+        if (ts.isIdentifier(unwrapped.typeName)) {
+            const alias = imports.localTypeAliases.get(unwrapped.typeName.text);
+            if (alias !== undefined) {
+                return HandlerSources.resolveAlias(unwrapped.typeName.text, alias, walk, (resolved) => HandlerSources.frameworkEnvelope(resolved, imports, walk));
+            }
+            return imports.protoSymbols.has(unwrapped.typeName.text)
+                ? unwrapped.typeName.text
+                : undefined;
+        }
+        if (ts.isQualifiedName(unwrapped.typeName) && ts.isIdentifier(unwrapped.typeName.left)) {
+            const namespace = unwrapped.typeName.left.text;
+            const name = unwrapped.typeName.right.text;
+            return imports.protoNamespaces.has(namespace) && (name === "Event" || name === "Command")
+                ? `${namespace}.${name}`
+                : undefined;
+        }
+        return undefined;
+    },
+    unwrapReadonly(typeNode) {
+        if (ts.isParenthesizedTypeNode(typeNode)) {
+            return HandlerSources.unwrapReadonly(typeNode.type);
+        }
+        if (ts.isTypeOperatorNode(typeNode) && typeNode.operator === ts.SyntaxKind.ReadonlyKeyword) {
+            return HandlerSources.unwrapReadonly(typeNode.type);
+        }
+        return typeNode;
+    },
+    isExplicitVoidType(typeNode) {
+        if (typeNode === undefined) {
+            return false;
+        }
+        if (ts.isParenthesizedTypeNode(typeNode)) {
+            return HandlerSources.isExplicitVoidType(typeNode.type);
+        }
+        return typeNode.kind === ts.SyntaxKind.VoidKeyword;
+    },
+    isArrayReferenceType(typeNode) {
+        return (ts.isIdentifier(typeNode.typeName) &&
+            (typeNode.typeName.text === "Array" || typeNode.typeName.text === "ReadonlyArray"));
+    },
+    handlerKind(decorator, signalKind) {
+        switch (decorator) {
+            case "Assign":
+                return "command-assignment";
+            case "Command":
+                return "command-reaction";
+            case "React":
+                return "event-reaction";
+            case "Subscribe":
+                return signalKind === "state" ? "state-subscription" : "event-subscription";
+        }
+    },
+    acceptsSignalKind(decorator, kind) {
+        if (decorator === "Command") {
+            return kind === "command" || kind === "event" || kind === "rejection";
+        }
+        if (decorator === "Assign") {
+            return kind === "command";
+        }
+        return (kind === "event" || kind === "rejection" || (decorator === "Subscribe" && kind === "state"));
+    },
+    signalMessage(decorator) {
+        if (decorator === "Command") {
+            return "a generated command, event, or rejection type";
+        }
+        if (decorator === "Assign") {
+            return "a generated command type";
+        }
+        return decorator === "Subscribe"
+            ? "a generated event, rejection, or Entity state type"
+            : "a generated event or rejection type";
+    },
+    emittedSignalKind(decorator) {
+        if (decorator === "Command") {
+            return "command";
+        }
+        if (decorator === "Assign" || decorator === "React") {
+            return "event";
+        }
+        return undefined;
+    },
+    externalOrigin(parameters, scope, className, method) {
+        const first = parameters[0]?.type;
+        if (first === undefined)
+            return undefined;
+        const marker = HandlerSources.externalMarker(first, scope);
+        const laterMarker = parameters
+            .slice(1)
+            .some((parameter) => parameter.type === undefined
+            ? false
+            : HandlerSources.containsExternalMarker(parameter.type, scope));
+        const nestedMarker = marker === undefined && HandlerSources.containsExternalMarker(first, scope);
+        if (laterMarker || nestedMarker || (marker !== undefined && !marker.direct)) {
+            HandlerTypes.pushDiagnostic(scope, "INVALID_EXTERNAL_ORIGIN", laterMarker ? (parameters[1]?.type ?? first) : first, "External<T> is valid only as the direct first receptor parameter type.", className, method);
+            return undefined;
+        }
+        if (marker?.direct === true && marker.type !== undefined) {
+            return { value: "external", type: marker.type };
+        }
+        return { value: "domestic", type: first };
+    },
+    externalMarker(type, scope) {
+        if (!ts.isTypeReferenceNode(type))
+            return undefined;
+        const canonical = (ts.isIdentifier(type.typeName) &&
+            scope.imports.serverSymbols.get(type.typeName.text) === "External") ||
+            (ts.isQualifiedName(type.typeName) &&
+                ts.isIdentifier(type.typeName.left) &&
+                type.typeName.right.text === "External" &&
+                scope.imports.serverNamespaces.has(type.typeName.left.text));
+        if (!canonical || !HandlerSources.isCanonicalExternal(type.typeName, scope.program))
+            return undefined;
+        const argument = type.typeArguments?.[0];
+        return argument === undefined
+            ? { direct: false }
+            : { direct: type.typeArguments?.length === 1, type: argument };
+    },
+    containsExternalMarker(type, scope, seen = new Set()) {
+        if (HandlerSources.externalMarker(type, scope) !== undefined)
+            return true;
+        if (ts.isTypeReferenceNode(type) && ts.isIdentifier(type.typeName)) {
+            const alias = scope.imports.localTypeAliases.get(type.typeName.text);
+            if (alias !== undefined && !seen.has(type.typeName.text)) {
+                const next = new Set(seen);
+                next.add(type.typeName.text);
+                if (HandlerSources.containsExternalMarker(alias, scope, next))
+                    return true;
+            }
+        }
+        let found = false;
+        const visit = (node) => {
+            if (found)
+                return;
+            if (ts.isTypeNode(node) && HandlerSources.externalMarker(node, scope) !== undefined) {
+                found = true;
+                return;
+            }
+            ts.forEachChild(node, visit);
+        };
+        ts.forEachChild(type, visit);
+        return found;
+    },
+    isCanonicalExternal(name, program) {
+        const checker = program.getTypeChecker();
+        const location = ts.isQualifiedName(name) ? name.right : name;
+        let symbol = checker.getSymbolAtLocation(location);
+        if (symbol === undefined)
+            return false;
+        if ((symbol.flags & ts.SymbolFlags.Alias) !== 0) {
+            symbol = checker.getAliasedSymbol(symbol);
+        }
+        return (symbol.declarations ?? []).some((declaration) => ts.isTypeAliasDeclaration(declaration) &&
+            declaration.name.text === "External" &&
+            PackageIdentity.nameFor(declaration.getSourceFile().fileName) ===
+                "@spine-event-engine/server" &&
+            /^external(?:\.d)?\.ts$/u.test(declaration.getSourceFile().fileName.split(/[\\/]/u).at(-1) ?? ""));
+    },
+    newTypeWalk() {
+        return { remaining: maxAliasDepth, seen: new Set() };
+    },
+    consumeTypeWalk(walk) {
+        walk.remaining -= 1;
+        return walk.remaining >= 0;
+    },
+    resolveAlias(name, typeNode, walk, resolveType) {
+        if (walk.seen.has(name)) {
+            return undefined;
+        }
+        walk.seen.add(name);
+        const resolved = resolveType(typeNode);
+        walk.seen.delete(name);
+        return resolved;
+    },
+    buildImportState(source, program) {
+        const state = {
+            generatedNamespaces: new Map(),
+            generatedSymbols: new Map(),
+            localTypeAliases: new Map(),
+            serverNamespaces: new Set(),
+            serverSymbols: new Map(),
+            protoNamespaces: new Set(),
+            protoSymbols: new Set(),
+        };
+        for (const statement of source.statements) {
+            HandlerSources.recordImportStatement(statement, source, program, state);
+        }
+        return state;
+    },
+    recordImportStatement(statement, source, program, state) {
+        if (ts.isImportDeclaration(statement) && ts.isStringLiteral(statement.moduleSpecifier)) {
+            HandlerSources.recordImportDeclaration(statement, statement.moduleSpecifier.text, source, program, state);
+        }
+        if (ts.isTypeAliasDeclaration(statement)) {
+            state.localTypeAliases.set(statement.name.text, statement.type);
+        }
+    },
+    recordImportDeclaration(statement, moduleSpecifier, source, program, state) {
+        const bindings = statement.importClause?.namedBindings;
+        if (bindings === undefined) {
+            return;
+        }
+        if (moduleSpecifier === "@spine-event-engine/server") {
+            HandlerSources.recordServerImport(bindings, state);
+        }
+        if (moduleSpecifier === "@spine-event-engine/proto") {
+            HandlerSources.recordProtoImport(bindings, state);
+        }
+        if (HandlerSources.isGeneratedModule(moduleSpecifier)) {
+            HandlerSources.recordGeneratedImport(bindings, moduleSpecifier, statement.importClause?.phaseModifier !== ts.SyntaxKind.TypeKeyword, source, program, state);
+        }
+    },
+    recordServerImport(bindings, state) {
+        if (ts.isNamespaceImport(bindings)) {
+            state.serverNamespaces.add(bindings.name.text);
+            return;
+        }
+        for (const element of bindings.elements) {
+            state.serverSymbols.set(element.name.text, element.propertyName?.text ?? element.name.text);
+        }
+    },
+    recordProtoImport(bindings, state) {
+        if (ts.isNamespaceImport(bindings)) {
+            state.protoNamespaces.add(bindings.name.text);
+            return;
+        }
+        for (const element of bindings.elements) {
+            const imported = element.propertyName?.text ?? element.name.text;
+            if (imported === "Event" || imported === "Command") {
+                state.protoSymbols.add(element.name.text);
+            }
+        }
+    },
+    recordGeneratedImport(bindings, moduleSpecifier, valueImport, source, program, state) {
+        const exported = HandlerSources.generatedModuleExports(source, moduleSpecifier, program);
+        if (exported === undefined) {
+            return;
+        }
+        if (ts.isNamespaceImport(bindings)) {
+            state.generatedNamespaces.set(bindings.name.text, { exports: exported, moduleSpecifier });
+            return;
+        }
+        for (const element of bindings.elements) {
+            const exportName = element.propertyName?.text ?? element.name.text;
+            if (!HandlerTypes.hasGeneratedType(exported, exportName)) {
+                continue;
+            }
+            const schemaExportName = `${exportName}Schema`;
+            state.generatedSymbols.set(element.name.text, {
+                exports: exported,
+                moduleSpecifier,
+                exportName,
+                kind: exported.schemaRoles.get(schemaExportName),
+                schemaExportName: exported.values.has(schemaExportName) ? schemaExportName : undefined,
+                schemaValue: valueImport && !element.isTypeOnly && exported.values.has(exportName),
+            });
+        }
+    },
+    isGeneratedModule(moduleSpecifier) {
+        return /(^|\/)generated\/.+_pb(\.js)?$/.test(moduleSpecifier);
+    },
+    generatedModuleExports(source, moduleSpecifier, program) {
+        const module = HandlerSources.generatedModuleSource(source, moduleSpecifier, program);
+        if (module === undefined)
+            return undefined;
+        const declarations = HandlerSources.exportedNames(module);
+        const runtime = HandlerSources.pairedRuntimeExports(module);
+        if (runtime === undefined)
+            return declarations;
+        return {
+            types: declarations.types,
+            values: runtime.values,
+            schemaRoles: runtime.schemaRoles,
+        };
+    },
+    pairedRuntimeExports(declarations) {
+        if (!declarations.isDeclarationFile)
+            return undefined;
+        const runtimePath = declarations.fileName.replace(/\.d\.ts$/u, ".js");
+        try {
+            return HandlerSources.exportedNames(ts.createSourceFile(runtimePath, readFileSync(runtimePath, "utf8"), ts.ScriptTarget.Latest));
+        }
+        catch {
+            return undefined;
+        }
+    },
+    generatedModuleSource(source, moduleSpecifier, program) {
+        const imported = HandlerSources.importedModuleSource(source, moduleSpecifier, program);
+        if (imported !== undefined) {
+            return imported;
+        }
+        const resolved = ts.resolveModuleName(moduleSpecifier, source.fileName, program.getCompilerOptions(), ts.sys).resolvedModule?.resolvedFileName;
+        const base = resolve(dirname(source.fileName), moduleSpecifier);
+        const candidates = HandlerSources.uniqueStrings([
+            ...(resolved === undefined ? [] : [resolved]),
+            base.replace(/\.js$/, ".ts"),
+            `${base}.ts`,
+            base,
+            base.replace(/\.js$/, ".d.ts"),
+            `${base}.d.ts`,
+        ]);
+        const sourceFiles = new Map(program.getSourceFiles().map((candidate) => [resolve(candidate.fileName), candidate]));
+        for (const candidate of candidates) {
+            const sourceFile = sourceFiles.get(candidate);
+            if (sourceFile !== undefined) {
+                return sourceFile;
+            }
+        }
+        return undefined;
+    },
+    importedModuleSource(source, moduleSpecifier, program) {
+        const declaration = source.statements.find((statement) => ts.isImportDeclaration(statement) &&
+            ts.isStringLiteral(statement.moduleSpecifier) &&
+            statement.moduleSpecifier.text === moduleSpecifier);
+        if (declaration === undefined)
+            return undefined;
+        const symbol = program.getTypeChecker().getSymbolAtLocation(declaration.moduleSpecifier);
+        const imported = symbol?.declarations
+            ?.map((candidate) => candidate.getSourceFile())
+            .find((candidate) => candidate !== source);
+        return imported;
+    },
+    uniqueStrings(values) {
+        return [...new Set(values)];
+    },
+    exportedNames(source) {
+        const files = HandlerSources.generatedFiles(source);
+        const schemaRoles = new Map();
+        const exports = { types: new Set(), values: new Set(), schemaRoles };
+        for (const statement of source.statements) {
+            HandlerSources.recordExportedNames(statement, exports, files);
+        }
+        return exports;
+    },
+    generatedFiles(source) {
+        const files = new Map();
+        for (const statement of source.statements) {
+            if (!ts.isVariableStatement(statement)) {
+                continue;
+            }
+            for (const declaration of statement.declarationList.declarations) {
+                if (!ts.isIdentifier(declaration.name)) {
+                    continue;
+                }
+                const descriptor = HandlerSources.fileDescriptor(declaration.initializer);
+                if (descriptor !== undefined) {
+                    files.set(declaration.name.text, descriptor);
+                }
+            }
+        }
+        return files;
+    },
+    recordExportedNames(statement, exports, files) {
+        if (ts.isVariableStatement(statement) &&
+            HandlerTypes.hasModifier(statement, ts.SyntaxKind.ExportKeyword)) {
+            for (const declaration of statement.declarationList.declarations) {
+                if (ts.isIdentifier(declaration.name)) {
+                    exports.values.add(declaration.name.text);
+                    const schemaRole = HandlerSources.schemaRoleFromInitializer(declaration.name.text, declaration.initializer, files);
+                    if (schemaRole.found) {
+                        exports.schemaRoles.set(declaration.name.text, schemaRole.kind);
+                    }
+                }
+            }
+        }
+        if (HandlerTypes.hasModifier(statement, ts.SyntaxKind.ExportKeyword)) {
+            HandlerTypes.recordNamedExport(statement, exports);
+        }
+    },
+    schemaRoleFromInitializer(schemaExportName, initializer, files) {
+        const call = HandlerSources.callExpression(initializer, "messageDesc");
+        if (call === undefined) {
+            return { found: false, kind: undefined };
+        }
+        const fileName = call.arguments[0];
+        if (fileName === undefined || !ts.isIdentifier(fileName)) {
+            return { found: false, kind: undefined };
+        }
+        const file = files.get(fileName.text);
+        if (file === undefined) {
+            return { found: true, kind: undefined };
+        }
+        const indexes = HandlerSources.messageDescIndexes(call);
+        const message = HandlerSources.descriptorMessageAt(file, indexes);
+        const messageName = message?.exportName;
+        const expectedName = schemaExportName.replace(/Schema$/, "");
+        if (messageName === undefined || messageName !== expectedName) {
+            return { found: true, kind: undefined };
+        }
+        return {
+            found: true,
+            kind: message?.descriptor.isEntityState
+                ? "state"
+                : HandlerSources.signalKindFromProto(file.sourceFile, indexes),
+        };
+    },
+    messageDescIndexes(call) {
+        const indexes = [];
+        for (const argument of call.arguments.slice(1)) {
+            if (!ts.isNumericLiteral(argument)) {
+                return undefined;
+            }
+            const index = Number(argument.text);
+            if (!Number.isInteger(index) || index < 0) {
+                return undefined;
+            }
+            indexes.push(index);
+        }
+        return indexes.length === 0 ? undefined : indexes;
+    },
+    descriptorMessageAt(file, indexes) {
+        if (indexes === undefined) {
+            return undefined;
+        }
+        let messages = file.messages;
+        let message;
+        const path = [];
+        for (const index of indexes) {
+            message = messages[index];
+            if (message === undefined) {
+                return undefined;
+            }
+            path.push(message.name);
+            messages = message.nested;
+        }
+        return message === undefined ? undefined : { descriptor: message, exportName: path.join("_") };
+    },
+    fileDescriptor(initializer) {
+        const call = HandlerSources.callExpression(initializer, "fileDesc");
+        const descriptor = call?.arguments[0];
+        if (descriptor === undefined || !ts.isStringLiteralLike(descriptor)) {
+            return undefined;
+        }
+        try {
+            const { protobuf, protobufWkt } = PackageDependencies.current();
+            const file = protobuf.fromBinary(protobufWkt.FileDescriptorProtoSchema, Buffer.from(descriptor.text, "base64"));
+            return file.name === ""
+                ? undefined
+                : {
+                    sourceFile: file.name,
+                    messages: file.messageType.map(HandlerSources.descriptorMessage),
+                };
+        }
+        catch {
+            return undefined;
+        }
+    },
+    callExpression(expression, functionName) {
+        if (expression === undefined) {
+            return undefined;
+        }
+        const unwrapped = HandlerSources.unwrapExpression(expression);
+        if (!ts.isCallExpression(unwrapped) || !ts.isIdentifier(unwrapped.expression)) {
+            return undefined;
+        }
+        return unwrapped.expression.text === functionName ? unwrapped : undefined;
+    },
+    unwrapExpression(expression) {
+        if (ts.isParenthesizedExpression(expression)) {
+            return HandlerSources.unwrapExpression(expression.expression);
+        }
+        if (ts.isAsExpression(expression) || ts.isSatisfiesExpression(expression)) {
+            return HandlerSources.unwrapExpression(expression.expression);
+        }
+        return expression;
+    },
+    signalKindFromProto(sourceFile, messageIndexes) {
+        const sourceName = sourceFile.split(/[\\/]/u).at(-1);
+        if (sourceName === "rejections.proto" || sourceName?.endsWith("_rejections.proto") === true) {
+            return messageIndexes?.length === 1 ? "rejection" : undefined;
+        }
+        if (sourceFile.endsWith("commands.proto")) {
+            return "command";
+        }
+        if (sourceFile.endsWith("events.proto")) {
+            return "event";
+        }
+        return undefined;
+    },
+    descriptorMessage(message) {
+        return {
+            name: message.name,
+            isEntityState: message.options?.$unknown?.some((field) => field.no === entityOptionFieldNumber) === true,
+            nested: message.nestedType.map(HandlerSources.descriptorMessage),
+        };
+    },
+});
+/**
+ * Finds the package identity that owns an analyzed source file.
+ */
+export const PackageIdentity = Object.freeze({
+    nameFor(sourceFile) {
+        let directory = resolve(dirname(sourceFile));
+        let manifest = join(directory, "package.json");
+        while (!existsSync(manifest)) {
+            const parent = dirname(directory);
+            if (parent === directory)
+                return undefined;
+            directory = parent;
+            manifest = join(directory, "package.json");
+        }
+        try {
+            const { name } = JSON.parse(readFileSync(manifest, "utf8"));
+            return typeof name === "string" ? name : undefined;
+        }
+        catch {
+            return undefined;
+        }
+    },
+});
+const PackageDependencies = Object.freeze({
+    load(program) {
+        packageDependencies ??= {
+            protobuf: PackageDependencies.require("@bufbuild/protobuf", program),
+            protobufWkt: PackageDependencies.require("@bufbuild/protobuf/wkt", program),
+        };
+    },
+    current() {
+        if (packageDependencies === undefined)
+            throw new Error("Build handler analyzer dependencies are not loaded.");
+        return packageDependencies;
+    },
+    require(specifier, program) {
+        try {
+            return createRequire(import.meta.url)(specifier);
+        }
+        catch (directError) {
+            const appRoot = program.getRootFileNames()[0];
+            if (appRoot === undefined)
+                throw directError;
+            const applicationRequire = createRequire(appRoot);
+            try {
+                return applicationRequire(specifier);
+            }
+            catch {
+                // The in-repository generator transpiles this module into a temporary
+                // cache directory. A fresh workspace install has the descriptor
+                // package at the application's resolution boundary, while the
+                // temporary module has no package boundary of its own.
+            }
+            try {
+                const toolingEntry = applicationRequire.resolve("@spine-event-engine/proto-tools");
+                return createRequire(join(PackageDependencies.rootFor(toolingEntry), "package.json"))(specifier);
+            }
+            catch {
+                throw directError;
+            }
+        }
+    },
+    rootFor(entry) {
+        let directory = dirname(entry);
+        while (!existsSync(join(directory, "package.json"))) {
+            const parent = dirname(directory);
+            if (parent === directory)
+                throw new Error("Cannot locate proto-tools package manifest.");
+            directory = parent;
+        }
+        return directory;
+    },
+});
+const HandlerTypes = Object.freeze({
+    recordNamedExport(statement, exports) {
+        if (ts.isClassDeclaration(statement) || ts.isEnumDeclaration(statement)) {
+            const name = statement.name;
+            if (name !== undefined) {
+                exports.types.add(name.text);
+                exports.values.add(name.text);
+            }
+            return;
+        }
+        if (ts.isFunctionDeclaration(statement)) {
+            const name = statement.name;
+            if (name !== undefined) {
+                exports.values.add(name.text);
+            }
+            return;
+        }
+        if (ts.isInterfaceDeclaration(statement) || ts.isTypeAliasDeclaration(statement)) {
+            exports.types.add(statement.name.text);
+        }
+    },
+    hasGeneratedType(exports, name) {
+        return exports.types.has(name) || exports.values.has(name);
+    },
+    serverDecorator(name) {
+        return name === "Assign" ||
+            name === "Command" ||
+            name === "React" ||
+            name === "Subscribe" ||
+            name === "Apply" ||
+            name === "Where"
+            ? name
+            : undefined;
+    },
+    methodName(node) {
+        if (ts.isIdentifier(node.name) || ts.isStringLiteral(node.name)) {
+            return node.name.text;
+        }
+        return undefined;
+    },
+    hasModifier(node, kind) {
+        return (ts.canHaveModifiers(node) &&
+            (ts.getModifiers(node) ?? []).some((modifier) => modifier.kind === kind));
+    },
+    expressionName(expression) {
+        if (ts.isIdentifier(expression)) {
+            return expression.text;
+        }
+        if (ts.isPropertyAccessExpression(expression)) {
+            const prefix = HandlerTypes.expressionName(expression.expression);
+            return prefix === undefined ? undefined : `${prefix}.${expression.name.text}`;
+        }
+        return undefined;
+    },
+    pushDiagnostic(scope, code, node, message, className, methodNameValue) {
+        const location = scope.source.getLineAndCharacterOfPosition(node.getStart(scope.source));
+        const base = {
+            code,
+            sourceFile: scope.source.fileName,
+            line: location.line + 1,
+            column: location.character + 1,
+            message,
+        };
+        scope.diagnostics.push({
+            ...base,
+            ...(className === undefined ? {} : { className }),
+            ...(methodNameValue === undefined ? {} : { methodName: methodNameValue }),
+        });
+    },
+    syntaxDiagnostic(source, diagnostic) {
+        const location = source.getLineAndCharacterOfPosition(diagnostic.start);
+        return {
+            code: "TYPESCRIPT_SYNTAX_ERROR",
+            sourceFile: source.fileName,
+            line: location.line + 1,
+            column: location.character + 1,
+            message: ts.flattenDiagnosticMessageText(diagnostic.messageText, "\n"),
+        };
+    },
+});
+//# sourceMappingURL=build-time-handler-analyzer.js.map