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

package/src/__tests__/circular-refs.test.ts

@@ -0,0 +1,121 @@
+import { describe, expect, test } from 'bun:test';
+
+import { circularRefs } from '../rules/circular-refs.js';
+
+const TEST_FILE = 'contours.ts';
+
+describe('circular-refs', () => {
+  test('passes when contour references are acyclic', () => {
+    const code = `
+import { contour } from '@ontrails/core';
+import { z } from 'zod';
+
+const user = contour('user', {
+  id: z.string().uuid(),
+}, { identity: 'id' });
+
+const gist = contour('gist', {
+  id: z.string().uuid(),
+  ownerId: user.id(),
+}, { identity: 'id' });
+`;
+
+    expect(circularRefs.check(code, TEST_FILE)).toEqual([]);
+  });
+
+  test('warns on direct local contour cycles', () => {
+    const code = `
+import { contour } from '@ontrails/core';
+import { z } from 'zod';
+
+const user = contour('user', {
+  gistId: gist.id(),
+  id: z.string().uuid(),
+}, { identity: 'id' });
+
+const gist = contour('gist', {
+  id: z.string().uuid(),
+  ownerId: user.id(),
+}, { identity: 'id' });
+`;
+
+    const diagnostics = circularRefs.check(code, TEST_FILE);
+
+    expect(diagnostics).toHaveLength(2);
+    expect(diagnostics[0]?.rule).toBe('circular-refs');
+    expect(diagnostics[0]?.message).toContain('user -> gist -> user');
+  });
+
+  test('warns on transitive cycles discovered through project context', () => {
+    const code = `
+import { contour } from '@ontrails/core';
+import { z } from 'zod';
+import { gist } from './gist';
+
+const user = contour('user', {
+  gistId: gist.id(),
+  id: z.string().uuid(),
+}, { identity: 'id' });
+`;
+
+    const diagnostics = circularRefs.checkWithContext(code, TEST_FILE, {
+      contourReferencesByName: new Map([
+        ['account', ['user']],
+        ['gist', ['account']],
+      ]),
+      knownContourIds: new Set(['account', 'gist', 'user']),
+      knownTrailIds: new Set<string>(),
+    });
+
+    expect(diagnostics).toHaveLength(1);
+    expect(diagnostics[0]?.message).toContain(
+      'user -> gist -> account -> user'
+    );
+  });
+
+  test('warns on local cycles formed through wrapped contour id schemas', () => {
+    const code = `
+import { contour } from '@ontrails/core';
+import { z } from 'zod';
+
+const user = contour('user', {
+  gistId: gist.id().optional(),
+  id: z.string().uuid(),
+}, { identity: 'id' });
+
+const gist = contour('gist', {
+  id: z.string().uuid(),
+  ownerId: user.id().nullable(),
+}, { identity: 'id' });
+`;
+
+    const diagnostics = circularRefs.check(code, TEST_FILE);
+
+    expect(diagnostics).toHaveLength(2);
+    expect(diagnostics[0]?.rule).toBe('circular-refs');
+    expect(diagnostics[0]?.message).toContain('user -> gist -> user');
+  });
+
+  test('warns on local cycles formed through namespace-imported references', () => {
+    const code = `
+import { contour } from '@ontrails/core';
+import * as contours from './contours';
+
+const user = contour('user', {
+  id: 'x',
+  gistId: contours.gist.id(),
+}, { identity: 'id' });
+
+const gist = contour('gist', {
+  id: 'x',
+  ownerId: contours.user.id(),
+}, { identity: 'id' });
+`;
+
+    const diagnostics = circularRefs.check(code, TEST_FILE);
+
+    expect(diagnostics).toHaveLength(2);
+    expect(diagnostics[0]?.rule).toBe('circular-refs');
+    expect(diagnostics[0]?.message).toContain('user -> gist -> user');
+  });
+});

package/src/__tests__/cli.test.ts

