@ontrails/warden 1.0.0-beta.2 → 1.0.0-beta.21

package/src/__tests__/rules.test.ts

@@ -1,188 +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", {
-  implementation: 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", {
-  implementation: 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", {
-  implementation: 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", {
-  implementation: 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", {
-  implementation: 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", {
-  implementation: 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" }],
-  implementation: 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", {
-  implementation: async (input, ctx) => Result.ok(data)
-})
-
-trail("entity.show", {
-  detours: [{ target: "entity.edit" }],
-  implementation: 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" }],
-  implementation: 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);
-  });
-});
-
-// ---------------------------------------------------------------------------
-// no-direct-impl-in-route
-// ---------------------------------------------------------------------------
-describe('no-direct-impl-in-route', () => {
-  test('warns on direct .implementation() call in route', () => {
-    const code = `
-hike("entity.onboard", {
-  follows: ["entity.create"],
-  implementation: async (input, ctx) => {
-    const result = await entityCreate.implementation(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 = `
-hike("entity.onboard", {
-  follows: ["entity.create"],
-  implementation: 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 files without hike() calls', () => {
-    const code = `
-const result = await someTrail.implementation(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"),
-  }),
-  implementation: (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() }),
-  implementation: (input) => Result.ok(input),
-})
-
-trail("entity.show", {
-  input: z.object({
-    query: z.string().describe("Search query. @see entity.search"),
-  }),
-  implementation: (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"),
-  }),
-  implementation: (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/no-direct-impl-in-route.ts

@@ -1,77 +0,0 @@
-/**
- * Detects hike implementations that call `.implementation()` directly.
- *
- * Uses AST parsing to find hike definition bodies and check for
- * `.implementation()` call expressions.
- */
-
-import {
-  findImplementationBodies,
-  findTrailDefinitions,
-  isImplementationCall,
-  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 findImplCallsInHike = (
-  def: { readonly config: AstNode },
-  filePath: string,
-  sourceCode: string,
-  diagnostics: WardenDiagnostic[]
-): void => {
-  for (const body of findImplementationBodies(def.config as AstNode)) {
-    walk(body, (node) => {
-      if (isImplementationCall(node as AstNode)) {
-        diagnostics.push({
-          filePath,
-          line: offsetToLine(sourceCode, node.start),
-          message:
-            'Use ctx.follow("trailId", input) instead of direct .implementation() calls. ctx.follow() validates input and propagates tracing.',
-          rule: 'no-direct-impl-in-route',
-          severity: 'warn',
-        });
-      }
-    });
-  }
-};
-
-/**
- * Detects routes that call another trail's `.implementation()` directly.
- */
-export const noDirectImplInRoute: WardenRule = {
-  check(sourceCode: string, filePath: string): readonly WardenDiagnostic[] {
-    if (!/\bhike\s*\(/.test(sourceCode)) {
-      return [];
-    }
-
-    const ast = parse(filePath, sourceCode);
-    if (!ast) {
-      return [];
-    }
-
-    const diagnostics: WardenDiagnostic[] = [];
-    const hikeDefs = findTrailDefinitions(ast as AstNode).filter(
-      (d) => d.kind === 'hike'
-    );
-
-    for (const def of hikeDefs) {
-      findImplCallsInHike(def, filePath, sourceCode, diagnostics);
-    }
-
-    return diagnostics;
-  },
-  description:
-    'Prefer ctx.follow() over direct .implementation() calls in route bodies.',
-  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 {
-  findImplementationBodies,
-  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 findImplementationBodies(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',
-};

package/src/rules/valid-detour-refs.ts

@@ -1,187 +0,0 @@
-import { collectTrailIds } from './specs.js';
-import type {
-  ProjectAwareWardenRule,
-  ProjectContext,
-  WardenDiagnostic,
-} from './types.js';
-
-interface BraceState {
-  depth: number;
-  found: boolean;
-}
-
-const trackBraces = (line: string, state: BraceState): void => {
-  for (const ch of line) {
-    if (ch === '{') {
-      state.depth += 1;
-      state.found = true;
-    }
-    if (ch === '}') {
-      state.depth -= 1;
-    }
-  }
-};
-
-const collectArrayText = (lines: readonly string[], start: number): string => {
-  let text = '';
-  for (let k = start; k < lines.length && k < start + 20; k += 1) {
-    const line = lines[k];
-    if (!line) {
-      continue;
-    }
-    text += `${line}\n`;
-    if (text.includes(']')) {
-      break;
-    }
-  }
-  return text;
-};
-
-const findMissingDetourTargets = (
-  text: string,
-  knownIds: ReadonlySet<string>
-): string[] => {
-  const missing: string[] = [];
-  for (const m of text.matchAll(/target\s*:\s*["'`]([^"'`]+)["'`]/g)) {
-    const [, id] = m;
-    if (id && !knownIds.has(id)) {
-      missing.push(id);
-    }
-  }
-  return missing;
-};
-
-const findMissingPlainDetours = (
-  text: string,
-  knownIds: ReadonlySet<string>
-): string[] => {
-  const missing: string[] = [];
-  const cleaned = text.replaceAll(/target\s*:\s*["'`][^"'`]+["'`]/g, '');
-  for (const m of cleaned.matchAll(/["'`]([^"'`]+)["'`]/g)) {
-    const [, id] = m;
-    if (id && id.includes('.') && !knownIds.has(id)) {
-      missing.push(id);
-    }
-  }
-  return missing;
-};
-
-const findAllMissingDetours = (
-  text: string,
-  knownIds: ReadonlySet<string>
-): string[] => [
-  ...findMissingDetourTargets(text, knownIds),
-  ...findMissingPlainDetours(text, knownIds),
-];
-
-const addMissingDetourDiagnostics = (
-  specLine: string,
-  j: number,
-  lines: readonly string[],
-  trailId: string,
-  lineNum: number,
-  filePath: string,
-  knownIds: ReadonlySet<string>,
-  diagnostics: WardenDiagnostic[]
-): void => {
-  if (!/\bdetours\s*:/.test(specLine)) {
-    return;
-  }
-  for (const targetId of findAllMissingDetours(
-    collectArrayText(lines, j),
-    knownIds
-  )) {
-    diagnostics.push({
-      filePath,
-      line: lineNum,
-      message: `Trail "${trailId}" has detour targeting "${targetId}" which is not defined.`,
-      rule: 'valid-detour-refs',
-      severity: 'error',
-    });
-  }
-};
-
-const scanTrailDetours = (
-  lines: readonly string[],
-  startIndex: number,
-  trailId: string,
-  filePath: string,
-  knownIds: ReadonlySet<string>,
-  diagnostics: WardenDiagnostic[]
-): void => {
-  const braceState: BraceState = { depth: 0, found: false };
-  for (let j = startIndex; j < lines.length && j < startIndex + 200; j += 1) {
-    const specLine = lines[j];
-    if (!specLine) {
-      continue;
-    }
-    trackBraces(specLine, braceState);
-    addMissingDetourDiagnostics(
-      specLine,
-      j,
-      lines,
-      trailId,
-      startIndex + 1,
-      filePath,
-      knownIds,
-      diagnostics
-    );
-    if (braceState.found && braceState.depth <= 0) {
-      break;
-    }
-  }
-};
-
-const processLine = (
-  line: string,
-  i: number,
-  lines: readonly string[],
-  filePath: string,
-  knownIds: ReadonlySet<string>,
-  diagnostics: WardenDiagnostic[]
-): void => {
-  const trailMatch = line.match(/\btrail\s*\(\s*["'`]([^"'`]+)["'`]/);
-  if (!trailMatch) {
-    return;
-  }
-  const [, trailId] = trailMatch;
-  if (!trailId) {
-    return;
-  }
-  scanTrailDetours(lines, i, trailId, filePath, knownIds, diagnostics);
-};
-
-const checkDetourRefs = (
-  sourceCode: string,
-  filePath: string,
-  knownIds: ReadonlySet<string>
-): readonly WardenDiagnostic[] => {
-  const diagnostics: WardenDiagnostic[] = [];
-  const lines = sourceCode.split('\n');
-  for (let i = 0; i < lines.length; i += 1) {
-    const line = lines[i];
-    if (line) {
-      processLine(line, i, lines, filePath, knownIds, diagnostics);
-    }
-  }
-  return diagnostics;
-};
-
-/**
- * Checks that all trail IDs referenced in `detours` declarations exist.
- */
-export const validDetourRefs: ProjectAwareWardenRule = {
-  check(sourceCode: string, filePath: string): readonly WardenDiagnostic[] {
-    return checkDetourRefs(sourceCode, filePath, collectTrailIds(sourceCode));
-  },
-  checkWithContext(
-    sourceCode: string,
-    filePath: string,
-    context: ProjectContext
-  ): readonly WardenDiagnostic[] {
-    return checkDetourRefs(sourceCode, filePath, context.knownTrailIds);
-  },
-  description: 'Ensure all detour target trail IDs reference defined trails.',
-  name: 'valid-detour-refs',
-  severity: 'error',
-};

package/tsconfig.json

@@ -1,9 +0,0 @@
-{
-  "extends": "../../tsconfig.json",
-  "compilerOptions": {
-    "outDir": "dist",
-    "rootDir": "src"
-  },
-  "include": ["src"],
-  "exclude": ["**/__tests__/**", "**/*.test.ts", "dist"]
-}

package/tsconfig.tsbuildinfo

@@ -1 +0,0 @@
-{"root":["./src/cli.ts","./src/drift.ts","./src/formatters.ts","./src/index.ts","./src/rules/ast.ts","./src/rules/context-no-surface-types.ts","./src/rules/implementation-returns-result.ts","./src/rules/index.ts","./src/rules/no-direct-impl-in-route.ts","./src/rules/no-direct-implementation-call.ts","./src/rules/no-sync-result-assumption.ts","./src/rules/no-throw-in-detour-target.ts","./src/rules/no-throw-in-implementation.ts","./src/rules/prefer-schema-inference.ts","./src/rules/scan.ts","./src/rules/specs.ts","./src/rules/structure.ts","./src/rules/types.ts","./src/rules/valid-describe-refs.ts","./src/rules/valid-detour-refs.ts"],"version":"5.9.3"}