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

package/src/__tests__/no-throw-in-detour-target.test.ts

@@ -9,11 +9,11 @@ describe('no-throw-in-detour-target', () => {
     const code = `
 trail("entity.show", {
   detours: { NotFoundError: ["entity.fallback"] },
-  implementation: async (input, ctx) => Result.ok({ id: "123" })
+  run: async (input, ctx) => Result.ok({ id: "123" })
 })
 
 trail("entity.fallback", {
-  implementation: async (input, ctx) => {
+  run: async (input, ctx) => {
     throw new Error("boom");
   }
 })`;
@@ -28,7 +28,7 @@ trail("entity.fallback", {
   test('allows throw in implementations that are not detour targets', () => {
     const code = `
 trail("entity.show", {
-  implementation: async (input, ctx) => {
+  run: async (input, ctx) => {
     throw new Error("boom");
   }
 })`;
@@ -42,11 +42,11 @@ trail("entity.show", {
     const code = `
 trail("entity.show", {
   detours: { NotFoundError: ["entity.fallback"] },
-  implementation: async (input, ctx) => Result.ok({ id: "123" })
+  run: async (input, ctx) => Result.ok({ id: "123" })
 })
 
 trail("entity.fallback", {
-  implementation: async (input, ctx) => { throw new Error("boom"); }
+  run: async (input, ctx) => { throw new Error("boom"); }
 })`;
 
     const diagnostics = noThrowInDetourTarget.check(code, TEST_FILE);
@@ -58,7 +58,7 @@ trail("entity.fallback", {
   test('uses project context when the detour target is defined in another file', () => {
     const code = `
 trail("entity.fallback", {
-  implementation: async (input, ctx) => {
+  run: async (input, ctx) => {
     throw new Error("boom");
   }
 })`;

package/src/__tests__/prefer-schema-inference.test.ts

@@ -10,7 +10,7 @@ trail("entity.show", {
   fields: {
     firstName: { label: "First Name" },
   },
-  implementation: (input) => Result.ok(input),
+  run: (input) => Result.ok(input),
 })`;
 
     const diagnostics = preferSchemaInference.check(code, 'src/entity.ts');
@@ -31,7 +31,7 @@ trail("entity.paint", {
       options: [{ value: "red" }, { value: "green" }],
     },
   },
-  implementation: (input) => Result.ok(input),
+  run: (input) => Result.ok(input),
 })`;
 
     const diagnostics = preferSchemaInference.check(code, 'src/entity.ts');
@@ -56,7 +56,7 @@ trail("entity.paint", {
     },
     displayName: { label: "Public name" },
   },
-  implementation: (input) => Result.ok(input),
+  run: (input) => Result.ok(input),
 })`;
 
     const diagnostics = preferSchemaInference.check(code, 'src/entity.ts');
@@ -74,7 +74,7 @@ trail("entity.show", {
       message: "Who should we greet?",
     },
   },
-  implementation: (input) => Result.ok(input),
+  run: (input) => Result.ok(input),
 })`;
 
     const diagnostics = preferSchemaInference.check(code, 'src/entity.ts');

package/src/__tests__/rules.test.ts

@@ -14,7 +14,7 @@ describe('no-throw-in-implementation', () => {
   test('flags throw inside implementation body', () => {
     const code = `
 trail("entity.show", {
-  implementation: async (input, ctx) => {
+  run: async (input, ctx) => {
     throw new Error("boom");
   }
 })`;
@@ -27,7 +27,7 @@ trail("entity.show", {
   test('allows Result.err() in implementation', () => {
     const code = `
 trail("entity.show", {
-  implementation: async (input, ctx) => {
+  run: async (input, ctx) => {
     return Result.err(new NotFoundError("not found"));
   }
 })`;
@@ -42,7 +42,7 @@ function helper() {
 }
 
 trail("entity.show", {
-  implementation: async (input, ctx) => {
+  run: async (input, ctx) => {
     return Result.ok(data);
   }
 })`;
@@ -59,7 +59,7 @@ describe('context-no-surface-types', () => {
     const code = `
 import { Request, Response } from "express";
 trail("entity.show", {
-  implementation: async (input, ctx) => {
+  run: async (input, ctx) => {
     return Result.ok(data);
   }
 })`;
@@ -73,7 +73,7 @@ trail("entity.show", {
     const code = `
 import type { McpSession } from "@modelcontextprotocol/sdk";
 trail("entity.show", {
-  implementation: async (input, ctx) => {
+  run: async (input, ctx) => {
     return Result.ok(data);
   }
 })`;
@@ -85,7 +85,7 @@ trail("entity.show", {
     const code = `
 import { trail, Result } from "@ontrails/core";
 trail("entity.show", {
-  implementation: async (input, ctx) => {
+  run: async (input, ctx) => {
     return Result.ok(data);
   }
 })`;
@@ -110,7 +110,7 @@ describe('valid-detour-refs', () => {
     const code = `
 trail("entity.show", {
   detours: [{ target: "entity.edit" }],
-  implementation: async (input, ctx) => Result.ok(data)
+  run: async (input, ctx) => Result.ok(data)
 })`;
     const diagnostics = validDetourRefs.check(code, TEST_FILE);
     expect(diagnostics.length).toBe(1);
@@ -120,12 +120,12 @@ trail("entity.show", {
   test('passes when detour target exists', () => {
     const code = `
 trail("entity.edit", {
-  implementation: async (input, ctx) => Result.ok(data)
+  run: async (input, ctx) => Result.ok(data)
 })
 
 trail("entity.show", {
   detours: [{ target: "entity.edit" }],
-  implementation: async (input, ctx) => Result.ok(data)
+  run: async (input, ctx) => Result.ok(data)
 })`;
     const diagnostics = validDetourRefs.check(code, TEST_FILE);
     expect(diagnostics.length).toBe(0);
@@ -135,7 +135,7 @@ trail("entity.show", {
     const code = `
 trail("entity.show", {
   detours: [{ target: "entity.edit" }],
-  implementation: async (input, ctx) => Result.ok(data)
+  run: async (input, ctx) => Result.ok(data)
 })`;
     const context = { knownTrailIds: new Set(['entity.show', 'entity.edit']) };
     const diagnostics = validDetourRefs.checkWithContext(
@@ -145,18 +145,45 @@ trail("entity.show", {
     );
     expect(diagnostics.length).toBe(0);
   });
+
+  test('flags detour target in trail with follow that does not exist', () => {
+    const code = `
+trail("entity.onboard", {
+  detours: [{ target: "entity.missing" }],
+  follow: ["entity.create"],
+  run: async (input, ctx) => Result.ok(data)
+})`;
+    const diagnostics = validDetourRefs.check(code, TEST_FILE);
+    expect(diagnostics.length).toBe(1);
+    expect(diagnostics[0]?.message).toContain('entity.missing');
+  });
+
+  test('passes when trail with follow detour target exists', () => {
+    const code = `
+trail("entity.fallback", {
+  run: async (input, ctx) => Result.ok(data)
+})
+
+trail("entity.onboard", {
+  detours: [{ target: "entity.fallback" }],
+  follow: ["entity.create"],
+  run: async (input, ctx) => Result.ok(data)
+})`;
+    const diagnostics = validDetourRefs.check(code, TEST_FILE);
+    expect(diagnostics.length).toBe(0);
+  });
 });
 
 // ---------------------------------------------------------------------------
 // no-direct-impl-in-route
 // ---------------------------------------------------------------------------
 describe('no-direct-impl-in-route', () => {
-  test('warns on direct .implementation() call in route', () => {
+  test('warns on direct .run() call in trail with follow', () => {
     const code = `
-hike("entity.onboard", {
-  follows: ["entity.create"],
-  implementation: async (input, ctx) => {
-    const result = await entityCreate.implementation(data);
+trail("entity.onboard", {
+  follow: ["entity.create"],
+  run: async (input, ctx) => {
+    const result = await entityCreate.run(data);
     return Result.ok(result);
   }
 })`;
@@ -168,9 +195,9 @@ hike("entity.onboard", {
 
   test('allows ctx.follow() calls', () => {
     const code = `
-hike("entity.onboard", {
-  follows: ["entity.create"],
-  implementation: async (input, ctx) => {
+trail("entity.onboard", {
+  follow: ["entity.create"],
+  run: async (input, ctx) => {
     const result = await ctx.follow("entity.create", data);
     return Result.ok(result);
   }
@@ -179,9 +206,21 @@ hike("entity.onboard", {
     expect(diagnostics.length).toBe(0);
   });
 
-  test('ignores files without hike() calls', () => {
+  test('ignores trails without follow', () => {
+    const code = `
+trail("entity.show", {
+  run: async (input, ctx) => {
+    const result = await someTrail.run(data);
+    return Result.ok(result);
+  }
+})`;
+    const diagnostics = noDirectImplInRoute.check(code, TEST_FILE);
+    expect(diagnostics.length).toBe(0);
+  });
+
+  test('ignores files without trail() calls', () => {
     const code = `
-const result = await someTrail.implementation(data);`;
+const result = await someTrail.run(data);`;
     const diagnostics = noDirectImplInRoute.check(code, TEST_FILE);
     expect(diagnostics.length).toBe(0);
   });

package/src/__tests__/trails.test.ts

@@ -0,0 +1,19 @@
+import { describe, expect, test } from 'bun:test';
+import { testAll } from '@ontrails/testing';
+
+import { wardenTopo } from '../trails/topo.js';
+
+// oxlint-disable-next-line jest/require-hook -- testAll generates describe/test blocks, not setup code
+testAll(wardenTopo);
+
+describe('wardenTopo', () => {
+  test('contains all 11 rule trails', () => {
+    expect(wardenTopo.count).toBe(11);
+  });
+
+  test('all trail IDs follow warden.rule.* naming', () => {
+    for (const id of wardenTopo.ids()) {
+      expect(id).toMatch(/^warden\.rule\./);
+    }
+  });
+});

package/src/__tests__/valid-describe-refs.test.ts

@@ -9,7 +9,7 @@ trail("entity.show", {
   input: z.object({
     query: z.string().describe("Search query. @see entity.search"),
   }),
-  implementation: (input) => Result.ok(input),
+  run: (input) => Result.ok(input),
 })`;
 
     const diagnostics = validDescribeRefs.check(code, 'src/entity.ts');
@@ -23,14 +23,14 @@ trail("entity.show", {
     const code = `
 trail("entity.search", {
   input: z.object({ query: z.string() }),
-  implementation: (input) => Result.ok(input),
+  run: (input) => Result.ok(input),
 })
 
 trail("entity.show", {
   input: z.object({
     query: z.string().describe("Search query. @see entity.search"),
   }),
-  implementation: (input) => Result.ok(input),
+  run: (input) => Result.ok(input),
 })`;
 
     const diagnostics = validDescribeRefs.check(code, 'src/entity.ts');
@@ -44,7 +44,7 @@ trail("entity.show", {
   input: z.object({
     query: z.string().describe("Search query. @see entity.search"),
   }),
-  implementation: (input) => Result.ok(input),
+  run: (input) => Result.ok(input),
 })`;
 
     const diagnostics = validDescribeRefs.checkWithContext(

package/src/cli.ts

@@ -152,10 +152,7 @@ const loadSourceFiles = async (
 };
 
 const buildProjectContextFromTopo = (appTopo: Topo): ProjectContext => {
-  const knownTrailIds = new Set<string>([
-    ...appTopo.trails.keys(),
-    ...appTopo.hikes.keys(),
-  ]);
+  const knownTrailIds = new Set<string>(appTopo.trails.keys());
 
   const detourTargetTrailIds = new Set<string>();
   for (const t of appTopo.trails.values()) {

package/src/index.ts

@@ -45,3 +45,24 @@ export {
 // Drift detection
 export type { DriftResult } from './drift.js';
 export { checkDrift } from './drift.js';
+
+// Trail layer
+export { wardenTopo } from './trails/topo.js';
+export { runWardenTrails } from './trails/run.js';
+export {
+  contextNoSurfaceTypesTrail,
+  diagnosticSchema,
+  followDeclarationsTrail,
+  implementationReturnsResultTrail,
+  noDirectImplInRouteTrail,
+  noDirectImplementationCallTrail,
+  noSyncResultAssumptionTrail,
+  noThrowInDetourTargetTrail,
+  noThrowInImplementationTrail,
+  preferSchemaInferenceTrail,
+  ruleInput,
+  ruleOutput,
+  validDescribeRefsTrail,
+  validDetourRefsTrail,
+} from './trails/index.js';
+export type { RuleInput, RuleOutput } from './trails/index.js';

package/src/rules/ast.ts

@@ -74,38 +74,52 @@ export const offsetToLine = (sourceCode: string, offset: number): number => {
   return line;
 };
 
-/** Find all `implementation:` property values in an AST. */
-export const findImplementationBodies = (ast: AstNode): AstNode[] => {
-  const bodies: AstNode[] = [];
-  walk(ast, (node) => {
-    if (
-      node.type === 'Property' &&
-      node.key?.name === 'implementation' &&
-      node.value
-    ) {
-      bodies.push(node.value);
+// ---------------------------------------------------------------------------
+// Config property extraction helpers
+// ---------------------------------------------------------------------------
+
+/** Find a Property node by key name inside an ObjectExpression config. */
+export const findConfigProperty = (
+  config: AstNode,
+  propertyName: string
+): AstNode | null => {
+  if (config.type !== 'ObjectExpression') {
+    return null;
+  }
+  const properties = config['properties'] as readonly AstNode[] | undefined;
+  if (!properties) {
+    return null;
+  }
+  for (const prop of properties) {
+    if (prop.type === 'Property' && prop.key?.name === propertyName) {
+      return prop;
     }
-  });
-  return bodies;
+  }
+  return null;
 };
 
+// ---------------------------------------------------------------------------
+// Trail definition extraction
+// ---------------------------------------------------------------------------
+
 export interface TrailDefinition {
   /** Trail ID string, e.g. "entity.show" */
   readonly id: string;
-  /** "trail" or "hike" */
+  /** "trail" or "event" */
   readonly kind: string;
-  /** The config object argument (second arg to trail/hike call) */
+  /** The config object argument (second arg to trail() call) */
   readonly config: AstNode;
   /** Start offset of the call expression */
   readonly start: number;
 }
 
 /**
- * Find all `trail("id", { ... })` and `hike("id", { ... })` call sites.
+ * Find all `trail("id", { ... })`, `trail({ id: "x", ... })`, and
+ * `event("id", { ... })` call sites.
  *
  * Returns the trail ID, kind, and config object node for each definition.
  */
-const TRAIL_CALLEE_NAMES = new Set(['trail', 'hike']);
+const TRAIL_CALLEE_NAMES = new Set(['trail', 'event']);
 
 const getTrailCalleeName = (node: AstNode): string | null => {
   if (node.type !== 'CallExpression') {
@@ -119,18 +133,49 @@ const getTrailCalleeName = (node: AstNode): string | null => {
   return name && TRAIL_CALLEE_NAMES.has(name) ? name : null;
 };
 
+/** Extract args from a trail() call, handling both two-arg and single-object forms. */
 const extractTrailArgs = (
   node: AstNode
-): { idArg: AstNode; configArg: AstNode } | null => {
+): { idArg: AstNode | null; configArg: AstNode } | null => {
   const args = node['arguments'] as readonly AstNode[] | undefined;
-  if (!args || args.length < 2) {
+  if (!args || args.length === 0) {
+    return null;
+  }
+
+  const [firstArg, secondArg] = args;
+  if (!firstArg) {
     return null;
   }
-  const [idArg, configArg] = args;
-  if (!idArg || !configArg) {
+
+  // Two-arg form: trail('id', { ... })
+  if (secondArg && firstArg.type !== 'ObjectExpression') {
+    return { configArg: secondArg, idArg: firstArg };
+  }
+
+  // Single-object form: trail({ id: 'x', ... })
+  return firstArg.type === 'ObjectExpression'
+    ? { configArg: firstArg, idArg: null }
+    : null;
+};
+
+/** Extract the string value from an `id` property inside a config ObjectExpression. */
+const extractIdFromConfig = (config: AstNode): string | null => {
+  const idProp = findConfigProperty(config, 'id');
+  if (!idProp || !idProp.value) {
     return null;
   }
-  return { configArg, idArg };
+  const val = (idProp.value as unknown as { value?: unknown }).value;
+  return typeof val === 'string' ? val : null;
+};
+
+const extractTrailId = (trailArgs: {
+  idArg: AstNode | null;
+  configArg: AstNode;
+}): string | null => {
+  if (trailArgs.idArg) {
+    return (trailArgs.idArg as unknown as { value?: string }).value ?? null;
+  }
+  return extractIdFromConfig(trailArgs.configArg);
 };
 
 const extractTrailDefinition = (node: AstNode): TrailDefinition | null => {
@@ -144,7 +189,7 @@ const extractTrailDefinition = (node: AstNode): TrailDefinition | null => {
     return null;
   }
 
-  const trailId = (trailArgs.idArg as unknown as { value?: string }).value;
+  const trailId = extractTrailId(trailArgs);
   if (!trailId) {
     return null;
   }
@@ -157,28 +202,6 @@ const extractTrailDefinition = (node: AstNode): TrailDefinition | null => {
   };
 };
 
-/** Check if a node is a call to `.implementation()` on some object. */
-export const isImplementationCall = (node: AstNode): boolean => {
-  if (node.type !== 'CallExpression') {
-    return false;
-  }
-  const callee = node['callee'] as AstNode | undefined;
-  if (!callee) {
-    return false;
-  }
-  if (
-    callee.type !== 'StaticMemberExpression' &&
-    callee.type !== 'MemberExpression'
-  ) {
-    return false;
-  }
-  const prop = (callee as unknown as { property?: AstNode }).property;
-  return (
-    prop?.type === 'Identifier' &&
-    (prop as unknown as { name: string }).name === 'implementation'
-  );
-};
-
 export const findTrailDefinitions = (ast: AstNode): TrailDefinition[] => {
   const definitions: TrailDefinition[] = [];
 
@@ -193,25 +216,71 @@ export const findTrailDefinitions = (ast: AstNode): TrailDefinition[] => {
 };
 
 // ---------------------------------------------------------------------------
-// Config property extraction helpers
+// Run body extraction
 // ---------------------------------------------------------------------------
 
-/** Find a Property node by key name inside an ObjectExpression config. */
-export const findConfigProperty = (
-  config: AstNode,
-  propertyName: string
-): AstNode | null => {
-  if (config.type !== 'ObjectExpression') {
-    return null;
-  }
+/**
+ * Extract top-level `run:` property values from an ObjectExpression's direct properties.
+ *
+ * Does not recurse into nested objects, so `metadata: { run: ... }` is ignored.
+ */
+const extractRunFromConfig = (config: AstNode): AstNode[] => {
+  const bodies: AstNode[] = [];
   const properties = config['properties'] as readonly AstNode[] | undefined;
   if (!properties) {
-    return null;
+    return bodies;
   }
   for (const prop of properties) {
-    if (prop.type === 'Property' && prop.key?.name === propertyName) {
-      return prop;
+    if (prop.type === 'Property' && prop.key?.name === 'run' && prop.value) {
+      bodies.push(prop.value);
     }
   }
-  return null;
+  return bodies;
+};
+
+/**
+ * Find `run:` property values.
+ *
+ * When given an ObjectExpression (trail config), returns only its direct `run:`
+ * properties. When given a full AST, finds trail definitions first and extracts
+ * `run:` from each config — in both cases ignoring nested `run:` properties
+ * (e.g. `metadata: { run: ... }`).
+ */
+export const findRunBodies = (node: AstNode): AstNode[] => {
+  if (node.type === 'ObjectExpression') {
+    return extractRunFromConfig(node);
+  }
+
+  // Full AST — find trail definitions and extract run from their configs
+  const bodies: AstNode[] = [];
+  for (const def of findTrailDefinitions(node)) {
+    bodies.push(...extractRunFromConfig(def.config));
+  }
+  return bodies;
+};
+
+// ---------------------------------------------------------------------------
+// Misc helpers
+// ---------------------------------------------------------------------------
+
+/** Check if a node is a call to `.run()` on some object. */
+export const isRunCall = (node: AstNode): boolean => {
+  if (node.type !== 'CallExpression') {
+    return false;
+  }
+  const callee = node['callee'] as AstNode | undefined;
+  if (!callee) {
+    return false;
+  }
+  if (
+    callee.type !== 'StaticMemberExpression' &&
+    callee.type !== 'MemberExpression'
+  ) {
+    return false;
+  }
+  const prop = (callee as unknown as { property?: AstNode }).property;
+  return (
+    prop?.type === 'Identifier' &&
+    (prop as unknown as { name: string }).name === 'run'
+  );
 };

package/src/rules/context-no-surface-types.ts

@@ -123,7 +123,7 @@ const classifyImport = (
  */
 export const contextNoSurfaceTypes: WardenRule = {
   check(sourceCode: string, filePath: string): readonly WardenDiagnostic[] {
-    if (!/\b(?:trail|hike)\s*\(/.test(sourceCode)) {
+    if (!/\btrail\s*\(/.test(sourceCode)) {
       return [];
     }