@ontrails/warden 1.0.0-beta.0

package/src/rules/index.ts

@@ -0,0 +1,54 @@
+import { contextNoSurfaceTypes } from './context-no-surface-types.js';
+import { implementationReturnsResult } from './implementation-returns-result.js';
+import { noDirectImplInRoute } from './no-direct-impl-in-route.js';
+import { noDirectImplementationCall } from './no-direct-implementation-call.js';
+import { noSyncResultAssumption } from './no-sync-result-assumption.js';
+import { noThrowInDetourTarget } from './no-throw-in-detour-target.js';
+import { noThrowInImplementation } from './no-throw-in-implementation.js';
+import { preferSchemaInference } from './prefer-schema-inference.js';
+import type { WardenRule } from './types.js';
+import { validDescribeRefs } from './valid-describe-refs.js';
+import { validDetourRefs } from './valid-detour-refs.js';
+
+export type {
+  ProjectAwareWardenRule,
+  ProjectContext,
+  WardenDiagnostic,
+  WardenRule,
+  WardenSeverity,
+} from './types.js';
+
+export { noThrowInImplementation } from './no-throw-in-implementation.js';
+export { contextNoSurfaceTypes } from './context-no-surface-types.js';
+export { validDetourRefs } from './valid-detour-refs.js';
+export { noDirectImplInRoute } from './no-direct-impl-in-route.js';
+export { noDirectImplementationCall } from './no-direct-implementation-call.js';
+export { noSyncResultAssumption } from './no-sync-result-assumption.js';
+export { implementationReturnsResult } from './implementation-returns-result.js';
+export { noThrowInDetourTarget } from './no-throw-in-detour-target.js';
+export { preferSchemaInference } from './prefer-schema-inference.js';
+export { validDescribeRefs } from './valid-describe-refs.js';
+
+/**
+ * All built-in warden rules, keyed by rule name.
+ *
+ * Rules that duplicate validateTopo checks (follows-trails-exist,
+ * no-recursive-follows, event-origins-exist, examples-match-schema,
+ * require-output-schema) and follows-matches-calls (now covered by
+ * testExamples follows coverage) have been removed.
+ */
+export const wardenRules: ReadonlyMap<string, WardenRule> = new Map<
+  string,
+  WardenRule
+>([
+  [noThrowInImplementation.name, noThrowInImplementation],
+  [contextNoSurfaceTypes.name, contextNoSurfaceTypes],
+  [preferSchemaInference.name, preferSchemaInference],
+  [validDescribeRefs.name, validDescribeRefs],
+  [validDetourRefs.name, validDetourRefs],
+  [noDirectImplementationCall.name, noDirectImplementationCall],
+  [noSyncResultAssumption.name, noSyncResultAssumption],
+  [implementationReturnsResult.name, implementationReturnsResult],
+  [noThrowInDetourTarget.name, noThrowInDetourTarget],
+  [noDirectImplInRoute.name, noDirectImplInRoute],
+]);

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

@@ -0,0 +1,77 @@
+/**
+ * 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-direct-implementation-call.ts

@@ -0,0 +1,47 @@
+/**
+ * Flags direct `.implementation()` calls in application code.
+ *
+ * Uses AST parsing to find `.implementation()` call expressions,
+ * ignoring occurrences in strings and comments.
+ */
+
+import { isImplementationCall, offsetToLine, parse, walk } from './ast.js';
+import { isFrameworkInternalFile, isTestFile } from './scan.js';
+import type { WardenDiagnostic, WardenRule } from './types.js';
+
+/**
+ * Flags direct `.implementation()` calls in application code.
+ */
+export const noDirectImplementationCall: WardenRule = {
+  check(sourceCode: string, filePath: string): readonly WardenDiagnostic[] {
+    if (isTestFile(filePath) || isFrameworkInternalFile(filePath)) {
+      return [];
+    }
+
+    const ast = parse(filePath, sourceCode);
+    if (!ast) {
+      return [];
+    }
+
+    const diagnostics: WardenDiagnostic[] = [];
+
+    walk(ast, (node) => {
+      if (isImplementationCall(node)) {
+        diagnostics.push({
+          filePath,
+          line: offsetToLine(sourceCode, node.start),
+          message:
+            'Use ctx.follow("trailId", input) instead of direct .implementation() calls. Direct implementation access bypasses validation, tracing, and layers.',
+          rule: 'no-direct-implementation-call',
+          severity: 'warn',
+        });
+      }
+    });
+
+    return diagnostics;
+  },
+  description:
+    'Disallow direct .implementation() calls in application code. Use ctx.follow() instead.',
+  name: 'no-direct-implementation-call',
+  severity: 'warn',
+};

