@ontrails/warden 1.0.0-beta.11 → 1.0.0-beta.13

package/src/rules/{follow-declarations.ts → cross-declarations.ts}

@@ -1,14 +1,14 @@
 /**
- * Validates that `ctx.follow()` calls match the declared `follow` array.
+ * Validates that `ctx.cross()` calls match the declared `crosses` array.
  *
- * Statically analyzes trail run functions to find `ctx.follow('trailId', ...)`
- * calls and compares them against the `follow: [...]` declaration in the trail
- * config. Reports errors for undeclared follows and warnings for unused ones.
+ * Statically analyzes trail `blaze` functions to find `ctx.cross('trailId', ...)`
+ * calls and compares them against the `crosses: [...]` declaration in the trail
+ * config. Reports errors for undeclared crossings and warnings for unused ones.
  */
 
 import {
   findConfigProperty,
-  findRunBodies,
+  findBlazeBodies,
   findTrailDefinitions,
   offsetToLine,
   parse,
@@ -87,18 +87,34 @@ const resolveIdentifierElement = (
   return resolveConstString(name, sourceCode);
 };
 
+/** Resolve an array element to a static trail ID when possible. */
+const resolveCrossElementId = (
+  element: AstNode,
+  sourceCode: string
+): string | null => {
+  if (isStringLiteral(element)) {
+    return getStringValue(element);
+  }
+
+  if (element.type === 'Identifier') {
+    return resolveIdentifierElement(element, sourceCode);
+  }
+
+  return null;
+};
+
 // ---------------------------------------------------------------------------
-// Declared follow extraction
+// Declared crossing extraction
 // ---------------------------------------------------------------------------
 
-/** Extract the ArrayExpression elements from a config's `follow` property. */
-const getFollowElements = (config: AstNode): readonly AstNode[] | null => {
-  const followProp = findConfigProperty(config, 'follow');
-  if (!followProp) {
+/** Extract the ArrayExpression elements from a config's `crosses` property. */
+const getCrossElements = (config: AstNode): readonly AstNode[] | null => {
+  const crossesProp = findConfigProperty(config, 'crosses');
+  if (!crossesProp) {
     return null;
   }
 
-  const arrayNode = followProp.value;
+  const arrayNode = crossesProp.value;
   if (!arrayNode || (arrayNode as AstNode).type !== 'ArrayExpression') {
     return null;
   }
@@ -115,33 +131,26 @@ const collectStringIds = (
   sourceCode: string
 ): Set<string> => {
   const ids = new Set<string>();
-  for (const el of elements) {
-    if (isStringLiteral(el)) {
-      const val = getStringValue(el);
-      if (val) {
-        ids.add(val);
-      }
-    } else if (el.type === 'Identifier') {
-      const resolved = resolveIdentifierElement(el, sourceCode);
-      if (resolved) {
-        ids.add(resolved);
-      }
+  for (const element of elements) {
+    const resolved = resolveCrossElementId(element, sourceCode);
+    if (resolved) {
+      ids.add(resolved);
     }
   }
   return ids;
 };
 
-/** Extract string literal elements from a `follow: [...]` array property. */
-const extractDeclaredFollows = (
+/** Extract string literal elements from a `crosses: [...]` array property. */
+const extractDeclaredCrosses = (
   config: AstNode,
   sourceCode: string
 ): ReadonlySet<string> => {
-  const elements = getFollowElements(config);
+  const elements = getCrossElements(config);
   return elements ? collectStringIds(elements, sourceCode) : new Set();
 };
 
 // ---------------------------------------------------------------------------
-// Called follow extraction — member expression helpers
+// Called crossing extraction — member expression helpers
 // ---------------------------------------------------------------------------
 
 const MEMBER_TYPES = new Set(['StaticMemberExpression', 'MemberExpression']);
@@ -173,7 +182,6 @@ const extractFirstStringArg = (node: AstNode): string | null => {
 
   const [firstArg] = args;
   if (!firstArg || !isStringLiteral(firstArg)) {
-    // Dynamic ID — cannot resolve statically
     return null;
   }
 
@@ -181,34 +189,34 @@ const extractFirstStringArg = (node: AstNode): string | null => {
 };
 
 /**
- * Extract the second parameter name from a run function node.
+ * Extract the second parameter name from a blaze function node.
  *
- * Handles `(input, ctx) => ...` and `async (input, context) => ...` and
+ * Handles `(input, ctx) => ...`, `async (input, context) => ...`, and
  * `function(input, ctx) { ... }` forms.
  */
-const extractContextParamName = (runBody: AstNode): string | null => {
-  const params = runBody['params'] as readonly AstNode[] | undefined;
+const extractContextParamName = (blazeBody: AstNode): string | null => {
+  const params = blazeBody['params'] as readonly AstNode[] | undefined;
   if (!params || params.length < 2) {
     return null;
   }
   return identifierName(params[1]);
 };
 
-/** Check if a callee is a member-style follow call: <ctxName>.follow(...). */
-const isMemberFollowCall = (
+/** Check if a callee is a member-style cross call: <ctxName>.cross(...). */
+const isMemberCrossCall = (
   callee: AstNode,
   ctxNames: ReadonlySet<string>
 ): boolean => {
   const pair = extractMemberPair(callee);
-  return !!pair && ctxNames.has(pair.objName) && pair.propName === 'follow';
+  return !!pair && ctxNames.has(pair.objName) && pair.propName === 'cross';
 };
 
 /**
- * Check if a node is a `<ctxName>.follow(...)` call and return the string trail ID.
+ * Check if a node is a `<ctxName>.cross(...)` call and return the string trail ID.
  *
- * Also matches bare `follow(...)` calls (destructured pattern).
+ * Also matches bare `cross(...)` calls from destructuring.
  */
-const extractFollowCallId = (
+const extractCrossCallId = (
   node: AstNode,
   ctxNames: ReadonlySet<string>
 ): string | null => {
@@ -221,12 +229,11 @@ const extractFollowCallId = (
     return null;
   }
 
-  if (isMemberFollowCall(callee, ctxNames)) {
+  if (isMemberCrossCall(callee, ctxNames)) {
     return extractFirstStringArg(node);
   }
 
-  // Match bare follow(...) — destructured pattern
-  if (identifierName(callee) === 'follow') {
+  if (identifierName(callee) === 'cross') {
     return extractFirstStringArg(node);
   }
 
@@ -243,15 +250,15 @@ const buildCtxNames = (body: AstNode): ReadonlySet<string> => {
   return ctxNames;
 };
 
-/** Walk run bodies and collect all statically resolvable ctx.follow() trail IDs. */
-const extractCalledFollows = (config: AstNode): ReadonlySet<string> => {
+/** Walk blaze bodies and collect all statically resolvable ctx.cross() trail IDs. */
+const extractCalledCrosses = (config: AstNode): ReadonlySet<string> => {
   const ids = new Set<string>();
 
-  for (const body of findRunBodies(config)) {
+  for (const body of findBlazeBodies(config)) {
     const ctxNames = buildCtxNames(body);
 
     walk(body, (node) => {
-      const id = extractFollowCallId(node, ctxNames);
+      const id = extractCrossCallId(node, ctxNames);
       if (id) {
         ids.add(id);
       }
@@ -267,27 +274,27 @@ const extractCalledFollows = (config: AstNode): ReadonlySet<string> => {
 
 const buildUndeclaredDiagnostic = (
   trailId: string,
-  followId: string,
+  crossedId: string,
   filePath: string,
   line: number
 ): WardenDiagnostic => ({
   filePath,
   line,
-  message: `Trail "${trailId}": ctx.follow('${followId}') called but '${followId}' is not declared in follow`,
-  rule: 'follow-declarations',
+  message: `Trail "${trailId}": ctx.cross('${crossedId}') called but '${crossedId}' is not declared in crosses`,
+  rule: 'cross-declarations',
   severity: 'error',
 });
 
 const buildUnusedDiagnostic = (
   trailId: string,
-  followId: string,
+  crossedId: string,
   filePath: string,
   line: number
 ): WardenDiagnostic => ({
   filePath,
   line,
-  message: `Trail "${trailId}": '${followId}' declared in follow but ctx.follow('${followId}') never called`,
-  rule: 'follow-declarations',
+  message: `Trail "${trailId}": '${crossedId}' declared in crosses but ctx.cross('${crossedId}') never called`,
+  rule: 'cross-declarations',
   severity: 'warn',
 });
 
@@ -333,8 +340,8 @@ const checkTrailDefinition = (
   sourceCode: string,
   diagnostics: WardenDiagnostic[]
 ): void => {
-  const declared = extractDeclaredFollows(def.config, sourceCode);
-  const called = extractCalledFollows(def.config);
+  const declared = extractDeclaredCrosses(def.config, sourceCode);
+  const called = extractCalledCrosses(def.config);
 
   if (declared.size === 0 && called.size === 0) {
     return;
@@ -352,9 +359,9 @@ const checkTrailDefinition = (
 // ---------------------------------------------------------------------------
 
 /**
- * Validates that `ctx.follow()` calls align with declared `follow` arrays.
+ * Validates that `ctx.cross()` calls align with declared `crosses` arrays.
  */
-export const followDeclarations: WardenRule = {
+export const crossDeclarations: WardenRule = {
   check(sourceCode: string, filePath: string): readonly WardenDiagnostic[] {
     if (isTestFile(filePath)) {
       return [];
@@ -374,7 +381,7 @@ export const followDeclarations: WardenRule = {
     return diagnostics;
   },
   description:
-    'Ensure ctx.follow() calls match the declared follow array in trail definitions.',
-  name: 'follow-declarations',
+    'Ensure ctx.cross() calls match the declared crosses array in trail definitions.',
+  name: 'cross-declarations',
   severity: 'error',
 };

package/src/rules/implementation-returns-result.ts

@@ -1,13 +1,13 @@
 /**
  * Finds implementations that return raw values instead of `Result`.
  *
- * Uses AST parsing to find `run:` bodies and check that
- * every return statement returns Result.ok(), Result.err(), ctx.follow(),
+ * Uses AST parsing to find `blaze:` bodies and check that
+ * every return statement returns Result.ok(), Result.err(), ctx.cross(),
  * or a tracked Result-typed variable.
  */
 
 import {
-  findRunBodies,
+  findBlazeBodies,
   findTrailDefinitions,
   offsetToLine,
   parse,
@@ -60,10 +60,10 @@ const isResultMemberCall = (callee: AstNode): boolean => {
   if (objName === 'Result' && (propName === 'ok' || propName === 'err')) {
     return true;
   }
-  if (objName === 'ctx' && propName === 'follow') {
+  if (objName === 'ctx' && propName === 'cross') {
     return true;
   }
-  return propName === 'run';
+  return propName === 'blaze';
 };
 
 // ---------------------------------------------------------------------------
@@ -362,7 +362,7 @@ const checkAllDefinitions = (
 
   for (const def of findTrailDefinitions(ast)) {
     const info = { id: def.id, label: 'Trail' };
-    for (const implValue of findRunBodies(def.config as AstNode)) {
+    for (const implValue of findBlazeBodies(def.config as AstNode)) {
       checkImplementation(
         implValue,
         info,

package/src/rules/index.ts

@@ -1,5 +1,5 @@
-import { contextNoSurfaceTypes } from './context-no-surface-types.js';
-import { followDeclarations } from './follow-declarations.js';
+import { contextNoTrailheadTypes } from './context-no-trailhead-types.js';
+import { crossDeclarations } from './cross-declarations.js';
 import { implementationReturnsResult } from './implementation-returns-result.js';
 import { noDirectImplInRoute } from './no-direct-impl-in-route.js';
 import { noDirectImplementationCall } from './no-direct-implementation-call.js';
@@ -7,8 +7,8 @@ import { noSyncResultAssumption } from './no-sync-result-assumption.js';
 import { noThrowInDetourTarget } from './no-throw-in-detour-target.js';
 import { noThrowInImplementation } from './no-throw-in-implementation.js';
 import { preferSchemaInference } from './prefer-schema-inference.js';
-import { serviceDeclarations } from './service-declarations.js';
-import { serviceExists } from './service-exists.js';
+import { provisionDeclarations } from './provision-declarations.js';
+import { provisionExists } from './provision-exists.js';
 import type { WardenRule } from './types.js';
 import { validDescribeRefs } from './valid-describe-refs.js';
 import { validDetourRefs } from './valid-detour-refs.js';
@@ -22,8 +22,8 @@ export type {
 } from './types.js';
 
 export { noThrowInImplementation } from './no-throw-in-implementation.js';
-export { contextNoSurfaceTypes } from './context-no-surface-types.js';
-export { followDeclarations } from './follow-declarations.js';
+export { contextNoTrailheadTypes } from './context-no-trailhead-types.js';
+export { crossDeclarations } from './cross-declarations.js';
 export { validDetourRefs } from './valid-detour-refs.js';
 export { noDirectImplInRoute } from './no-direct-impl-in-route.js';
 export { noDirectImplementationCall } from './no-direct-implementation-call.js';
@@ -31,8 +31,8 @@ export { noSyncResultAssumption } from './no-sync-result-assumption.js';
 export { implementationReturnsResult } from './implementation-returns-result.js';
 export { noThrowInDetourTarget } from './no-throw-in-detour-target.js';
 export { preferSchemaInference } from './prefer-schema-inference.js';
-export { serviceDeclarations } from './service-declarations.js';
-export { serviceExists } from './service-exists.js';
+export { provisionDeclarations } from './provision-declarations.js';
+export { provisionExists } from './provision-exists.js';
 export { validDescribeRefs } from './valid-describe-refs.js';
 
 /** All built-in warden rules, keyed by rule name. */
@@ -41,10 +41,10 @@ export const wardenRules: ReadonlyMap<string, WardenRule> = new Map<
   WardenRule
 >([
   [noThrowInImplementation.name, noThrowInImplementation],
-  [contextNoSurfaceTypes.name, contextNoSurfaceTypes],
-  [followDeclarations.name, followDeclarations],
-  [serviceDeclarations.name, serviceDeclarations],
-  [serviceExists.name, serviceExists],
+  [contextNoTrailheadTypes.name, contextNoTrailheadTypes],
+  [crossDeclarations.name, crossDeclarations],
+  [provisionDeclarations.name, provisionDeclarations],
+  [provisionExists.name, provisionExists],
   [preferSchemaInference.name, preferSchemaInference],
   [validDescribeRefs.name, validDescribeRefs],
   [validDetourRefs.name, validDetourRefs],

package/src/rules/no-direct-impl-in-route.ts

@@ -1,15 +1,15 @@
 /**
- * Detects trail implementations with `follow` that call `.run()` directly.
+ * Detects trail implementations with `crosses` that call `.blaze()` directly.
  *
- * Uses AST parsing to find trail definitions that declare `follow` and check for
- * `.run()` call expressions in their bodies.
+ * Uses AST parsing to find trail definitions that declare `crosses` and check for
+ * `.blaze()` call expressions in their bodies.
  */
 
 import {
   findConfigProperty,
-  findRunBodies,
+  findBlazeBodies,
   findTrailDefinitions,
-  isRunCall,
+  isBlazeCall,
   offsetToLine,
   parse,
   walk,
@@ -23,20 +23,20 @@ interface AstNode {
   readonly [key: string]: unknown;
 }
 
-const findImplCallsInTrailWithFollow = (
+const findImplCallsInTrailWithCrosses = (
   def: { readonly config: AstNode },
   filePath: string,
   sourceCode: string,
   diagnostics: WardenDiagnostic[]
 ): void => {
-  for (const body of findRunBodies(def.config as AstNode)) {
+  for (const body of findBlazeBodies(def.config as AstNode)) {
     walk(body, (node) => {
-      if (isRunCall(node as AstNode)) {
+      if (isBlazeCall(node as AstNode)) {
         diagnostics.push({
           filePath,
           line: offsetToLine(sourceCode, node.start),
           message:
-            'Use ctx.follow("trailId", input) instead of direct .run() calls. ctx.follow() validates input and propagates tracing.',
+            'Use ctx.cross("trailId", input) instead of direct .blaze() calls. ctx.cross() validates input and propagates tracing.',
           rule: 'no-direct-impl-in-route',
           severity: 'warn',
         });
@@ -45,11 +45,11 @@ const findImplCallsInTrailWithFollow = (
   }
 };
 
-const hasFollowProperty = (config: AstNode): boolean =>
-  findConfigProperty(config as AstNode, 'follow') !== null;
+const hasCrossesProperty = (config: AstNode): boolean =>
+  findConfigProperty(config as AstNode, 'crosses') !== null;
 
 /**
- * Detects trails with `follow` that call another trail's `.run()` directly.
+ * Detects trails with `crosses` that call another trail's `.blaze()` directly.
  */
 export const noDirectImplInRoute: WardenRule = {
   check(sourceCode: string, filePath: string): readonly WardenDiagnostic[] {
@@ -63,18 +63,18 @@ export const noDirectImplInRoute: WardenRule = {
     }
 
     const diagnostics: WardenDiagnostic[] = [];
-    const followDefs = findTrailDefinitions(ast as AstNode).filter((d) =>
-      hasFollowProperty(d.config as AstNode)
+    const crossDefs = findTrailDefinitions(ast as AstNode).filter((d) =>
+      hasCrossesProperty(d.config as AstNode)
     );
 
-    for (const def of followDefs) {
-      findImplCallsInTrailWithFollow(def, filePath, sourceCode, diagnostics);
+    for (const def of crossDefs) {
+      findImplCallsInTrailWithCrosses(def, filePath, sourceCode, diagnostics);
     }
 
     return diagnostics;
   },
   description:
-    'Prefer ctx.follow() over direct .run() calls in trail bodies with follow.',
+    'Prefer ctx.cross() over direct .blaze() calls in trail bodies with crossings.',
   name: 'no-direct-impl-in-route',
 
   severity: 'warn',

package/src/rules/no-direct-implementation-call.ts

@@ -1,16 +1,16 @@
 /**
- * Flags direct `.run()` calls in application code.
+ * Flags direct `.blaze()` calls in application code.
  *
- * Uses AST parsing to find `.run()` call expressions,
+ * Uses AST parsing to find `.blaze()` call expressions,
  * ignoring occurrences in strings and comments.
  */
 
-import { isRunCall, offsetToLine, parse, walk } from './ast.js';
+import { isBlazeCall, offsetToLine, parse, walk } from './ast.js';
 import { isFrameworkInternalFile, isTestFile } from './scan.js';
 import type { WardenDiagnostic, WardenRule } from './types.js';
 
 /**
- * Flags direct `.run()` calls in application code.
+ * Flags direct `.blaze()` calls in application code.
  */
 export const noDirectImplementationCall: WardenRule = {
   check(sourceCode: string, filePath: string): readonly WardenDiagnostic[] {
@@ -26,12 +26,12 @@ export const noDirectImplementationCall: WardenRule = {
     const diagnostics: WardenDiagnostic[] = [];
 
     walk(ast, (node) => {
-      if (isRunCall(node)) {
+      if (isBlazeCall(node)) {
         diagnostics.push({
           filePath,
           line: offsetToLine(sourceCode, node.start),
           message:
-            'Use ctx.follow("trailId", input) instead of direct .run() calls. Direct implementation access bypasses validation, tracing, and layers.',
+            'Use ctx.cross("trailId", input) instead of direct .blaze() calls. Direct implementation access bypasses validation, tracing, and gates.',
           rule: 'no-direct-implementation-call',
           severity: 'warn',
         });
@@ -41,7 +41,7 @@ export const noDirectImplementationCall: WardenRule = {
     return diagnostics;
   },
   description:
-    'Disallow direct .run() calls in application code. Use ctx.follow() instead.',
+    'Disallow direct .blaze() calls in application code. Use ctx.cross() instead.',
   name: 'no-direct-implementation-call',
   severity: 'warn',
 };

package/src/rules/no-sync-result-assumption.ts

@@ -7,10 +7,10 @@ import {
 
 const RESULT_ACCESS_PATTERN =
   /\.(?:isOk|isErr|match|map)\s*\(|\.(?:value|error)\b/;
-const IMPLEMENTATION_CALL_PATTERN = /\.run\s*\(/;
+const IMPLEMENTATION_CALL_PATTERN = /\.blaze\s*\(/;
 
 const isAwaitedImplementationCall = (line: string): boolean => {
-  const callIndex = line.indexOf('.run(');
+  const callIndex = line.indexOf('.blaze(');
   if (callIndex === -1) {
     return false;
   }
@@ -39,7 +39,7 @@ interface PendingCall {
 }
 
 const MISSING_AWAIT_MESSAGE =
-  'Missing await: .run() returns Promise<Result> after normalization. Use `const result = await trail.run(input, ctx)`.';
+  'Missing await: .blaze() returns Promise<Result> after normalization. Use `const result = await trail.blaze(input, ctx)`.';
 
 const createMissingAwaitDiagnostic = (
   filePath: string,
@@ -140,7 +140,7 @@ const scanSourceCode = (
 };
 
 /**
- * Flags code that assumes `.run()` returns a synchronous result.
+ * Flags code that assumes `.blaze()` returns a synchronous result.
  */
 export const noSyncResultAssumption: WardenRule = {
   check(sourceCode: string, filePath: string): readonly WardenDiagnostic[] {
@@ -150,7 +150,7 @@ export const noSyncResultAssumption: WardenRule = {
     return scanSourceCode(stripQuotedContent(sourceCode), filePath);
   },
   description:
-    'Disallow treating .run() as synchronous after normalization. Always await the returned Promise<Result>.',
+    'Disallow treating .blaze() as synchronous after normalization. Always await the returned Promise<Result>.',
   name: 'no-sync-result-assumption',
   severity: 'error',
 };

package/src/rules/no-throw-in-detour-target.ts

@@ -6,7 +6,7 @@
  */
 
 import {
-  findRunBodies,
+  findBlazeBodies,
   findTrailDefinitions,
   offsetToLine,
   parse,
@@ -66,7 +66,7 @@ const findThrowsInTargetedTrails = (
       continue;
     }
 
-    for (const body of findRunBodies(def.config as AstNode)) {
+    for (const body of findBlazeBodies(def.config as AstNode)) {
       walk(body, (node) => {
         if (node.type === 'ThrowStatement') {
           diagnostics.push({

package/src/rules/no-throw-in-implementation.ts

@@ -1,11 +1,11 @@
 /**
- * Finds `throw` statements inside `run:` function bodies.
+ * Finds `throw` statements inside `blaze:` function bodies.
  *
  * Uses AST parsing for accurate detection — no false positives from
  * throw in comments, strings, or nested non-implementation functions.
  */
 
-import { findRunBodies, offsetToLine, parse, walk } from './ast.js';
+import { findBlazeBodies, offsetToLine, parse, walk } from './ast.js';
 import type { WardenDiagnostic, WardenRule } from './types.js';
 
 export const noThrowInImplementation: WardenRule = {
@@ -17,7 +17,7 @@ export const noThrowInImplementation: WardenRule = {
 
     const diagnostics: WardenDiagnostic[] = [];
 
-    for (const body of findRunBodies(ast)) {
+    for (const body of findBlazeBodies(ast)) {
       walk(body, (node) => {
         if (node.type === 'ThrowStatement') {
           diagnostics.push({