@ontrails/warden 0.2.0

package/src/rules/context-no-surface-types.ts

@@ -0,0 +1,214 @@
+/**
+ * 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 {
+  getNodeCallee,
+  getNodeComputed,
+  getNodeName,
+  getNodeProperty,
+  offsetToLine,
+  parse,
+  walk,
+} from '@ontrails/source';
+import type { AstNode } from '@ontrails/source';
+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 ImportSpecifier {
+  readonly local?: { readonly name?: string };
+  readonly imported?: { readonly name?: string };
+}
+
+const isBareTrailCallee = (callee: AstNode): boolean => {
+  if (callee.type !== 'Identifier') {
+    return false;
+  }
+  return getNodeName(callee) === 'trail';
+};
+
+const isNamespacedTrailCallee = (callee: AstNode): boolean => {
+  if (
+    callee.type !== 'MemberExpression' &&
+    callee.type !== 'StaticMemberExpression'
+  ) {
+    return false;
+  }
+  // Skip computed access like `ns[trail]()` — the bracketed expression may
+  // resolve to any runtime value, not the `trail` primitive, even when it
+  // happens to be an identifier literally named `trail`.
+  if (getNodeComputed(callee) === true) {
+    return false;
+  }
+  const prop = getNodeProperty(callee);
+  if (prop?.type !== 'Identifier') {
+    return false;
+  }
+  return getNodeName(prop) === 'trail';
+};
+
+/**
+ * True when `ast` contains a `trail(...)` call expression — i.e. this file
+ * looks like a trail definition. AST-based replacement for the legacy
+ * `/\btrail\s*\(/.test(sourceCode)` gate, which fired on string literals,
+ * comments, and docstrings.
+ *
+ * @remarks
+ * Both bare-identifier `trail(...)` and namespaced `ns.trail(...)` callees
+ * are recognized, so files using either `import { trail }` or
+ * `import * as ns from '@ontrails/core'` are detected as trail definitions.
+ *
+ * The inner `if (found)` guard skips further work in each callback invocation,
+ * but the shared `walk` helper from `@ontrails/source` exposes no abort
+ * mechanism, so
+ * the full tree is still traversed once a match is seen. Acceptable: `walk`
+ * is cheap and this rule only runs on files that already matched a path
+ * filter upstream.
+ */
+const hasTrailCall = (ast: AstNode): boolean => {
+  let found = false;
+  walk(ast, (node) => {
+    if (found || node.type !== 'CallExpression') {
+      return;
+    }
+    const callee = getNodeCallee(node);
+    if (!callee) {
+      return;
+    }
+    if (isBareTrailCallee(callee) || isNamespacedTrailCallee(callee)) {
+      found = true;
+    }
+  });
+  return found;
+};
+
+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 files. Trail logic stays surface-agnostic: extract what the trail needs from ${typeName} at the surface boundary and pass it through the trail's input schema.`
+  );
+};
+
+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 files. Trail logic stays surface-agnostic: keep ${moduleName} wiring in the surface entry module and pass what the trail needs through its input schema.`
+    );
+  }
+
+  return checkSpecifiersForSurfaceTypes(node, filePath, sourceCode);
+};
+
+/**
+ * Detects imports of surface-specific types in trail files.
+ */
+export const contextNoSurfaceTypes: WardenRule = {
+  check(sourceCode: string, filePath: string): readonly WardenDiagnostic[] {
+    const ast = parse(filePath, sourceCode);
+    if (!ast) {
+      return [];
+    }
+    if (!hasTrailCall(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 files.',
+  name: 'context-no-surface-types',
+
+  severity: 'error',
+};

package/src/rules/dead-internal-trail.ts

@@ -0,0 +1,161 @@
+import { collectComposeTargetTrailIds } from './source/composition.js';
+import {
+  findConfigProperty,
+  findTrailDefinitions,
+  getNodeValue,
+  getStringValue,
+  isStringLiteral,
+  offsetToLine,
+  parse,
+} from '@ontrails/source';
+import type { AstNode } from '@ontrails/source';
+import { isTestFile } from './scan.js';
+import type {
+  ProjectAwareWardenRule,
+  ProjectContext,
+  WardenDiagnostic,
+} from './types.js';
+
+const isNonEmptyActivationValue = (onValue: AstNode): boolean => {
+  // Identifier reference (e.g. `on: signalsArray`) — conservatively treat as
+  // having activation to avoid false positives. We can't cheaply resolve what
+  // the identifier binds to, so assume it's a non-empty activation.
+  if (onValue.type === 'Identifier') {
+    return true;
+  }
+  if (onValue.type !== 'ArrayExpression') {
+    return false;
+  }
+  const elements = onValue['elements'] as readonly AstNode[] | undefined;
+  return (elements?.length ?? 0) > 0;
+};
+
+const hasOnActivation = (config: AstNode): boolean => {
+  const onProp = findConfigProperty(config, 'on');
+  const onValue = onProp?.value as AstNode | undefined;
+  return onValue ? isNonEmptyActivationValue(onValue) : false;
+};
+
+const hasExplicitInternalVisibility = (config: AstNode): boolean => {
+  const visibilityProp = findConfigProperty(config, 'visibility');
+  const visibilityValue = visibilityProp?.value as AstNode | undefined;
+  return (
+    !!visibilityValue &&
+    isStringLiteral(visibilityValue) &&
+    getStringValue(visibilityValue) === 'internal'
+  );
+};
+
+/** Check legacy `meta: { internal: true }` convention (mirrors runtime effectiveVisibility). */
+const hasLegacyMetaInternal = (config: AstNode): boolean => {
+  const metaProp = findConfigProperty(config, 'meta');
+  const metaValue = metaProp?.value as AstNode | undefined;
+  if (!metaValue || metaValue.type !== 'ObjectExpression') {
+    return false;
+  }
+  const internalProp = findConfigProperty(metaValue, 'internal');
+  const internalValue = internalProp?.value as AstNode | undefined;
+  return (
+    internalValue?.type === 'BooleanLiteral' &&
+    getNodeValue(internalValue) === true
+  );
+};
+
+const isInternalTrail = (config: AstNode): boolean =>
+  hasExplicitInternalVisibility(config) || hasLegacyMetaInternal(config);
+
+const buildDeadInternalTrailDiagnostic = (
+  trailId: string,
+  filePath: string,
+  line: number
+): WardenDiagnostic => ({
+  filePath,
+  line,
+  message: `Trail "${trailId}" is marked visibility: 'internal' but nothing composes it and it has no on: activation. Internal trails should stay reachable through ctx.compose() or reactive activation.`,
+  rule: 'dead-internal-trail',
+  severity: 'warn',
+});
+
+const checkDeadInternalTrails = (
+  ast: AstNode | null,
+  sourceCode: string,
+  filePath: string,
+  composedTrailIds: ReadonlySet<string>,
+  topoTrailIds?: ReadonlySet<string> | undefined
+): readonly WardenDiagnostic[] => {
+  if (isTestFile(filePath) || !ast) {
+    return [];
+  }
+
+  const diagnostics: WardenDiagnostic[] = [];
+
+  for (const def of findTrailDefinitions(ast)) {
+    if (def.kind !== 'trail' || !isInternalTrail(def.config)) {
+      continue;
+    }
+
+    if (
+      hasOnActivation(def.config) ||
+      composedTrailIds.has(def.id) ||
+      topoTrailIds?.has(def.id)
+    ) {
+      continue;
+    }
+
+    diagnostics.push(
+      buildDeadInternalTrailDiagnostic(
+        def.id,
+        filePath,
+        offsetToLine(sourceCode, def.start)
+      )
+    );
+  }
+
+  return diagnostics;
+};
+
+export const deadInternalTrail: ProjectAwareWardenRule = {
+  check(sourceCode: string, filePath: string): readonly WardenDiagnostic[] {
+    const ast = parse(filePath, sourceCode);
+    return checkDeadInternalTrails(
+      ast,
+      sourceCode,
+      filePath,
+      ast ? collectComposeTargetTrailIds(ast, sourceCode) : new Set<string>()
+    );
+  },
+  checkWithContext(
+    sourceCode: string,
+    filePath: string,
+    context: ProjectContext
+  ): readonly WardenDiagnostic[] {
+    const ast = parse(filePath, sourceCode);
+    const localComposeTargetTrailIds = ast
+      ? collectComposeTargetTrailIds(ast, sourceCode)
+      : new Set<string>();
+    // Union project-wide compose evidence with the file-local evidence rather
+    // than preferring one over the other. The project context only collects
+    // compose edges from registered app topos, so a trail defined in a package
+    // that is scanned but not part of any registered topo (e.g. an internal
+    // child composed in its own module) would be absent from the context set
+    // yet present in the local set. Preferring the context set alone produced a
+    // false dead-internal-trail warning for those same-file compositions.
+    const composeTargetTrailIds = context.composeTargetTrailIds
+      ? new Set<string>([
+          ...context.composeTargetTrailIds,
+          ...localComposeTargetTrailIds,
+        ])
+      : localComposeTargetTrailIds;
+    return checkDeadInternalTrails(
+      ast,
+      sourceCode,
+      filePath,
+      composeTargetTrailIds,
+      context.topoTrailIds
+    );
+  },
+  description:
+    'Warn when an internal trail has no compositions anywhere in the project and no on: activation.',
+  name: 'dead-internal-trail',
+  severity: 'warn',
+};

package/src/rules/dead-public-trail.ts

@@ -0,0 +1,258 @@
+import { collectComposeTargetTrailIds } from './source/composition.js';
+import {
+  findConfigProperty,
+  findTrailDefinitions,
+  getNodeDeclaration,
+  getNodeDeclarations,
+  getNodeId,
+  getNodeInit,
+  getNodeLocal,
+  getNodeName,
+  getNodeSpecifiers,
+  getNodeValue,
+  getStringValue,
+  isStringLiteral,
+  offsetToLine,
+  parse,
+  walkWithParents,
+} from '@ontrails/source';
+import type { AstNode, AstParentContext } from '@ontrails/source';
+import { isTestFile } from './scan.js';
+import type {
+  ProjectAwareWardenRule,
+  ProjectContext,
+  WardenDiagnostic,
+} from './types.js';
+
+const RULE_NAME = 'dead-public-trail';
+
+const isNonEmptyActivationValue = (onValue: AstNode): boolean => {
+  if (onValue.type === 'Identifier') {
+    return true;
+  }
+  if (onValue.type !== 'ArrayExpression') {
+    return false;
+  }
+  const elements = onValue['elements'] as readonly AstNode[] | undefined;
+  return (elements?.length ?? 0) > 0;
+};
+
+const hasOnActivation = (config: AstNode): boolean => {
+  const onProp = findConfigProperty(config, 'on');
+  const onValue = onProp?.value as AstNode | undefined;
+  return onValue ? isNonEmptyActivationValue(onValue) : false;
+};
+
+const hasExplicitInternalVisibility = (config: AstNode): boolean => {
+  const visibilityProp = findConfigProperty(config, 'visibility');
+  const visibilityValue = visibilityProp?.value as AstNode | undefined;
+  return (
+    !!visibilityValue &&
+    isStringLiteral(visibilityValue) &&
+    getStringValue(visibilityValue) === 'internal'
+  );
+};
+
+const hasLegacyMetaInternal = (config: AstNode): boolean => {
+  const metaProp = findConfigProperty(config, 'meta');
+  const metaValue = metaProp?.value as AstNode | undefined;
+  if (!metaValue || metaValue.type !== 'ObjectExpression') {
+    return false;
+  }
+  const internalProp = findConfigProperty(metaValue, 'internal');
+  const internalValue = internalProp?.value as AstNode | undefined;
+  return (
+    internalValue?.type === 'BooleanLiteral' &&
+    getNodeValue(internalValue) === true
+  );
+};
+
+const isInternalTrail = (config: AstNode): boolean =>
+  hasExplicitInternalVisibility(config) || hasLegacyMetaInternal(config);
+
+const isExportDeclaration = (node: AstNode | null | undefined): boolean =>
+  node?.type === 'ExportNamedDeclaration' ||
+  node?.type === 'ExportDefaultDeclaration';
+
+const identifierName = (node: AstNode | undefined): string | null =>
+  node?.type === 'Identifier' ? (getNodeName(node) ?? null) : null;
+
+const trailBindingStarts = (ast: AstNode): ReadonlyMap<string, number> => {
+  const trailStarts = new Set(
+    findTrailDefinitions(ast)
+      .filter((definition) => definition.kind === 'trail')
+      .map((definition) => definition.start)
+  );
+  const bindings = new Map<string, number>();
+
+  walkWithParents(ast, (node: AstNode) => {
+    if (node.type !== 'VariableDeclarator') {
+      return;
+    }
+    const id = getNodeId(node);
+    const init = getNodeInit(node);
+    const name = identifierName(id);
+    if (name && init && trailStarts.has(init.start)) {
+      bindings.set(name, init.start);
+    }
+  });
+
+  return bindings;
+};
+
+const addExportedSpecifierStarts = (
+  node: AstNode,
+  bindings: ReadonlyMap<string, number>,
+  exported: Set<number>
+): void => {
+  const specifiers = getNodeSpecifiers(node) ?? [];
+  for (const specifier of specifiers) {
+    const local = getNodeLocal(specifier);
+    const name = identifierName(local);
+    const start = name ? bindings.get(name) : undefined;
+    if (start !== undefined) {
+      exported.add(start);
+    }
+  }
+};
+
+const exportedTrailStarts = (ast: AstNode): ReadonlySet<number> => {
+  const exported = new Set<number>();
+  const bindings = trailBindingStarts(ast);
+
+  walkWithParents(ast, (node: AstNode, context: AstParentContext) => {
+    if (node.type !== 'CallExpression') {
+      return;
+    }
+
+    // Catch `export default trail(...)`. Exported variable declarations are
+    // handled by the VariableDeclaration walk below.
+    if (isExportDeclaration(context.parent)) {
+      exported.add(node.start);
+    }
+  });
+
+  walkWithParents(ast, (node: AstNode, context: AstParentContext) => {
+    if (node.type !== 'VariableDeclaration') {
+      return;
+    }
+    if (!isExportDeclaration(context.parent)) {
+      return;
+    }
+    const declarations = getNodeDeclarations(node) ?? [];
+    for (const declaration of declarations) {
+      const init = getNodeInit(declaration);
+      if (init?.type === 'CallExpression') {
+        exported.add(init.start);
+      }
+    }
+  });
+
+  walkWithParents(ast, (node: AstNode) => {
+    if (node.type === 'ExportNamedDeclaration') {
+      addExportedSpecifierStarts(node, bindings, exported);
+      return;
+    }
+
+    if (node.type !== 'ExportDefaultDeclaration') {
+      return;
+    }
+    const declaration = getNodeDeclaration(node);
+    const name = identifierName(declaration);
+    const start = name ? bindings.get(name) : undefined;
+    if (start !== undefined) {
+      exported.add(start);
+    }
+  });
+
+  return exported;
+};
+
+const buildDiagnostic = (
+  trailId: string,
+  filePath: string,
+  line: number
+): WardenDiagnostic => ({
+  filePath,
+  line,
+  message: `Exported public trail "${trailId}" is not registered in a configured app topo, composed by another trail, or activated by on:. Anchor the contract in a topo, compose it, mark it internal, or remove the public export.`,
+  rule: RULE_NAME,
+  severity: 'warn',
+});
+
+const unionComposeTargetIds = (
+  ast: AstNode | null,
+  sourceCode: string,
+  context: ProjectContext
+): ReadonlySet<string> => {
+  const local = ast
+    ? collectComposeTargetTrailIds(ast, sourceCode)
+    : new Set<string>();
+  return context.composeTargetTrailIds
+    ? new Set([...context.composeTargetTrailIds, ...local])
+    : local;
+};
+
+const checkDeadPublicTrails = (
+  ast: AstNode | null,
+  sourceCode: string,
+  filePath: string,
+  context: ProjectContext
+): readonly WardenDiagnostic[] => {
+  if (isTestFile(filePath) || !ast || !context.topoTrailIds) {
+    return [];
+  }
+
+  const exportedStarts = exportedTrailStarts(ast);
+  const composeTargetTrailIds = unionComposeTargetIds(ast, sourceCode, context);
+  const diagnostics: WardenDiagnostic[] = [];
+
+  for (const def of findTrailDefinitions(ast)) {
+    if (
+      def.kind !== 'trail' ||
+      isInternalTrail(def.config) ||
+      !exportedStarts.has(def.start)
+    ) {
+      continue;
+    }
+
+    if (
+      hasOnActivation(def.config) ||
+      composeTargetTrailIds.has(def.id) ||
+      context.topoTrailIds.has(def.id)
+    ) {
+      continue;
+    }
+
+    diagnostics.push(
+      buildDiagnostic(def.id, filePath, offsetToLine(sourceCode, def.start))
+    );
+  }
+
+  return diagnostics;
+};
+
+export const deadPublicTrail: ProjectAwareWardenRule = {
+  check(sourceCode: string, filePath: string): readonly WardenDiagnostic[] {
+    const ast = parse(filePath, sourceCode);
+    return checkDeadPublicTrails(ast, sourceCode, filePath, {
+      knownTrailIds: new Set<string>(),
+    });
+  },
+  checkWithContext(
+    sourceCode: string,
+    filePath: string,
+    context: ProjectContext
+  ): readonly WardenDiagnostic[] {
+    return checkDeadPublicTrails(
+      parse(filePath, sourceCode),
+      sourceCode,
+      filePath,
+      context
+    );
+  },
+  description:
+    'Warn when an exported public trail is neither registered in configured app topos nor reachable through composition or activation.',
+  name: RULE_NAME,
+  severity: 'warn',
+};