@ontrails/warden 1.0.0-beta.14 → 1.0.0-beta.16

package/src/__tests__/rules.test.ts

@@ -1,227 +0,0 @@
-import { describe, expect, test } from 'bun:test';
-
-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';
-
-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", {
-  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 implementation', () => {
-    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 outside implementation', () => {
-    const code = `
-function helper() {
-  throw new Error("boom");
-}
-
-trail("entity.show", {
-  blaze: async (input, ctx) => {
-    return Result.ok(data);
-  }
-})`;
-    const diagnostics = noThrowInImplementation.check(code, TEST_FILE);
-    expect(diagnostics.length).toBe(0);
-  });
-});
-
-// ---------------------------------------------------------------------------
-// context-no-trailhead-types
-// ---------------------------------------------------------------------------
-describe('context-no-trailhead-types', () => {
-  test('flags express import in trail file', () => {
-    const code = `
-import { Request, Response } from "express";
-trail("entity.show", {
-  blaze: async (input, ctx) => {
-    return Result.ok(data);
-  }
-})`;
-    const diagnostics = contextNoTrailheadTypes.check(code, TEST_FILE);
-    expect(diagnostics.length).toBe(1);
-    expect(diagnostics[0]?.rule).toBe('context-no-trailhead-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", {
-  blaze: async (input, ctx) => {
-    return Result.ok(data);
-  }
-})`;
-    const diagnostics = contextNoTrailheadTypes.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", {
-  blaze: async (input, ctx) => {
-    return Result.ok(data);
-  }
-})`;
-    const diagnostics = contextNoTrailheadTypes.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 = contextNoTrailheadTypes.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', () => {
-    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);
-    expect(diagnostics.length).toBe(0);
-  });
-});
-
-// ---------------------------------------------------------------------------
-// no-direct-impl-in-route
-// ---------------------------------------------------------------------------
-describe('no-direct-impl-in-route', () => {
-  test('warns on direct .blaze() call in trail with crossings', () => {
-    const code = `
-trail("entity.onboard", {
-  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.cross');
-  });
-
-  test('allows ctx.cross() calls', () => {
-    const code = `
-trail("entity.onboard", {
-  crosses: ["entity.create"],
-  blaze: async (input, ctx) => {
-    const result = await ctx.cross("entity.create", data);
-    return Result.ok(result);
-  }
-})`;
-    const diagnostics = noDirectImplInRoute.check(code, TEST_FILE);
-    expect(diagnostics.length).toBe(0);
-  });
-
-  test('ignores trails without crossings', () => {
-    const code = `
-trail("entity.show", {
-  blaze: async (input, ctx) => {
-    const result = await someTrail.blaze(data);
-    return Result.ok(result);
-  }
-})`;
-    const diagnostics = noDirectImplInRoute.check(code, TEST_FILE);
-    expect(diagnostics.length).toBe(0);
-  });
-
-  test('ignores files without trail() calls', () => {
-    const code = `
-const result = await someTrail.blaze(data);`;
-    const diagnostics = noDirectImplInRoute.check(code, TEST_FILE);
-    expect(diagnostics.length).toBe(0);
-  });
-});

package/src/__tests__/trails.test.ts

@@ -1,19 +0,0 @@
-import { describe, expect, test } from 'bun:test';
-import { testAll } from '@ontrails/testing';
-
-import { wardenTopo } from '../trails/topo.js';
-
-// oxlint-disable-next-line jest/require-hook -- testAll generates describe/test blocks, not setup code
-testAll(wardenTopo);
-
-describe('wardenTopo', () => {
-  test('contains all 13 rule trails', () => {
-    expect(wardenTopo.count).toBe(13);
-  });
-
-  test('all trail IDs follow warden.rule.* naming', () => {
-    for (const id of wardenTopo.ids()) {
-      expect(id).toMatch(/^warden\.rule\./);
-    }
-  });
-});

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

@@ -1,60 +0,0 @@
-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"),
-  }),
-  blaze: (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() }),
-  blaze: (input) => Result.ok(input),
-})
-
-trail("entity.show", {
-  input: z.object({
-    query: z.string().describe("Search query. @see entity.search"),
-  }),
-  blaze: (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"),
-  }),
-  blaze: (input) => Result.ok(input),
-})`;
-
-    const diagnostics = validDescribeRefs.checkWithContext(
-      code,
-      'src/entity.ts',
-      {
-        knownTrailIds: new Set(['entity.search', 'entity.show']),
-      }
-    );
-
-    expect(diagnostics).toHaveLength(0);
-  });
-});

