@ontrails/warden 1.0.0-beta.0 → 1.0.0-beta.10

package/src/rules/follow-declarations.ts

@@ -0,0 +1,380 @@
+/**
+ * Validates that `ctx.follow()` calls match the declared `follow` 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.
+ */
+
+import {
+  findConfigProperty,
+  findRunBodies,
+  findTrailDefinitions,
+  offsetToLine,
+  parse,
+  walk,
+} from './ast.js';
+import type { AstNode } from './ast.js';
+import { isTestFile } from './scan.js';
+import type { WardenDiagnostic, WardenRule } from './types.js';
+
+// ---------------------------------------------------------------------------
+// Shared identifier helpers
+// ---------------------------------------------------------------------------
+
+/** Get the name of an Identifier node, or null. */
+const identifierName = (node: AstNode | undefined): string | null => {
+  if (node?.type !== 'Identifier') {
+    return null;
+  }
+  return (node as unknown as { name?: string }).name ?? null;
+};
+
+// ---------------------------------------------------------------------------
+// String literal helpers
+// ---------------------------------------------------------------------------
+
+/** Check if a node is a string literal (covers `StringLiteral` and `Literal` with string value). */
+const isStringLiteral = (node: AstNode): boolean => {
+  if (node.type === 'StringLiteral') {
+    return true;
+  }
+  if (node.type === 'Literal') {
+    return typeof (node as unknown as { value?: unknown }).value === 'string';
+  }
+  return false;
+};
+
+/** Extract the string value from a string literal node. */
+const getStringValue = (node: AstNode): string | null => {
+  const val = (node as unknown as { value?: unknown }).value;
+  return typeof val === 'string' ? val : null;
+};
+
+// ---------------------------------------------------------------------------
+// Const identifier resolution
+// ---------------------------------------------------------------------------
+
+/**
+ * Best-effort resolution of `const NAME = 'value'` declarations via regex.
+ *
+ * Returns the string value if a simple `const <name> = '...'` or `"..."` is
+ * found in the source. Returns null for anything more complex.
+ */
+const resolveConstString = (
+  name: string,
+  sourceCode: string
+): string | null => {
+  const pattern = new RegExp(
+    `const\\s+${name}\\s*=\\s*(?:'([^']*)'|"([^"]*)")`
+  );
+  const match = pattern.exec(sourceCode);
+  if (!match) {
+    return null;
+  }
+  return match[1] ?? match[2] ?? null;
+};
+
+/** Try to resolve an Identifier element to a string via const declaration. */
+const resolveIdentifierElement = (
+  el: AstNode,
+  sourceCode: string
+): string | null => {
+  const name = identifierName(el);
+  if (!name) {
+    return null;
+  }
+  return resolveConstString(name, sourceCode);
+};
+
+// ---------------------------------------------------------------------------
+// Declared follow 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) {
+    return null;
+  }
+
+  const arrayNode = followProp.value;
+  if (!arrayNode || (arrayNode as AstNode).type !== 'ArrayExpression') {
+    return null;
+  }
+
+  const elements = (arrayNode as AstNode)['elements'] as
+    | readonly AstNode[]
+    | undefined;
+  return elements ?? null;
+};
+
+/** Collect string IDs from array elements, resolving identifiers when possible. */
+const collectStringIds = (
+  elements: readonly AstNode[],
+  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);
+      }
+    }
+  }
+  return ids;
+};
+
+/** Extract string literal elements from a `follow: [...]` array property. */
+const extractDeclaredFollows = (
+  config: AstNode,
+  sourceCode: string
+): ReadonlySet<string> => {
+  const elements = getFollowElements(config);
+  return elements ? collectStringIds(elements, sourceCode) : new Set();
+};
+
+// ---------------------------------------------------------------------------
+// Called follow extraction — member expression helpers
+// ---------------------------------------------------------------------------
+
+const MEMBER_TYPES = new Set(['StaticMemberExpression', 'MemberExpression']);
+
+/** Extract object and property Identifier names from a MemberExpression. */
+const extractMemberPair = (
+  callee: AstNode
+): { objName: string; propName: string } | null => {
+  if (!MEMBER_TYPES.has(callee.type)) {
+    return null;
+  }
+
+  const objName = identifierName(
+    (callee as unknown as { object?: AstNode }).object
+  );
+  const propName = identifierName(
+    (callee as unknown as { property?: AstNode }).property
+  );
+
+  return objName && propName ? { objName, propName } : null;
+};
+
+/** Extract the first argument string from a CallExpression's arguments list. */
+const extractFirstStringArg = (node: AstNode): string | null => {
+  const args = node['arguments'] as readonly AstNode[] | undefined;
+  if (!args || args.length === 0) {
+    return null;
+  }
+
+  const [firstArg] = args;
+  if (!firstArg || !isStringLiteral(firstArg)) {
+    // Dynamic ID — cannot resolve statically
+    return null;
+  }
+
+  return getStringValue(firstArg);
+};
+
+/**
+ * Extract the second parameter name from a run function node.
+ *
+ * Handles `(input, ctx) => ...` and `async (input, context) => ...` and
+ * `function(input, ctx) { ... }` forms.
+ */
+const extractContextParamName = (runBody: AstNode): string | null => {
+  const params = runBody['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 = (
+  callee: AstNode,
+  ctxNames: ReadonlySet<string>
+): boolean => {
+  const pair = extractMemberPair(callee);
+  return !!pair && ctxNames.has(pair.objName) && pair.propName === 'follow';
+};
+
+/**
+ * Check if a node is a `<ctxName>.follow(...)` call and return the string trail ID.
+ *
+ * Also matches bare `follow(...)` calls (destructured pattern).
+ */
+const extractFollowCallId = (
+  node: AstNode,
+  ctxNames: ReadonlySet<string>
+): string | null => {
+  if (node.type !== 'CallExpression') {
+    return null;
+  }
+
+  const callee = node['callee'] as AstNode | undefined;
+  if (!callee) {
+    return null;
+  }
+
+  if (isMemberFollowCall(callee, ctxNames)) {
+    return extractFirstStringArg(node);
+  }
+
+  // Match bare follow(...) — destructured pattern
+  if (identifierName(callee) === 'follow') {
+    return extractFirstStringArg(node);
+  }
+
+  return null;
+};
+
+/** Build the set of context parameter names to match against. */
+const buildCtxNames = (body: AstNode): ReadonlySet<string> => {
+  const ctxNames = new Set(['ctx', 'context']);
+  const paramName = extractContextParamName(body);
+  if (paramName) {
+    ctxNames.add(paramName);
+  }
+  return ctxNames;
+};
+
+/** Walk run bodies and collect all statically resolvable ctx.follow() trail IDs. */
+const extractCalledFollows = (config: AstNode): ReadonlySet<string> => {
+  const ids = new Set<string>();
+
+  for (const body of findRunBodies(config)) {
+    const ctxNames = buildCtxNames(body);
+
+    walk(body, (node) => {
+      const id = extractFollowCallId(node, ctxNames);
+      if (id) {
+        ids.add(id);
+      }
+    });
+  }
+
+  return ids;
+};
+
+// ---------------------------------------------------------------------------
+// Diagnostic builders
+// ---------------------------------------------------------------------------
+
+const buildUndeclaredDiagnostic = (
+  trailId: string,
+  followId: 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',
+  severity: 'error',
+});
+
+const buildUnusedDiagnostic = (
+  trailId: string,
+  followId: string,
+  filePath: string,
+  line: number
+): WardenDiagnostic => ({
+  filePath,
+  line,
+  message: `Trail "${trailId}": '${followId}' declared in follow but ctx.follow('${followId}') never called`,
+  rule: 'follow-declarations',
+  severity: 'warn',
+});
+
+// ---------------------------------------------------------------------------
+// Comparison
+// ---------------------------------------------------------------------------
+
+/** Emit error for each called ID not present in declared set. */
+const reportUndeclared = (
+  called: ReadonlySet<string>,
+  declared: ReadonlySet<string>,
+  ctx: { trailId: string; filePath: string; line: number },
+  diagnostics: WardenDiagnostic[]
+): void => {
+  for (const id of called) {
+    if (!declared.has(id)) {
+      diagnostics.push(
+        buildUndeclaredDiagnostic(ctx.trailId, id, ctx.filePath, ctx.line)
+      );
+    }
+  }
+};
+
+/** Emit warning for each declared ID not present in called set. */
+const reportUnused = (
+  declared: ReadonlySet<string>,
+  called: ReadonlySet<string>,
+  ctx: { trailId: string; filePath: string; line: number },
+  diagnostics: WardenDiagnostic[]
+): void => {
+  for (const id of declared) {
+    if (!called.has(id)) {
+      diagnostics.push(
+        buildUnusedDiagnostic(ctx.trailId, id, ctx.filePath, ctx.line)
+      );
+    }
+  }
+};
+
+const checkTrailDefinition = (
+  def: { id: string; config: AstNode; start: number },
+  filePath: string,
+  sourceCode: string,
+  diagnostics: WardenDiagnostic[]
+): void => {
+  const declared = extractDeclaredFollows(def.config, sourceCode);
+  const called = extractCalledFollows(def.config);
+
+  if (declared.size === 0 && called.size === 0) {
+    return;
+  }
+
+  const line = offsetToLine(sourceCode, def.start);
+  const ctx = { filePath, line, trailId: def.id };
+
+  reportUndeclared(called, declared, ctx, diagnostics);
+  reportUnused(declared, called, ctx, diagnostics);
+};
+
+// ---------------------------------------------------------------------------
+// Rule
+// ---------------------------------------------------------------------------
+
+/**
+ * Validates that `ctx.follow()` calls align with declared `follow` arrays.
+ */
+export const followDeclarations: WardenRule = {
+  check(sourceCode: string, filePath: string): readonly WardenDiagnostic[] {
+    if (isTestFile(filePath)) {
+      return [];
+    }
+
+    const ast = parse(filePath, sourceCode);
+    if (!ast) {
+      return [];
+    }
+
+    const diagnostics: WardenDiagnostic[] = [];
+
+    for (const def of findTrailDefinitions(ast)) {
+      checkTrailDefinition(def, filePath, sourceCode, diagnostics);
+    }
+
+    return diagnostics;
+  },
+  description:
+    'Ensure ctx.follow() calls match the declared follow array in trail definitions.',
+  name: 'follow-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 `implementation:` bodies and check that
+ * Uses AST parsing to find `run:` bodies and check that
  * every return statement returns Result.ok(), Result.err(), ctx.follow(),
  * or a tracked Result-typed variable.
  */
 
 import {
-  findImplementationBodies,
+  findRunBodies,
   findTrailDefinitions,
   offsetToLine,
   parse,
@@ -63,7 +63,7 @@ const isResultMemberCall = (callee: AstNode): boolean => {
   if (objName === 'ctx' && propName === 'follow') {
     return true;
   }
-  return propName === 'implementation';
+  return propName === 'run';
 };
 
 // ---------------------------------------------------------------------------
@@ -158,6 +158,63 @@ const trackResultVariable = (node: AstNode, resultVars: Set<string>): void => {
   }
 };
 
+// ---------------------------------------------------------------------------
+// Shallow walk (stops at nested function boundaries)
+// ---------------------------------------------------------------------------
+
+const FUNCTION_BOUNDARY_TYPES = new Set([
+  'ArrowFunctionExpression',
+  'FunctionExpression',
+  'FunctionDeclaration',
+]);
+
+/** Check if a value is a function-boundary AST node that should not be recursed into. */
+const isFunctionBoundary = (val: unknown): boolean =>
+  !!val &&
+  typeof val === 'object' &&
+  FUNCTION_BOUNDARY_TYPES.has((val as AstNode).type);
+
+/** Recurse into a single AST property value, skipping function boundaries. */
+const visitValue = (
+  val: unknown,
+  visit: (node: AstNode) => void,
+  recurse: (node: unknown, visit: (node: AstNode) => void) => void
+): void => {
+  if (Array.isArray(val)) {
+    for (const item of val) {
+      if (!isFunctionBoundary(item)) {
+        recurse(item, visit);
+      }
+    }
+  } else if (
+    val &&
+    typeof val === 'object' &&
+    (val as AstNode).type &&
+    !isFunctionBoundary(val)
+  ) {
+    recurse(val, visit);
+  }
+};
+
+/**
+ * Walk an AST node tree without recursing into nested function bodies.
+ *
+ * This ensures that return statements inside `.map()`, `.filter()`, `.then()`
+ * callbacks etc. are not mistakenly checked as implementation-level returns.
+ */
+const walkShallow = (node: unknown, visit: (node: AstNode) => void): void => {
+  if (!node || typeof node !== 'object') {
+    return;
+  }
+  const n = node as AstNode;
+  if (n.type) {
+    visit(n);
+  }
+  for (const val of Object.values(n)) {
+    visitValue(val, visit, walkShallow);
+  }
+};
+
 // ---------------------------------------------------------------------------
 // Return statement checking
 // ---------------------------------------------------------------------------
@@ -173,7 +230,7 @@ const checkReturnStatements = (
 ): void => {
   const resultVars = new Set<string>();
 
-  walk(blockBody, (node) => {
+  walkShallow(blockBody, (node) => {
     if (node.type === 'VariableDeclarator') {
       trackResultVariable(node, resultVars);
     }
@@ -304,8 +361,8 @@ const checkAllDefinitions = (
   const helperNames = collectResultHelperNames(ast, sourceCode);
 
   for (const def of findTrailDefinitions(ast)) {
-    const info = { id: def.id, label: def.kind === 'hike' ? 'Hike' : 'Trail' };
-    for (const implValue of findImplementationBodies(def.config as AstNode)) {
+    const info = { id: def.id, label: 'Trail' };
+    for (const implValue of findRunBodies(def.config as AstNode)) {
       checkImplementation(
         implValue,
         info,

package/src/rules/index.ts

@@ -1,4 +1,5 @@
 import { contextNoSurfaceTypes } from './context-no-surface-types.js';
+import { followDeclarations } from './follow-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';
@@ -20,6 +21,7 @@ export type {
 
 export { noThrowInImplementation } from './no-throw-in-implementation.js';
 export { contextNoSurfaceTypes } from './context-no-surface-types.js';
+export { followDeclarations } from './follow-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';
@@ -29,20 +31,14 @@ export { noThrowInDetourTarget } from './no-throw-in-detour-target.js';
 export { preferSchemaInference } from './prefer-schema-inference.js';
 export { validDescribeRefs } from './valid-describe-refs.js';
 
-/**
- * All built-in warden rules, keyed by rule name.
- *
- * Rules that duplicate validateTopo checks (follows-trails-exist,
- * no-recursive-follows, event-origins-exist, examples-match-schema,
- * require-output-schema) and follows-matches-calls (now covered by
- * testExamples follows coverage) have been removed.
- */
+/** All built-in warden rules, keyed by rule name. */
 export const wardenRules: ReadonlyMap<string, WardenRule> = new Map<
   string,
   WardenRule
 >([
   [noThrowInImplementation.name, noThrowInImplementation],
   [contextNoSurfaceTypes.name, contextNoSurfaceTypes],
+  [followDeclarations.name, followDeclarations],
   [preferSchemaInference.name, preferSchemaInference],
   [validDescribeRefs.name, validDescribeRefs],
   [validDetourRefs.name, validDetourRefs],

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

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

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

@@ -1,16 +1,16 @@
 /**
- * Flags direct `.implementation()` calls in application code.
+ * Flags direct `.run()` calls in application code.
  *
- * Uses AST parsing to find `.implementation()` call expressions,
+ * Uses AST parsing to find `.run()` call expressions,
  * ignoring occurrences in strings and comments.
  */
 
-import { isImplementationCall, offsetToLine, parse, walk } from './ast.js';
+import { isRunCall, offsetToLine, parse, walk } from './ast.js';
 import { isFrameworkInternalFile, isTestFile } from './scan.js';
 import type { WardenDiagnostic, WardenRule } from './types.js';
 
 /**
- * Flags direct `.implementation()` calls in application code.
+ * Flags direct `.run()` 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 (isImplementationCall(node)) {
+      if (isRunCall(node)) {
         diagnostics.push({
           filePath,
           line: offsetToLine(sourceCode, node.start),
           message:
-            'Use ctx.follow("trailId", input) instead of direct .implementation() calls. Direct implementation access bypasses validation, tracing, and layers.',
+            'Use ctx.follow("trailId", input) instead of direct .run() calls. Direct implementation access bypasses validation, tracing, and layers.',
           rule: 'no-direct-implementation-call',
           severity: 'warn',
         });
@@ -41,7 +41,7 @@ export const noDirectImplementationCall: WardenRule = {
     return diagnostics;
   },
   description:
-    'Disallow direct .implementation() calls in application code. Use ctx.follow() instead.',
+    'Disallow direct .run() calls in application code. Use ctx.follow() 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 = /\.implementation\s*\(/;
+const IMPLEMENTATION_CALL_PATTERN = /\.run\s*\(/;
 
 const isAwaitedImplementationCall = (line: string): boolean => {
-  const callIndex = line.indexOf('.implementation(');
+  const callIndex = line.indexOf('.run(');
   if (callIndex === -1) {
     return false;
   }
@@ -39,7 +39,7 @@ interface PendingCall {
 }
 
 const MISSING_AWAIT_MESSAGE =
-  'Missing await: .implementation() returns Promise<Result> after normalization. Use `const result = await trail.implementation(input, ctx)`.';
+  'Missing await: .run() returns Promise<Result> after normalization. Use `const result = await trail.run(input, ctx)`.';
 
 const createMissingAwaitDiagnostic = (
   filePath: string,
@@ -140,7 +140,7 @@ const scanSourceCode = (
 };
 
 /**
- * Flags code that assumes `.implementation()` returns a synchronous result.
+ * Flags code that assumes `.run()` 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 .implementation() as synchronous after normalization. Always await the returned Promise<Result>.',
+    'Disallow treating .run() as synchronous after normalization. Always await the returned Promise<Result>.',
   name: 'no-sync-result-assumption',
   severity: 'error',
 };