@ontrails/warden 0.2.0

package/src/rules/unreachable-detour-shadowing.ts

@@ -0,0 +1,343 @@
+import { TrailsError, errorClasses } from '@ontrails/core';
+
+import {
+  extractStringLiteral,
+  findConfigProperty,
+  findTrailDefinitions,
+  getNodeId,
+  getNodeImported,
+  getNodeInit,
+  getNodeLocal,
+  getNodeSource,
+  getNodeSpecifiers,
+  getNodeSuperClass,
+  identifierName,
+  offsetToLine,
+  parse,
+  walk,
+} from '@ontrails/source';
+import type { AstNode } from '@ontrails/source';
+import { isTestFile } from './scan.js';
+import type { WardenDiagnostic, WardenRule } from './types.js';
+
+interface ErrorTypeShape {
+  readonly name: string;
+  readonly prototype: TrailsError;
+}
+
+interface DetourOnType {
+  readonly line: number;
+  readonly onType: string;
+}
+
+const knownErrorConstructors = new Map<string, ErrorTypeShape>([
+  [TrailsError.name, TrailsError],
+  ...errorClasses.map(({ ctor, name }) => [name, ctor] as const),
+]);
+
+const knownErrorParents = new Map<string, string | null>(
+  [...knownErrorConstructors.entries()].map(([name, ctor]) => {
+    const parent = Object.getPrototypeOf(ctor.prototype)?.constructor;
+    const parentName =
+      typeof parent?.name === 'string' &&
+      knownErrorConstructors.has(parent.name)
+        ? parent.name
+        : null;
+    return [name, parentName];
+  })
+);
+
+const resolveKnownErrorName = (
+  name: string,
+  aliases: ReadonlyMap<string, string>
+): string => aliases.get(name) ?? name;
+
+const coreImportSource = (node: AstNode): string | null =>
+  extractStringLiteral(getNodeSource(node));
+
+const collectImportSpecifierAliases = (
+  specifiers: readonly AstNode[] | undefined,
+  aliases: Map<string, string>
+): void => {
+  for (const specifier of specifiers ?? []) {
+    if (specifier.type !== 'ImportSpecifier') {
+      continue;
+    }
+
+    const localName = identifierName(getNodeLocal(specifier));
+    const importedName =
+      identifierName(getNodeImported(specifier)) ?? localName;
+
+    if (localName && importedName && knownErrorConstructors.has(importedName)) {
+      aliases.set(localName, importedName);
+    }
+  }
+};
+
+const collectKnownErrorAliases = (
+  ast: AstNode
+): ReadonlyMap<string, string> => {
+  const aliases = new Map<string, string>();
+
+  walk(ast, (node) => {
+    if (node.type !== 'ImportDeclaration') {
+      return;
+    }
+
+    if (coreImportSource(node) !== '@ontrails/core') {
+      return;
+    }
+
+    const specifiers = getNodeSpecifiers(node);
+    collectImportSpecifierAliases(specifiers, aliases);
+  });
+
+  return aliases;
+};
+
+const recordLocalErrorParent = (
+  parents: Map<string, string>,
+  aliases: ReadonlyMap<string, string>,
+  className: string | null,
+  parentName: string | null
+): void => {
+  if (!className || !parentName) {
+    return;
+  }
+
+  parents.set(className, resolveKnownErrorName(parentName, aliases));
+};
+
+const collectClassExpressionParent = (
+  node: AstNode,
+  parents: Map<string, string>,
+  aliases: ReadonlyMap<string, string>
+): void => {
+  if (node.type !== 'VariableDeclarator') {
+    return;
+  }
+
+  const init = getNodeInit(node);
+  if (!init || init.type !== 'ClassExpression') {
+    return;
+  }
+
+  const className = identifierName(getNodeId(node));
+  const parentName = identifierName(getNodeSuperClass(init));
+  recordLocalErrorParent(parents, aliases, className, parentName);
+};
+
+const collectLocalErrorParents = (
+  ast: AstNode,
+  aliases: ReadonlyMap<string, string>
+): ReadonlyMap<string, string> => {
+  const parents = new Map<string, string>();
+
+  walk(ast, (node) => {
+    if (node.type === 'ClassDeclaration') {
+      const className = identifierName(getNodeId(node));
+      const parentName = identifierName(getNodeSuperClass(node));
+      recordLocalErrorParent(parents, aliases, className, parentName);
+      return;
+    }
+
+    collectClassExpressionParent(node, parents, aliases);
+  });
+
+  return parents;
+};
+
+/**
+ * Return the raw AST elements of a trail's `detours` array.
+ *
+ * @remarks
+ * Spread elements (`...baseDetours`) in the `detours` array are intentionally
+ * skipped here and by {@link extractDetourOnTypes}. This makes the ordering
+ * analysis best-effort for arrays that contain spreads: only literal inline
+ * detour object entries are ordering-checked, so spreads can cause both false
+ * negatives and false positives depending on where they sit relative to the
+ * literal entries.
+ */
+const getDetourElements = (config: AstNode): readonly (AstNode | null)[] => {
+  const detoursProp = findConfigProperty(config, 'detours');
+  if (!detoursProp) {
+    return [];
+  }
+
+  const detoursValue = detoursProp.value as AstNode | undefined;
+  if (!detoursValue || detoursValue.type !== 'ArrayExpression') {
+    return [];
+  }
+
+  const elements = (detoursValue as AstNode)['elements'] as
+    | readonly (AstNode | null)[]
+    | undefined;
+  return elements ?? [];
+};
+
+const extractDetourOnTypes = (
+  config: AstNode,
+  sourceCode: string,
+  aliases: ReadonlyMap<string, string>
+): readonly DetourOnType[] =>
+  getDetourElements(config).flatMap((element) => {
+    if (!element || element.type !== 'ObjectExpression') {
+      return [];
+    }
+
+    const onProp = findConfigProperty(element, 'on');
+    const onNode = onProp?.value as AstNode | undefined;
+    const onTypeName = identifierName(onNode);
+    if (!onNode || !onTypeName) {
+      return [];
+    }
+
+    return [
+      {
+        line: offsetToLine(sourceCode, onNode.start),
+        onType: resolveKnownErrorName(onTypeName, aliases),
+      },
+    ];
+  });
+
+const nextParentType = (
+  errorType: string,
+  localParents: ReadonlyMap<string, string>
+): string | null =>
+  localParents.get(errorType) ?? knownErrorParents.get(errorType) ?? null;
+
+const isSameOrSubtype = (
+  candidate: string,
+  ancestor: string,
+  localParents: ReadonlyMap<string, string>
+): boolean => {
+  let current: string | null = candidate;
+  const seen = new Set<string>();
+
+  while (current && !seen.has(current)) {
+    if (current === ancestor) {
+      return true;
+    }
+
+    seen.add(current);
+    current = nextParentType(current, localParents);
+  }
+
+  return false;
+};
+
+const buildDiagnostic = (
+  trailId: string,
+  shadowedType: string,
+  shadowingType: string,
+  filePath: string,
+  line: number
+): WardenDiagnostic => ({
+  filePath,
+  line,
+  message: `Trail "${trailId}" declares detour on "${shadowedType}" after earlier detour on "${shadowingType}". Because "${shadowingType}" matches "${shadowedType}" first, the later detour is unreachable. ${
+    shadowedType === shadowingType
+      ? `Remove or consolidate the duplicate "${shadowedType}" detour — only the first can ever run.`
+      : `Move the "${shadowedType}" detour before "${shadowingType}" so the more specific recovery runs, or remove it if the broader detour should own this case.`
+  }`,
+  rule: 'unreachable-detour-shadowing',
+  severity: 'error',
+});
+
+const findShadowingDetour = (
+  detours: readonly DetourOnType[],
+  index: number,
+  localParents: ReadonlyMap<string, string>
+): DetourOnType | null => {
+  const detour = detours[index];
+  if (!detour) {
+    return null;
+  }
+
+  for (let previousIndex = 0; previousIndex < index; previousIndex += 1) {
+    const previous = detours[previousIndex];
+    if (
+      previous &&
+      isSameOrSubtype(detour.onType, previous.onType, localParents)
+    ) {
+      return previous;
+    }
+  }
+
+  return null;
+};
+
+const buildTrailDiagnostics = (
+  trailId: string,
+  detours: readonly DetourOnType[],
+  filePath: string,
+  localParents: ReadonlyMap<string, string>
+): readonly WardenDiagnostic[] => {
+  const diagnostics: WardenDiagnostic[] = [];
+
+  for (let index = 1; index < detours.length; index += 1) {
+    const detour = detours[index];
+    const shadowing = findShadowingDetour(detours, index, localParents);
+    if (!detour || !shadowing) {
+      continue;
+    }
+
+    diagnostics.push(
+      buildDiagnostic(
+        trailId,
+        detour.onType,
+        shadowing.onType,
+        filePath,
+        detour.line
+      )
+    );
+  }
+
+  return diagnostics;
+};
+
+const buildDiagnostics = (
+  ast: AstNode,
+  sourceCode: string,
+  filePath: string
+): readonly WardenDiagnostic[] => {
+  const aliases = collectKnownErrorAliases(ast);
+  const localParents = collectLocalErrorParents(ast, aliases);
+  const diagnostics: WardenDiagnostic[] = [];
+
+  for (const definition of findTrailDefinitions(ast)) {
+    if (definition.kind !== 'trail') {
+      continue;
+    }
+
+    diagnostics.push(
+      ...buildTrailDiagnostics(
+        definition.id,
+        extractDetourOnTypes(definition.config, sourceCode, aliases),
+        filePath,
+        localParents
+      )
+    );
+  }
+
+  return diagnostics;
+};
+
+export const unreachableDetourShadowing: WardenRule = {
+  check(sourceCode: string, filePath: string): readonly WardenDiagnostic[] {
+    if (isTestFile(filePath)) {
+      return [];
+    }
+
+    const ast = parse(filePath, sourceCode);
+    if (!ast) {
+      return [];
+    }
+
+    return buildDiagnostics(ast, sourceCode, filePath);
+  },
+  description:
+    'Detect later detours whose on: error type is already matched by an earlier same or broader detour.',
+  name: 'unreachable-detour-shadowing',
+  severity: 'error',
+};

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