package/src/__tests__/wrap-rule.test.ts

@@ -1,41 +0,0 @@
-import { describe, expect, test } from 'bun:test';
-
-import { createTrailContext } from '@ontrails/core';
-
-import { wrapRule } from '../trails/wrap-rule.js';
-import type { ProjectAwareWardenRule } from '../rules/types.js';
-
-describe('wrapRule', () => {
-  test('preserves undefined knownProvisionIds and defaults knownTrailIds to empty set', async () => {
-    let capturedContext:
-      | {
-          readonly knownProvisionIds?: ReadonlySet<string>;
-          readonly knownTrailIds?: ReadonlySet<string>;
-        }
-      | undefined;
-
-    const rule: ProjectAwareWardenRule = {
-      check: () => [],
-      checkWithContext: (_sourceCode, _filePath, context) => {
-        capturedContext = context;
-        return [];
-      },
-      description: 'dummy rule',
-      name: 'dummy-rule',
-      severity: 'error',
-    };
-
-    const wrapped = wrapRule({ examples: [], rule });
-    const result = await wrapped.blaze(
-      { filePath: 'entity.ts', sourceCode: '' },
-      createTrailContext()
-    );
-
-    expect(result.isOk()).toBe(true);
-    expect(result.unwrap()).toEqual({ diagnostics: [] });
-    expect(capturedContext).toEqual({
-      knownProvisionIds: undefined,
-      knownTrailIds: new Set<string>(),
-    });
-  });
-});

package/src/rules/no-direct-impl-in-route.ts

