@ontrails/warden 1.0.0-beta.4 → 1.0.0-beta.42

package/src/__tests__/rules.test.ts

@@ -1,227 +0,0 @@
-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", {
-  run: 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", {
-  run: 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", {
-  run: 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", {
-  run: 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", {
-  run: 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", {
-  run: 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" }],
-  run: 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", {
-  run: async (input, ctx) => Result.ok(data)
-})
-
-trail("entity.show", {
-  detours: [{ target: "entity.edit" }],
-  run: 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" }],
-  run: 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 follow that does not exist', () => {
-    const code = `
-trail("entity.onboard", {
-  detours: [{ target: "entity.missing" }],
-  follow: ["entity.create"],
-  run: 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 follow detour target exists', () => {
-    const code = `
-trail("entity.fallback", {
-  run: async (input, ctx) => Result.ok(data)
-})
-
-trail("entity.onboard", {
-  detours: [{ target: "entity.fallback" }],
-  follow: ["entity.create"],
-  run: 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 .run() call in trail with follow', () => {
-    const code = `
-trail("entity.onboard", {
-  follow: ["entity.create"],
-  run: async (input, ctx) => {
-    const result = await entityCreate.run(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 = `
-trail("entity.onboard", {
-  follow: ["entity.create"],
-  run: 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 trails without follow', () => {
-    const code = `
-trail("entity.show", {
-  run: async (input, ctx) => {
-    const result = await someTrail.run(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.run(data);`;
-    const diagnostics = noDirectImplInRoute.check(code, TEST_FILE);
-    expect(diagnostics.length).toBe(0);
-  });
-});

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"),
-  }),
-  run: (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() }),
-  run: (input) => Result.ok(input),
-})
-
-trail("entity.show", {
-  input: z.object({
-    query: z.string().describe("Search query. @see entity.search"),
-  }),
-  run: (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"),
-  }),
-  run: (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/rules/ast.ts

@@ -1,213 +0,0 @@
-/**
- * Shared AST utilities for warden rules.
- *
- * Uses oxc-parser for native-speed TypeScript parsing. Provides a lightweight
- * walker and helpers for finding trail implementation bodies.
- */
-
-import { parseSync } from 'oxc-parser';
-
-// ---------------------------------------------------------------------------
-// Types (minimal, avoiding full @oxc-project/types dep)
-// ---------------------------------------------------------------------------
-
-export interface AstNode {
-  readonly type: string;
-  readonly start: number;
-  readonly end: number;
-  readonly key?: { readonly name?: string };
-  readonly value?: AstNode;
-  readonly body?: AstNode | readonly AstNode[];
-  readonly [key: string]: unknown;
-}
-
-// ---------------------------------------------------------------------------
-// Parser
-// ---------------------------------------------------------------------------
-
-/** Parse TypeScript source into an AST. Returns null on parse failure. */
-export const parse = (filePath: string, sourceCode: string): AstNode | null => {
-  try {
-    const result = parseSync(filePath, sourceCode, { sourceType: 'module' });
-    return result.program as unknown as AstNode;
-  } catch {
-    return null;
-  }
-};
-
-// ---------------------------------------------------------------------------
-// Walker
-// ---------------------------------------------------------------------------
-
-/** Walk an AST node tree, calling `visit` on every node. */
-export const walk = (node: unknown, visit: (node: AstNode) => void): void => {
-  if (!node || typeof node !== 'object') {
-    return;
-  }
-  const n = node as AstNode;
-  if (n.type) {
-    visit(n);
-  }
-  for (const val of Object.values(n)) {
-    if (Array.isArray(val)) {
-      for (const item of val) {
-        walk(item, visit);
-      }
-    } else if (val && typeof val === 'object' && (val as AstNode).type) {
-      walk(val, visit);
-    }
-  }
-};
-
-// ---------------------------------------------------------------------------
-// Helpers
-// ---------------------------------------------------------------------------
-
-/** Find the byte offset's line number (1-based) in source code. */
-export const offsetToLine = (sourceCode: string, offset: number): number => {
-  let line = 1;
-  for (let i = 0; i < offset && i < sourceCode.length; i += 1) {
-    if (sourceCode[i] === '\n') {
-      line += 1;
-    }
-  }
-  return line;
-};
-
-/** Find all `run:` property values in an AST. */
-export const findRunBodies = (ast: AstNode): AstNode[] => {
-  const bodies: AstNode[] = [];
-  walk(ast, (node) => {
-    if (node.type === 'Property' && node.key?.name === 'run' && node.value) {
-      bodies.push(node.value);
-    }
-  });
-  return bodies;
-};
-
-export interface TrailDefinition {
-  /** Trail ID string, e.g. "entity.show" */
-  readonly id: string;
-  /** "trail" or "event" */
-  readonly kind: string;
-  /** The config object argument (second arg to trail() call) */
-  readonly config: AstNode;
-  /** Start offset of the call expression */
-  readonly start: number;
-}
-
-/**
- * Find all `trail("id", { ... })` and `event("id", { ... })` call sites.
- *
- * Returns the trail ID, kind, and config object node for each definition.
- */
-const TRAIL_CALLEE_NAMES = new Set(['trail', 'event']);
-
-const getTrailCalleeName = (node: AstNode): string | null => {
-  if (node.type !== 'CallExpression') {
-    return null;
-  }
-  const callee = node['callee'] as AstNode | undefined;
-  if (!callee || callee.type !== 'Identifier') {
-    return null;
-  }
-  const { name } = callee as unknown as { name?: string };
-  return name && TRAIL_CALLEE_NAMES.has(name) ? name : null;
-};
-
-const extractTrailArgs = (
-  node: AstNode
-): { idArg: AstNode; configArg: AstNode } | null => {
-  const args = node['arguments'] as readonly AstNode[] | undefined;
-  if (!args || args.length < 2) {
-    return null;
-  }
-  const [idArg, configArg] = args;
-  if (!idArg || !configArg) {
-    return null;
-  }
-  return { configArg, idArg };
-};
-
-const extractTrailDefinition = (node: AstNode): TrailDefinition | null => {
-  const calleeName = getTrailCalleeName(node);
-  if (!calleeName) {
-    return null;
-  }
-
-  const trailArgs = extractTrailArgs(node);
-  if (!trailArgs) {
-    return null;
-  }
-
-  const trailId = (trailArgs.idArg as unknown as { value?: string }).value;
-  if (!trailId) {
-    return null;
-  }
-
-  return {
-    config: trailArgs.configArg,
-    id: trailId,
-    kind: calleeName,
-    start: node.start,
-  };
-};
-
-/** Check if a node is a call to `.run()` on some object. */
-export const isRunCall = (node: AstNode): boolean => {
-  if (node.type !== 'CallExpression') {
-    return false;
-  }
-  const callee = node['callee'] as AstNode | undefined;
-  if (!callee) {
-    return false;
-  }
-  if (
-    callee.type !== 'StaticMemberExpression' &&
-    callee.type !== 'MemberExpression'
-  ) {
-    return false;
-  }
-  const prop = (callee as unknown as { property?: AstNode }).property;
-  return (
-    prop?.type === 'Identifier' &&
-    (prop as unknown as { name: string }).name === 'run'
-  );
-};
-
-export const findTrailDefinitions = (ast: AstNode): TrailDefinition[] => {
-  const definitions: TrailDefinition[] = [];
-
-  walk(ast, (node) => {
-    const def = extractTrailDefinition(node);
-    if (def) {
-      definitions.push(def);
-    }
-  });
-
-  return definitions;
-};
-
-// ---------------------------------------------------------------------------
-// Config property extraction helpers
-// ---------------------------------------------------------------------------
-
-/** Find a Property node by key name inside an ObjectExpression config. */
-export const findConfigProperty = (
-  config: AstNode,
-  propertyName: string
-): AstNode | null => {
-  if (config.type !== 'ObjectExpression') {
-    return null;
-  }
-  const properties = config['properties'] as readonly AstNode[] | undefined;
-  if (!properties) {
-    return null;
-  }
-  for (const prop of properties) {
-    if (prop.type === 'Property' && prop.key?.name === propertyName) {
-      return prop;
-    }
-  }
-  return null;
-};

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

@@ -1,81 +0,0 @@
-/**
- * Detects trail implementations with `follow` that call `.run()` directly.
- *
- * Uses AST parsing to find trail definitions that declare `follow` and check for
- * `.run()` call expressions in their bodies.
- */
-
-import {
-  findConfigProperty,
-  findRunBodies,
-  findTrailDefinitions,
-  isRunCall,
-  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 findImplCallsInTrailWithFollow = (
-  def: { readonly config: AstNode },
-  filePath: string,
-  sourceCode: string,
-  diagnostics: WardenDiagnostic[]
-): void => {
-  for (const body of findRunBodies(def.config as AstNode)) {
-    walk(body, (node) => {
-      if (isRunCall(node as AstNode)) {
-        diagnostics.push({
-          filePath,
-          line: offsetToLine(sourceCode, node.start),
-          message:
-            'Use ctx.follow("trailId", input) instead of direct .run() calls. ctx.follow() validates input and propagates tracing.',
-          rule: 'no-direct-impl-in-route',
-          severity: 'warn',
-        });
-      }
-    });
-  }
-};
-
-const hasFollowProperty = (config: AstNode): boolean =>
-  findConfigProperty(config as AstNode, 'follow') !== null;
-
-/**
- * Detects trails with `follow` that call another trail's `.run()` 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 followDefs = findTrailDefinitions(ast as AstNode).filter((d) =>
-      hasFollowProperty(d.config as AstNode)
-    );
-
-    for (const def of followDefs) {
-      findImplCallsInTrailWithFollow(def, filePath, sourceCode, diagnostics);
-    }
-
-    return diagnostics;
-  },
-  description:
-    'Prefer ctx.follow() over direct .run() calls in trail bodies with follow.',
-  name: 'no-direct-impl-in-route',
-
-  severity: 'warn',
-};