@ontrails/warden 1.0.0-beta.0

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

@@ -0,0 +1,83 @@
+import { describe, expect, test } from 'bun:test';
+
+import { noDirectImplementationCall } from '../rules/no-direct-implementation-call.js';
+
+describe('no-direct-implementation-call', () => {
+  test('flags direct implementation access in application code', () => {
+    const code = `
+import { trail, Result } from "@ontrails/core";
+
+const entityShow = trail("entity.show", {
+  implementation: async (input, ctx) => Result.ok({ id: input.id }),
+});
+
+async function run() {
+  const result = await entityShow.implementation({ id: "1" }, ctx);
+  return result;
+}`;
+
+    const diagnostics = noDirectImplementationCall.check(code, 'src/app.ts');
+
+    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');
+  });
+
+  test('allows ctx.follow() calls', () => {
+    const code = `
+hike("entity.onboard", {
+  follows: ["entity.create"],
+  implementation: async (input, ctx) => {
+    const result = await ctx.follow("entity.create", input);
+    return Result.ok(result);
+  },
+});
+`;
+
+    const diagnostics = noDirectImplementationCall.check(code, 'src/app.ts');
+
+    expect(diagnostics).toHaveLength(0);
+  });
+
+  test('ignores test files', () => {
+    const code = `
+async function run() {
+  return await entityShow.implementation({ id: "1" }, ctx);
+}`;
+
+    const diagnostics = noDirectImplementationCall.check(
+      code,
+      'src/__tests__/app.test.ts'
+    );
+
+    expect(diagnostics).toHaveLength(0);
+  });
+
+  test('ignores framework internals that intentionally call implementations', () => {
+    const code = `
+export async function run() {
+  return await entityShow.implementation({ id: "1" }, ctx);
+}`;
+
+    const diagnostics = noDirectImplementationCall.check(
+      code,
+      '/repo/packages/testing/src/trail.ts'
+    );
+
+    expect(diagnostics).toHaveLength(0);
+  });
+
+  test('ignores implementation references inside template strings', () => {
+    const code = `
+const generated = \`const result = await entityShow.implementation({ id: "1" }, ctx);\`;
+`;
+
+    const diagnostics = noDirectImplementationCall.check(
+      code,
+      'src/new-trail.ts'
+    );
+
+    expect(diagnostics).toHaveLength(0);
+  });
+});

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

@@ -0,0 +1,85 @@
+import { describe, expect, test } from 'bun:test';
+
+import { noSyncResultAssumption } from '../rules/no-sync-result-assumption.js';
+
+describe('no-sync-result-assumption', () => {
+  test('flags direct result access on implementation calls', () => {
+    const code = `
+async function run() {
+  const isOk = entityShow.implementation({ id: "1" }, ctx).isOk();
+  return isOk;
+}`;
+
+    const diagnostics = noSyncResultAssumption.check(code, 'src/app.ts');
+
+    expect(diagnostics).toHaveLength(1);
+    expect(diagnostics[0]?.rule).toBe('no-sync-result-assumption');
+    expect(diagnostics[0]?.severity).toBe('error');
+    expect(diagnostics[0]?.message).toContain('Missing await');
+  });
+
+  test('flags a stored implementation result that is used synchronously', () => {
+    const code = `
+const result = entityShow.implementation({ id: "1" }, ctx);
+
+if (result.isOk()) {
+  console.log("ok");
+}`;
+
+    const diagnostics = noSyncResultAssumption.check(code, 'src/app.ts');
+
+    expect(diagnostics).toHaveLength(1);
+    expect(diagnostics[0]?.line).toBe(4);
+  });
+
+  test('allows awaited implementation calls before result access', () => {
+    const code = `
+async function run() {
+  const result = await entityShow.implementation({ id: "1" }, ctx);
+  return result.isOk();
+}`;
+
+    const diagnostics = noSyncResultAssumption.check(code, 'src/app.ts');
+
+    expect(diagnostics).toHaveLength(0);
+  });
+
+  test('allows awaited implementation calls when the property access is chained', () => {
+    const code = `
+async function run() {
+  return (await entityShow.implementation({ id: "1" }, ctx)).isOk();
+}`;
+
+    const diagnostics = noSyncResultAssumption.check(code, 'src/app.ts');
+
+    expect(diagnostics).toHaveLength(0);
+  });
+
+  test('ignores test files', () => {
+    const code = `
+const result = entityShow.implementation({ id: "1" }, ctx);
+result.isOk();
+`;
+
+    const diagnostics = noSyncResultAssumption.check(
+      code,
+      'src/__tests__/app.test.ts'
+    );
+
+    expect(diagnostics).toHaveLength(0);
+  });
+
+  test('ignores framework internals that intentionally call implementations', () => {
+    const code = `
+const result = entityShow.implementation({ id: "1" }, ctx);
+result.isOk();
+`;
+
+    const diagnostics = noSyncResultAssumption.check(
+      code,
+      '/repo/packages/testing/src/trail.ts'
+    );
+
+    expect(diagnostics).toHaveLength(0);
+  });
+});

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

