@ontrails/warden 1.0.0-beta.0

package/src/rules/ast.ts

@@ -0,0 +1,217 @@
+/**
+ * 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 `implementation:` property values in an AST. */
+export const findImplementationBodies = (ast: AstNode): AstNode[] => {
+  const bodies: AstNode[] = [];
+  walk(ast, (node) => {
+    if (
+      node.type === 'Property' &&
+      node.key?.name === 'implementation' &&
+      node.value
+    ) {
+      bodies.push(node.value);
+    }
+  });
+  return bodies;
+};
+
+export interface TrailDefinition {
+  /** Trail ID string, e.g. "entity.show" */
+  readonly id: string;
+  /** "trail" or "hike" */
+  readonly kind: string;
+  /** The config object argument (second arg to trail/hike call) */
+  readonly config: AstNode;
+  /** Start offset of the call expression */
+  readonly start: number;
+}
+
+/**
+ * Find all `trail("id", { ... })` and `hike("id", { ... })` call sites.
+ *
+ * Returns the trail ID, kind, and config object node for each definition.
+ */
+const TRAIL_CALLEE_NAMES = new Set(['trail', 'hike']);
+
+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 `.implementation()` on some object. */
+export const isImplementationCall = (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 === 'implementation'
+  );
+};
+
+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/context-no-surface-types.ts

