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

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

@@ -0,0 +1,93 @@
+import { describe, expect, test } from 'bun:test';
+
+import { noThrowInDetourRecover } from '../rules/no-throw-in-detour-recover.js';
+
+const TEST_FILE = 'detour.ts';
+
+describe('no-throw-in-detour-recover', () => {
+  test('flags throw inside an inline detour recover function', () => {
+    const code = `
+trail("entity.save", {
+  detours: [
+    {
+      on: ConflictError,
+      recover: async () => {
+        throw new Error("boom");
+      },
+    },
+  ],
+  blaze: () => Result.err(new ConflictError("conflict")),
+})`;
+
+    const diagnostics = noThrowInDetourRecover.check(code, TEST_FILE);
+
+    expect(diagnostics).toHaveLength(1);
+    expect(diagnostics[0]?.rule).toBe('no-throw-in-detour-recover');
+    expect(diagnostics[0]?.severity).toBe('error');
+  });
+
+  test('flags throw inside a detour recover function declaration binding', () => {
+    const code = `
+async function recoverConflict() {
+  throw new Error("boom");
+}
+
+trail("entity.save", {
+  detours: [
+    {
+      on: ConflictError,
+      recover: recoverConflict,
+    },
+  ],
+  blaze: () => Result.err(new ConflictError("conflict")),
+})`;
+
+    const diagnostics = noThrowInDetourRecover.check(code, TEST_FILE);
+
+    expect(diagnostics).toHaveLength(1);
+    expect(diagnostics[0]?.message).toContain('detour[0]');
+  });
+
+  test('does not flag throw inside a nested callback within recover', () => {
+    const code = `
+trail("entity.save", {
+  detours: [
+    {
+      on: ConflictError,
+      recover: async () => {
+        [1].map(() => {
+          throw new Error("inner");
+        });
+        return Result.err(new ConflictError("still conflicting"));
+      },
+    },
+  ],
+  blaze: () => Result.err(new ConflictError("conflict")),
+})`;
+
+    const diagnostics = noThrowInDetourRecover.check(code, TEST_FILE);
+
+    expect(diagnostics).toEqual([]);
+  });
+
+  test('ignores throws outside detour recover functions', () => {
+    const code = `
+function helper() {
+  throw new Error("boom");
+}
+
+trail("entity.save", {
+  detours: [
+    {
+      on: ConflictError,
+      recover: async () => Result.err(new ConflictError("still conflicting")),
+    },
+  ],
+  blaze: () => Result.err(new ConflictError("conflict")),
+})`;
+
+    const diagnostics = noThrowInDetourRecover.check(code, TEST_FILE);
+
+    expect(diagnostics).toEqual([]);
+  });
+});

package/src/__tests__/no-throw-in-implementation.test.ts