@@ -0,0 +1,78 @@
+import { describe, expect, test } from 'bun:test';
+
+import { noThrowInDetourTarget } from '../rules/no-throw-in-detour-target.js';
+
+const TEST_FILE = 'test.ts';
+
+describe('no-throw-in-detour-target', () => {
+  test('flags throw inside a detour target implementation', () => {
+    const code = `
+trail("entity.show", {
+  detours: { NotFoundError: ["entity.fallback"] },
+  implementation: async (input, ctx) => Result.ok({ id: "123" })
+})
+
+trail("entity.fallback", {
+  implementation: async (input, ctx) => {
+    throw new Error("boom");
+  }
+})`;
+
+    const diagnostics = noThrowInDetourTarget.check(code, TEST_FILE);
+
+    expect(diagnostics.length).toBe(1);
+    expect(diagnostics[0]?.rule).toBe('no-throw-in-detour-target');
+    expect(diagnostics[0]?.severity).toBe('error');
+  });
+
+  test('allows throw in implementations that are not detour targets', () => {
+    const code = `
+trail("entity.show", {
+  implementation: async (input, ctx) => {
+    throw new Error("boom");
+  }
+})`;
+
+    const diagnostics = noThrowInDetourTarget.check(code, TEST_FILE);
+
+    expect(diagnostics.length).toBe(0);
+  });
+
+  test('flags concise detour target implementations that throw inline', () => {
+    const code = `
+trail("entity.show", {
+  detours: { NotFoundError: ["entity.fallback"] },
+  implementation: async (input, ctx) => Result.ok({ id: "123" })
+})
+
+trail("entity.fallback", {
+  implementation: async (input, ctx) => { throw new Error("boom"); }
+})`;
+
+    const diagnostics = noThrowInDetourTarget.check(code, TEST_FILE);
+
+    expect(diagnostics.length).toBe(1);
+    expect(diagnostics[0]?.message).toContain('entity.fallback');
+  });
+
+  test('uses project context when the detour target is defined in another file', () => {
+    const code = `
+trail("entity.fallback", {
+  implementation: async (input, ctx) => {
+    throw new Error("boom");
+  }
+})`;
+
+    const diagnostics = noThrowInDetourTarget.checkWithContext(
+      code,
+      TEST_FILE,
+      {
+        detourTargetTrailIds: new Set(['entity.fallback']),
+        knownTrailIds: new Set(['entity.show', 'entity.fallback']),
+      }
+    );
+
+    expect(diagnostics).toHaveLength(1);
+    expect(diagnostics[0]?.rule).toBe('no-throw-in-detour-target');
+  });
+});

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

@@ -0,0 +1,84 @@
+import { describe, expect, test } from 'bun:test';
+
+import { preferSchemaInference } from '../rules/prefer-schema-inference.js';
+
+describe('prefer-schema-inference', () => {
+  test('warns when a fields label only repeats the derived humanized label', () => {
+    const code = `
+trail("entity.show", {
+  input: z.object({ firstName: z.string() }),
+  fields: {
+    firstName: { label: "First Name" },
+  },
+  implementation: (input) => Result.ok(input),
+})`;
+
+    const diagnostics = preferSchemaInference.check(code, 'src/entity.ts');
+
+    expect(diagnostics).toHaveLength(1);
+    expect(diagnostics[0]?.rule).toBe('prefer-schema-inference');
+    expect(diagnostics[0]?.message).toContain('firstName');
+  });
+
+  test('warns when enum options only repeat schema-derived values', () => {
+    const code = `
+trail("entity.paint", {
+  input: z.object({
+    color: z.enum(["red", "green"]),
+  }),
+  fields: {
+    color: {
+      options: [{ value: "red" }, { value: "green" }],
+    },
+  },
+  implementation: (input) => Result.ok(input),
+})`;
+
+    const diagnostics = preferSchemaInference.check(code, 'src/entity.ts');
+
+    expect(diagnostics).toHaveLength(1);
+    expect(diagnostics[0]?.message).toContain('schema-derived options');
+  });
+
+  test('allows custom labels and enriched enum options', () => {
+    const code = `
+trail("entity.paint", {
+  input: z.object({
+    color: z.enum(["red", "green"]),
+    displayName: z.string().describe("Display name"),
+  }),
+  fields: {
+    color: {
+      options: [
+        { value: "red", label: "Red" },
+        { value: "green", hint: "Safe default" },
+      ],
+    },
+    displayName: { label: "Public name" },
+  },
+  implementation: (input) => Result.ok(input),
+})`;
+
+    const diagnostics = preferSchemaInference.check(code, 'src/entity.ts');
+
+    expect(diagnostics).toHaveLength(0);
+  });
+
+  test('does not warn when the override carries other field metadata', () => {
+    const code = `
+trail("entity.show", {
+  input: z.object({ firstName: z.string() }),
+  fields: {
+    firstName: {
+      label: "First Name",
+      message: "Who should we greet?",
+    },
+  },
+  implementation: (input) => Result.ok(input),
+})`;
+
+    const diagnostics = preferSchemaInference.check(code, 'src/entity.ts');
+
+    expect(diagnostics).toHaveLength(0);
+  });
+});