package/src/rules/no-sync-result-assumption.ts

@@ -0,0 +1,156 @@
+import type { WardenDiagnostic, WardenRule } from './types.js';
+import {
+  isFrameworkInternalFile,
+  isTestFile,
+  stripQuotedContent,
+} from './scan.js';
+
+const RESULT_ACCESS_PATTERN =
+  /\.(?:isOk|isErr|match|map)\s*\(|\.(?:value|error)\b/;
+const IMPLEMENTATION_CALL_PATTERN = /\.implementation\s*\(/;
+
+const isAwaitedImplementationCall = (line: string): boolean => {
+  const callIndex = line.indexOf('.implementation(');
+  if (callIndex === -1) {
+    return false;
+  }
+
+  const awaitIndex = line.indexOf('await');
+  return awaitIndex !== -1 && awaitIndex < callIndex;
+};
+
+const isDirectResultAccess = (line: string): boolean =>
+  IMPLEMENTATION_CALL_PATTERN.test(line) &&
+  RESULT_ACCESS_PATTERN.test(line) &&
+  !isAwaitedImplementationCall(line);
+
+const isPendingUse = (line: string, variableName: string): boolean => {
+  const escaped = variableName.replaceAll(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  const pendingPattern = new RegExp(
+    `\\b${escaped}\\s*(?:\\.(?:isOk|isErr|match|map)\\s*\\(|\\.(?:value|error)\\b)`
+  );
+  return pendingPattern.test(line);
+};
+
+interface PendingCall {
+  line: number;
+  remainingLines: number;
+  variableName: string;
+}
+
+const MISSING_AWAIT_MESSAGE =
+  'Missing await: .implementation() returns Promise<Result> after normalization. Use `const result = await trail.implementation(input, ctx)`.';
+
+const createMissingAwaitDiagnostic = (
+  filePath: string,
+  line: number
+): WardenDiagnostic => ({
+  filePath,
+  line,
+  message: MISSING_AWAIT_MESSAGE,
+  rule: 'no-sync-result-assumption',
+  severity: 'error',
+});
+
+const trackPendingCall = (line: string): string | undefined => {
+  const match = line.match(
+    /\b(?:const|let|var)\s+([A-Za-z_$][\w$]*)\s*=\s*([^;]*)/
+  );
+  if (!match?.[1] || !match[2] || !IMPLEMENTATION_CALL_PATTERN.test(match[2])) {
+    return undefined;
+  }
+
+  if (isAwaitedImplementationCall(match[2])) {
+    return undefined;
+  }
+
+  return match[1];
+};
+
+const addPendingCall = (
+  pendingCalls: PendingCall[],
+  variableName: string,
+  lineNumber: number
+): void => {
+  pendingCalls.push({
+    line: lineNumber,
+    remainingLines: 6,
+    variableName,
+  });
+};
+
+const advancePendingCalls = (
+  line: string,
+  filePath: string,
+  lineNumber: number,
+  pendingCalls: PendingCall[],
+  diagnostics: WardenDiagnostic[]
+): void => {
+  for (let j = pendingCalls.length - 1; j >= 0; j -= 1) {
+    const pendingCall = pendingCalls[j];
+    if (pendingCall && isPendingUse(line, pendingCall.variableName)) {
+      diagnostics.push(createMissingAwaitDiagnostic(filePath, lineNumber));
+      pendingCalls.splice(j, 1);
+    } else if (pendingCall) {
+      pendingCall.remainingLines -= 1;
+      if (pendingCall.remainingLines <= 0) {
+        pendingCalls.splice(j, 1);
+      }
+    }
+  }
+};
+
+const processLine = (
+  line: string,
+  filePath: string,
+  lineNumber: number,
+  pendingCalls: PendingCall[],
+  diagnostics: WardenDiagnostic[]
+): void => {
+  if (isDirectResultAccess(line)) {
+    diagnostics.push(createMissingAwaitDiagnostic(filePath, lineNumber));
+    return;
+  }
+
+  const variableName = trackPendingCall(line);
+  if (variableName) {
+    addPendingCall(pendingCalls, variableName, lineNumber);
+  }
+
+  advancePendingCalls(line, filePath, lineNumber, pendingCalls, diagnostics);
+};
+
+const scanSourceCode = (
+  sourceCode: string,
+  filePath: string
+): readonly WardenDiagnostic[] => {
+  const diagnostics: WardenDiagnostic[] = [];
+  const lines = sourceCode.split('\n');
+  const pendingCalls: PendingCall[] = [];
+
+  for (let i = 0; i < lines.length; i += 1) {
+    const line = lines[i];
+    if (!line) {
+      continue;
+    }
+    processLine(line, filePath, i + 1, pendingCalls, diagnostics);
+  }
+
+  return diagnostics;
+};
+
+/**
+ * Flags code that assumes `.implementation()` returns a synchronous result.
+ */
+export const noSyncResultAssumption: WardenRule = {
+  check(sourceCode: string, filePath: string): readonly WardenDiagnostic[] {
+    if (isTestFile(filePath) || isFrameworkInternalFile(filePath)) {
+      return [];
+    }
+    return scanSourceCode(stripQuotedContent(sourceCode), filePath);
+  },
+  description:
+    'Disallow treating .implementation() as synchronous after normalization. Always await the returned Promise<Result>.',
+  name: 'no-sync-result-assumption',
+  severity: 'error',
+};

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

@@ -0,0 +1,150 @@
+/**
+ * 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/no-throw-in-implementation.ts

@@ -0,0 +1,41 @@
+/**
+ * Finds `throw` statements inside `implementation:` function bodies.
+ *
+ * Uses AST parsing for accurate detection — no false positives from
+ * throw in comments, strings, or nested non-implementation functions.
+ */
+
+import { findImplementationBodies, offsetToLine, parse, walk } from './ast.js';
+import type { WardenDiagnostic, WardenRule } from './types.js';
+
+export const noThrowInImplementation: WardenRule = {
+  check(sourceCode: string, filePath: string): readonly WardenDiagnostic[] {
+    const ast = parse(filePath, sourceCode);
+    if (!ast) {
+      return [];
+    }
+
+    const diagnostics: WardenDiagnostic[] = [];
+
+    for (const body of findImplementationBodies(ast)) {
+      walk(body, (node) => {
+        if (node.type === 'ThrowStatement') {
+          diagnostics.push({
+            filePath,
+            line: offsetToLine(sourceCode, node.start),
+            message:
+              'Do not throw inside implementation. Use Result.err() instead.',
+            rule: 'no-throw-in-implementation',
+            severity: 'error',
+          });
+        }
+      });
+    }
+
+    return diagnostics;
+  },
+  description:
+    'Disallow throw statements inside trail/route implementation bodies. Use Result.err() instead.',
+  name: 'no-throw-in-implementation',
+  severity: 'error',
+};

package/src/rules/prefer-schema-inference.ts

@@ -0,0 +1,141 @@
+import type { WardenDiagnostic, WardenRule } from './types.js';
+import { isTestFile } from './scan.js';
+import {
+  findTrailLikeSpecs,
+  parseArrayEntries,
+  parseObjectProperties,
+  parseStringLiteral,
+  parseZodObjectShape,
+} from './specs.js';
+
+const REDUNDANT_OVERRIDE_KEYS = new Set(['label', 'options']);
+
+const hasOnlyRedundantKeys = (
+  properties: ReadonlyMap<string, { value: string }>
+): boolean =>
+  [...properties.keys()].every((key) => REDUNDANT_OVERRIDE_KEYS.has(key));
+
+const redundantLabelPart = (
+  derivedLabel: string,
+  properties: ReadonlyMap<string, { value: string }>
+): string[] => {
+  const label = parseStringLiteral(properties.get('label')?.value ?? '');
+  return label !== null && label === derivedLabel ? ['label'] : [];
+};
+
+const optionsAreDerivedDefaults = (
+  optionsText: string,
+  schemaOptions: readonly string[]
+): boolean => {
+  const entries = parseArrayEntries(optionsText, 0, optionsText);
+  if (entries.length !== schemaOptions.length) {
+    return false;
+  }
+
+  return entries.every((entry, index) => {
+    if (!entry.text.startsWith('{')) {
+      return false;
+    }
+
+    const properties = parseObjectProperties(entry.text, 0, entry.text);
+    if (properties.size !== 1) {
+      return false;
+    }
+
+    const value = parseStringLiteral(properties.get('value')?.value ?? '');
+    return value !== null && value === schemaOptions[index];
+  });
+};
+
+const redundantOptionsPart = (
+  options: { value: string } | undefined,
+  schemaOptions: readonly string[] | undefined
+): string[] =>
+  options !== undefined &&
+  schemaOptions !== undefined &&
+  optionsAreDerivedDefaults(options.value, schemaOptions)
+    ? ['options']
+    : [];
+
+const findRedundantParts = (
+  fieldKey: string,
+  fieldOverride: string,
+  schemaText: string
+): string[] => {
+  const fieldInfo = parseZodObjectShape(schemaText).get(fieldKey);
+  if (!fieldInfo) {
+    return [];
+  }
+
+  const properties = parseObjectProperties(fieldOverride, 0, fieldOverride);
+  if (properties.size === 0) {
+    return ['field metadata'];
+  }
+
+  if (!hasOnlyRedundantKeys(properties)) {
+    return [];
+  }
+
+  const redundant = [
+    ...redundantLabelPart(fieldInfo.derivedLabel, properties),
+    ...redundantOptionsPart(properties.get('options'), fieldInfo.options),
+  ];
+
+  return redundant.length === properties.size ? redundant : [];
+};
+
+const diagnosticsForSpec = (
+  sourceCode: string,
+  filePath: string,
+  spec: ReturnType<typeof findTrailLikeSpecs>[number]
+): readonly WardenDiagnostic[] => {
+  const input = spec.properties.get('input');
+  const fields = spec.properties.get('fields');
+  if (!input || !fields) {
+    return [];
+  }
+
+  const fieldEntries = parseObjectProperties(
+    fields.value,
+    fields.start,
+    sourceCode
+  );
+  return [...fieldEntries.entries()]
+    .map(([fieldKey, fieldEntry]) => ({
+      fieldEntry,
+      fieldKey,
+      redundantParts: findRedundantParts(
+        fieldKey,
+        fieldEntry.value,
+        input.value
+      ),
+    }))
+    .filter(({ redundantParts }) => redundantParts.length > 0)
+    .map(({ fieldEntry, fieldKey, redundantParts }) => ({
+      filePath,
+      line: fieldEntry.line,
+      message: `Trail "${spec.id}" field "${fieldKey}" only repeats schema-derived ${redundantParts.join(' and ')}. Remove the override and let deriveFields() infer it.`,
+      rule: 'prefer-schema-inference',
+      severity: 'warn' as const,
+    }));
+};
+
+/**
+ * Warns when a fields override only repeats metadata deriveFields() already gets from
+ * the schema.
+ */
+export const preferSchemaInference: WardenRule = {
+  check(sourceCode: string, filePath: string): readonly WardenDiagnostic[] {
+    if (isTestFile(filePath)) {
+      return [];
+    }
+
+    return findTrailLikeSpecs(sourceCode).flatMap((spec) =>
+      diagnosticsForSpec(sourceCode, filePath, spec)
+    );
+  },
+  description:
+    'Warn when fields overrides only restate labels or enum options deriveFields() already infers from the Zod schema.',
+  name: 'prefer-schema-inference',
+  severity: 'warn',
+};