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

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

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

package/src/__tests__/provision-declarations.test.ts

@@ -0,0 +1,318 @@
+import { describe, expect, test } from 'bun:test';
+
+import { provisionDeclarations } from '../rules/provision-declarations.js';
+
+const TEST_FILE = 'test.ts';
+
+describe('provision-declarations', () => {
+  describe('clean cases', () => {
+    test('declared provisions match provision.from(ctx) usage', () => {
+      const code = `
+import { Result, provision, trail } from '@ontrails/core';
+
+const db = provision('db.main', {
+  create: () => Result.ok({ source: 'factory' }),
+});
+
+trail('entity.show', {
+  provisions: [db],
+  blaze: async (_input, ctx) => {
+    return Result.ok({ source: db.from(ctx).source });
+  },
+});
+`;
+
+      const diagnostics = provisionDeclarations.check(code, TEST_FILE);
+
+      expect(diagnostics.length).toBe(0);
+    });
+
+    test('local helper named provision() is not treated as ctx lookup', () => {
+      const code = `
+import { Result, provision, trail } from '@ontrails/core';
+
+const db = provision('db.main', {
+  create: () => Result.ok({ source: 'factory' }),
+});
+
+trail('entity.show', {
+  provisions: [db],
+  blaze: async (_input, ctx) => {
+    const provision = (id: string) => id;
+    return Result.ok({
+      resolved: provision('db.main'),
+      source: db.from(ctx).source,
+    });
+  },
+});
+`;
+
+      const diagnostics = provisionDeclarations.check(code, TEST_FILE);
+
+      expect(diagnostics.length).toBe(0);
+    });
+
+    test('declared provisions match ctx.provision() usage', () => {
+      const code = `
+import { Result, provision, trail } from '@ontrails/core';
+
+const db = provision('db.main', {
+  create: () => Result.ok({ source: 'factory' }),
+});
+
+trail('entity.show', {
+  provisions: [db],
+  blaze: async (_input, ctx) => {
+    const resolved = ctx.provision('db.main');
+    return Result.ok(resolved);
+  },
+});
+`;
+
+      const diagnostics = provisionDeclarations.check(code, TEST_FILE);
+
+      expect(diagnostics.length).toBe(0);
+    });
+
+    test('recognizes destructured provision() calls', () => {
+      const code = `
+import { Result, provision, trail } from '@ontrails/core';
+
+const db = provision('db.main', {
+  create: () => Result.ok({ source: 'factory' }),
+});
+
+trail('entity.show', {
+  provisions: [db],
+  blaze: async (_input, ctx) => {
+    const { provision } = ctx;
+    return Result.ok(provision('db.main'));
+  },
+});
+`;
+
+      const diagnostics = provisionDeclarations.check(code, TEST_FILE);
+
+      expect(diagnostics.length).toBe(0);
+    });
+
+    test('recognizes ctx.provision(db) lookups by declared provision object', () => {
+      const code = `
+import { Result, provision, trail } from '@ontrails/core';
+
+const db = provision('db.main', {
+  create: () => Result.ok({ source: 'factory' }),
+});
+
+trail('entity.show', {
+  provisions: [db],
+  blaze: async (_input, ctx) => {
+    return Result.ok(ctx.provision(db));
+  },
+});
+`;
+
+      const diagnostics = provisionDeclarations.check(code, TEST_FILE);
+
+      expect(diagnostics.length).toBe(0);
+    });
+  });
+
+  describe('error cases', () => {
+    test('provision.from(ctx) without a declaration produces an error', () => {
+      const code = `
+import { Result, provision, trail } from '@ontrails/core';
+
+const db = provision('db.main', {
+  create: () => Result.ok({ source: 'factory' }),
+});
+
+trail('entity.show', {
+  blaze: async (_input, ctx) => {
+    return Result.ok({ source: db.from(ctx).source });
+  },
+});
+`;
+
+      const diagnostics = provisionDeclarations.check(code, TEST_FILE);
+
+      expect(diagnostics.length).toBe(1);
+      expect(diagnostics[0]?.severity).toBe('error');
+      expect(diagnostics[0]?.rule).toBe('provision-declarations');
+      expect(diagnostics[0]?.message).toContain('db.from(ctx)');
+      expect(diagnostics[0]?.message).toContain('not declared in provisions');
+    });
+
+    test('ctx.provision() without a declaration produces an error', () => {
+      const code = `
+trail('entity.show', {
+  blaze: async (_input, ctx) => {
+    return Result.ok(ctx.provision('db.main'));
+  },
+});
+`;
+
+      const diagnostics = provisionDeclarations.check(code, TEST_FILE);
+
+      expect(diagnostics.length).toBe(1);
+      expect(diagnostics[0]?.severity).toBe('error');
+      expect(diagnostics[0]?.message).toContain("ctx.provision('db.main')");
+    });
+
+    test('unresolved imported provision declarations do not suppress lookup diagnostics', () => {
+      const code = `
+import { Result, trail } from '@ontrails/core';
+import { db } from './provisions';
+
+// const db = provision('db.main', {
+//   create: () => Result.ok({ source: 'factory' }),
+// });
+
+trail('entity.show', {
+  provisions: [db],
+  blaze: async (_input, ctx) => {
+    return Result.ok(ctx.provision('db.main'));
+  },
+});
+`;
+
+      const diagnostics = provisionDeclarations.check(code, TEST_FILE);
+
+      expect(diagnostics.length).toBe(1);
+      expect(diagnostics[0]?.severity).toBe('error');
+      expect(diagnostics[0]?.message).toContain("ctx.provision('db.main')");
+    });
+
+    test('ctx.provision(db) without a declaration produces an error', () => {
+      const code = `
+import { Result, provision, trail } from '@ontrails/core';
+
+const db = provision('db.main', {
+  create: () => Result.ok({ source: 'factory' }),
+});
+
+trail('entity.show', {
+  blaze: async (_input, ctx) => {
+    return Result.ok(ctx.provision(db));
+  },
+});
+`;
+
+      const diagnostics = provisionDeclarations.check(code, TEST_FILE);
+
+      expect(diagnostics.length).toBe(1);
+      expect(diagnostics[0]?.severity).toBe('error');
+      expect(diagnostics[0]?.message).toContain('ctx.provision(db)');
+    });
+  });
+
+  describe('warn cases', () => {
+    test('declared but unused provision produces a warning', () => {
+      const code = `
+import { Result, provision, trail } from '@ontrails/core';
+
+const db = provision('db.main', {
+  create: () => Result.ok({ source: 'factory' }),
+});
+
+trail('entity.show', {
+  provisions: [db],
+  blaze: async () => {
+    return Result.ok({ ok: true });
+  },
+});
+`;
+
+      const diagnostics = provisionDeclarations.check(code, TEST_FILE);
+
+      expect(diagnostics.length).toBe(1);
+      expect(diagnostics[0]?.severity).toBe('warn');
+      expect(diagnostics[0]?.rule).toBe('provision-declarations');
+      expect(diagnostics[0]?.message).toContain("'db' declared in provisions");
+      expect(diagnostics[0]?.message).toContain('never used');
+    });
+  });
+
+  describe('single-object overload', () => {
+    test('recognizes trail({ id, provisions, blaze }) form', () => {
+      const code = `
+import { Result, provision, trail } from '@ontrails/core';
+
+const db = provision('db.main', {
+  create: () => Result.ok({ source: 'factory' }),
+});
+
+trail({
+  id: 'entity.show',
+  provisions: [db],
+  blaze: async (_input, ctx) => {
+    return Result.ok({ source: db.from(ctx).source });
+  },
+});
+`;
+
+      const diagnostics = provisionDeclarations.check(code, TEST_FILE);
+
+      expect(diagnostics.length).toBe(0);
+    });
+  });
+
+  describe('context parameter naming', () => {
+    test('recognizes database.from(context) when second param is named context', () => {
+      const code = `
+import { Result, provision, trail } from '@ontrails/core';
+
+const database = provision('db.main', {
+  create: () => Result.ok({ source: 'factory' }),
+});
+
+trail('entity.show', {
+  provisions: [database],
+  blaze: async (_input, context) => {
+    return Result.ok(database.from(context));
+  },
+});
+`;
+
+      const diagnostics = provisionDeclarations.check(code, TEST_FILE);
+
+      expect(diagnostics.length).toBe(0);
+    });
+  });
+
+  describe('nested run false positives', () => {
+    test('meta.run does not trigger false positives', () => {
+      const code = `
+import { Result, provision, trail } from '@ontrails/core';
+
+const db = provision('db.main', {
+  create: () => Result.ok({ source: 'factory' }),
+});
+
+trail('entity.show', {
+  provisions: [db],
+  meta: { blaze: async () => ctx.provision('phantom') },
+  blaze: async (_input, ctx) => {
+    return Result.ok(db.from(ctx));
+  },
+});
+`;
+
+      const diagnostics = provisionDeclarations.check(code, TEST_FILE);
+
+      expect(diagnostics.length).toBe(0);
+    });
+  });
+
+  test('skips test files', () => {
+    const code = `
+trail('entity.show', {
+  blaze: async (_input, ctx) => {
+    return Result.ok(ctx.provision('db.main'));
+  },
+});
+`;
+
+    expect(provisionDeclarations.check(code, 'entity.test.ts')).toEqual([]);
+  });
+});

