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

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

@@ -0,0 +1,225 @@
+import {
+  findConfigProperty,
+  findTrailDefinitions,
+  identifierName,
+  offsetToLine,
+  parse,
+  walk,
+  walkScope,
+} from './ast.js';
+import type { AstNode } from './ast.js';
+import { isTestFile } from './scan.js';
+import type { WardenDiagnostic, WardenRule } from './types.js';
+
+const TRANSPARENT_WRAPPER_TYPES = new Set([
+  'ParenthesizedExpression',
+  'TSAsExpression',
+  'TSSatisfiesExpression',
+  'TSNonNullExpression',
+  'TSTypeAssertion',
+]);
+
+const FUNCTION_TYPES = new Set([
+  'ArrowFunctionExpression',
+  'FunctionDeclaration',
+  'FunctionExpression',
+]);
+
+const unwrapExpression = (node: AstNode | undefined): AstNode | undefined => {
+  let current = node;
+  while (current && TRANSPARENT_WRAPPER_TYPES.has(current.type)) {
+    current = current['expression'] as AstNode | undefined;
+  }
+  return current;
+};
+
+const getDetourElements = (config: AstNode): readonly (AstNode | null)[] => {
+  const detoursProp = findConfigProperty(config, 'detours');
+  if (!detoursProp) {
+    return [];
+  }
+
+  const detoursValue = unwrapExpression(
+    detoursProp.value as AstNode | undefined
+  );
+  if (!detoursValue || detoursValue.type !== 'ArrayExpression') {
+    return [];
+  }
+
+  return (
+    ((detoursValue as AstNode)['elements'] as readonly (AstNode | null)[]) ?? []
+  );
+};
+
+const getFunctionBody = (node: AstNode | undefined): AstNode | undefined => {
+  if (!node || !FUNCTION_TYPES.has(node.type)) {
+    return undefined;
+  }
+
+  const { body } = node;
+  return Array.isArray(body) ? undefined : (body as AstNode | undefined);
+};
+
+interface RecoverBodyMatch {
+  readonly index: number;
+  readonly trailId: string;
+  readonly body: AstNode;
+}
+
+const collectFunctionRecoverBinding = (
+  bindings: Map<string, AstNode>,
+  node: AstNode
+): boolean => {
+  if (node.type !== 'FunctionDeclaration') {
+    return false;
+  }
+
+  const name = identifierName(node['id'] as AstNode | undefined);
+  if (name) {
+    bindings.set(name, node);
+  }
+  return true;
+};
+
+const collectVariableRecoverBinding = (
+  bindings: Map<string, AstNode>,
+  node: AstNode
+): void => {
+  if (node.type !== 'VariableDeclarator') {
+    return;
+  }
+
+  const name = identifierName(node['id'] as AstNode | undefined);
+  const init = unwrapExpression(node['init'] as AstNode | undefined);
+  if (!name || !init || !FUNCTION_TYPES.has(init.type)) {
+    return;
+  }
+
+  bindings.set(name, init);
+};
+
+const collectRecoverBinding = (
+  bindings: Map<string, AstNode>,
+  node: AstNode
+): void => {
+  if (collectFunctionRecoverBinding(bindings, node)) {
+    return;
+  }
+
+  collectVariableRecoverBinding(bindings, node);
+};
+
+const collectRecoverBindings = (ast: AstNode): ReadonlyMap<string, AstNode> => {
+  const bindings = new Map<string, AstNode>();
+
+  walk(ast, (node) => {
+    collectRecoverBinding(bindings, node);
+  });
+
+  return bindings;
+};
+
+const resolveRecoverBody = (
+  node: AstNode | undefined,
+  bindings: ReadonlyMap<string, AstNode>
+): AstNode | undefined => {
+  const unwrapped = unwrapExpression(node);
+  if (!unwrapped) {
+    return undefined;
+  }
+
+  const inlineBody = getFunctionBody(unwrapped);
+  if (inlineBody) {
+    return inlineBody;
+  }
+
+  const bindingName = identifierName(unwrapped);
+  if (!bindingName) {
+    return undefined;
+  }
+
+  return getFunctionBody(bindings.get(bindingName));
+};
+
+const resolveRecoverBodyFromElement = (
+  element: AstNode | null,
+  bindings: ReadonlyMap<string, AstNode>
+): AstNode | undefined => {
+  if (!element || element.type !== 'ObjectExpression') {
+    return undefined;
+  }
+
+  const recoverProp = findConfigProperty(element, 'recover');
+  return resolveRecoverBody(
+    recoverProp?.value as AstNode | undefined,
+    bindings
+  );
+};
+
+const appendRecoverBodies = (
+  bodies: RecoverBodyMatch[],
+  definition: { readonly config: AstNode; readonly id: string },
+  bindings: ReadonlyMap<string, AstNode>
+): void => {
+  const detourElements = getDetourElements(definition.config);
+  for (const [index, element] of detourElements.entries()) {
+    const body = resolveRecoverBodyFromElement(element, bindings);
+    if (!body) {
+      continue;
+    }
+
+    bodies.push({ body, index, trailId: definition.id });
+  }
+};
+
+const findRecoverBodies = (ast: AstNode): readonly RecoverBodyMatch[] => {
+  const bindings = collectRecoverBindings(ast);
+  const bodies: RecoverBodyMatch[] = [];
+
+  for (const definition of findTrailDefinitions(ast)) {
+    if (definition.kind !== 'trail') {
+      continue;
+    }
+
+    appendRecoverBodies(bodies, definition, bindings);
+  }
+
+  return bodies;
+};
+
+export const noThrowInDetourRecover: WardenRule = {
+  check(sourceCode: string, filePath: string): readonly WardenDiagnostic[] {
+    if (isTestFile(filePath)) {
+      return [];
+    }
+
+    const ast = parse(filePath, sourceCode);
+    if (!ast) {
+      return [];
+    }
+
+    const diagnostics: WardenDiagnostic[] = [];
+
+    for (const recover of findRecoverBodies(ast)) {
+      walkScope(recover.body, (node) => {
+        if (node.type !== 'ThrowStatement') {
+          return;
+        }
+
+        diagnostics.push({
+          filePath,
+          line: offsetToLine(sourceCode, node.start),
+          message: `Trail "${recover.trailId}" detour[${recover.index}] recover must not throw. Return Result.err() instead.`,
+          rule: 'no-throw-in-detour-recover',
+          severity: 'error',
+        });
+      });
+    }
+
+    return diagnostics;
+  },
+  description:
+    'Disallow throw statements inside detour recover functions. Use Result.err() instead.',
+  name: 'no-throw-in-detour-recover',
+  severity: 'error',
+};