@@ -0,0 +1,88 @@
+import { describe, expect, test } from 'bun:test';
+
+import { noThrowInImplementation } from '../rules/no-throw-in-implementation.js';
+
+const TEST_FILE = 'test.ts';
+
+describe('no-throw-in-implementation', () => {
+  test('flags direct throw inside blaze body', () => {
+    const code = `
+trail("entity.show", {
+  blaze: 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 blaze body', () => {
+    const code = `
+trail("entity.show", {
+  blaze: 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 inside a nested .map() callback', () => {
+    const code = `
+trail("demo", {
+  blaze: async () => {
+    [1].map(() => {
+      throw new Error("boom");
+    });
+    return Result.ok({ ok: true });
+  }
+})`;
+    const diagnostics = noThrowInImplementation.check(code, TEST_FILE);
+    expect(diagnostics).toHaveLength(0);
+  });
+
+  test('does not flag throw inside a nested .filter() callback', () => {
+    const code = `
+trail("demo", {
+  blaze: async () => {
+    [1].filter(() => {
+      throw new Error("boom");
+    });
+    return Result.ok({ ok: true });
+  }
+})`;
+    const diagnostics = noThrowInImplementation.check(code, TEST_FILE);
+    expect(diagnostics).toHaveLength(0);
+  });
+
+  test('does not flag throw inside a nested function declaration', () => {
+    const code = `
+trail("demo", {
+  blaze: async () => {
+    function helper() {
+      throw new Error("boom");
+    }
+    return Result.ok({ ok: true });
+  }
+})`;
+    const diagnostics = noThrowInImplementation.check(code, TEST_FILE);
+    expect(diagnostics).toHaveLength(0);
+  });
+
+  test('still flags direct throw alongside a safe nested callback', () => {
+    const code = `
+trail("demo", {
+  blaze: async () => {
+    [1].map(() => {
+      throw new Error("inner — allowed");
+    });
+    throw new Error("outer — flagged");
+  }
+})`;
+    const diagnostics = noThrowInImplementation.check(code, TEST_FILE);
+    expect(diagnostics).toHaveLength(1);
+    expect(diagnostics[0]?.rule).toBe('no-throw-in-implementation');
+  });
+});

package/src/__tests__/on-references-exist.test.ts

@@ -0,0 +1,151 @@
+import { describe, expect, test } from 'bun:test';
+
+import { onReferencesExist } from '../rules/on-references-exist.js';
+
+const TEST_FILE = 'consumer.ts';
+
+describe('on-references-exist', () => {
+  test('passes when a locally defined signal is referenced', () => {
+    const code = `
+import { signal, trail, Result } from '@ontrails/core';
+import { z } from 'zod';
+
+const created = signal('entity.created', { payload: z.object({ id: z.string() }) });
+
+trail('notify', {
+  on: ['entity.created'],
+  input: z.object({ id: z.string() }),
+  blaze: async (input, ctx) => Result.ok({}),
+});
+`;
+
+    expect(onReferencesExist.check(code, TEST_FILE)).toEqual([]);
+  });
+
+  test('flags an on: reference missing from project context', () => {
+    const code = `
+import { trail, Result } from '@ontrails/core';
+
+trail('notify', {
+  on: ['entity.created'],
+  blaze: async (input, ctx) => Result.ok({}),
+});
+`;
+
+    const diagnostics = onReferencesExist.checkWithContext(code, TEST_FILE, {
+      knownSignalIds: new Set(['some.other.signal']),
+      knownTrailIds: new Set(['notify']),
+    });
+
+    expect(diagnostics).toHaveLength(1);
+    expect(diagnostics[0]?.rule).toBe('on-references-exist');
+    expect(diagnostics[0]?.severity).toBe('error');
+    expect(diagnostics[0]?.message).toContain('entity.created');
+  });
+
+  test('passes when project context includes the referenced signal', () => {
+    const code = `
+import { trail, Result } from '@ontrails/core';
+
+trail('notify', {
+  on: ['entity.created'],
+  blaze: async (input, ctx) => Result.ok({}),
+});
+`;
+
+    const diagnostics = onReferencesExist.checkWithContext(code, TEST_FILE, {
+      knownSignalIds: new Set(['entity.created']),
+      knownTrailIds: new Set(['notify']),
+    });
+
+    expect(diagnostics).toEqual([]);
+  });
+
+  test('flags only the unresolved id when multiple references are present', () => {
+    const code = `
+import { trail, Result } from '@ontrails/core';
+
+trail('notify', {
+  on: ['entity.created', 'audit.logged'],
+  blaze: async (input, ctx) => Result.ok({}),
+});
+`;
+
+    const diagnostics = onReferencesExist.checkWithContext(code, TEST_FILE, {
+      knownSignalIds: new Set(['entity.created']),
+      knownTrailIds: new Set(['notify']),
+    });
+
+    expect(diagnostics).toHaveLength(1);
+    expect(diagnostics[0]?.message).toContain('audit.logged');
+  });
+
+  test('skips trails with no on: declaration', () => {
+    const code = `
+import { trail, Result } from '@ontrails/core';
+
+trail('plain', {
+  blaze: async (input, ctx) => Result.ok({}),
+});
+`;
+
+    expect(
+      onReferencesExist.checkWithContext(code, TEST_FILE, {
+        knownSignalIds: new Set(),
+        knownTrailIds: new Set(['plain']),
+      })
+    ).toEqual([]);
+  });
+
+  test('resolves const identifiers in on: array', () => {
+    const code = `
+import { trail, Result } from '@ontrails/core';
+
+const ENTITY_CREATED = 'entity.created';
+
+trail('notify', {
+  on: [ENTITY_CREATED],
+  blaze: async (input, ctx) => Result.ok({}),
+});
+`;
+
+    const diagnostics = onReferencesExist.checkWithContext(code, TEST_FILE, {
+      knownSignalIds: new Set(['entity.created']),
+      knownTrailIds: new Set(['notify']),
+    });
+
+    expect(diagnostics).toEqual([]);
+  });
+
+  test('skips test files', () => {
+    const code = `
+trail('notify', {
+  on: ['unknown.signal'],
+  blaze: async (input, ctx) => Result.ok({}),
+});
+`;
+
+    expect(
+      onReferencesExist.check(code, 'src/__tests__/notify.test.ts')
+    ).toEqual([]);
+  });
+
+  test('skips object-form Signal value references without error', () => {
+    const code = `
+import { trail, signal, Result } from '@ontrails/core';
+const orderPlaced = signal('order.placed', { payload: z.object({}) });
+trail('notify', {
+  on: [orderPlaced],
+  blaze: async (input, ctx) => Result.ok({}),
+});
+`;
+
+    // Even without registering 'order.placed' as known, the object-form entry
+    // is skipped — runtime normalization is the source of truth.
+    const diagnostics = onReferencesExist.checkWithContext(code, TEST_FILE, {
+      knownSignalIds: new Set(),
+      knownTrailIds: new Set(['notify']),
+    });
+    expect(diagnostics).toEqual([]);
+  });
+});

package/src/__tests__/orphaned-signal.test.ts

@@ -0,0 +1,137 @@
+import { describe, expect, test } from 'bun:test';
+
+import { orphanedSignal } from '../rules/orphaned-signal.js';
+
+const TEST_FILE = 'store.ts';
+
+describe('orphaned-signal', () => {
+  test('warns when a crud-backed store table has no reactive consumers for its change signals', () => {
+    const code = `
+import { Result, resource } from '@ontrails/core';
+import { store } from '@ontrails/store';
+import { crud } from '@ontrails/store/trails';
+import { z } from 'zod';
+
+const definition = store({
+  notes: {
+    identity: 'id',
+    schema: z.object({
+      id: z.string(),
+      title: z.string(),
+    }),
+  },
+});
+
+const notesResource = resource('db.notes', {
+  create: () => Result.ok({}),
+  mock: () => ({}),
+});
+
+const noteTrails = crud(definition.tables.notes, notesResource);
+`;
+
+    const diagnostics = orphanedSignal.check(code, TEST_FILE);
+
+    expect(diagnostics).toHaveLength(1);
+    expect(diagnostics[0]?.rule).toBe('orphaned-signal');
+    expect(diagnostics[0]?.severity).toBe('warn');
+    expect(diagnostics[0]?.message).toContain('notes');
+    expect(diagnostics[0]?.message).toContain('notes.created');
+    expect(diagnostics[0]?.message).toContain('notes.updated');
+    expect(diagnostics[0]?.message).toContain('notes.removed');
+  });
+
+  test('stays quiet when all derived change signals are consumed elsewhere in the project', () => {
+    const code = `
+import { store } from '@ontrails/store';
+import { z } from 'zod';
+
+const definition = store({
+  notes: {
+    identity: 'id',
+    schema: z.object({
+      id: z.string(),
+      title: z.string(),
+    }),
+  },
+});
+`;
+
+    const diagnostics = orphanedSignal.checkWithContext(code, TEST_FILE, {
+      // Keys are composite (`${storeBinding}:${tableName}`) so two stores
+      // that share a table name don't collide across files.
+      crudTableIds: new Set(['definition:notes']),
+      knownTrailIds: new Set(['notes.notify']),
+      onTargetSignalIds: new Set([
+        'definition:notes.created',
+        'definition:notes.updated',
+        'definition:notes.removed',
+      ]),
+    });
+
+    expect(diagnostics).toEqual([]);
+  });
+
+  test('tracks two stores with colliding table names independently', () => {
+    const code = `
+import { Result, resource } from '@ontrails/core';
+import { store } from '@ontrails/store';
+import { crud } from '@ontrails/store/trails';
+import { z } from 'zod';
+
+const primary = store({
+  notes: {
+    identity: 'id',
+    schema: z.object({ id: z.string(), title: z.string() }),
+  },
+});
+
+const archive = store({
+  notes: {
+    identity: 'id',
+    schema: z.object({ id: z.string(), title: z.string() }),
+  },
+});
+
+const primaryResource = resource('db.primary', {
+  create: () => Result.ok({}),
+  mock: () => ({}),
+});
+const archiveResource = resource('db.archive', {
+  create: () => Result.ok({}),
+  mock: () => ({}),
+});
+
+const primaryTrails = crud(primary.tables.notes, primaryResource);
+const archiveTrails = crud(archive.tables.notes, archiveResource);
+`;
+
+    const diagnostics = orphanedSignal.check(code, TEST_FILE);
+
+    // Both stores warn, but independently — not one combined message.
+    expect(diagnostics).toHaveLength(2);
+    for (const diagnostic of diagnostics) {
+      expect(diagnostic.rule).toBe('orphaned-signal');
+      expect(diagnostic.message).toContain('notes');
+    }
+  });
+
+  test('stays quiet when the table is not used with crud()', () => {
+    const code = `
+import { store } from '@ontrails/store';
+import { z } from 'zod';
+
+const definition = store({
+  notes: {
+    identity: 'id',
+    schema: z.object({
+      id: z.string(),
+      title: z.string(),
+    }),
+  },
+});
+`;
+
+    expect(orphanedSignal.check(code, TEST_FILE)).toEqual([]);
+  });
+});

package/src/__tests__/permit-governance.test.ts

@@ -0,0 +1,66 @@
+import { describe, expect, test } from 'bun:test';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+
+import { Result, topo, trail } from '@ontrails/core';
+import { z } from 'zod';
+
+import { runWarden } from '../cli.js';
+import { permitGovernance } from '../rules/permit-governance.js';
+
+describe('permitGovernance', () => {
+  test('emits permit diagnostics from the compiled topo', async () => {
+    const destroyTrail = trail('entity.delete', {
+      blaze: () => Result.ok({ ok: true }),
+      input: z.object({}),
+      intent: 'destroy',
+      output: z.object({ ok: z.boolean() }),
+    });
+
+    const diagnostics = await permitGovernance.checkTopo(
+      topo('permit-topo', { destroyTrail })
+    );
+
+    expect(diagnostics).toEqual([
+      {
+        filePath: '<topo>',
+        line: 1,
+        message:
+          'Trail "entity.delete" has intent \'destroy\' but no permit declaration',
+        rule: 'permit.destroyWithoutPermit',
+        severity: 'error',
+      },
+    ]);
+  });
+
+  test('runWarden includes permit governance when topo is supplied', async () => {
+    const rootDir = mkdtempSync(join(tmpdir(), 'warden-permit-'));
+    const destroyTrail = trail('entity.delete', {
+      blaze: () => Result.ok({ ok: true }),
+      input: z.object({}),
+      intent: 'destroy',
+      output: z.object({ ok: z.boolean() }),
+    });
+
+    try {
+      const report = await runWarden({
+        rootDir,
+        topo: topo('permit-topo', { destroyTrail }),
+      });
+
+      expect(report.diagnostics).toEqual(
+        expect.arrayContaining([
+          expect.objectContaining({
+            message: expect.stringContaining('no permit declaration'),
+            rule: 'permit.destroyWithoutPermit',
+            severity: 'error',
+          }),
+        ])
+      );
+      expect(report.errorCount).toBeGreaterThan(0);
+    } finally {
+      rmSync(rootDir, { force: true, recursive: true });
+    }
+  });
+});