package/src/__tests__/provision-exists.test.ts

@@ -0,0 +1,122 @@
+import { describe, expect, test } from 'bun:test';
+
+import { provisionExists } from '../rules/provision-exists.js';
+
+const TEST_FILE = 'entity.ts';
+
+describe('provision-exists', () => {
+  test('passes when a locally declared provision exists', () => {
+    const code = `
+import { Result, provision, trail } from '@ontrails/core';
+import type { Provision } from '@ontrails/core';
+
+const db: Provision<{ source: string }> = provision('db.main', {
+  create: () => Result.ok({ source: 'factory' }),
+});
+
+trail('entity.show', {
+  provisions: [db],
+  blaze: async (_input, ctx) => Result.ok(db.from(ctx)),
+});
+`;
+
+    expect(provisionExists.check(code, TEST_FILE)).toEqual([]);
+  });
+
+  test('ignores commented-out provision declarations when resolving local ids', () => {
+    const code = `
+import { Result, trail } from '@ontrails/core';
+
+trail('entity.show', {
+  provisions: ['db.main'],
+  blaze: async (_input, ctx) => Result.ok(ctx.provision('db.main')),
+});
+
+// const db = provision('db.main', {
+//   create: () => Result.ok({ source: 'factory' }),
+// });
+`;
+
+    const diagnostics = provisionExists.check(code, TEST_FILE);
+
+    expect(diagnostics).toHaveLength(1);
+    expect(diagnostics[0]?.rule).toBe('provision-exists');
+    expect(diagnostics[0]?.message).toContain('db.main');
+  });
+
+  test('flags a declared provision missing from project context', () => {
+    const code = `
+import { Result, provision, trail } from '@ontrails/core';
+
+const db = provision('db.main', {
+  create: () => Result.ok({ source: 'factory' }),
+});
+
+trail('entity.show', {
+  provisions: [db],
+  blaze: async (_input, ctx) => Result.ok(db.from(ctx)),
+});
+`;
+
+    const diagnostics = provisionExists.checkWithContext(code, TEST_FILE, {
+      knownProvisionIds: new Set(['db.other']),
+      knownTrailIds: new Set(['entity.show']),
+    });
+
+    expect(diagnostics).toHaveLength(1);
+    expect(diagnostics[0]?.rule).toBe('provision-exists');
+    expect(diagnostics[0]?.message).toContain('db.main');
+  });
+
+  test('passes when project context includes the declared provision', () => {
+    const code = `
+import { Result, provision, trail } from '@ontrails/core';
+
+const db = provision('db.main', {
+  create: () => Result.ok({ source: 'factory' }),
+});
+
+trail('entity.show', {
+  provisions: [db],
+  blaze: async (_input, ctx) => Result.ok(db.from(ctx)),
+});
+`;
+
+    const diagnostics = provisionExists.checkWithContext(code, TEST_FILE, {
+      knownProvisionIds: new Set(['db.main']),
+      knownTrailIds: new Set(['entity.show']),
+    });
+
+    expect(diagnostics).toEqual([]);
+  });
+
+  test('skips unresolved imported provisions instead of guessing', () => {
+    const code = `
+import { trail } from '@ontrails/core';
+import { db } from './provisions';
+
+trail('entity.show', {
+  provisions: [db],
+  blaze: async (_input, ctx) => Result.ok(db.from(ctx)),
+});
+`;
+
+    expect(
+      provisionExists.checkWithContext(code, TEST_FILE, {
+        knownProvisionIds: new Set(['db.main']),
+        knownTrailIds: new Set(['entity.show']),
+      })
+    ).toEqual([]);
+  });
+
+  test('skips test files', () => {
+    const code = `
+trail('entity.show', {
+  provisions: ['db.main'],
+  blaze: async (_input, ctx) => Result.ok(ctx.provision('db.main')),
+});
+`;
+
+    expect(provisionExists.check(code, 'entity.test.ts')).toEqual([]);
+  });
+});