package/src/rules/no-throw-in-implementation.ts

@@ -1,11 +1,13 @@
 /**
- * Finds `throw` statements inside `implementation:` function bodies.
+ * Finds `throw` statements inside `blaze:` function bodies.
  *
- * Uses AST parsing for accurate detection — no false positives from
- * throw in comments, strings, or nested non-implementation functions.
+ * Uses scope-aware AST walking so throws inside nested callbacks
+ * (e.g. `.map()`, `.filter()`, inner helpers) are not attributed to
+ * the blaze body itself. ADR-0007 requires this class of false positive
+ * to be avoided — only throws in the blaze body scope should be flagged.
  */
 
-import { findImplementationBodies, offsetToLine, parse, walk } from './ast.js';
+import { findBlazeBodies, offsetToLine, parse, walkScope } from './ast.js';
 import type { WardenDiagnostic, WardenRule } from './types.js';
 
 export const noThrowInImplementation: WardenRule = {
@@ -17,14 +19,13 @@ export const noThrowInImplementation: WardenRule = {
 
     const diagnostics: WardenDiagnostic[] = [];
 
-    for (const body of findImplementationBodies(ast)) {
-      walk(body, (node) => {
+    for (const body of findBlazeBodies(ast)) {
+      walkScope(body, (node) => {
         if (node.type === 'ThrowStatement') {
           diagnostics.push({
             filePath,
             line: offsetToLine(sourceCode, node.start),
-            message:
-              'Do not throw inside implementation. Use Result.err() instead.',
+            message: 'Do not throw inside the blaze. Use Result.err() instead.',
             rule: 'no-throw-in-implementation',
             severity: 'error',
           });
@@ -35,7 +36,7 @@ export const noThrowInImplementation: WardenRule = {
     return diagnostics;
   },
   description:
-    'Disallow throw statements inside trail/route implementation bodies. Use Result.err() instead.',
+    'Disallow throw statements inside blaze bodies. Use Result.err() instead.',
   name: 'no-throw-in-implementation',
   severity: 'error',
 };

package/src/rules/no-top-level-surface.ts

@@ -0,0 +1,389 @@
+import {
+  getStringValue,
+  identifierName,
+  isStringLiteral,
+  offsetToLine,
+  parse,
+} from './ast.js';
+import type { AstNode } from './ast.js';
+import type { WardenDiagnostic, WardenRule } from './types.js';
+
+const RULE_NAME = 'no-top-level-surface';
+
+const TOPO_EXPORT_NAMES = new Set(['app', 'graph']);
+const SURFACE_OPEN_CALLEE_NAMES = new Set([
+  'connectStdio',
+  'startServer',
+  'surface',
+]);
+const TOPO_IMPORT_SOURCES = new Set(['@ontrails/core']);
+const SURFACE_IMPORT_SOURCES = new Set([
+  '@ontrails/commander',
+  '@ontrails/hono',
+  '@ontrails/http',
+  '@ontrails/http/bun',
+  '@ontrails/mcp',
+]);
+
+const diagnosticMessage =
+  'This module exports a topo and opens a surface at module top level. Trails introspection commands (`survey`, `guide`, `compile`) import topo entry modules, so opening a surface here can trigger sockets or transports during introspection. Move surface-opening to a separate entry/bin and keep the topo-export module side-effect-free.';
+
+const unwrapExportDeclaration = (node: AstNode): AstNode =>
+  node.type === 'ExportNamedDeclaration' ||
+  node.type === 'ExportDefaultDeclaration'
+    ? ((node as unknown as { declaration?: AstNode }).declaration ?? node)
+    : node;
+
+interface ImportedBindings {
+  readonly named: ReadonlyMap<string, string>;
+  readonly namespaces: ReadonlySet<string>;
+}
+
+const importSource = (node: AstNode): string | null => {
+  const { source } = node as unknown as { readonly source?: AstNode };
+  return source && isStringLiteral(source) ? getStringValue(source) : null;
+};
+
+const importedSpecifierName = (node: AstNode | undefined): string | null =>
+  identifierName(node) ??
+  (node && isStringLiteral(node) ? getStringValue(node) : null);
+
+const addFrameworkImportBindings = (
+  ast: AstNode,
+  sources: ReadonlySet<string>,
+  allowedImports: ReadonlySet<string>
+): ImportedBindings => {
+  const named = new Map<string, string>();
+  const namespaces = new Set<string>();
+  const body = (ast as unknown as { body?: readonly AstNode[] }).body ?? [];
+
+  for (const statement of body) {
+    if (
+      statement.type !== 'ImportDeclaration' ||
+      !sources.has(importSource(statement) ?? '')
+    ) {
+      continue;
+    }
+
+    const specifiers =
+      (statement as unknown as { specifiers?: readonly AstNode[] })
+        .specifiers ?? [];
+    for (const specifier of specifiers) {
+      if (specifier.type === 'ImportNamespaceSpecifier') {
+        const localName = identifierName(
+          (specifier as unknown as { local?: AstNode }).local
+        );
+        if (localName) {
+          namespaces.add(localName);
+        }
+        continue;
+      }
+      if (specifier.type !== 'ImportSpecifier') {
+        continue;
+      }
+
+      const { imported, local } = specifier as unknown as {
+        readonly imported?: AstNode;
+        readonly local?: AstNode;
+      };
+      const importedName = importedSpecifierName(imported);
+      const localName = identifierName(local);
+      if (importedName && allowedImports.has(importedName) && localName) {
+        named.set(localName, importedName);
+      }
+    }
+  }
+
+  return { named, namespaces };
+};
+
+const unwrapExpression = (node: AstNode | undefined): AstNode | undefined => {
+  let current = node;
+  while (
+    current?.type === 'AwaitExpression' ||
+    current?.type === 'ChainExpression' ||
+    current?.type === 'TSAsExpression' ||
+    current?.type === 'TSSatisfiesExpression'
+  ) {
+    current =
+      (current as unknown as { argument?: AstNode; expression?: AstNode })
+        .expression ??
+      (current as unknown as { argument?: AstNode; expression?: AstNode })
+        .argument;
+  }
+  return current;
+};
+
+const memberExpressionParts = (
+  node: AstNode | undefined
+): { objectName: string | null; propertyName: string | null } => {
+  if (node?.type !== 'MemberExpression') {
+    return { objectName: null, propertyName: null };
+  }
+  const { computed, property } = node as unknown as {
+    readonly computed?: boolean;
+    readonly object?: AstNode;
+    readonly property?: AstNode;
+  };
+  return {
+    objectName: identifierName(
+      (node as unknown as { object?: AstNode }).object
+    ),
+    propertyName: computed ? null : identifierName(property),
+  };
+};
+
+const calleeName = (
+  node: AstNode | undefined,
+  bindings: ImportedBindings
+): string | null => {
+  const callee = unwrapExpression(node);
+  if (!callee) {
+    return null;
+  }
+  const directName = identifierName(callee);
+  if (directName && bindings.named.has(directName)) {
+    return bindings.named.get(directName) ?? null;
+  }
+
+  const { objectName, propertyName } = memberExpressionParts(callee);
+  if (
+    objectName &&
+    propertyName &&
+    bindings.namespaces.has(objectName) &&
+    (SURFACE_OPEN_CALLEE_NAMES.has(propertyName) || propertyName === 'topo')
+  ) {
+    return propertyName;
+  }
+
+  return null;
+};
+
+const isTopoCall = (
+  node: AstNode | undefined,
+  bindings: ImportedBindings
+): boolean =>
+  calleeName(
+    (unwrapExpression(node) as unknown as { callee?: AstNode })?.callee,
+    bindings
+  ) === 'topo';
+
+const isSurfaceOpenCall = (
+  node: AstNode | undefined,
+  bindings: ImportedBindings
+): boolean => {
+  const expression = unwrapExpression(node);
+  if (expression?.type !== 'CallExpression') {
+    return false;
+  }
+
+  const { callee } = expression as unknown as { readonly callee?: AstNode };
+  const directName = calleeName(callee, bindings);
+  if (directName && SURFACE_OPEN_CALLEE_NAMES.has(directName)) {
+    return true;
+  }
+  const { objectName, propertyName } = memberExpressionParts(callee);
+  if (
+    objectName &&
+    propertyName === 'listen' &&
+    bindings.namespaces.has(objectName)
+  ) {
+    return true;
+  }
+
+  return false;
+};
+
+const declarationIdName = (node: AstNode | undefined): string | null =>
+  identifierName(node) ??
+  identifierName((node as unknown as { left?: AstNode } | undefined)?.left);
+
+const collectTopLevelTopoBindings = (
+  ast: AstNode,
+  topoBindings: ImportedBindings
+): ReadonlySet<string> => {
+  const bindings = new Set<string>();
+  const body = (ast as unknown as { body?: readonly AstNode[] }).body ?? [];
+
+  for (const statement of body) {
+    const declaration = unwrapExportDeclaration(statement);
+    if (declaration.type === 'VariableDeclaration') {
+      const declarations =
+        (declaration as unknown as { declarations?: readonly AstNode[] })
+          .declarations ?? [];
+      for (const item of declarations) {
+        const { id, init } = item as unknown as {
+          readonly id?: AstNode;
+          readonly init?: AstNode;
+        };
+        const name = declarationIdName(id);
+        if (name && isTopoCall(init, topoBindings)) {
+          bindings.add(name);
+        }
+      }
+    }
+  }
+
+  return bindings;
+};
+
+const namedExportCarriesTopo = (
+  statement: AstNode,
+  topLevelTopoBindings: ReadonlySet<string>
+): boolean => {
+  const specifiers =
+    (statement as unknown as { specifiers?: readonly AstNode[] }).specifiers ??
+    [];
+
+  for (const specifier of specifiers) {
+    const { exported, local } = specifier as unknown as {
+      readonly exported?: AstNode;
+      readonly local?: AstNode;
+    };
+    const exportedName = identifierName(exported);
+    const localName = identifierName(local);
+    if (
+      exportedName &&
+      TOPO_EXPORT_NAMES.has(exportedName) &&
+      localName &&
+      topLevelTopoBindings.has(localName)
+    ) {
+      return true;
+    }
+  }
+
+  return false;
+};
+
+const moduleExportsTopo = (
+  ast: AstNode,
+  topoBindings: ImportedBindings
+): boolean => {
+  const topLevelTopoBindings = collectTopLevelTopoBindings(ast, topoBindings);
+  const body = (ast as unknown as { body?: readonly AstNode[] }).body ?? [];
+
+  for (const statement of body) {
+    if (statement.type === 'ExportDefaultDeclaration') {
+      const declaration = unwrapExportDeclaration(statement);
+      if (isTopoCall(declaration, topoBindings)) {
+        return true;
+      }
+      const defaultName = identifierName(declaration);
+      if (defaultName && topLevelTopoBindings.has(defaultName)) {
+        return true;
+      }
+    }
+
+    if (statement.type === 'ExportNamedDeclaration') {
+      const declaration = unwrapExportDeclaration(statement);
+      if (namedExportCarriesTopo(statement, topLevelTopoBindings)) {
+        return true;
+      }
+      if (declaration.type !== 'VariableDeclaration') {
+        continue;
+      }
+      const declarations =
+        (declaration as unknown as { declarations?: readonly AstNode[] })
+          .declarations ?? [];
+      for (const item of declarations) {
+        const { id, init } = item as unknown as {
+          readonly id?: AstNode;
+          readonly init?: AstNode;
+        };
+        const name = declarationIdName(id);
+        if (
+          name &&
+          TOPO_EXPORT_NAMES.has(name) &&
+          isTopoCall(init, topoBindings)
+        ) {
+          return true;
+        }
+      }
+    }
+  }
+
+  return false;
+};
+
+const topLevelSurfaceOpen = (
+  statement: AstNode,
+  surfaceBindings: ImportedBindings
+): AstNode | null => {
+  const declaration = unwrapExportDeclaration(statement);
+  if (declaration.type === 'ExpressionStatement') {
+    const { expression } = declaration as unknown as {
+      readonly expression?: AstNode;
+    };
+    const unwrapped = unwrapExpression(expression);
+    return isSurfaceOpenCall(unwrapped, surfaceBindings)
+      ? (unwrapped ?? null)
+      : null;
+  }
+
+  const unwrappedDeclaration = unwrapExpression(declaration);
+  if (isSurfaceOpenCall(unwrappedDeclaration, surfaceBindings)) {
+    return unwrappedDeclaration ?? null;
+  }
+
+  if (declaration.type !== 'VariableDeclaration') {
+    return null;
+  }
+
+  const declarations =
+    (declaration as unknown as { declarations?: readonly AstNode[] })
+      .declarations ?? [];
+  for (const item of declarations) {
+    const { init } = item as unknown as { readonly init?: AstNode };
+    const unwrapped = unwrapExpression(init);
+    if (isSurfaceOpenCall(unwrapped, surfaceBindings)) {
+      return unwrapped ?? null;
+    }
+  }
+
+  return null;
+};
+
+export const noTopLevelSurface: WardenRule = {
+  check(sourceCode: string, filePath: string): readonly WardenDiagnostic[] {
+    const ast = parse(filePath, sourceCode);
+    if (!ast) {
+      return [];
+    }
+
+    const topoBindings = addFrameworkImportBindings(
+      ast,
+      TOPO_IMPORT_SOURCES,
+      new Set(['topo'])
+    );
+    if (!moduleExportsTopo(ast, topoBindings)) {
+      return [];
+    }
+    const surfaceBindings = addFrameworkImportBindings(
+      ast,
+      SURFACE_IMPORT_SOURCES,
+      SURFACE_OPEN_CALLEE_NAMES
+    );
+
+    const diagnostics: WardenDiagnostic[] = [];
+    const body = (ast as unknown as { body?: readonly AstNode[] }).body ?? [];
+    for (const statement of body) {
+      const surfaceOpen = topLevelSurfaceOpen(statement, surfaceBindings);
+      if (!surfaceOpen) {
+        continue;
+      }
+      diagnostics.push({
+        filePath,
+        line: offsetToLine(sourceCode, surfaceOpen.start),
+        message: diagnosticMessage,
+        rule: RULE_NAME,
+        severity: 'warn',
+      });
+    }
+
+    return diagnostics;
+  },
+  description:
+    'Coach topo export modules to keep surface-opening side effects out of module top level.',
+  name: RULE_NAME,
+  severity: 'warn',
+};