@@ -1,81 +0,0 @@
-/**
- * Detects trail implementations with `crosses` that call `.blaze()` directly.
- *
- * Uses AST parsing to find trail definitions that declare `crosses` and check for
- * `.blaze()` call expressions in their bodies.
- */
-
-import {
-  findConfigProperty,
-  findBlazeBodies,
-  findTrailDefinitions,
-  isBlazeCall,
-  offsetToLine,
-  parse,
-  walk,
-} from './ast.js';
-import type { WardenDiagnostic, WardenRule } from './types.js';
-
-interface AstNode {
-  readonly type: string;
-  readonly start: number;
-  readonly end: number;
-  readonly [key: string]: unknown;
-}
-
-const findImplCallsInTrailWithCrosses = (
-  def: { readonly config: AstNode },
-  filePath: string,
-  sourceCode: string,
-  diagnostics: WardenDiagnostic[]
-): void => {
-  for (const body of findBlazeBodies(def.config as AstNode)) {
-    walk(body, (node) => {
-      if (isBlazeCall(node as AstNode)) {
-        diagnostics.push({
-          filePath,
-          line: offsetToLine(sourceCode, node.start),
-          message:
-            'Use ctx.cross("trailId", input) instead of direct .blaze() calls. ctx.cross() validates input and propagates tracing.',
-          rule: 'no-direct-impl-in-route',
-          severity: 'warn',
-        });
-      }
-    });
-  }
-};
-
-const hasCrossesProperty = (config: AstNode): boolean =>
-  findConfigProperty(config as AstNode, 'crosses') !== null;
-
-/**
- * Detects trails with `crosses` that call another trail's `.blaze()` directly.
- */
-export const noDirectImplInRoute: WardenRule = {
-  check(sourceCode: string, filePath: string): readonly WardenDiagnostic[] {
-    if (!/\btrail\s*\(/.test(sourceCode)) {
-      return [];
-    }
-
-    const ast = parse(filePath, sourceCode);
-    if (!ast) {
-      return [];
-    }
-
-    const diagnostics: WardenDiagnostic[] = [];
-    const crossDefs = findTrailDefinitions(ast as AstNode).filter((d) =>
-      hasCrossesProperty(d.config as AstNode)
-    );
-
-    for (const def of crossDefs) {
-      findImplCallsInTrailWithCrosses(def, filePath, sourceCode, diagnostics);
-    }
-
-    return diagnostics;
-  },
-  description:
-    'Prefer ctx.cross() over direct .blaze() calls in trail bodies with crossings.',
-  name: 'no-direct-impl-in-route',
-
-  severity: 'warn',
-};

package/src/rules/no-throw-in-detour-target.ts

@@ -1,150 +0,0 @@
-/**
- * Flags throws in implementations that are used as detour targets.
- *
- * Uses AST parsing for accurate detection of detour target IDs and
- * throw statements within those trail implementations.
- */
-
-import {
-  findBlazeBodies,
-  findTrailDefinitions,
-  offsetToLine,
-  parse,
-  walk,
-} from './ast.js';
-import { isTestFile } from './scan.js';
-import type {
-  ProjectAwareWardenRule,
-  ProjectContext,
-  WardenDiagnostic,
-} from './types.js';
-
-interface AstNode {
-  readonly type: string;
-  readonly start: number;
-  readonly end: number;
-  readonly [key: string]: unknown;
-}
-
-/** Collect all trail IDs referenced as detour targets in the AST. */
-const collectDetourTargets = (ast: AstNode): ReadonlySet<string> => {
-  const targets = new Set<string>();
-
-  walk(ast, (node) => {
-    if (
-      node.type !== 'Property' ||
-      node.key?.name !== 'detours' ||
-      !node.value
-    ) {
-      return;
-    }
-
-    walk(node.value as AstNode, (inner) => {
-      if (inner.type === 'Literal' || inner.type === 'StringLiteral') {
-        const { value } = inner as unknown as { value?: unknown };
-        if (typeof value === 'string' && value.includes('.')) {
-          targets.add(value);
-        }
-      }
-    });
-  });
-
-  return targets;
-};
-
-/** Find throws in implementation bodies of targeted trails. */
-const findThrowsInTargetedTrails = (
-  ast: AstNode,
-  sourceCode: string,
-  filePath: string,
-  detourTargets: ReadonlySet<string>
-): WardenDiagnostic[] => {
-  const diagnostics: WardenDiagnostic[] = [];
-
-  for (const def of findTrailDefinitions(ast)) {
-    if (!detourTargets.has(def.id)) {
-      continue;
-    }
-
-    for (const body of findBlazeBodies(def.config as AstNode)) {
-      walk(body, (node) => {
-        if (node.type === 'ThrowStatement') {
-          diagnostics.push({
-            filePath,
-            line: offsetToLine(sourceCode, node.start),
-            message: `Trail "${def.id}" is a detour target and must not throw. Use Result.err() instead.`,
-            rule: 'no-throw-in-detour-target',
-            severity: 'error',
-          });
-        }
-      });
-    }
-  }
-
-  return diagnostics;
-};
-
-const checkThrowInDetourTargets = (
-  sourceCode: string,
-  filePath: string,
-  detourTargets: ReadonlySet<string>
-): readonly WardenDiagnostic[] => {
-  if (isTestFile(filePath)) {
-    return [];
-  }
-
-  const ast = parse(filePath, sourceCode);
-  if (!ast) {
-    return [];
-  }
-
-  return findThrowsInTargetedTrails(
-    ast as AstNode,
-    sourceCode,
-    filePath,
-    detourTargets
-  );
-};
-
-/**
- * Flags throws in implementations that are used as detour targets.
- */
-export const noThrowInDetourTarget: ProjectAwareWardenRule = {
-  check(sourceCode: string, filePath: string): readonly WardenDiagnostic[] {
-    const ast = parse(filePath, sourceCode);
-    if (!ast) {
-      return [];
-    }
-    return checkThrowInDetourTargets(
-      sourceCode,
-      filePath,
-      collectDetourTargets(ast as AstNode)
-    );
-  },
-  checkWithContext(
-    sourceCode: string,
-    filePath: string,
-    context: ProjectContext
-  ): readonly WardenDiagnostic[] {
-    if (context.detourTargetTrailIds) {
-      return checkThrowInDetourTargets(
-        sourceCode,
-        filePath,
-        context.detourTargetTrailIds
-      );
-    }
-    const ast = parse(filePath, sourceCode);
-    if (!ast) {
-      return [];
-    }
-    return checkThrowInDetourTargets(
-      sourceCode,
-      filePath,
-      collectDetourTargets(ast as AstNode)
-    );
-  },
-  description:
-    'Disallow throw statements inside implementations that are referenced as detour targets.',
-  name: 'no-throw-in-detour-target',
-  severity: 'error',
-};