package/src/__tests__/rules.test.ts

@@ -1,6 +1,6 @@
 import { describe, expect, test } from 'bun:test';
 
-import { contextNoSurfaceTypes } from '../rules/context-no-surface-types.js';
+import { contextNoTrailheadTypes } from '../rules/context-no-trailhead-types.js';
 import { noDirectImplInRoute } from '../rules/no-direct-impl-in-route.js';
 import { noThrowInImplementation } from '../rules/no-throw-in-implementation.js';
 import { validDetourRefs } from '../rules/valid-detour-refs.js';
@@ -14,7 +14,7 @@ describe('no-throw-in-implementation', () => {
   test('flags throw inside implementation body', () => {
     const code = `
 trail("entity.show", {
-  run: async (input, ctx) => {
+  blaze: 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", {
-  run: async (input, ctx) => {
+  blaze: async (input, ctx) => {
     return Result.err(new NotFoundError("not found"));
   }
 })`;
@@ -42,7 +42,7 @@ function helper() {
 }
 
 trail("entity.show", {
-  run: async (input, ctx) => {
+  blaze: async (input, ctx) => {
     return Result.ok(data);
   }
 })`;
@@ -52,20 +52,20 @@ trail("entity.show", {
 });
 
 // ---------------------------------------------------------------------------
-// context-no-surface-types
+// context-no-trailhead-types
 // ---------------------------------------------------------------------------
-describe('context-no-surface-types', () => {
+describe('context-no-trailhead-types', () => {
   test('flags express import in trail file', () => {
     const code = `
 import { Request, Response } from "express";
 trail("entity.show", {
-  run: async (input, ctx) => {
+  blaze: async (input, ctx) => {
     return Result.ok(data);
   }
 })`;
-    const diagnostics = contextNoSurfaceTypes.check(code, TEST_FILE);
+    const diagnostics = contextNoTrailheadTypes.check(code, TEST_FILE);
     expect(diagnostics.length).toBe(1);
-    expect(diagnostics[0]?.rule).toBe('context-no-surface-types');
+    expect(diagnostics[0]?.rule).toBe('context-no-trailhead-types');
     expect(diagnostics[0]?.message).toContain('express');
   });
 
@@ -73,11 +73,11 @@ trail("entity.show", {
     const code = `
 import type { McpSession } from "@modelcontextprotocol/sdk";
 trail("entity.show", {
-  run: async (input, ctx) => {
+  blaze: async (input, ctx) => {
     return Result.ok(data);
   }
 })`;
-    const diagnostics = contextNoSurfaceTypes.check(code, TEST_FILE);
+    const diagnostics = contextNoTrailheadTypes.check(code, TEST_FILE);
     expect(diagnostics.length).toBe(1);
   });
 
@@ -85,11 +85,11 @@ trail("entity.show", {
     const code = `
 import { trail, Result } from "@ontrails/core";
 trail("entity.show", {
-  run: async (input, ctx) => {
+  blaze: async (input, ctx) => {
     return Result.ok(data);
   }
 })`;
-    const diagnostics = contextNoSurfaceTypes.check(code, TEST_FILE);
+    const diagnostics = contextNoTrailheadTypes.check(code, TEST_FILE);
     expect(diagnostics.length).toBe(0);
   });
 
@@ -97,7 +97,7 @@ trail("entity.show", {
     const code = `
 import { Request, Response } from "express";
 export function handleRequest(req: Request, res: Response) {}`;
-    const diagnostics = contextNoSurfaceTypes.check(code, TEST_FILE);
+    const diagnostics = contextNoTrailheadTypes.check(code, TEST_FILE);
     expect(diagnostics.length).toBe(0);
   });
 });
@@ -110,7 +110,7 @@ describe('valid-detour-refs', () => {
     const code = `
 trail("entity.show", {
   detours: [{ target: "entity.edit" }],
-  run: async (input, ctx) => Result.ok(data)
+  blaze: 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", {
-  run: async (input, ctx) => Result.ok(data)
+  blaze: async (input, ctx) => Result.ok(data)
 })
 
 trail("entity.show", {
   detours: [{ target: "entity.edit" }],
-  run: async (input, ctx) => Result.ok(data)
+  blaze: 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" }],
-  run: async (input, ctx) => Result.ok(data)
+  blaze: async (input, ctx) => Result.ok(data)
 })`;
     const context = { knownTrailIds: new Set(['entity.show', 'entity.edit']) };
     const diagnostics = validDetourRefs.checkWithContext(
@@ -146,28 +146,28 @@ trail("entity.show", {
     expect(diagnostics.length).toBe(0);
   });
 
-  test('flags detour target in trail with follow that does not exist', () => {
+  test('flags detour target in trail with crossings that does not exist', () => {
     const code = `
 trail("entity.onboard", {
   detours: [{ target: "entity.missing" }],
-  follow: ["entity.create"],
-  run: async (input, ctx) => Result.ok(data)
+  crosses: ["entity.create"],
+  blaze: 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', () => {
+  test('passes when trail with crossings detour target exists', () => {
     const code = `
 trail("entity.fallback", {
-  run: async (input, ctx) => Result.ok(data)
+  blaze: async (input, ctx) => Result.ok(data)
 })
 
 trail("entity.onboard", {
   detours: [{ target: "entity.fallback" }],
-  follow: ["entity.create"],
-  run: async (input, ctx) => Result.ok(data)
+  crosses: ["entity.create"],
+  blaze: async (input, ctx) => Result.ok(data)
 })`;
     const diagnostics = validDetourRefs.check(code, TEST_FILE);
     expect(diagnostics.length).toBe(0);
@@ -178,27 +178,27 @@ trail("entity.onboard", {
 // no-direct-impl-in-route
 // ---------------------------------------------------------------------------
 describe('no-direct-impl-in-route', () => {
-  test('warns on direct .run() call in trail with follow', () => {
+  test('warns on direct .blaze() call in trail with crossings', () => {
     const code = `
 trail("entity.onboard", {
-  follow: ["entity.create"],
-  run: async (input, ctx) => {
-    const result = await entityCreate.run(data);
+  crosses: ["entity.create"],
+  blaze: async (input, ctx) => {
+    const result = await entityCreate.blaze(data);
     return Result.ok(result);
   }
 })`;
     const diagnostics = noDirectImplInRoute.check(code, TEST_FILE);
     expect(diagnostics.length).toBe(1);
     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", data);
+  crosses: ["entity.create"],
+  blaze: async (input, ctx) => {
+    const result = await ctx.cross("entity.create", data);
     return Result.ok(result);
   }
 })`;
@@ -206,11 +206,11 @@ trail("entity.onboard", {
     expect(diagnostics.length).toBe(0);
   });
 
-  test('ignores trails without follow', () => {
+  test('ignores trails without crossings', () => {
     const code = `
 trail("entity.show", {
-  run: async (input, ctx) => {
-    const result = await someTrail.run(data);
+  blaze: async (input, ctx) => {
+    const result = await someTrail.blaze(data);
     return Result.ok(result);
   }
 })`;
@@ -220,7 +220,7 @@ trail("entity.show", {
 
   test('ignores files without trail() calls', () => {
     const code = `
-const result = await someTrail.run(data);`;
+const result = await someTrail.blaze(data);`;
     const diagnostics = noDirectImplInRoute.check(code, TEST_FILE);
     expect(diagnostics.length).toBe(0);
   });