@@ -0,0 +1,150 @@
+/**
+ * Detects imports of surface-specific modules and types in trail files.
+ *
+ * Uses AST parsing for accurate detection — no false positives from
+ * imports in comments or strings.
+ */
+
+import { offsetToLine, parse, walk } from './ast.js';
+import type { WardenDiagnostic, WardenRule } from './types.js';
+
+const SURFACE_MODULES = new Set([
+  'express',
+  'hono',
+  'fastify',
+  '@modelcontextprotocol/sdk',
+  'node:http',
+  'node:https',
+  '@hono/node-server',
+  'koa',
+]);
+
+const SURFACE_TYPE_NAMES = new Set([
+  'Request',
+  'Response',
+  'NextFunction',
+  'McpSession',
+  'McpCallToolRequest',
+  'IncomingMessage',
+  'ServerResponse',
+]);
+
+interface AstNode {
+  readonly type: string;
+  readonly start: number;
+  readonly [key: string]: unknown;
+}
+
+interface ImportSpecifier {
+  readonly local?: { readonly name?: string };
+  readonly imported?: { readonly name?: string };
+}
+
+const makeDiag = (
+  filePath: string,
+  sourceCode: string,
+  node: AstNode,
+  message: string
+): WardenDiagnostic => ({
+  filePath,
+  line: offsetToLine(sourceCode, node.start),
+  message,
+  rule: 'context-no-surface-types',
+  severity: 'error',
+});
+
+const findSurfaceTypeName = (
+  specifiers: readonly ImportSpecifier[]
+): string | undefined => {
+  for (const spec of specifiers) {
+    const name = spec.imported?.name ?? spec.local?.name;
+    if (name && SURFACE_TYPE_NAMES.has(name)) {
+      return name;
+    }
+  }
+  return undefined;
+};
+
+const getImportModuleName = (node: AstNode): string | null => {
+  if (node.type !== 'ImportDeclaration') {
+    return null;
+  }
+  const source = node['source'] as { readonly value?: string } | undefined;
+  return source?.value ?? null;
+};
+
+const checkSpecifiersForSurfaceTypes = (
+  node: AstNode,
+  filePath: string,
+  sourceCode: string
+): WardenDiagnostic | undefined => {
+  const specifiers = node['specifiers'] as
+    | readonly ImportSpecifier[]
+    | undefined;
+  if (!specifiers) {
+    return undefined;
+  }
+  const typeName = findSurfaceTypeName(specifiers);
+  if (!typeName) {
+    return undefined;
+  }
+  return makeDiag(
+    filePath,
+    sourceCode,
+    node,
+    `Do not import surface type "${typeName}" in trail implementation files.`
+  );
+};
+
+const classifyImport = (
+  node: AstNode,
+  filePath: string,
+  sourceCode: string
+): WardenDiagnostic | undefined => {
+  const moduleName = getImportModuleName(node);
+  if (!moduleName) {
+    return undefined;
+  }
+
+  if (SURFACE_MODULES.has(moduleName)) {
+    return makeDiag(
+      filePath,
+      sourceCode,
+      node,
+      `Do not import from surface module "${moduleName}" in trail implementation files.`
+    );
+  }
+
+  return checkSpecifiersForSurfaceTypes(node, filePath, sourceCode);
+};
+
+/**
+ * Detects imports of surface-specific types in trail implementation files.
+ */
+export const contextNoSurfaceTypes: WardenRule = {
+  check(sourceCode: string, filePath: string): readonly WardenDiagnostic[] {
+    if (!/\b(?:trail|hike)\s*\(/.test(sourceCode)) {
+      return [];
+    }
+
+    const ast = parse(filePath, sourceCode);
+    if (!ast) {
+      return [];
+    }
+
+    const diagnostics: WardenDiagnostic[] = [];
+    walk(ast, (node) => {
+      const diag = classifyImport(node as AstNode, filePath, sourceCode);
+      if (diag) {
+        diagnostics.push(diag);
+      }
+    });
+
+    return diagnostics;
+  },
+  description:
+    'Disallow surface-specific type imports (Request, Response, McpSession, etc.) in trail implementation files.',
+  name: 'context-no-surface-types',
+
+  severity: 'error',
+};

package/src/rules/implementation-returns-result.ts

@@ -0,0 +1,343 @@
+/**
+ * Finds implementations that return raw values instead of `Result`.
+ *
+ * Uses AST parsing to find `implementation:` bodies and check that
+ * every return statement returns Result.ok(), Result.err(), ctx.follow(),
+ * or a tracked Result-typed variable.
+ */
+
+import {
+  findImplementationBodies,
+  findTrailDefinitions,
+  offsetToLine,
+  parse,
+  walk,
+} from './ast.js';
+import { isTestFile } from './scan.js';
+import type { WardenDiagnostic, WardenRule } from './types.js';
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+interface AstNode {
+  readonly type: string;
+  readonly start: number;
+  readonly end: number;
+  readonly [key: string]: unknown;
+}
+
+// ---------------------------------------------------------------------------
+// Member expression helpers
+// ---------------------------------------------------------------------------
+
+/** Extract object.property names from a MemberExpression callee. */
+const extractMemberNames = (
+  callee: AstNode
+): { objName: string | undefined; propName: string | undefined } => {
+  const obj = (callee as unknown as { object?: AstNode }).object;
+  const prop = (callee as unknown as { property?: AstNode }).property;
+  const objName =
+    obj?.type === 'Identifier'
+      ? (obj as unknown as { name: string }).name
+      : undefined;
+  const propName =
+    prop?.type === 'Identifier'
+      ? (prop as unknown as { name: string }).name
+      : undefined;
+  return { objName, propName };
+};
+
+const isMemberExpression = (callee: AstNode): boolean =>
+  callee.type === 'StaticMemberExpression' ||
+  callee.type === 'MemberExpression';
+
+const isResultMemberCall = (callee: AstNode): boolean => {
+  if (!isMemberExpression(callee)) {
+    return false;
+  }
+  const { objName, propName } = extractMemberNames(callee);
+  if (objName === 'Result' && (propName === 'ok' || propName === 'err')) {
+    return true;
+  }
+  if (objName === 'ctx' && propName === 'follow') {
+    return true;
+  }
+  return propName === 'implementation';
+};
+
+// ---------------------------------------------------------------------------
+// Expression classification
+// ---------------------------------------------------------------------------
+
+/** Check if an expression node is an allowed Result-returning expression. */
+const isResultExpression = (node: AstNode): boolean => {
+  if (node.type === 'CallExpression') {
+    const callee = node['callee'] as AstNode | undefined;
+    if (!callee) {
+      return false;
+    }
+    return isResultMemberCall(callee);
+  }
+
+  if (node.type === 'AwaitExpression') {
+    const arg = (node as unknown as { argument?: AstNode }).argument;
+    return arg ? isResultExpression(arg) : false;
+  }
+
+  return false;
+};
+
+/** Check if a node is a call to a known Result-returning helper. */
+const isHelperCall = (
+  node: AstNode,
+  helperNames: ReadonlySet<string>
+): boolean => {
+  const target =
+    node.type === 'AwaitExpression'
+      ? ((node as unknown as { argument?: AstNode }).argument ?? null)
+      : node;
+
+  if (!target || target.type !== 'CallExpression') {
+    return false;
+  }
+
+  const callee = target['callee'] as AstNode | undefined;
+  if (callee?.type === 'Identifier') {
+    const { name } = callee as unknown as { name: string };
+    return helperNames.has(name);
+  }
+
+  return false;
+};
+
+/** Unwrap an optional AwaitExpression to get the inner identifier name. */
+const resolveIdentifierName = (node: AstNode): string | null => {
+  if (node.type === 'Identifier') {
+    return (node as unknown as { name: string }).name;
+  }
+  if (node.type === 'AwaitExpression') {
+    const inner = (node as unknown as { argument?: AstNode }).argument;
+    if (inner?.type === 'Identifier') {
+      return (inner as unknown as { name: string }).name;
+    }
+  }
+  return null;
+};
+
+/** Check if a return argument is an allowed Result value. */
+const isAllowedReturnArgument = (
+  argument: AstNode,
+  helperNames: ReadonlySet<string>,
+  resultVars: ReadonlySet<string>
+): boolean => {
+  if (isResultExpression(argument)) {
+    return true;
+  }
+  if (isHelperCall(argument, helperNames)) {
+    return true;
+  }
+
+  const varName = resolveIdentifierName(argument);
+  return varName !== null && resultVars.has(varName);
+};
+
+// ---------------------------------------------------------------------------
+// Variable tracking
+// ---------------------------------------------------------------------------
+
+/** Track a VariableDeclarator, adding to resultVars if it produces a Result. */
+const trackResultVariable = (node: AstNode, resultVars: Set<string>): void => {
+  const { init } = node as unknown as { init?: AstNode };
+  const { id } = node as unknown as { id?: AstNode };
+  if (init && id?.type === 'Identifier') {
+    const { name } = id as unknown as { name: string };
+    if (isResultExpression(init)) {
+      resultVars.add(name);
+    }
+  }
+};
+
+// ---------------------------------------------------------------------------
+// Return statement checking
+// ---------------------------------------------------------------------------
+
+/** Check return statements in a block body for non-Result returns. */
+const checkReturnStatements = (
+  blockBody: AstNode,
+  trailInfo: { id: string; label: string },
+  filePath: string,
+  sourceCode: string,
+  helperNames: ReadonlySet<string>,
+  diagnostics: WardenDiagnostic[]
+): void => {
+  const resultVars = new Set<string>();
+
+  walk(blockBody, (node) => {
+    if (node.type === 'VariableDeclarator') {
+      trackResultVariable(node, resultVars);
+    }
+
+    if (node.type !== 'ReturnStatement') {
+      return;
+    }
+
+    const { argument } = node as unknown as { argument?: AstNode };
+    // Bare return — not a value return
+    if (!argument) {
+      return;
+    }
+
+    if (isAllowedReturnArgument(argument, helperNames, resultVars)) {
+      return;
+    }
+
+    diagnostics.push({
+      filePath,
+      line: offsetToLine(sourceCode, node.start),
+      message: `${trailInfo.label} "${trailInfo.id}" implementation must return Result.ok(...) or Result.err(...), not a raw value.`,
+      rule: 'implementation-returns-result',
+      severity: 'error',
+    });
+  });
+};
+
+// ---------------------------------------------------------------------------
+// Result helper name collection
+// ---------------------------------------------------------------------------
+
+/** Check if a return type annotation mentions Result. */
+const hasResultReturnType = (node: AstNode, sourceCode: string): boolean => {
+  const { returnType } = node as unknown as { returnType?: AstNode };
+  if (!returnType) {
+    return false;
+  }
+  const annotationText = sourceCode.slice(returnType.start, returnType.end);
+  return /\bResult\s*</.test(annotationText);
+};
+
+const isFunctionLikeExpression = (node: AstNode): boolean =>
+  node.type === 'ArrowFunctionExpression' || node.type === 'FunctionExpression';
+
+/** Collect names of top-level functions/consts with explicit Result return types. */
+const collectResultHelperNames = (
+  ast: AstNode,
+  sourceCode: string
+): ReadonlySet<string> => {
+  const names = new Set<string>();
+
+  walk(ast, (node) => {
+    if (node.type === 'VariableDeclarator') {
+      const { id } = node as unknown as { id?: AstNode };
+      const { init } = node as unknown as { init?: AstNode };
+      if (
+        id?.type === 'Identifier' &&
+        init &&
+        isFunctionLikeExpression(init) &&
+        hasResultReturnType(init, sourceCode)
+      ) {
+        names.add((id as unknown as { name: string }).name);
+      }
+    }
+
+    if (node.type === 'FunctionDeclaration') {
+      const { id } = node as unknown as { id?: AstNode };
+      if (id?.type === 'Identifier' && hasResultReturnType(node, sourceCode)) {
+        names.add((id as unknown as { name: string }).name);
+      }
+    }
+  });
+
+  return names;
+};
+
+// ---------------------------------------------------------------------------
+// Per-implementation checking
+// ---------------------------------------------------------------------------
+
+const checkImplementation = (
+  implValue: AstNode,
+  info: { id: string; label: string },
+  filePath: string,
+  sourceCode: string,
+  helperNames: ReadonlySet<string>,
+  diagnostics: WardenDiagnostic[]
+): void => {
+  const fnBody = (implValue as unknown as { body?: AstNode }).body;
+  if (!fnBody) {
+    return;
+  }
+
+  if (fnBody.type === 'BlockStatement' || fnBody.type === 'FunctionBody') {
+    checkReturnStatements(
+      fnBody,
+      info,
+      filePath,
+      sourceCode,
+      helperNames,
+      diagnostics
+    );
+    return;
+  }
+
+  if (!isResultExpression(fnBody) && !isHelperCall(fnBody, helperNames)) {
+    diagnostics.push({
+      filePath,
+      line: offsetToLine(sourceCode, implValue.start),
+      message: `${info.label} "${info.id}" implementation must return Result.ok(...) or Result.err(...), not a raw value.`,
+      rule: 'implementation-returns-result',
+      severity: 'error',
+    });
+  }
+};
+
+// ---------------------------------------------------------------------------
+// Rule
+// ---------------------------------------------------------------------------
+
+const checkAllDefinitions = (
+  ast: AstNode,
+  filePath: string,
+  sourceCode: string
+): WardenDiagnostic[] => {
+  const diagnostics: WardenDiagnostic[] = [];
+  const helperNames = collectResultHelperNames(ast, sourceCode);
+
+  for (const def of findTrailDefinitions(ast)) {
+    const info = { id: def.id, label: def.kind === 'hike' ? 'Hike' : 'Trail' };
+    for (const implValue of findImplementationBodies(def.config as AstNode)) {
+      checkImplementation(
+        implValue,
+        info,
+        filePath,
+        sourceCode,
+        helperNames,
+        diagnostics
+      );
+    }
+  }
+
+  return diagnostics;
+};
+
+/**
+ * Finds implementations that return raw values instead of `Result`.
+ */
+export const implementationReturnsResult: WardenRule = {
+  check(sourceCode: string, filePath: string): readonly WardenDiagnostic[] {
+    if (isTestFile(filePath)) {
+      return [];
+    }
+
+    const ast = parse(filePath, sourceCode);
+    if (!ast) {
+      return [];
+    }
+
+    return checkAllDefinitions(ast as AstNode, filePath, sourceCode);
+  },
+  description:
+    'Disallow implementations that return raw values instead of Result.ok() or Result.err().',
+  name: 'implementation-returns-result',
+  severity: 'error',
+};