@@ -3,8 +3,29 @@ import { mkdirSync, rmSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 
+import { ConflictError, Result, topo, trail } from '@ontrails/core';
+import { z } from 'zod';
+
 import { formatWardenReport, runWarden } from '../cli.js';
 
+const isDraftFileMarking = (rule: string): boolean =>
+  rule === 'draft-file-marking';
+
+const isDraftFileMarkingError = (diagnostic: {
+  rule: string;
+  severity?: string;
+}): boolean =>
+  isDraftFileMarking(diagnostic.rule) && diagnostic.severity === 'error';
+
+const isDraftFileMarkingWarn = (diagnostic: {
+  rule: string;
+  severity?: string;
+}): boolean =>
+  isDraftFileMarking(diagnostic.rule) && diagnostic.severity === 'warn';
+
+const isDraftVisibleDebt = (rule: string): boolean =>
+  rule === 'draft-visible-debt';
+
 const makeTempDir = (): string => {
   const dir = join(
     tmpdir(),
@@ -14,7 +35,7 @@ const makeTempDir = (): string => {
   return dir;
 };
 
-describe('runWarden', () => {
+describe('runWarden basics', () => {
   test('produces a report with diagnostics for bad code', async () => {
     const dir = makeTempDir();
     try {
@@ -81,67 +102,356 @@ describe('runWarden', () => {
       rmSync(dir, { force: true, recursive: true });
     }
   });
+});
 
-  test('uses project context for detour references across files', async () => {
+describe('runWarden project context', () => {
+  test('reports throw inside detour recover functions', async () => {
     const dir = makeTempDir();
     try {
       writeFileSync(
-        join(dir, 'show.ts'),
+        join(dir, 'recover.ts'),
         `trail("entity.show", {
-  detours: { NotFoundError: ["entity.search"] },
-  blaze: async (input, ctx) => {
-    return Result.ok(data);
-  }
+  detours: [
+    {
+      on: ConflictError,
+      recover: async () => {
+        throw new Error("boom");
+      },
+    },
+  ],
+  blaze: () => Result.err(new ConflictError("conflict")),
 })`
       );
+
+      const report = await runWarden({ rootDir: dir });
+      const detourRecoverErrors = report.diagnostics.filter(
+        (diagnostic) => diagnostic.rule === 'no-throw-in-detour-recover'
+      );
+
+      expect(detourRecoverErrors).toHaveLength(1);
+    } finally {
+      rmSync(dir, { force: true, recursive: true });
+    }
+  });
+
+  test('reports detours shadowed by earlier broader on: types', async () => {
+    const dir = makeTempDir();
+    try {
       writeFileSync(
-        join(dir, 'search.ts'),
-        `trail("entity.search", {
-  blaze: async (input, ctx) => {
-    return Result.ok(data);
-  }
+        join(dir, 'shadowed.ts'),
+        `import { ConflictError, Result, TrailsError, trail } from '@ontrails/core';
+
+trail("entity.save", {
+  detours: [
+    { on: TrailsError, recover: async () => Result.ok({ winner: "broad" }) },
+    { on: ConflictError, recover: async () => Result.ok({ winner: "specific" }) },
+  ],
+  blaze: () => Result.err(new ConflictError("boom")),
+});`
+      );
+
+      const report = await runWarden({ rootDir: dir });
+      const shadowRules = report.diagnostics.filter(
+        (diagnostic) => diagnostic.rule === 'unreachable-detour-shadowing'
+      );
+
+      expect(shadowRules).toHaveLength(1);
+      expect(shadowRules[0]?.message).toContain('TrailsError');
+      expect(shadowRules[0]?.message).toContain('ConflictError');
+    } finally {
+      rmSync(dir, { force: true, recursive: true });
+    }
+  });
+
+  test('includes topo-aware detour contract diagnostics when topo is supplied', async () => {
+    const validTrail = trail('entity.save', {
+      blaze: () => Result.ok({ ok: true }),
+      detours: [
+        {
+          on: ConflictError,
+          recover: () => Result.ok({ ok: true }),
+        },
+      ],
+      input: z.object({}),
+      output: z.object({ ok: z.boolean() }),
+    });
+
+    const malformed = {
+      ...validTrail,
+      detours: [
+        {
+          on: 'ConflictError',
+          recover: 'not callable',
+        },
+      ],
+    } as typeof validTrail;
+
+    const report = await runWarden({
+      topo: topo('invalid-detour-contract', {
+        malformed,
+      } as Record<string, unknown>),
+    });
+
+    const contractDiagnostics = report.diagnostics.filter(
+      (diagnostic) => diagnostic.rule === 'valid-detour-contract'
+    );
+
+    expect(contractDiagnostics).toHaveLength(2);
+  });
+
+  test('uses project context for contour references across files', async () => {
+    const dir = makeTempDir();
+    try {
+      writeFileSync(
+        join(dir, 'user.ts'),
+        `import { contour } from '@ontrails/core';
+import { z } from 'zod';
+
+export const user = contour('user', {
+  id: z.string().uuid(),
+}, { identity: 'id' });`
+      );
+      writeFileSync(
+        join(dir, 'gist.ts'),
+        `import { contour } from '@ontrails/core';
+import { z } from 'zod';
+import { user } from './user';
+
+export const gist = contour('gist', {
+  id: z.string().uuid(),
+  ownerId: user.id(),
+}, { identity: 'id' });`
+      );
+
+      const report = await runWarden({ rootDir: dir });
+      const referenceErrors = report.diagnostics.filter(
+        (diagnostic) => diagnostic.rule === 'reference-exists'
+      );
+
+      expect(referenceErrors).toHaveLength(0);
+    } finally {
+      rmSync(dir, { force: true, recursive: true });
+    }
+  });
+
+  test('preserves empty topo resource sets instead of falling back to file-local ids', async () => {
+    const dir = makeTempDir();
+    try {
+      writeFileSync(
+        join(dir, 'entity.ts'),
+        `import { Result, resource, trail } from '@ontrails/core';
+
+const db = resource('db.main', {
+  create: () => Result.ok({ source: 'factory' }),
+});
+
+trail('entity.show', {
+  resources: [db],
+  blaze: async (_input, ctx) => Result.ok(db.from(ctx)),
+});`
+      );
+
+      const report = await runWarden({ rootDir: dir, topo: topo('empty-app') });
+      const resourceErrors = report.diagnostics.filter(
+        (diagnostic) => diagnostic.rule === 'resource-exists'
+      );
+
+      expect(resourceErrors).toHaveLength(1);
+      expect(resourceErrors[0]?.message).toContain('db.main');
+    } finally {
+      rmSync(dir, { force: true, recursive: true });
+    }
+  });
+
+  test('warns on contour cycles declared across files', async () => {
+    const dir = makeTempDir();
+    try {
+      writeFileSync(
+        join(dir, 'user.ts'),
+        `import { contour } from '@ontrails/core';
+import { z } from 'zod';
+import { gist } from './gist';
+
+export const user = contour('user', {
+  gistId: gist.id(),
+  id: z.string().uuid(),
+}, { identity: 'id' });`
+      );
+      writeFileSync(
+        join(dir, 'gist.ts'),
+        `import { contour } from '@ontrails/core';
+import { z } from 'zod';
+import { user } from './user';
+
+export const gist = contour('gist', {
+  id: z.string().uuid(),
+  ownerId: user.id(),
+}, { identity: 'id' });`
+      );
+
+      const report = await runWarden({ rootDir: dir });
+      const circularWarnings = report.diagnostics.filter(
+        (diagnostic) => diagnostic.rule === 'circular-refs'
+      );
+
+      expect(circularWarnings.length).toBeGreaterThan(0);
+    } finally {
+      rmSync(dir, { force: true, recursive: true });
+    }
+  });
+
+  test('uses project context for store factory completeness across files', async () => {
+    const dir = makeTempDir();
+    try {
+      writeFileSync(
+        join(dir, 'store.ts'),
+        `import { Result, resource } from '@ontrails/core';
+import { store } from '@ontrails/store';
+import { crud } from '@ontrails/store/trails';
+import { z } from 'zod';
+
+export const definition = store({
+  notes: {
+    identity: 'id',
+    schema: z.object({
+      id: z.string(),
+      title: z.string(),
+    }),
+    versioned: true,
+  },
+});
+
+const notesResource = resource('db.notes', {
+  create: () => Result.ok({}),
+  mock: () => ({}),
+});
+
+const noteTrails = crud(definition.tables.notes, notesResource);`
+      );
+      writeFileSync(
+        join(dir, 'reconcile.ts'),
+        `import { Result, resource } from '@ontrails/core';
+import { reconcile } from '@ontrails/store/trails';
+import { definition } from './store';
+
+const notesResource = resource('db.notes', {
+  create: () => Result.ok({}),
+  mock: () => ({}),
+});
+
+const reconcileNotes = reconcile({
+  resource: notesResource,
+  table: definition.tables.notes,
+});`
+      );
+      writeFileSync(
+        join(dir, 'listener.ts'),
+        `import { Result, trail } from '@ontrails/core';
+import { definition } from './store';
+import { z } from 'zod';
+
+trail('notes.notify', {
+  on: [
+    definition.tables.notes.signals.created,
+    definition.tables.notes.signals.updated,
+    definition.tables.notes.signals.removed,
+  ],
+  blaze: async () => Result.ok({ ok: true }),
+  output: z.object({ ok: z.boolean() }),
+});`
+      );
+
+      const report = await runWarden({ rootDir: dir });
+
+      expect(
+        report.diagnostics.filter(
+          (diagnostic) => diagnostic.rule === 'missing-reconcile'
+        )
+      ).toHaveLength(0);
+      expect(
+        report.diagnostics.filter(
+          (diagnostic) => diagnostic.rule === 'orphaned-signal'
+        )
+      ).toHaveLength(0);
+    } finally {
+      rmSync(dir, { force: true, recursive: true });
+    }
+  });
+});
+
+describe('runWarden draft markers', () => {
+  test('requires draft-bearing files to be visibly marked', async () => {
+    const dir = makeTempDir();
+    try {
+      writeFileSync(
+        join(dir, 'draft-id.ts'),
+        `trail("_draft.entity.prepare", {
+  blaze: async () => Result.ok({ ok: true }),
+  input: z.object({})
 })`
       );
 
       const report = await runWarden({ rootDir: dir });
-      const detourRefErrors = report.diagnostics.filter(
-        (diagnostic) => diagnostic.rule === 'valid-detour-refs'
+
+      const hasDraftFileMarking = report.diagnostics.some((diagnostic) =>
+        isDraftFileMarking(diagnostic.rule)
+      );
+      const hasDraftVisibleDebt = report.diagnostics.some((diagnostic) =>
+        isDraftVisibleDebt(diagnostic.rule)
       );
 
-      expect(detourRefErrors).toHaveLength(0);
+      expect(hasDraftFileMarking).toBe(true);
+      expect(hasDraftVisibleDebt).toBe(true);
     } finally {
       rmSync(dir, { force: true, recursive: true });
     }
   });
 
-  test('flags throws in detour targets declared in another file', async () => {
+  test('allows correctly marked draft files while keeping the debt visible', async () => {
     const dir = makeTempDir();
     try {
       writeFileSync(
-        join(dir, 'show.ts'),
-        `trail("entity.show", {
-  detours: { NotFoundError: ["entity.search"] },
-  blaze: async (input, ctx) => {
-    return Result.ok(data);
-  }
+        join(dir, '_draft.entity.ts'),
+        `trail("_draft.entity.prepare", {
+  blaze: async () => Result.ok({ ok: true }),
+  input: z.object({})
 })`
       );
+
+      const report = await runWarden({ rootDir: dir });
+
+      const hasDraftFileMarkingError = report.diagnostics.some((diagnostic) =>
+        isDraftFileMarkingError(diagnostic)
+      );
+      const hasDraftVisibleDebt = report.diagnostics.some((diagnostic) =>
+        isDraftVisibleDebt(diagnostic.rule)
+      );
+
+      expect(hasDraftFileMarkingError).toBe(false);
+      expect(hasDraftVisibleDebt).toBe(true);
+    } finally {
+      rmSync(dir, { force: true, recursive: true });
+    }
+  });
+
+  test('warns when a draft-marked file no longer contains draft ids', async () => {
+    const dir = makeTempDir();
+    try {
       writeFileSync(
-        join(dir, 'search.ts'),
-        `trail("entity.search", {
-  blaze: async (input, ctx) => {
-    throw new Error("boom");
-  }
+        join(dir, 'entity.draft.ts'),
+        `trail("entity.prepare", {
+  blaze: async () => Result.ok({ ok: true }),
+  input: z.object({})
 })`
       );
 
       const report = await runWarden({ rootDir: dir });
-      const detourThrowRules = report.diagnostics.filter(
-        (diagnostic) => diagnostic.rule === 'no-throw-in-detour-target'
+
+      const hasDraftFileMarkingWarn = report.diagnostics.some((diagnostic) =>
+        isDraftFileMarkingWarn(diagnostic)
       );
 
-      expect(detourThrowRules).toHaveLength(1);
-      expect(detourThrowRules[0]?.message).toContain('entity.search');
+      expect(hasDraftFileMarkingWarn).toBe(true);
     } finally {
       rmSync(dir, { force: true, recursive: true });
     }
@@ -192,7 +502,25 @@ describe('formatWardenReport', () => {
       passed: false,
       warnCount: 0,
     });
-    expect(output).toContain('trailhead.lock is stale');
+    expect(output).toContain('trails.lock is stale');
     expect(output).toContain('Result: FAIL');
   });
+
+  test('formats a report with blocked established exports', () => {
+    const output = formatWardenReport({
+      diagnostics: [],
+      drift: {
+        blockedReason:
+          'Established topo validation failed with 1 draft issue(s)',
+        committedHash: null,
+        currentHash: 'blocked',
+        stale: true,
+      },
+      errorCount: 0,
+      passed: false,
+      warnCount: 0,
+    });
+    expect(output).toContain('Drift: blocked');
+    expect(output).toContain('established exports blocked');
+  });
 });