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

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

@@ -0,0 +1,344 @@
+import { TrailsError, errorClasses } from '@ontrails/core';
+
+import {
+  extractStringLiteral,
+  findConfigProperty,
+  findTrailDefinitions,
+  identifierName,
+  offsetToLine,
+  parse,
+  walk,
+} from './ast.js';
+import type { AstNode } from './ast.js';
+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((node as unknown as { source?: AstNode }).source);
+
+const collectImportSpecifierAliases = (
+  specifiers: readonly AstNode[] | undefined,
+  aliases: Map<string, string>
+): void => {
+  for (const specifier of specifiers ?? []) {
+    if (specifier.type !== 'ImportSpecifier') {
+      continue;
+    }
+
+    const localName = identifierName(
+      (specifier as unknown as { local?: AstNode }).local
+    );
+    const importedName =
+      identifierName(
+        (specifier as unknown as { imported?: AstNode }).imported
+      ) ?? 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 } = node as unknown as {
+      specifiers?: readonly AstNode[];
+    };
+    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 } = node as unknown as { init?: AstNode };
+  if (!init || init.type !== 'ClassExpression') {
+    return;
+  }
+
+  const className = identifierName((node as unknown as { id?: AstNode }).id);
+  const parentName = identifierName(
+    (init as unknown as { superClass?: AstNode }).superClass
+  );
+  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(
+        (node as unknown as { id?: AstNode }).id
+      );
+      const parentName = identifierName(
+        (node as unknown as { superClass?: AstNode }).superClass
+      );
+      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.`,
+  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

@@ -1,13 +1,17 @@
+import {
+  extractStringOrTemplateLiteral,
+  offsetToLine,
+  parse,
+  walk,
+} from './ast.js';
+import type { AstNode } from './ast.js';
+import { isTestFile } from './scan.js';
+import { collectTrailIds } from './specs.js';
 import type {
   ProjectAwareWardenRule,
   ProjectContext,
   WardenDiagnostic,
 } from './types.js';
-import { isTestFile } from './scan.js';
-import { collectTrailIds, parseStringLiteral } from './specs.js';
-import { captureBalanced, lineNumberAt } from './structure.js';
-
-const DESCRIBE_PATTERN = /\.describe\s*\(/g;
 
 const SEE_PATTERN = /@see\s+([A-Za-z0-9_.-]+)/g;
 
@@ -16,41 +20,160 @@ interface DescribeRef {
   readonly ref: string;
 }
 
-const describeTextAt = (
-  sourceCode: string,
-  matchIndex: number
-): string | null => {
-  const openParen = sourceCode.indexOf('(', matchIndex);
-  if (openParen === -1) {
+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 = (callee as unknown as { property?: AstNode }).property;
+  return (
+    prop?.type === 'Identifier' &&
+    (prop as unknown as { name?: string }).name === '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 } = quasi as unknown as {
+    value?: { cooked?: unknown; raw?: unknown };
+  };
+  if (typeof value?.cooked === 'string') {
+    return value.cooked;
+  }
+  if (typeof value?.raw === 'string') {
+    return value.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');
+};
 
-  return captureBalanced(sourceCode, openParen)?.text.slice(1, -1) ?? null;
+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)
+  );
 };
 
-const refsInDescription = (
+/**
+ * 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
-): readonly DescribeRef[] =>
-  [...description.matchAll(SEE_PATTERN)].flatMap((see) =>
-    see[1] ? [{ line, ref: see[1] }] : []
-  );
+  line: number,
+  out: DescribeRef[]
+): void => {
+  for (const match of description.matchAll(SEE_PATTERN)) {
+    const [, ref] = match;
+    if (ref) {
+      out.push({ line, ref });
+    }
+  }
+};
 
-const refsForDescribe = (
-  sourceCode: string,
-  matchIndex: number
+const collectDescribeRefs = (
+  ast: AstNode,
+  sourceCode: string
 ): readonly DescribeRef[] => {
-  const args = describeTextAt(sourceCode, matchIndex);
-  const description = args ? parseStringLiteral(args) : null;
-  return description === null
-    ? []
-    : refsInDescription(description, lineNumberAt(sourceCode, matchIndex));
-};
+  const refs: DescribeRef[] = [];
 
-const collectDescribeRefs = (sourceCode: string): readonly DescribeRef[] =>
-  [...sourceCode.matchAll(DESCRIBE_PATTERN)].flatMap((match) =>
-    match.index === undefined ? [] : refsForDescribe(sourceCode, match.index)
-  );
+  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,
@@ -61,7 +184,12 @@ const checkDescribeRefs = (
     return [];
   }
 
-  return collectDescribeRefs(sourceCode)
+  const ast = parse(filePath, sourceCode);
+  if (!ast) {
+    return [];
+  }
+
+  return collectDescribeRefs(ast, sourceCode)
     .filter(({ ref }) => !knownTrailIds.has(ref))
     .map(({ line, ref }) => ({
       filePath,

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)}.`,
+            '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',
+};