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

package/src/__tests__/rules.test.ts

@@ -1,9 +1,8 @@
 import { describe, expect, test } from 'bun:test';
 
-import { contextNoTrailheadTypes } from '../rules/context-no-trailhead-types.js';
+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';
 
@@ -52,9 +51,9 @@ trail("entity.show", {
 });
 
 // ---------------------------------------------------------------------------
-// context-no-trailhead-types
+// context-no-surface-types
 // ---------------------------------------------------------------------------
-describe('context-no-trailhead-types', () => {
+describe('context-no-surface-types', () => {
   test('flags express import in trail file', () => {
     const code = `
 import { Request, Response } from "express";
@@ -63,9 +62,9 @@ trail("entity.show", {
     return Result.ok(data);
   }
 })`;
-    const diagnostics = contextNoTrailheadTypes.check(code, TEST_FILE);
+    const diagnostics = contextNoSurfaceTypes.check(code, TEST_FILE);
     expect(diagnostics.length).toBe(1);
-    expect(diagnostics[0]?.rule).toBe('context-no-trailhead-types');
+    expect(diagnostics[0]?.rule).toBe('context-no-surface-types');
     expect(diagnostics[0]?.message).toContain('express');
   });
 
@@ -77,7 +76,7 @@ trail("entity.show", {
     return Result.ok(data);
   }
 })`;
-    const diagnostics = contextNoTrailheadTypes.check(code, TEST_FILE);
+    const diagnostics = contextNoSurfaceTypes.check(code, TEST_FILE);
     expect(diagnostics.length).toBe(1);
   });
 
@@ -89,7 +88,7 @@ trail("entity.show", {
     return Result.ok(data);
   }
 })`;
-    const diagnostics = contextNoTrailheadTypes.check(code, TEST_FILE);
+    const diagnostics = contextNoSurfaceTypes.check(code, TEST_FILE);
     expect(diagnostics.length).toBe(0);
   });
 
@@ -97,79 +96,20 @@ trail("entity.show", {
     const code = `
 import { Request, Response } from "express";
 export function handleRequest(req: Request, res: Response) {}`;
-    const diagnostics = contextNoTrailheadTypes.check(code, TEST_FILE);
+    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" }],
-  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.edit');
-  });
 
-  test('passes when detour target exists', () => {
+  test('ignores computed member access like ns[trail]()', () => {
+    // Computed bracket access may resolve to any runtime value; it must not
+    // be treated as a trail() call just because the key is an identifier
+    // literally named `trail`.
     const code = `
-trail("entity.edit", {
-  blaze: async (input, ctx) => Result.ok(data)
-})
-
-trail("entity.show", {
-  detours: [{ target: "entity.edit" }],
-  blaze: 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" }],
-  blaze: 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);
-  });
-
-  test('flags detour target in trail with crossings that does not exist', () => {
-    const code = `
-trail("entity.onboard", {
-  detours: [{ target: "entity.missing" }],
-  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 crossings detour target exists', () => {
-    const code = `
-trail("entity.fallback", {
-  blaze: async (input, ctx) => Result.ok(data)
-})
-
-trail("entity.onboard", {
-  detours: [{ target: "entity.fallback" }],
-  crosses: ["entity.create"],
-  blaze: async (input, ctx) => Result.ok(data)
-})`;
-    const diagnostics = validDetourRefs.check(code, TEST_FILE);
+import { Request, Response } from "express";
+const trail = "entity.show";
+ns[trail]("entity.show", { blaze: async () => Result.ok(null) });
+export function handleRequest(req: Request, res: Response) {}`;
+    const diagnostics = contextNoSurfaceTypes.check(code, TEST_FILE);
     expect(diagnostics.length).toBe(0);
   });
 });

package/src/__tests__/topo-aware-rule.test.ts

@@ -0,0 +1,257 @@
+/**
+ * End-to-end dispatch test for `TopoAwareWardenRule`.
+ *
+ * Exercises the CLI → topo-aware rule dispatch path with a no-op mock rule
+ * injected via `extraTopoRules`. Proves the plumbing works without shipping
+ * any production topo-aware rule.
+ */
+
+import { describe, expect, test } from 'bun:test';
+import { mkdirSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { createTrailContext, topo, trail, Result } from '@ontrails/core';
+import { z } from 'zod';
+
+import { runWarden } from '../cli.js';
+import type { TopoAwareWardenRule, WardenDiagnostic } from '../rules/types.js';
+import { topoAwareRuleInput } from '../trails/schema.js';
+import { wrapTopoRule } from '../trails/wrap-rule.js';
+
+const makeTempDir = (): string => {
+  const dir = join(
+    tmpdir(),
+    `warden-topo-aware-test-${Date.now()}-${Math.random().toString(36).slice(2)}`
+  );
+  mkdirSync(dir, { recursive: true });
+  return dir;
+};
+
+const buildFixtureTopo = () => {
+  const echo = trail('fixture.echo', {
+    blaze: (input: { value: string }) => Result.ok({ value: input.value }),
+    description: 'echo',
+    examples: [
+      {
+        expected: { value: 'a' },
+        input: { value: 'a' },
+        name: 'roundtrips',
+      },
+    ],
+    input: z.object({ value: z.string() }),
+    intent: 'read',
+    output: z.object({ value: z.string() }),
+  });
+  return topo('fixture', { echo });
+};
+
+const PLACEHOLDER_FINDING: WardenDiagnostic = {
+  filePath: '<topo>',
+  line: 1,
+  message: 'synthetic topo-level finding',
+  rule: 'placeholder-topo-aware',
+  severity: 'warn',
+};
+
+const buildPlaceholderRule = (seen: string[]): TopoAwareWardenRule => ({
+  checkTopo: (inspectedTopo) => {
+    seen.push(inspectedTopo.name);
+    return [PLACEHOLDER_FINDING];
+  },
+  description: 'placeholder rule returning one diagnostic',
+  name: 'placeholder-topo-aware',
+  severity: 'warn',
+});
+
+describe('TopoAwareWardenRule dispatch', () => {
+  test('CLI dispatches injected topo-aware rules and aggregates diagnostics into the report', async () => {
+    const dir = makeTempDir();
+    try {
+      const seen: string[] = [];
+      const report = await runWarden({
+        extraTopoRules: [buildPlaceholderRule(seen)],
+        lintOnly: true,
+        rootDir: dir,
+        topo: buildFixtureTopo(),
+      });
+      const emitted = report.diagnostics.filter(
+        (d) => d.rule === 'placeholder-topo-aware'
+      );
+
+      expect(seen).toEqual(['fixture']);
+      expect(emitted).toHaveLength(1);
+      expect(emitted[0]).toEqual(PLACEHOLDER_FINDING);
+      expect(report.warnCount).toBeGreaterThanOrEqual(1);
+    } finally {
+      rmSync(dir, { force: true, recursive: true });
+    }
+  });
+
+  test('CLI skips topo-aware rules when no topo is provided', async () => {
+    const dir = makeTempDir();
+    try {
+      let invoked = false;
+      const placeholder: TopoAwareWardenRule = {
+        checkTopo: () => {
+          invoked = true;
+          return [];
+        },
+        description: 'placeholder',
+        name: 'placeholder-unused',
+        severity: 'warn',
+      };
+
+      await runWarden({
+        extraTopoRules: [placeholder],
+        lintOnly: true,
+        rootDir: dir,
+      });
+
+      expect(invoked).toBe(false);
+    } finally {
+      rmSync(dir, { force: true, recursive: true });
+    }
+  });
+
+  test('wrapTopoRule flows diagnostics through the trail pipeline', async () => {
+    const diagnostic: WardenDiagnostic = {
+      filePath: '<topo>',
+      line: 1,
+      message: 'synthetic finding',
+      rule: 'synthetic-topo-rule',
+      severity: 'warn',
+    };
+    const placeholder: TopoAwareWardenRule = {
+      checkTopo: () => [diagnostic],
+      description: 'synthetic',
+      name: 'synthetic-topo-rule',
+      severity: 'warn',
+    };
+
+    const wrapped = wrapTopoRule({ examples: [], rule: placeholder });
+    const result = await wrapped.blaze(
+      { topo: buildFixtureTopo() },
+      createTrailContext()
+    );
+
+    expect(result.isOk()).toBe(true);
+    expect(result.unwrap()).toEqual({ diagnostics: [diagnostic] });
+    expect(wrapped.id).toBe('warden.rule.synthetic-topo-rule');
+  });
+
+  test('CLI awaits async topo-aware rules before aggregating diagnostics', async () => {
+    const dir = makeTempDir();
+    try {
+      const seen: string[] = [];
+      const asyncRule: TopoAwareWardenRule = {
+        checkTopo(inspectedTopo) {
+          seen.push(inspectedTopo.name);
+          return Promise.resolve([
+            {
+              ...PLACEHOLDER_FINDING,
+              rule: 'async-placeholder-topo-aware',
+            },
+          ]);
+        },
+        description: 'async placeholder',
+        name: 'async-placeholder-topo-aware',
+        severity: 'warn',
+      };
+
+      const report = await runWarden({
+        extraTopoRules: [asyncRule],
+        lintOnly: true,
+        rootDir: dir,
+        topo: buildFixtureTopo(),
+      });
+
+      expect(seen).toEqual(['fixture']);
+      expect(
+        report.diagnostics.filter(
+          (d) => d.rule === 'async-placeholder-topo-aware'
+        )
+      ).toEqual([
+        { ...PLACEHOLDER_FINDING, rule: 'async-placeholder-topo-aware' },
+      ]);
+    } finally {
+      rmSync(dir, { force: true, recursive: true });
+    }
+  });
+
+  test('CLI converts thrown topo-aware rule errors into diagnostics', async () => {
+    const dir = makeTempDir();
+    try {
+      const report = await runWarden({
+        extraTopoRules: [
+          {
+            checkTopo: () => {
+              throw new Error('graph shape changed unexpectedly');
+            },
+            description: 'rule that throws',
+            name: 'throwing-topo-rule',
+            severity: 'error',
+          },
+        ],
+        lintOnly: true,
+        rootDir: dir,
+        topo: buildFixtureTopo(),
+      });
+
+      expect(
+        report.diagnostics.filter((d) => d.rule === 'throwing-topo-rule')
+      ).toEqual([
+        {
+          filePath: '<topo>',
+          line: 1,
+          message:
+            'Topo-aware rule "throwing-topo-rule" threw: graph shape changed unexpectedly',
+          rule: 'throwing-topo-rule',
+          severity: 'error',
+        },
+      ]);
+      expect(report.errorCount).toBeGreaterThanOrEqual(1);
+    } finally {
+      rmSync(dir, { force: true, recursive: true });
+    }
+  });
+
+  test('topoAwareRuleInput rejects partial topo-shaped objects', () => {
+    const result = topoAwareRuleInput.safeParse({
+      topo: {
+        resources: new Map(),
+        trails: new Map(),
+      },
+    });
+
+    expect(result.success).toBe(false);
+  });
+
+  test('wrapTopoRule converts thrown errors into Result.err with InternalError', async () => {
+    const throwing: TopoAwareWardenRule = {
+      checkTopo: () => {
+        throw new Error('graph shape changed unexpectedly');
+      },
+      description: 'rule that throws',
+      name: 'throwing-topo-rule',
+      severity: 'error',
+    };
+
+    const wrapped = wrapTopoRule({ examples: [], rule: throwing });
+    const result = await wrapped.blaze(
+      { topo: buildFixtureTopo() },
+      createTrailContext()
+    );
+
+    expect(result.isErr()).toBe(true);
+    const err = result.match({
+      err: (e) => e,
+      ok: () => {
+        throw new Error('expected Result.err');
+      },
+    });
+    expect(err.name).toBe('InternalError');
+    expect(err.message).toContain('throwing-topo-rule');
+    expect(err.message).toContain('graph shape changed unexpectedly');
+  });
+});

package/src/__tests__/trails.test.ts

@@ -7,8 +7,8 @@ import { wardenTopo } from '../trails/topo.js';
 testAll(wardenTopo);
 
 describe('wardenTopo', () => {
-  test('contains all 13 rule trails', () => {
-    expect(wardenTopo.count).toBe(13);
+  test('contains all 34 rule trails', () => {
+    expect(wardenTopo.count).toBe(34);
   });
 
   test('all trail IDs follow warden.rule.* naming', () => {

package/src/__tests__/unreachable-detour-shadowing.test.ts

@@ -0,0 +1,128 @@
+import { describe, expect, test } from 'bun:test';
+
+import { unreachableDetourShadowing } from '../rules/unreachable-detour-shadowing.js';
+
+const TEST_FILE = 'detour.ts';
+
+describe('unreachable-detour-shadowing', () => {
+  test('passes when the more specific detour is declared first', () => {
+    const code = `
+trail('entity.save', {
+  detours: [
+    { on: ConflictError, recover: async () => Result.ok({ winner: 'specific' }) },
+    { on: TrailsError, recover: async () => Result.ok({ winner: 'broad' }) },
+  ],
+});
+`;
+
+    expect(unreachableDetourShadowing.check(code, TEST_FILE)).toEqual([]);
+  });
+
+  test('flags a later detour shadowed by an earlier broader core error type', () => {
+    const code = `
+trail('entity.save', {
+  detours: [
+    { on: TrailsError, recover: async () => Result.ok({ winner: 'broad' }) },
+    { on: ConflictError, recover: async () => Result.ok({ winner: 'specific' }) },
+  ],
+});
+`;
+
+    const diagnostics = unreachableDetourShadowing.check(code, TEST_FILE);
+
+    expect(diagnostics).toHaveLength(1);
+    expect(diagnostics[0]?.rule).toBe('unreachable-detour-shadowing');
+    expect(diagnostics[0]?.severity).toBe('error');
+    expect(diagnostics[0]?.message).toContain('TrailsError');
+    expect(diagnostics[0]?.message).toContain('ConflictError');
+  });
+
+  test('flags a later local subclass shadowed by its parent detour', () => {
+    const code = `
+class StoreConflictError extends ConflictError {}
+
+trail('entity.save', {
+  detours: [
+    { on: ConflictError, recover: async () => Result.ok({ winner: 'parent' }) },
+    { on: StoreConflictError, recover: async () => Result.ok({ winner: 'child' }) },
+  ],
+});
+`;
+
+    const diagnostics = unreachableDetourShadowing.check(code, TEST_FILE);
+
+    expect(diagnostics).toHaveLength(1);
+    expect(diagnostics[0]?.message).toContain('ConflictError');
+    expect(diagnostics[0]?.message).toContain('StoreConflictError');
+  });
+
+  test('flags a later detour shadowed by an earlier DerivationError detour', () => {
+    const code = `
+trail('entity.derive', {
+  detours: [
+    { on: DerivationError, recover: async () => Result.ok({ winner: 'broad' }) },
+    { on: DerivationError, recover: async () => Result.ok({ winner: 'dup' }) },
+  ],
+});
+`;
+
+    const diagnostics = unreachableDetourShadowing.check(code, TEST_FILE);
+
+    expect(diagnostics).toHaveLength(1);
+    expect(diagnostics[0]?.message).toContain('DerivationError');
+  });
+
+  test('flags a later detour shadowed by a ClassExpression-bound local subclass', () => {
+    const code = `
+const StoreConflictError = class extends ConflictError {};
+
+trail('entity.save', {
+  detours: [
+    { on: ConflictError, recover: async () => Result.ok({ winner: 'parent' }) },
+    { on: StoreConflictError, recover: async () => Result.ok({ winner: 'child' }) },
+  ],
+});
+`;
+
+    const diagnostics = unreachableDetourShadowing.check(code, TEST_FILE);
+
+    expect(diagnostics).toHaveLength(1);
+    expect(diagnostics[0]?.message).toContain('ConflictError');
+    expect(diagnostics[0]?.message).toContain('StoreConflictError');
+  });
+
+  test('tolerates sparse holes in the detours array', () => {
+    const code = `
+trail('entity.save', {
+  detours: [
+    ,
+    { on: TrailsError, recover: async () => Result.ok({ winner: 'broad' }) },
+    ,
+    { on: ConflictError, recover: async () => Result.ok({ winner: 'specific' }) },
+  ],
+});
+`;
+
+    let diagnostics: readonly { message: string }[] = [];
+    expect(() => {
+      diagnostics = unreachableDetourShadowing.check(code, TEST_FILE);
+    }).not.toThrow();
+
+    expect(diagnostics).toHaveLength(1);
+    expect(diagnostics[0]?.message).toContain('TrailsError');
+    expect(diagnostics[0]?.message).toContain('ConflictError');
+  });
+
+  test('does not flag unrelated sibling error types', () => {
+    const code = `
+trail('entity.save', {
+  detours: [
+    { on: ConflictError, recover: async () => Result.ok({ winner: 'conflict' }) },
+    { on: ValidationError, recover: async () => Result.ok({ winner: 'validation' }) },
+  ],
+});
+`;
+
+    expect(unreachableDetourShadowing.check(code, TEST_FILE)).toEqual([]);
+  });
+});