@ontrails/warden 1.0.0-beta.39 → 1.0.0-beta.41

package/src/rules/example-valid.ts

@@ -1,10 +1,10 @@
-import { contour } from '@ontrails/core';
+import { entity } from '@ontrails/core';
 import { z } from 'zod';
 
 import {
   extractStringLiteral,
   findConfigProperty,
-  findContourDefinitions,
+  findEntityDefinitions,
   getNodeExpression,
   getNodeObject,
   getNodeProperty,
@@ -12,24 +12,24 @@ import {
   identifierName,
   offsetToLine,
   parse,
-} from './ast.js';
-import type { AstNode, ContourDefinition } from './ast.js';
+} from '@ontrails/source';
+import type { AstNode, EntityDefinition } from '@ontrails/source';
 import { isTestFile } from './scan.js';
 import type { WardenDiagnostic, WardenRule } from './types.js';
 
-class UnsupportedContourEvaluationError extends Error {}
+class UnsupportedEntityEvaluationError extends Error {}
 
-type ContourEvaluationEnvironment = ReadonlyMap<string, unknown>;
+type EntityEvaluationEnvironment = ReadonlyMap<string, unknown>;
 
 const buildInvalidExampleDiagnostic = (
-  contourName: string,
+  entityName: string,
   message: string,
   filePath: string,
   line: number
 ): WardenDiagnostic => ({
   filePath,
   line,
-  message: `Contour "${contourName}" has invalid examples: ${message}`,
+  message: `Entity "${entityName}" has invalid examples: ${message}`,
   rule: 'example-valid',
   severity: 'error',
 });