@@ -0,0 +1,224 @@
+import {
+  extractStringOrTemplateLiteral,
+  getNodeName,
+  getNodeProperty,
+  getNodeValue,
+  offsetToLine,
+  parse,
+  walk,
+} from '@ontrails/source';
+import type { AstNode } from '@ontrails/source';
+import { isTestFile } from './scan.js';
+import { collectTrailIds } from './specs.js';
+import type {
+  ProjectAwareWardenRule,
+  ProjectContext,
+  WardenDiagnostic,
+} from './types.js';
+
+const SEE_PATTERN = /@see\s+([A-Za-z0-9_.-]+)/g;
+
+interface DescribeRef {
+  readonly line: number;
+  readonly ref: string;
+}
+
+const STRING_LITERAL_ARG_TYPES: ReadonlySet<string> = new Set([
+  'Literal',
+  'StringLiteral',
+  'TemplateLiteral',
+]);
+
+const MEMBER_CALLEE_TYPES: ReadonlySet<string> = new Set([
+  'MemberExpression',
+  'StaticMemberExpression',
+]);
+
+const isDescribeMemberCallee = (callee: AstNode | undefined): boolean => {
+  if (!callee || !MEMBER_CALLEE_TYPES.has(callee.type)) {
+    return false;
+  }
+  const prop = getNodeProperty(callee);
+  return prop?.type === 'Identifier' && getNodeName(prop) === 'describe';
+};
+
+const hasStringLiteralFirstArg = (node: AstNode): boolean => {
+  const args = node['arguments'] as readonly AstNode[] | undefined;
+  const firstArg = args?.[0];
+  return !!firstArg && STRING_LITERAL_ARG_TYPES.has(firstArg.type);
+};
+
+const isDescribeCall = (node: AstNode): boolean => {
+  if (node.type !== 'CallExpression') {
+    return false;
+  }
+  if (!isDescribeMemberCallee(node['callee'] as AstNode | undefined)) {
+    return false;
+  }
+  // Narrow to calls whose first argument is a string/template literal.
+  // Filters out RxJS-style `.describe(fn)` and other custom APIs whose
+  // `.describe()` overloads take non-string arguments. Zod's shape always
+  // passes a string literal here.
+  return hasStringLiteralFirstArg(node);
+};
+
+/**
+ * Extract scannable text from a template literal, even when it contains
+ * `${...}` expressions. Concatenates the cooked quasi chunks with a NUL
+ * sentinel between them — interpolated values are runtime-only and cannot
+ * contribute static `@see` tokens, but the surrounding quasi text can. The
+ * sentinel prevents phantom tokens that would otherwise appear when a quasi
+ * boundary splits the `@see` marker itself (e.g. `\`@s${x}ee missing\``
+ * would naively join to `"@seemissing"` and match `@see`).
+ *
+ * This is intentionally describe-local: the shared
+ * {@link extractStringOrTemplateLiteral} helper preserves "plain template
+ * literal only" semantics for other rules (e.g. resolving trail/signal IDs)
+ * that require a single clean string value. Here we only need to scan for
+ * `@see` tokens, so concatenating quasi cooked text is sound.
+ *
+ * @remarks
+ * A quasi's `cooked` value can be `null` in tagged-template positions where
+ * the literal contains escape sequences the parser can't decode. `.describe`
+ * is a plain method call, not a tagged template, so in practice its quasis
+ * always have a `cooked` string today. The `raw` fallback is defensive: if a
+ * future refactor wraps `describe(\`...\`)` in a tagged template, we still
+ * scan the raw source rather than silently dropping the quasi text and
+ * missing an `@see` token.
+ */
+const extractQuasiText = (quasi: AstNode): string | null => {
+  const value = getNodeValue(quasi);
+  if (!value || typeof value !== 'object') {
+    return null;
+  }
+  const record = value as Record<string, unknown>;
+  if (typeof record['cooked'] === 'string') {
+    return record['cooked'];
+  }
+  if (typeof record['raw'] === 'string') {
+    return record['raw'];
+  }
+  return null;
+};
+
+const extractTemplateLiteralQuasiText = (node: AstNode): string | null => {
+  if (node.type !== 'TemplateLiteral') {
+    return null;
+  }
+  const quasis = (node['quasis'] as readonly AstNode[] | undefined) ?? [];
+  const parts: string[] = [];
+  for (const quasi of quasis) {
+    const text = extractQuasiText(quasi);
+    if (text !== null) {
+      parts.push(text);
+    }
+  }
+  // Use a NUL sentinel (not a letter / ref character) so interpolation
+  // boundaries cannot silently fuse neighbouring quasis into a phantom
+  // `@see <ident>` match. `\u0000` cannot appear inside a valid trail ID,
+  // so it safely terminates any partial token on either side.
+  return parts.join('\u0000');
+};
+
+const extractDescribeDescription = (node: AstNode): string | null => {
+  const args = node['arguments'] as readonly AstNode[] | undefined;
+  const [firstArg] = args ?? [];
+  if (!firstArg) {
+    return null;
+  }
+  return (
+    extractStringOrTemplateLiteral(firstArg) ??
+    extractTemplateLiteralQuasiText(firstArg)
+  );
+};
+
+/**
+ * Anchor the diagnostic on the string argument that actually contains the
+ * `@see` token, not on the call-expression start. For multi-line schema
+ * chains, the call-expression start can be many lines above the describe
+ * argument, which confuses editor tooling.
+ */
+const describeAnchorOffset = (node: AstNode): number => {
+  const args = node['arguments'] as readonly AstNode[] | undefined;
+  return args?.[0]?.start ?? node.start;
+};
+
+const collectRefsFromDescription = (
+  description: string,
+  line: number,
+  out: DescribeRef[]
+): void => {
+  for (const match of description.matchAll(SEE_PATTERN)) {
+    const [, ref] = match;
+    if (ref) {
+      out.push({ line, ref });
+    }
+  }
+};
+
+const collectDescribeRefs = (
+  ast: AstNode,
+  sourceCode: string
+): readonly DescribeRef[] => {
+  const refs: DescribeRef[] = [];
+
+  walk(ast, (node) => {
+    if (!isDescribeCall(node)) {
+      return;
+    }
+    const description = extractDescribeDescription(node);
+    if (description === null) {
+      return;
+    }
+    const line = offsetToLine(sourceCode, describeAnchorOffset(node));
+    collectRefsFromDescription(description, line, refs);
+  });
+
+  return refs;
+};
+
+const checkDescribeRefs = (
+  sourceCode: string,
+  filePath: string,
+  knownTrailIds: ReadonlySet<string>
+): readonly WardenDiagnostic[] => {
+  if (isTestFile(filePath)) {
+    return [];
+  }
+
+  const ast = parse(filePath, sourceCode);
+  if (!ast) {
+    return [];
+  }
+
+  return collectDescribeRefs(ast, sourceCode)
+    .filter(({ ref }) => !knownTrailIds.has(ref))
+    .map(({ line, ref }) => ({
+      filePath,
+      line,
+      message: `@see reference "${ref}" does not resolve to a defined trail.`,
+      rule: 'valid-describe-refs',
+      severity: 'warn' as const,
+    }));
+};
+
+/**
+ * Warns when @see references inside Zod .describe() strings point at unknown
+ * trails.
+ */
+export const validDescribeRefs: ProjectAwareWardenRule = {
+  check(sourceCode: string, filePath: string): readonly WardenDiagnostic[] {
+    return checkDescribeRefs(sourceCode, filePath, collectTrailIds(sourceCode));
+  },
+  checkWithContext(
+    sourceCode: string,
+    filePath: string,
+    context: ProjectContext
+  ): readonly WardenDiagnostic[] {
+    return checkDescribeRefs(sourceCode, filePath, context.knownTrailIds);
+  },
+  description:
+    'Ensure @see tags inside schema .describe() strings reference defined trails.',
+  name: 'valid-describe-refs',
+  severity: 'warn',
+};

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