package/src/__tests__/rules.test.ts

@@ -0,0 +1,188 @@
+import { describe, expect, test } from 'bun:test';
+
+import { contextNoSurfaceTypes } from '../rules/context-no-surface-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';
+
+const TEST_FILE = 'test.ts';
+
+// ---------------------------------------------------------------------------
+// no-throw-in-implementation
+// ---------------------------------------------------------------------------
+describe('no-throw-in-implementation', () => {
+  test('flags throw inside implementation body', () => {
+    const code = `
+trail("entity.show", {
+  implementation: async (input, ctx) => {
+    throw new Error("boom");
+  }
+})`;
+    const diagnostics = noThrowInImplementation.check(code, TEST_FILE);
+    expect(diagnostics.length).toBe(1);
+    expect(diagnostics[0]?.rule).toBe('no-throw-in-implementation');
+    expect(diagnostics[0]?.severity).toBe('error');
+  });
+
+  test('allows Result.err() in implementation', () => {
+    const code = `
+trail("entity.show", {
+  implementation: async (input, ctx) => {
+    return Result.err(new NotFoundError("not found"));
+  }
+})`;
+    const diagnostics = noThrowInImplementation.check(code, TEST_FILE);
+    expect(diagnostics.length).toBe(0);
+  });
+
+  test('does not flag throw outside implementation', () => {
+    const code = `
+function helper() {
+  throw new Error("boom");
+}
+
+trail("entity.show", {
+  implementation: async (input, ctx) => {
+    return Result.ok(data);
+  }
+})`;
+    const diagnostics = noThrowInImplementation.check(code, TEST_FILE);
+    expect(diagnostics.length).toBe(0);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// context-no-surface-types
+// ---------------------------------------------------------------------------
+describe('context-no-surface-types', () => {
+  test('flags express import in trail file', () => {
+    const code = `
+import { Request, Response } from "express";
+trail("entity.show", {
+  implementation: async (input, ctx) => {
+    return Result.ok(data);
+  }
+})`;
+    const diagnostics = contextNoSurfaceTypes.check(code, TEST_FILE);
+    expect(diagnostics.length).toBe(1);
+    expect(diagnostics[0]?.rule).toBe('context-no-surface-types');
+    expect(diagnostics[0]?.message).toContain('express');
+  });
+
+  test('flags McpSession import in trail file', () => {
+    const code = `
+import type { McpSession } from "@modelcontextprotocol/sdk";
+trail("entity.show", {
+  implementation: async (input, ctx) => {
+    return Result.ok(data);
+  }
+})`;
+    const diagnostics = contextNoSurfaceTypes.check(code, TEST_FILE);
+    expect(diagnostics.length).toBe(1);
+  });
+
+  test('allows @ontrails/core imports in trail file', () => {
+    const code = `
+import { trail, Result } from "@ontrails/core";
+trail("entity.show", {
+  implementation: async (input, ctx) => {
+    return Result.ok(data);
+  }
+})`;
+    const diagnostics = contextNoSurfaceTypes.check(code, TEST_FILE);
+    expect(diagnostics.length).toBe(0);
+  });
+
+  test('ignores files without trail() calls', () => {
+    const code = `
+import { Request, Response } from "express";
+export function handleRequest(req: Request, res: Response) {}`;
+    const diagnostics = contextNoSurfaceTypes.check(code, TEST_FILE);
+    expect(diagnostics.length).toBe(0);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// valid-detour-refs
+// ---------------------------------------------------------------------------
+describe('valid-detour-refs', () => {
+  test('flags detour target that does not exist', () => {
+    const code = `
+trail("entity.show", {
+  detours: [{ target: "entity.edit" }],
+  implementation: async (input, ctx) => Result.ok(data)
+})`;
+    const diagnostics = validDetourRefs.check(code, TEST_FILE);
+    expect(diagnostics.length).toBe(1);
+    expect(diagnostics[0]?.message).toContain('entity.edit');
+  });
+
+  test('passes when detour target exists', () => {
+    const code = `
+trail("entity.edit", {
+  implementation: async (input, ctx) => Result.ok(data)
+})
+
+trail("entity.show", {
+  detours: [{ target: "entity.edit" }],
+  implementation: async (input, ctx) => Result.ok(data)
+})`;
+    const diagnostics = validDetourRefs.check(code, TEST_FILE);
+    expect(diagnostics.length).toBe(0);
+  });
+
+  test('uses project context when available', () => {
+    const code = `
+trail("entity.show", {
+  detours: [{ target: "entity.edit" }],
+  implementation: async (input, ctx) => Result.ok(data)
+})`;
+    const context = { knownTrailIds: new Set(['entity.show', 'entity.edit']) };
+    const diagnostics = validDetourRefs.checkWithContext(
+      code,
+      TEST_FILE,
+      context
+    );
+    expect(diagnostics.length).toBe(0);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// no-direct-impl-in-route
+// ---------------------------------------------------------------------------
+describe('no-direct-impl-in-route', () => {
+  test('warns on direct .implementation() call in route', () => {
+    const code = `
+hike("entity.onboard", {
+  follows: ["entity.create"],
+  implementation: async (input, ctx) => {
+    const result = await entityCreate.implementation(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');
+  });
+
+  test('allows ctx.follow() calls', () => {
+    const code = `
+hike("entity.onboard", {
+  follows: ["entity.create"],
+  implementation: async (input, ctx) => {
+    const result = await ctx.follow("entity.create", data);
+    return Result.ok(result);
+  }
+})`;
+    const diagnostics = noDirectImplInRoute.check(code, TEST_FILE);
+    expect(diagnostics.length).toBe(0);
+  });
+
+  test('ignores files without hike() calls', () => {
+    const code = `
+const result = await someTrail.implementation(data);`;
+    const diagnostics = noDirectImplInRoute.check(code, TEST_FILE);
+    expect(diagnostics.length).toBe(0);
+  });
+});

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

@@ -0,0 +1,60 @@
+import { describe, expect, test } from 'bun:test';
+
+import { validDescribeRefs } from '../rules/valid-describe-refs.js';
+
+describe('valid-describe-refs', () => {
+  test('warns when a describe @see tag points to a missing trail', () => {
+    const code = `
+trail("entity.show", {
+  input: z.object({
+    query: z.string().describe("Search query. @see entity.search"),
+  }),
+  implementation: (input) => Result.ok(input),
+})`;
+
+    const diagnostics = validDescribeRefs.check(code, 'src/entity.ts');
+
+    expect(diagnostics).toHaveLength(1);
+    expect(diagnostics[0]?.rule).toBe('valid-describe-refs');
+    expect(diagnostics[0]?.message).toContain('entity.search');
+  });
+
+  test('allows local @see references that resolve in the same file', () => {
+    const code = `
+trail("entity.search", {
+  input: z.object({ query: z.string() }),
+  implementation: (input) => Result.ok(input),
+})
+
+trail("entity.show", {
+  input: z.object({
+    query: z.string().describe("Search query. @see entity.search"),
+  }),
+  implementation: (input) => Result.ok(input),
+})`;
+
+    const diagnostics = validDescribeRefs.check(code, 'src/entity.ts');
+
+    expect(diagnostics).toHaveLength(0);
+  });
+
+  test('uses project context for cross-file @see references', () => {
+    const code = `
+trail("entity.show", {
+  input: z.object({
+    query: z.string().describe("Search query. @see entity.search"),
+  }),
+  implementation: (input) => Result.ok(input),
+})`;
+
+    const diagnostics = validDescribeRefs.checkWithContext(
+      code,
+      'src/entity.ts',
+      {
+        knownTrailIds: new Set(['entity.search', 'entity.show']),
+      }
+    );
+
+    expect(diagnostics).toHaveLength(0);
+  });
+});