@@ -49,53 +49,53 @@ const getPropertyName = (node: unknown): string | null => {
 
 const requireNode = (node: AstNode | undefined): AstNode => {
   if (!node) {
-    throw new UnsupportedContourEvaluationError(
-      'Missing node in contour evaluation.'
+    throw new UnsupportedEntityEvaluationError(
+      'Missing node in entity evaluation.'
     );
   }
 
   return node;
 };
 
-type ContourNodeEvaluator = (
+type EntityNodeEvaluator = (
   node: AstNode,
-  env: ContourEvaluationEnvironment
+  env: EntityEvaluationEnvironment
 ) => unknown;
 
 // The evaluator table is declared before `evaluateNode` so the recursive
 // dispatch can read it at call time without any forward references. Entries
 // are registered below once each per-type evaluator is defined.
-const contourNodeEvaluators = new Map<string, ContourNodeEvaluator>();
+const entityNodeEvaluators = new Map<string, EntityNodeEvaluator>();
 
-const evaluateNode: ContourNodeEvaluator = (
+const evaluateNode: EntityNodeEvaluator = (
   node: AstNode,
-  env: ContourEvaluationEnvironment
+  env: EntityEvaluationEnvironment
 ): unknown => {
-  const evaluator = contourNodeEvaluators.get(node.type);
+  const evaluator = entityNodeEvaluators.get(node.type);
   if (evaluator) {
     return evaluator(node, env);
   }
 
-  throw new UnsupportedContourEvaluationError(
-    `Unsupported AST node "${node.type}" in contour evaluation.`
+  throw new UnsupportedEntityEvaluationError(
+    `Unsupported AST node "${node.type}" in entity evaluation.`
   );
 };
 
-const evaluateArrayExpression: ContourNodeEvaluator = (
+const evaluateArrayExpression: EntityNodeEvaluator = (
   node: AstNode,
-  env: ContourEvaluationEnvironment
+  env: EntityEvaluationEnvironment
 ): readonly unknown[] => {
   const elements = node['elements'] as readonly AstNode[] | undefined;
   return (elements ?? []).map((element) => evaluateNode(element, env));
 };
 
-const evaluateLiteralExpression: ContourNodeEvaluator = (
+const evaluateLiteralExpression: EntityNodeEvaluator = (
   node: AstNode
 ): unknown => getStringValue(node) ?? node.value;
 
-const evaluateIdentifierExpression: ContourNodeEvaluator = (
+const evaluateIdentifierExpression: EntityNodeEvaluator = (
   node: AstNode,
-  env: ContourEvaluationEnvironment
+  env: EntityEvaluationEnvironment
 ): unknown => {
   const name = identifierName(node);
   if (name === 'undefined') {
@@ -107,39 +107,39 @@ const evaluateIdentifierExpression: ContourNodeEvaluator = (
   }
 
   if (!name || !env.has(name)) {
-    throw new UnsupportedContourEvaluationError(
-      `Unknown identifier "${name ?? '<unknown>'}" in contour evaluation.`
+    throw new UnsupportedEntityEvaluationError(
+      `Unknown identifier "${name ?? '<unknown>'}" in entity evaluation.`
     );
   }
 
   return env.get(name);
 };
 
-const evaluateWrappedExpression: ContourNodeEvaluator = (
+const evaluateWrappedExpression: EntityNodeEvaluator = (
   node: AstNode,
-  env: ContourEvaluationEnvironment
+  env: EntityEvaluationEnvironment
 ): unknown => evaluateNode(requireNode(getNodeExpression(node)), env);
 
-const evaluateNullExpression: ContourNodeEvaluator = (): null => null;
+const evaluateNullExpression: EntityNodeEvaluator = (): null => null;
 
-const evaluateObjectExpression: ContourNodeEvaluator = (
+const evaluateObjectExpression: EntityNodeEvaluator = (
   node: AstNode,
-  env: ContourEvaluationEnvironment
+  env: EntityEvaluationEnvironment
 ): Record<string, unknown> => {
   const properties = node['properties'] as readonly AstNode[] | undefined;
   const value: Record<string, unknown> = {};
 
   for (const property of properties ?? []) {
     if (property.type !== 'Property') {
-      throw new UnsupportedContourEvaluationError(
+      throw new UnsupportedEntityEvaluationError(
         `Unsupported object property type "${property.type}".`
       );
     }
 
     const propertyName = getPropertyName(property.key);
     if (!propertyName) {
-      throw new UnsupportedContourEvaluationError(
-        'Unsupported object property key in contour evaluation.'
+      throw new UnsupportedEntityEvaluationError(
+        'Unsupported object property key in entity evaluation.'
       );
     }
 
@@ -154,107 +154,107 @@ const evaluateObjectExpression: ContourNodeEvaluator = (
 
 const evaluateCallArguments = (
   node: AstNode,
-  env: ContourEvaluationEnvironment
+  env: EntityEvaluationEnvironment
 ): readonly unknown[] =>
   ((node['arguments'] as readonly AstNode[] | undefined) ?? []).map((arg) =>
     evaluateNode(arg, env)
   );
 
-const resolveContourFallbackOptions = (
+const resolveEntityFallbackOptions = (
   shape: unknown
-): Parameters<typeof contour>[2] | null =>
+): Parameters<typeof entity>[2] | null =>
   typeof shape === 'object' &&
   shape !== null &&
   Object.hasOwn(shape, 'id') &&
   (shape as z.ZodRawShape)['id'] !== undefined
-    ? ({ identity: 'id' } as Parameters<typeof contour>[2])
+    ? ({ identity: 'id' } as Parameters<typeof entity>[2])
     : null;
 
-const resolveContourOptions = (
+const resolveEntityOptions = (
   shape: unknown,
   options: unknown
-): Parameters<typeof contour>[2] => {
+): Parameters<typeof entity>[2] => {
   if (options === undefined) {
-    const fallbackOptions = resolveContourFallbackOptions(shape);
+    const fallbackOptions = resolveEntityFallbackOptions(shape);
     if (fallbackOptions !== null) {
       return fallbackOptions;
     }
 
-    throw new UnsupportedContourEvaluationError(
-      'Contour evaluator requires literal options, or an `id` field when options are omitted.'
+    throw new UnsupportedEntityEvaluationError(
+      'Entity evaluator requires literal options, or an `id` field when options are omitted.'
     );
   }
 
   if (typeof options !== 'object' || options === null) {
-    throw new UnsupportedContourEvaluationError(
-      'Contour evaluator requires literal options when provided.'
+    throw new UnsupportedEntityEvaluationError(
+      'Entity evaluator requires literal options when provided.'
     );
   }
 
-  return options as Parameters<typeof contour>[2];
+  return options as Parameters<typeof entity>[2];
 };
 
-const evaluateContourCall = (args: readonly unknown[]): unknown => {
+const evaluateEntityCall = (args: readonly unknown[]): unknown => {
   const [name, shape, options] = args;
   if (typeof name !== 'string') {
-    throw new UnsupportedContourEvaluationError(
-      'Contour evaluator requires a literal name.'
+    throw new UnsupportedEntityEvaluationError(
+      'Entity evaluator requires a literal name.'
     );
   }
 
-  return contour(
+  return entity(
     name,
     shape as z.ZodRawShape,
-    resolveContourOptions(shape, options)
+    resolveEntityOptions(shape, options)
   );
 };
 
 const evaluateMemberCall = (
   callee: AstNode,
   args: readonly unknown[],
-  env: ContourEvaluationEnvironment
+  env: EntityEvaluationEnvironment
 ): unknown => {
   const receiver = evaluateNode(requireNode(getNodeObject(callee)), env);
   const propertyName = getPropertyName(getNodeProperty(callee));
   if (!propertyName) {
-    throw new UnsupportedContourEvaluationError(
-      'Unsupported member property in contour evaluation.'
+    throw new UnsupportedEntityEvaluationError(
+      'Unsupported member property in entity evaluation.'
     );
   }
 
   const method = (receiver as Record<string, unknown>)[propertyName];
   if (typeof method !== 'function') {
-    throw new UnsupportedContourEvaluationError(
-      `Contour evaluator could not call "${propertyName}".`
+    throw new UnsupportedEntityEvaluationError(
+      `Entity evaluator could not call "${propertyName}".`
     );
   }
 
   return Reflect.apply(method, receiver, args);
 };
 
-const evaluateCallExpression: ContourNodeEvaluator = (
+const evaluateCallExpression: EntityNodeEvaluator = (
   node: AstNode,
-  env: ContourEvaluationEnvironment
+  env: EntityEvaluationEnvironment
 ): unknown => {
   const args = evaluateCallArguments(node, env);
   const callee = requireNode(node['callee'] as AstNode | undefined);
 
   if (callee.type === 'Identifier') {
     const calleeName = identifierName(callee);
-    if (calleeName !== 'contour') {
-      throw new UnsupportedContourEvaluationError(
-        `Unsupported contour evaluator call "${calleeName ?? '<unknown>'}".`
+    if (calleeName !== 'entity') {
+      throw new UnsupportedEntityEvaluationError(
+        `Unsupported entity evaluator call "${calleeName ?? '<unknown>'}".`
       );
     }
 
-    return evaluateContourCall(args);
+    return evaluateEntityCall(args);
   }
 
   if (
     callee.type !== 'MemberExpression' &&
     callee.type !== 'StaticMemberExpression'
   ) {
-    throw new UnsupportedContourEvaluationError(
+    throw new UnsupportedEntityEvaluationError(
       `Unsupported callee type "${callee.type}".`
     );
   }
@@ -264,7 +264,7 @@ const evaluateCallExpression: ContourNodeEvaluator = (
 
 const EVALUATOR_REGISTRATIONS: readonly (readonly [
   string,
-  ContourNodeEvaluator,
+  EntityNodeEvaluator,
 ])[] = [
   ['ArrayExpression', evaluateArrayExpression],
   ['BooleanLiteral', evaluateLiteralExpression],
@@ -281,26 +281,26 @@ const EVALUATOR_REGISTRATIONS: readonly (readonly [
 ];
 
 for (const [type, evaluator] of EVALUATOR_REGISTRATIONS) {
-  contourNodeEvaluators.set(type, evaluator);
+  entityNodeEvaluators.set(type, evaluator);
 }
 
-const hasExamples = (definition: ContourDefinition): boolean =>
+const hasExamples = (definition: EntityDefinition): boolean =>
   definition.options !== null &&
   findConfigProperty(definition.options, 'examples') !== null;
 
-const evaluateContourDefinition = (
-  definition: ContourDefinition,
-  env: ContourEvaluationEnvironment
+const evaluateEntityDefinition = (
+  definition: EntityDefinition,
+  env: EntityEvaluationEnvironment
 ): unknown => evaluateNode(definition.call, env);
 
-const buildContourExampleErrorDiagnostic = (
-  definition: ContourDefinition,
+const buildEntityExampleErrorDiagnostic = (
+  definition: EntityDefinition,
   error: unknown,
   sourceCode: string,
   filePath: string
 ): WardenDiagnostic | null => {
   if (
-    error instanceof UnsupportedContourEvaluationError ||
+    error instanceof UnsupportedEntityEvaluationError ||
     !hasExamples(definition) ||
     !(error instanceof Error)
   ) {
@@ -315,21 +315,21 @@ const buildContourExampleErrorDiagnostic = (
   );
 };
 
-const evaluateContourExamples = (
-  definition: ContourDefinition,
+const evaluateEntityExamples = (
+  definition: EntityDefinition,
   env: Map<string, unknown>,
   sourceCode: string,
   filePath: string
 ): WardenDiagnostic | null => {
   try {
-    const value = evaluateContourDefinition(definition, env);
+    const value = evaluateEntityDefinition(definition, env);
     if (definition.bindingName) {
       env.set(definition.bindingName, value);
     }
 
     return null;
   } catch (error) {
-    return buildContourExampleErrorDiagnostic(
+    return buildEntityExampleErrorDiagnostic(
       definition,
       error,
       sourceCode,
@@ -338,8 +338,8 @@ const evaluateContourExamples = (
   }
 };
 
-const collectContourExampleDiagnostics = (
-  definitions: readonly ContourDefinition[],
+const collectEntityExampleDiagnostics = (
+  definitions: readonly EntityDefinition[],
   sourceCode: string,
   filePath: string
 ): readonly WardenDiagnostic[] => {
@@ -347,7 +347,7 @@ const collectContourExampleDiagnostics = (
   const env = new Map<string, unknown>();
 
   for (const definition of definitions) {
-    const diagnostic = evaluateContourExamples(
+    const diagnostic = evaluateEntityExamples(
       definition,
       env,
       sourceCode,
@@ -361,7 +361,7 @@ const collectContourExampleDiagnostics = (
   return diagnostics;
 };
 
-const checkContourExamples = (
+const checkEntityExamples = (
   sourceCode: string,
   filePath: string
 ): readonly WardenDiagnostic[] => {
@@ -374,22 +374,22 @@ const checkContourExamples = (
     return [];
   }
 
-  return collectContourExampleDiagnostics(
-    findContourDefinitions(ast),
+  return collectEntityExampleDiagnostics(
+    findEntityDefinitions(ast),
     sourceCode,
     filePath
   );
 };
 
 /**
- * Checks that contour examples validate against their schema.
+ * Checks that entity examples validate against their schema.
  */
 export const exampleValid: WardenRule = {
   check(sourceCode: string, filePath: string): readonly WardenDiagnostic[] {
-    return checkContourExamples(sourceCode, filePath);
+    return checkEntityExamples(sourceCode, filePath);
   },
   description:
-    'Ensure every contour example validates against the declared contour schema.',
+    'Ensure every entity example validates against the declared entity schema.',
   name: 'example-valid',
   severity: 'error',
 };

package/src/rules/fires-declarations.ts

@@ -1,7 +1,7 @@
 /**
  * Validates that `ctx.fire()` calls match the declared `fires` array.
  *
- * Statically analyzes trail `blaze` functions to find `ctx.fire(signal, ...)`
+ * Statically analyzes trail `implementation` functions to find `ctx.fire(signal, ...)`
  * calls and compares locally-resolved `Signal` values against the `fires: [...]`
  * declaration in the trail config. Reports errors for undeclared fires, string
  * fire calls that no longer match the public runtime API, and warnings for
@@ -11,12 +11,12 @@
  * shape, same const-identifier resolution, same context-parameter handling.
  */
 
+import { buildSignalIdentifierResolver } from './source/signals.js';
 import {
-  buildSignalIdentifierResolver,
   deriveConstString,
   extractStringLiteral,
-  findBlazeBodies,
   findConfigProperty,
+  findImplementationBodies,
   findTrailDefinitions,
   getNodeBodyNode,
   getNodeBodyStatements,
@@ -34,8 +34,9 @@ import {
   offsetToLine,
   parse,
   walkScope,
-} from './ast.js';
-import type { AstNode, SignalIdentifierResolver } from './ast.js';
+} from '@ontrails/source';
+import type { AstNode } from '@ontrails/source';
+import type { SignalIdentifierResolver } from './source/signals.js';
 import { isTestFile } from './scan.js';
 import type { WardenDiagnostic, WardenRule } from './types.js';
 
@@ -164,14 +165,16 @@ const extractMemberPair = (
 };
 
 /**
- * Extract the second parameter node from a blaze function node.
+ * Extract the second parameter node from a implementation function node.
  *
  * Handles `(input, ctx) => ...`, `async (input, context) => ...`,
  * `function(input, ctx) { ... }`, and parameter-level destructuring
  * like `(input, { fire }) => ...`.
  */
-const extractContextParamNode = (blazeBody: AstNode): AstNode | null => {
-  const params = blazeBody['params'] as readonly AstNode[] | undefined;
+const extractContextParamNode = (
+  implementationBody: AstNode
+): AstNode | null => {
+  const params = implementationBody['params'] as readonly AstNode[] | undefined;
   if (!params || params.length < 2) {
     return null;
   }
@@ -212,7 +215,7 @@ const collectFireNamesFromPattern = (
 };
 
 /**
- * Extract the second parameter name from a blaze function node.
+ * Extract the second parameter name from a implementation function node.
  *
  * Returns null when the parameter is not a plain Identifier (e.g. when the
  * author destructures `{ fire }` in the parameter list). Parameter-level
@@ -222,8 +225,10 @@ const collectFireNamesFromPattern = (
  * (AssignmentPattern whose `.left` is the Identifier). Without this, valid
  * signatures would silently drop out of ctx-access analysis.
  */
-const extractContextParamName = (blazeBody: AstNode): string | null => {
-  const param = extractContextParamNode(blazeBody);
+const extractContextParamName = (
+  implementationBody: AstNode
+): string | null => {
+  const param = extractContextParamNode(implementationBody);
   if (!param) {
     return null;
   }
@@ -238,7 +243,7 @@ const extractContextParamName = (blazeBody: AstNode): string | null => {
  * Collect `fire` local names bound via parameter-level destructuring.
  *
  * Recognizes `(input, { fire }) => ...` and `(input, { fire: emit }) => ...`.
- * When the blaze author destructures in the parameter list, there is no
+ * When the implementation author destructures in the parameter list, there is no
  * enclosing `ctx` identifier to track — we seed the fire local set directly
  * from the ObjectPattern in `params[1]`.
  */
@@ -350,7 +355,7 @@ const extractFireCallId = (
 };
 
 /**
- * Walk a blaze body and collect local names bound to `ctx.fire` via destructure.
+ * Walk a implementation body and collect local names bound to `ctx.fire` via destructure.
  *
  * Recognizes:
  *   - `const { fire } = ctx;` → adds `fire`
@@ -382,8 +387,8 @@ const getCtxDestructurePattern = (
 
 /**
  * Collect `fire` local names destructured from ctx at the TOP LEVEL of the
- * blaze body. Destructures inside nested functions are intentionally ignored
- * to avoid leaking nested-scope bindings into the outer blaze scope — a
+ * implementation body. Destructures inside nested functions are intentionally ignored
+ * to avoid leaking nested-scope bindings into the outer implementation scope — a
  * `const { fire } = ctx` inside a nested helper should not cause an outer
  * bare `fire('x')` to be treated as a ctx-bound call.
  *
@@ -398,7 +403,7 @@ const getCtxDestructurePattern = (
  * class of false positives. The runtime + signal-id compose-check still
  * validate real undeclared fires.
  */
-/** Get the top-level statements of a blaze function's BlockStatement body. */
+/** Get the top-level statements of a implementation function's BlockStatement body. */
 const getTopLevelStatements = (body: AstNode): readonly AstNode[] => {
   const blockBody = getNodeBodyNode(body);
   if (!blockBody || blockBody.type !== 'BlockStatement') {
@@ -448,10 +453,10 @@ const collectDestructuredFireNames = (
 /**
  * Build the set of context parameter names to match against.
  *
- * Returns ONLY the actual second-parameter name from the blaze signature.
- * No seeded defaults: if the blaze has no second parameter, the returned set
+ * Returns ONLY the actual second-parameter name from the implementation signature.
+ * No seeded defaults: if the implementation has no second parameter, the returned set
  * is empty and no `ctx.fire(...)` / `context.fire(...)` calls are tracked
- * for that blaze. An unrelated closure-scoped `ctx` identifier is not the
+ * for that implementation. An unrelated closure-scoped `ctx` identifier is not the
  * trail context and must not be treated as one.
  */
 const buildCtxNames = (body: AstNode): ReadonlySet<string> => {
@@ -464,7 +469,7 @@ const buildCtxNames = (body: AstNode): ReadonlySet<string> => {
 };
 
 /**
- * Walk blaze bodies and collect all statically resolvable ctx.fire() signal IDs.
+ * Walk implementation bodies and collect all statically resolvable ctx.fire() signal IDs.
  *
  * Traversal uses `walkScope`, which stops at nested function boundaries
  * (FunctionDeclaration, FunctionExpression, ArrowFunctionExpression). This
@@ -473,7 +478,7 @@ const buildCtxNames = (body: AstNode): ReadonlySet<string> => {
  * destructured `fire` local:
  *
  * ```ts
- * blaze: async (_, ctx) => {
+ * implementation: async (_, ctx) => {
  *   const { fire } = ctx;
  *   function nested(fire) { fire(orderPlaced); } // ignored — shadowed
  *   function other(ctx)  { ctx.fire(orderPlaced); } // ignored — shadowed
@@ -558,7 +563,7 @@ const extractCalledFires = (
   const stringIds = new Set<string>();
   const merged = { hasUnresolved: false, ids, stringIds };
 
-  for (const body of findBlazeBodies(config)) {
+  for (const body of findImplementationBodies(config)) {
     mergeCalledFires(
       merged,
       extractCalledFiresFromBody(body, sourceCode, signalIds)