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

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

@@ -1,41 +1,41 @@
 import { describe, expect, test } from 'bun:test';
 
-import { followDeclarations } from '../rules/follow-declarations.js';
+import { crossDeclarations } from '../rules/cross-declarations.js';
 
 const TEST_FILE = 'test.ts';
 
-describe('follow-declarations', () => {
+describe('cross-declarations', () => {
   describe('clean cases', () => {
     test('declared and called match exactly', () => {
       const code = `
 import { trail, Result } from '@ontrails/core';
 const t = trail('onboard', {
-  follow: ['entity.add', 'search'],
+  crosses: ['entity.add', 'search'],
   input: z.object({ name: z.string() }),
-  run: async (input, ctx) => {
-    await ctx.follow('entity.add', { name: input.name });
-    await ctx.follow('search', { query: input.name });
+  blaze: async (input, ctx) => {
+    await ctx.cross('entity.add', { name: input.name });
+    await ctx.cross('search', { query: input.name });
     return Result.ok({});
   },
 });
 `;
 
-      const diagnostics = followDeclarations.check(code, TEST_FILE);
+      const diagnostics = crossDeclarations.check(code, TEST_FILE);
 
       expect(diagnostics.length).toBe(0);
     });
 
-    test('no follow declaration and no ctx.follow() calls', () => {
+    test('no crosses declaration and no ctx.cross() calls', () => {
       const code = `
 trail('simple', {
   input: z.object({ name: z.string() }),
-  run: async (input, ctx) => {
+  blaze: async (input, ctx) => {
     return Result.ok({ greeting: 'hello ' + input.name });
   },
 });
 `;
 
-      const diagnostics = followDeclarations.check(code, TEST_FILE);
+      const diagnostics = crossDeclarations.check(code, TEST_FILE);
 
       expect(diagnostics.length).toBe(0);
     });
@@ -46,20 +46,20 @@ trail('simple', {
       const code = `
 trail('onboard', {
   input: z.object({ name: z.string() }),
-  run: async (input, ctx) => {
-    await ctx.follow('entity.add', { name: input.name });
+  blaze: async (input, ctx) => {
+    await ctx.cross('entity.add', { name: input.name });
     return Result.ok({});
   },
 });
 `;
 
-      const diagnostics = followDeclarations.check(code, TEST_FILE);
+      const diagnostics = crossDeclarations.check(code, TEST_FILE);
 
       expect(diagnostics.length).toBe(1);
       expect(diagnostics[0]?.severity).toBe('error');
-      expect(diagnostics[0]?.rule).toBe('follow-declarations');
-      expect(diagnostics[0]?.message).toContain("ctx.follow('entity.add')");
-      expect(diagnostics[0]?.message).toContain('not declared in follow');
+      expect(diagnostics[0]?.rule).toBe('cross-declarations');
+      expect(diagnostics[0]?.message).toContain("ctx.cross('entity.add')");
+      expect(diagnostics[0]?.message).toContain('not declared in crosses');
     });
   });
 
@@ -67,56 +67,56 @@ trail('onboard', {
     test('declared but not called produces warning', () => {
       const code = `
 trail('onboard', {
-  follow: ['entity.add', 'search'],
-  run: async (input, ctx) => {
-    await ctx.follow('entity.add', { name: input.name });
+  crosses: ['entity.add', 'search'],
+  blaze: async (input, ctx) => {
+    await ctx.cross('entity.add', { name: input.name });
     return Result.ok({});
   },
 });
 `;
 
-      const diagnostics = followDeclarations.check(code, TEST_FILE);
+      const diagnostics = crossDeclarations.check(code, TEST_FILE);
 
       expect(diagnostics.length).toBe(1);
       expect(diagnostics[0]?.severity).toBe('warn');
-      expect(diagnostics[0]?.rule).toBe('follow-declarations');
-      expect(diagnostics[0]?.message).toContain("'search' declared in follow");
+      expect(diagnostics[0]?.rule).toBe('cross-declarations');
+      expect(diagnostics[0]?.message).toContain("'search' declared in crosses");
       expect(diagnostics[0]?.message).toContain('never called');
     });
   });
 
   describe('single-object overload', () => {
-    test('recognizes trail({ id, follow, run }) form', () => {
+    test('recognizes trail({ id, crosses, blaze }) form', () => {
       const code = `
 trail({
   id: 'onboard',
-  follow: ['entity.add'],
+  crosses: ['entity.add'],
   input: z.object({ name: z.string() }),
-  run: async (input, ctx) => {
-    await ctx.follow('entity.add', { name: input.name });
+  blaze: async (input, ctx) => {
+    await ctx.cross('entity.add', { name: input.name });
     return Result.ok({});
   },
 });
 `;
 
-      const diagnostics = followDeclarations.check(code, TEST_FILE);
+      const diagnostics = crossDeclarations.check(code, TEST_FILE);
 
       expect(diagnostics.length).toBe(0);
     });
 
-    test('detects undeclared follows in single-object form', () => {
+    test('detects undeclared crossings in single-object form', () => {
       const code = `
 trail({
   id: 'onboard',
   input: z.object({ name: z.string() }),
-  run: async (input, ctx) => {
-    await ctx.follow('entity.add', { name: input.name });
+  blaze: async (input, ctx) => {
+    await ctx.cross('entity.add', { name: input.name });
     return Result.ok({});
   },
 });
 `;
 
-      const diagnostics = followDeclarations.check(code, TEST_FILE);
+      const diagnostics = crossDeclarations.check(code, TEST_FILE);
 
       expect(diagnostics.length).toBe(1);
       expect(diagnostics[0]?.severity).toBe('error');
@@ -125,112 +125,112 @@ trail({
   });
 
   describe('context parameter naming', () => {
-    test('recognizes context.follow() when second param is named context', () => {
+    test('recognizes context.cross() when second param is named context', () => {
       const code = `
 trail('onboard', {
-  follow: ['entity.add'],
+  crosses: ['entity.add'],
   input: z.object({ name: z.string() }),
-  run: async (input, context) => {
-    await context.follow('entity.add', { name: input.name });
+  blaze: async (input, context) => {
+    await context.cross('entity.add', { name: input.name });
     return Result.ok({});
   },
 });
 `;
 
-      const diagnostics = followDeclarations.check(code, TEST_FILE);
+      const diagnostics = crossDeclarations.check(code, TEST_FILE);
 
       expect(diagnostics.length).toBe(0);
     });
 
-    test('detects undeclared context.follow() calls', () => {
+    test('detects undeclared context.cross() calls', () => {
       const code = `
 trail('onboard', {
   input: z.object({ name: z.string() }),
-  run: async (input, context) => {
-    await context.follow('entity.add', { name: input.name });
+  blaze: async (input, context) => {
+    await context.cross('entity.add', { name: input.name });
     return Result.ok({});
   },
 });
 `;
 
-      const diagnostics = followDeclarations.check(code, TEST_FILE);
+      const diagnostics = crossDeclarations.check(code, TEST_FILE);
 
       expect(diagnostics.length).toBe(1);
       expect(diagnostics[0]?.severity).toBe('error');
     });
 
-    test('recognizes destructured follow() calls', () => {
+    test('recognizes destructured cross() calls', () => {
       const code = `
 trail('onboard', {
-  follow: ['entity.add'],
+  crosses: ['entity.add'],
   input: z.object({ name: z.string() }),
-  run: async (input, ctx) => {
-    const { follow } = ctx;
-    await follow('entity.add', { name: input.name });
+  blaze: async (input, ctx) => {
+    const { cross } = ctx;
+    await cross('entity.add', { name: input.name });
     return Result.ok({});
   },
 });
 `;
 
-      const diagnostics = followDeclarations.check(code, TEST_FILE);
+      const diagnostics = crossDeclarations.check(code, TEST_FILE);
 
       expect(diagnostics.length).toBe(0);
     });
   });
 
   describe('nested run false positives', () => {
-    test('metadata.run does not trigger false positives', () => {
+    test('meta.run does not trigger false positives', () => {
       const code = `
 trail('onboard', {
-  follow: ['entity.add'],
+  crosses: ['entity.add'],
   input: z.object({ name: z.string() }),
-  metadata: { run: async () => ctx.follow('phantom') },
-  run: async (input, ctx) => {
-    await ctx.follow('entity.add', { name: input.name });
+  meta: { blaze: async () => ctx.cross('phantom') },
+  blaze: async (input, ctx) => {
+    await ctx.cross('entity.add', { name: input.name });
     return Result.ok({});
   },
 });
 `;
 
-      const diagnostics = followDeclarations.check(code, TEST_FILE);
+      const diagnostics = crossDeclarations.check(code, TEST_FILE);
 
       expect(diagnostics.length).toBe(0);
     });
   });
 
-  describe('identifier resolution in follow arrays', () => {
-    test('resolves const identifiers in follow array', () => {
+  describe('identifier resolution in crosses arrays', () => {
+    test('resolves const identifiers in crosses array', () => {
       const code = `
 const ENTITY_ADD = 'entity.add';
 trail('onboard', {
-  follow: [ENTITY_ADD],
+  crosses: [ENTITY_ADD],
   input: z.object({ name: z.string() }),
-  run: async (input, ctx) => {
-    await ctx.follow('entity.add', { name: input.name });
+  blaze: async (input, ctx) => {
+    await ctx.cross('entity.add', { name: input.name });
     return Result.ok({});
   },
 });
 `;
 
-      const diagnostics = followDeclarations.check(code, TEST_FILE);
+      const diagnostics = crossDeclarations.check(code, TEST_FILE);
 
       expect(diagnostics.length).toBe(0);
     });
 
-    test('reports error when resolved identifier does not match called follow', () => {
+    test('reports error when resolved identifier does not match called cross', () => {
       const code = `
 const ENTITY_ADD = 'entity.add';
 trail('onboard', {
-  follow: [ENTITY_ADD],
+  crosses: [ENTITY_ADD],
   input: z.object({ name: z.string() }),
-  run: async (input, ctx) => {
-    await ctx.follow('search', { name: input.name });
+  blaze: async (input, ctx) => {
+    await ctx.cross('search', { name: input.name });
     return Result.ok({});
   },
 });
 `;
 
-      const diagnostics = followDeclarations.check(code, TEST_FILE);
+      const diagnostics = crossDeclarations.check(code, TEST_FILE);
 
       // 'search' called but not declared, 'entity.add' declared but not called
       expect(diagnostics.length).toBe(2);
@@ -238,20 +238,20 @@ trail('onboard', {
   });
 
   describe('edge cases', () => {
-    test('dynamic follow IDs are skipped', () => {
+    test('dynamic cross IDs are skipped', () => {
       const code = `
 trail('dispatch', {
-  follow: ['entity.add'],
-  run: async (input, ctx) => {
+  crosses: ['entity.add'],
+  blaze: async (input, ctx) => {
     const trailId = input.target;
-    await ctx.follow(trailId, input);
-    await ctx.follow('entity.add', input);
+    await ctx.cross(trailId, input);
+    await ctx.cross('entity.add', input);
     return Result.ok({});
   },
 });
 `;
 
-      const diagnostics = followDeclarations.check(code, TEST_FILE);
+      const diagnostics = crossDeclarations.check(code, TEST_FILE);
 
       expect(diagnostics.length).toBe(0);
     });
@@ -259,22 +259,22 @@ trail('dispatch', {
     test('multiple trails in one file are validated independently', () => {
       const code = `
 trail('alpha', {
-  follow: ['shared'],
-  run: async (input, ctx) => {
-    await ctx.follow('shared', input);
+  crosses: ['shared'],
+  blaze: async (input, ctx) => {
+    await ctx.cross('shared', input);
     return Result.ok({});
   },
 });
 
 trail('beta', {
-  run: async (input, ctx) => {
-    await ctx.follow('undeclared', input);
+  blaze: async (input, ctx) => {
+    await ctx.cross('undeclared', input);
     return Result.ok({});
   },
 });
 `;
 
-      const diagnostics = followDeclarations.check(code, TEST_FILE);
+      const diagnostics = crossDeclarations.check(code, TEST_FILE);
 
       expect(diagnostics.length).toBe(1);
       expect(diagnostics[0]?.message).toContain('Trail "beta"');
@@ -285,14 +285,14 @@ trail('beta', {
     test('skips test files', () => {
       const code = `
 trail('onboard', {
-  run: async (input, ctx) => {
-    await ctx.follow('entity.add', input);
+  blaze: async (input, ctx) => {
+    await ctx.cross('entity.add', input);
     return Result.ok({});
   },
 });
 `;
 
-      const diagnostics = followDeclarations.check(
+      const diagnostics = crossDeclarations.check(
         code,
         'src/__tests__/trails.test.ts'
       );

package/src/__tests__/drift.test.ts

@@ -4,16 +4,16 @@ import { join } from 'node:path';
 import { tmpdir } from 'node:os';
 
 import { trail, topo, Result } from '@ontrails/core';
-import { hashSurfaceMap, generateSurfaceMap } from '@ontrails/schema';
+import { hashTrailheadMap, generateTrailheadMap } from '@ontrails/schema';
 import { z } from 'zod';
 
 import { checkDrift } from '../drift.js';
 
 const makeTopo = () => {
   const t = trail('test.hello', {
+    blaze: () => Result.ok({ greeting: 'hi' }),
     input: z.object({ name: z.string() }),
     output: z.object({ greeting: z.string() }),
-    run: () => Result.ok({ greeting: 'hi' }),
   });
   return topo('test-app', { t });
 };
@@ -47,8 +47,8 @@ describe('checkDrift', () => {
     const dir = createTempDir();
     try {
       const tp = makeTopo();
-      const hash = hashSurfaceMap(generateSurfaceMap(tp));
-      writeFileSync(join(dir, 'surface.lock'), `${hash}\n`);
+      const hash = hashTrailheadMap(generateTrailheadMap(tp));
+      writeFileSync(join(dir, 'trailhead.lock'), `${hash}\n`);
 
       const result = await checkDrift(dir, tp);
       expect(result.stale).toBe(false);
@@ -62,7 +62,7 @@ describe('checkDrift', () => {
   test('returns stale: true when lock does not match', async () => {
     const dir = createTempDir();
     try {
-      writeFileSync(join(dir, 'surface.lock'), 'outdated-hash\n');
+      writeFileSync(join(dir, 'trailhead.lock'), 'outdated-hash\n');
 
       const result = await checkDrift(dir, makeTopo());
       expect(result.stale).toBe(true);

package/src/__tests__/formatters.test.ts

@@ -67,7 +67,7 @@ describe('formatGitHubAnnotations', () => {
 
   test('emits drift as a single ::error annotation', () => {
     const output = formatGitHubAnnotations(reportWithDrift);
-    expect(output).toContain('::error::drift: surface.lock is stale');
+    expect(output).toContain('::error::drift: trailhead.lock is stale');
   });
 
   test('produces one line per diagnostic', () => {
@@ -148,7 +148,7 @@ describe('formatSummary', () => {
   test('includes drift section when stale', () => {
     const output = formatSummary(reportWithDrift);
     expect(output).toContain('### Drift');
-    expect(output).toContain('surface.lock is stale');
+    expect(output).toContain('trailhead.lock is stale');
   });
 
   test('omits drift section when clean', () => {

package/src/__tests__/implementation-returns-result.test.ts

@@ -8,7 +8,7 @@ describe('implementation-returns-result', () => {
   test('flags raw object return in trail implementation', () => {
     const code = `
 trail("entity.show", {
-  run: async (input, ctx) => {
+  blaze: async (input, ctx) => {
     return { name: "foo" };
   }
 })`;
@@ -20,18 +20,18 @@ trail("entity.show", {
     expect(diagnostics[0]?.severity).toBe('error');
   });
 
-  test('allows Result.ok() and returning ctx.follow() results', () => {
+  test('allows Result.ok() and returning ctx.cross() results', () => {
     const code = `
 trail("entity.onboard", {
-  follow: ["entity.create"],
-  run: async (input, ctx) => {
-    const result = await ctx.follow("entity.create", input);
+  crosses: ["entity.create"],
+  blaze: async (input, ctx) => {
+    const result = await ctx.cross("entity.create", input);
     return result;
   }
 })
 
 trail("entity.create", {
-  run: async (input, ctx) => Result.ok({ id: "123" })
+  blaze: async (input, ctx) => Result.ok({ id: "123" })
 })`;
 
     const diagnostics = implementationReturnsResult.check(code, TEST_FILE);
@@ -42,7 +42,7 @@ trail("entity.create", {
   test('flags concise raw implementation bodies', () => {
     const code = `
 trail("entity.create", {
-  run: async (input, ctx) => ({ id: "123" })
+  blaze: async (input, ctx) => ({ id: "123" })
 })`;
 
     const diagnostics = implementationReturnsResult.check(code, TEST_FILE);
@@ -54,7 +54,7 @@ trail("entity.create", {
   test('ignores return statements inside nested callbacks like .map()', () => {
     const code = `
 trail("entity.list", {
-  run: async (input, ctx) => {
+  blaze: async (input, ctx) => {
     const items = ["a", "b", "c"];
     const mapped = items.map((item) => {
       return { name: item };
@@ -74,7 +74,7 @@ trail("entity.list", {
   test('ignores return statements inside .then() callbacks', () => {
     const code = `
 trail("entity.fetch", {
-  run: async (input, ctx) => {
+  blaze: async (input, ctx) => {
     const data = await somePromise.then((res) => {
       return res.json();
     });
@@ -90,7 +90,7 @@ trail("entity.fetch", {
   test('still flags raw returns at the implementation level', () => {
     const code = `
 trail("entity.list", {
-  run: async (input, ctx) => {
+  blaze: async (input, ctx) => {
     const items = ["a", "b"].map((item) => {
       return { name: item };
     });
@@ -113,7 +113,7 @@ const buildDiff = async (): Promise<Result<object, Error>> =>
   Result.ok({ breaking: [] });
 
 trail("survey", {
-  run: async (input, ctx) => {
+  blaze: async (input, ctx) => {
     if (input.diff) {
       return await buildDiff();
     }

package/src/__tests__/no-direct-implementation-call.test.ts

@@ -8,11 +8,11 @@ describe('no-direct-implementation-call', () => {
 import { trail, Result } from "@ontrails/core";
 
 const entityShow = trail("entity.show", {
-  run: async (input, ctx) => Result.ok({ id: input.id }),
+  blaze: async (input, ctx) => Result.ok({ id: input.id }),
 });
 
 async function run() {
-  const result = await entityShow.run({ id: "1" }, ctx);
+  const result = await entityShow.blaze({ id: "1" }, ctx);
   return result;
 }`;
 
@@ -21,15 +21,15 @@ async function run() {
     expect(diagnostics).toHaveLength(1);
     expect(diagnostics[0]?.rule).toBe('no-direct-implementation-call');
     expect(diagnostics[0]?.severity).toBe('warn');
-    expect(diagnostics[0]?.message).toContain('ctx.follow');
+    expect(diagnostics[0]?.message).toContain('ctx.cross');
   });
 
-  test('allows ctx.follow() calls', () => {
+  test('allows ctx.cross() calls', () => {
     const code = `
 trail("entity.onboard", {
-  follow: ["entity.create"],
-  run: async (input, ctx) => {
-    const result = await ctx.follow("entity.create", input);
+  crosses: ["entity.create"],
+  blaze: async (input, ctx) => {
+    const result = await ctx.cross("entity.create", input);
     return Result.ok(result);
   },
 });
@@ -43,7 +43,7 @@ trail("entity.onboard", {
   test('ignores test files', () => {
     const code = `
 async function run() {
-  return await entityShow.run({ id: "1" }, ctx);
+  return await entityShow.blaze({ id: "1" }, ctx);
 }`;
 
     const diagnostics = noDirectImplementationCall.check(
@@ -57,7 +57,7 @@ async function run() {
   test('ignores framework internals that intentionally call implementations', () => {
     const code = `
 export async function run() {
-  return await entityShow.run({ id: "1" }, ctx);
+  return await entityShow.blaze({ id: "1" }, ctx);
 }`;
 
     const diagnostics = noDirectImplementationCall.check(
@@ -70,7 +70,7 @@ export async function run() {
 
   test('ignores implementation references inside template strings', () => {
     const code = `
-const generated = \`const result = await entityShow.run({ id: "1" }, ctx);\`;
+const generated = \`const result = await entityShow.blaze({ id: "1" }, ctx);\`;
 `;
 
     const diagnostics = noDirectImplementationCall.check(

package/src/__tests__/no-sync-result-assumption.test.ts

@@ -6,7 +6,7 @@ describe('no-sync-result-assumption', () => {
   test('flags direct result access on implementation calls', () => {
     const code = `
 async function run() {
-  const isOk = entityShow.run({ id: "1" }, ctx).isOk();
+  const isOk = entityShow.blaze({ id: "1" }, ctx).isOk();
   return isOk;
 }`;
 
@@ -20,7 +20,7 @@ async function run() {
 
   test('flags a stored implementation result that is used synchronously', () => {
     const code = `
-const result = entityShow.run({ id: "1" }, ctx);
+const result = entityShow.blaze({ id: "1" }, ctx);
 
 if (result.isOk()) {
   console.log("ok");
@@ -35,7 +35,7 @@ if (result.isOk()) {
   test('allows awaited implementation calls before result access', () => {
     const code = `
 async function run() {
-  const result = await entityShow.run({ id: "1" }, ctx);
+  const result = await entityShow.blaze({ id: "1" }, ctx);
   return result.isOk();
 }`;
 
@@ -47,7 +47,7 @@ async function run() {
   test('allows awaited implementation calls when the property access is chained', () => {
     const code = `
 async function run() {
-  return (await entityShow.run({ id: "1" }, ctx)).isOk();
+  return (await entityShow.blaze({ id: "1" }, ctx)).isOk();
 }`;
 
     const diagnostics = noSyncResultAssumption.check(code, 'src/app.ts');
@@ -57,7 +57,7 @@ async function run() {
 
   test('ignores test files', () => {
     const code = `
-const result = entityShow.run({ id: "1" }, ctx);
+const result = entityShow.blaze({ id: "1" }, ctx);
 result.isOk();
 `;
 
@@ -71,7 +71,7 @@ result.isOk();
 
   test('ignores framework internals that intentionally call implementations', () => {
     const code = `
-const result = entityShow.run({ id: "1" }, ctx);
+const result = entityShow.blaze({ id: "1" }, ctx);
 result.isOk();
 `;
 

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"] },
-  run: async (input, ctx) => Result.ok({ id: "123" })
+  blaze: async (input, ctx) => Result.ok({ id: "123" })
 })
 
 trail("entity.fallback", {
-  run: async (input, ctx) => {
+  blaze: 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", {
-  run: async (input, ctx) => {
+  blaze: async (input, ctx) => {
     throw new Error("boom");
   }
 })`;
@@ -42,11 +42,11 @@ trail("entity.show", {
     const code = `
 trail("entity.show", {
   detours: { NotFoundError: ["entity.fallback"] },
-  run: async (input, ctx) => Result.ok({ id: "123" })
+  blaze: async (input, ctx) => Result.ok({ id: "123" })
 })
 
 trail("entity.fallback", {
-  run: async (input, ctx) => { throw new Error("boom"); }
+  blaze: 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", {
-  run: async (input, ctx) => {
+  blaze: async (input, ctx) => {
     throw new Error("boom");
   }
 })`;