@@ -0,0 +1,78 @@
+import type { Topo } from '@ontrails/core';
+
+import type { TopoAwareWardenRule, WardenDiagnostic } from './types.js';
+
+interface DetourLike {
+  readonly on?: unknown;
+  readonly recover?: unknown;
+}
+
+const isErrorConstructor = (
+  value: unknown
+): value is abstract new (...args: never[]) => Error => {
+  if (typeof value !== 'function') {
+    return false;
+  }
+
+  const { prototype } = value as { prototype?: unknown };
+  return prototype instanceof Error;
+};
+
+const describeOnValue = (value: unknown): string => {
+  if (typeof value === 'function') {
+    const { name } = value as { name?: unknown };
+    return typeof name === 'string' && name.length > 0
+      ? name
+      : '<anonymous constructor>';
+  }
+
+  return String(value);
+};
+
+const buildDiagnostic = (message: string, rule: string): WardenDiagnostic => ({
+  filePath: '<topo>',
+  line: 1,
+  message,
+  rule,
+  severity: 'error',
+});
+
+const collectTrailDiagnostics = (topo: Topo): readonly WardenDiagnostic[] => {
+  const diagnostics: WardenDiagnostic[] = [];
+
+  for (const trail of topo.trails.values()) {
+    for (const [index, detour] of trail.detours.entries()) {
+      const candidate = detour as DetourLike;
+
+      if (!isErrorConstructor(candidate.on)) {
+        diagnostics.push(
+          buildDiagnostic(
+            `Trail "${trail.id}" detour[${index}] must declare an error constructor in on:. Received ${describeOnValue(candidate.on)}. Pass the error class itself, such as on: TimeoutError — not an error instance, a string name, or an error category.`,
+            'valid-detour-contract'
+          )
+        );
+      }
+
+      if (typeof candidate.recover !== 'function') {
+        diagnostics.push(
+          buildDiagnostic(
+            `Trail "${trail.id}" detour[${index}] must declare a callable recover function. Expected recover: (attempt, ctx) => Promise<Result<...>>; inspect attempt.error for the matched error and return Result.err(...) for unrecoverable cases.`,
+            'valid-detour-contract'
+          )
+        );
+      }
+    }
+  }
+
+  return diagnostics;
+};
+
+export const validDetourContract: TopoAwareWardenRule = {
+  checkTopo(topo: Topo): readonly WardenDiagnostic[] {
+    return collectTrailDiagnostics(topo);
+  },
+  description:
+    'Ensure detours use real error constructors and callable recover functions.',
+  name: 'valid-detour-contract',
+  severity: 'error',
+};