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

package/src/rules/no-legacy-layer-imports.ts

@@ -0,0 +1,211 @@
+/**
+ * Flags references to legacy layer symbols removed during Layer Evolution.
+ *
+ * The pre-TRL-469 era of Trails shipped three first-party layers as ergonomics
+ * over `executeTrail`:
+ *
+ *   - `authLayer` — re-exposed permit enforcement, even though permits were
+ *     intrinsic to `executeTrail`.
+ *   - `autoIterateLayer` — wrapped the CLI iteration ergonomics that the
+ *     surface now derives directly via `--all` (TRL-469).
+ *   - `dateShortcutsLayer` — wrapped the CLI date-expansion helpers that the
+ *     surface now derives directly (TRL-470).
+ *
+ * TRL-475 removed `authLayer`; TRL-476 removed the CLI layer exports
+ * `autoIterateLayer` and `dateShortcutsLayer`. Importing them from
+ * `@ontrails/permits` or `@ontrails/cli` produces a TypeScript error today;
+ * this rule layers a coaching diagnostic on top so authors that still type
+ * the symbol — in a comment, a string, or a stale import — get a redirect to
+ * the migration ADR during the deprecation window.
+ *
+ * The rule is intentionally text-based: legacy names appear in a mix of
+ * imports, JSDoc, error messages, and migration notes, all of which should
+ * surface a coaching message.
+ *
+ * Allow-list: a small set of files documenting the removal itself reference
+ * the literal symbol names. The rule's own implementation file references
+ * each name and is also exempt.
+ *
+ * Test files (`__tests__/`, `*.test.ts`) are filtered before this rule is
+ * invoked by the warden runner, so the regression test referencing
+ * `authLayer` in its name (`packages/core/src/__tests__/execute-permit.test.ts`)
+ * does not need a separate exemption.
+ */
+import { resolve, sep } from 'node:path';
+
+import type { WardenDiagnostic, WardenFix, WardenRule } from './types.js';
+
+const RULE_NAME = 'no-legacy-layer-imports';
+
+/**
+ * Legacy layer symbol names that were removed during Layer Evolution.
+ *
+ * Listed longest-first is not required for correctness (none of these names
+ * are substrings of one another), but kept alphabetized for stable output
+ * across rule runs.
+ */
+const LEGACY_LAYER_NAMES = [
+  'authLayer',
+  'autoIterateLayer',
+  'dateShortcutsLayer',
+] as const;
+
+type LegacyLayerName = (typeof LEGACY_LAYER_NAMES)[number];
+
+interface LegacyLayerMigration {
+  readonly guidance: string;
+  readonly removedIn: 'TRL-475' | 'TRL-476';
+}
+
+const LEGACY_LAYER_MIGRATIONS: Record<LegacyLayerName, LegacyLayerMigration> = {
+  authLayer: {
+    guidance: 'Permit enforcement is intrinsic to executeTrail',
+    removedIn: 'TRL-475',
+  },
+  autoIterateLayer: {
+    guidance: 'Pagination uses CLI surface derivation (--all) per TRL-469',
+    removedIn: 'TRL-476',
+  },
+  dateShortcutsLayer: {
+    guidance: 'Date shortcuts use CLI surface derivation per TRL-470',
+    removedIn: 'TRL-476',
+  },
+};
+
+/**
+ * Path suffixes (in POSIX form) for source files that legitimately reference
+ * one or more removed legacy layer names. Other files are flagged.
+ *
+ * Each entry is matched against the normalized (forward-slash) absolute path
+ * with a trailing-segment match, so the rule stays correct regardless of the
+ * consumer's repository root.
+ */
+const ALLOWED_PATH_SUFFIXES: readonly string[] = [
+  // The CLI pagination module documents the removed `autoIterateLayer` in a
+  // migration note for apps moving onto the derived `--all` ergonomics.
+  '/packages/cli/src/pagination.ts',
+  // The CLI date-shortcuts module documents the removed `dateShortcutsLayer`
+  // in a migration note for apps moving onto the derived expansion helpers.
+  '/packages/cli/src/date-shortcuts.ts',
+  // The rule's own implementation file references the literals it searches for.
+  '/packages/warden/src/rules/no-legacy-layer-imports.ts',
+  // Warden rule metadata names the legacy symbols in the rule's invariant
+  // string for traceability between the rule and the removed exports.
+  '/packages/warden/src/rules/metadata.ts',
+  // The rule trail includes an executable example that demonstrates the
+  // diagnostic emitted for legacy layer imports.
+  '/packages/warden/src/trails/no-legacy-layer-imports.trail.ts',
+];
+
+const normalizePath = (filePath: string): string =>
+  resolve(filePath).split(sep).join('/');
+
+const isAllowedFile = (filePath: string): boolean => {
+  const normalized = normalizePath(filePath);
+  return ALLOWED_PATH_SUFFIXES.some((suffix) => normalized.endsWith(suffix));
+};
+
+interface Match {
+  readonly name: LegacyLayerName;
+  readonly index: number;
+}
+
+const IDENTIFIER_CHAR = /[$0-9A-Z_a-z]/u;
+
+const isIdentifierChar = (value: string): boolean =>
+  value !== '' && IDENTIFIER_CHAR.test(value);
+
+const indexOfStandaloneName = (
+  sourceCode: string,
+  name: LegacyLayerName
+): number => {
+  let fromIndex = 0;
+  while (fromIndex < sourceCode.length) {
+    const index = sourceCode.indexOf(name, fromIndex);
+    if (index === -1) {
+      return -1;
+    }
+    const before = index === 0 ? '' : (sourceCode[index - 1] ?? '');
+    const after = sourceCode[index + name.length] ?? '';
+    if (!(isIdentifierChar(before) || isIdentifierChar(after))) {
+      return index;
+    }
+    fromIndex = index + name.length;
+  }
+  return -1;
+};
+
+const findFirstMatch = (sourceCode: string): Match | null => {
+  let earliest: Match | null = null;
+  for (const name of LEGACY_LAYER_NAMES) {
+    const index = indexOfStandaloneName(sourceCode, name);
+    if (index === -1) {
+      continue;
+    }
+    if (earliest === null || index < earliest.index) {
+      earliest = { index, name };
+    }
+  }
+  return earliest;
+};
+
+const lineForOffset = (sourceCode: string, offset: number): number => {
+  let line = 1;
+  for (let i = 0; i < offset; i += 1) {
+    if (sourceCode.codePointAt(i) === 10) {
+      line += 1;
+    }
+  }
+  return line;
+};
+
+const buildMessage = (name: LegacyLayerName): string => {
+  const migration = LEGACY_LAYER_MIGRATIONS[name];
+  return `Legacy layer '${name}' was removed in ${migration.removedIn}. ${migration.guidance}. See docs/adr/0043-layer-evolution.md.`;
+};
+
+/**
+ * Build the term-rewrite fix metadata for a legacy layer finding.
+ *
+ * These layers were removed, not renamed, so there is no mechanical
+ * replacement: the fix is review-required and carries no edits. It still
+ * advertises the transform class and migration reason so `warden --fix`
+ * reports (but never auto-applies) it and downstream regrades can route it.
+ */
+const buildFix = (name: LegacyLayerName): WardenFix => {
+  const migration = LEGACY_LAYER_MIGRATIONS[name];
+  return {
+    class: 'term-rewrite',
+    reason: `Legacy layer '${name}' was removed in ${migration.removedIn}; ${migration.guidance}. Removal has no mechanical replacement, so it needs human migration.`,
+    safety: 'review',
+  };
+};
+
+/**
+ * Flags references to the removed legacy layer symbols in committed source.
+ */
+export const noLegacyLayerImports: WardenRule = {
+  check(sourceCode: string, filePath: string): readonly WardenDiagnostic[] {
+    if (isAllowedFile(filePath)) {
+      return [];
+    }
+    const match = findFirstMatch(sourceCode);
+    if (!match) {
+      return [];
+    }
+    return [
+      {
+        filePath,
+        fix: buildFix(match.name),
+        line: lineForOffset(sourceCode, match.index),
+        message: buildMessage(match.name),
+        rule: RULE_NAME,
+        severity: 'error',
+      },
+    ];
+  },
+  description:
+    'Disallow references to legacy layer exports (authLayer, autoIterateLayer, dateShortcutsLayer) removed across TRL-475/TRL-476.',
+  name: RULE_NAME,
+  severity: 'error',
+};

package/src/rules/no-native-error-result.ts

@@ -0,0 +1,111 @@
+import { identifierName, offsetToLine, parse, walk } from './ast.js';
+import { isFrameworkInternalFile } from './scan.js';
+import type { AstNode } from './ast.js';
+import type { WardenDiagnostic, WardenRule } from './types.js';
+
+const RULE_NAME = 'no-native-error-result';
+
+const NATIVE_ERROR_CONSTRUCTORS = new Set([
+  'AggregateError',
+  'Error',
+  'EvalError',
+  'RangeError',
+  'ReferenceError',
+  'SyntaxError',
+  'TypeError',
+  'URIError',
+]);
+
+const getMemberPropertyName = (node: AstNode): string | null => {
+  if (
+    node.type !== 'MemberExpression' &&
+    node.type !== 'StaticMemberExpression'
+  ) {
+    return null;
+  }
+
+  return identifierName((node as unknown as { property?: AstNode }).property);
+};
+
+const isResultObject = (node: AstNode | undefined): boolean => {
+  if (!node) {
+    return false;
+  }
+
+  if (identifierName(node) === 'Result') {
+    return true;
+  }
+
+  return getMemberPropertyName(node) === 'Result';
+};
+
+const isResultErrCall = (node: AstNode): boolean => {
+  if (node.type !== 'CallExpression') {
+    return false;
+  }
+
+  const { callee } = node as unknown as { callee?: AstNode };
+  if (!callee || getMemberPropertyName(callee) !== 'err') {
+    return false;
+  }
+
+  return isResultObject((callee as unknown as { object?: AstNode }).object);
+};
+
+const isNativeErrorConstruction = (node: AstNode | undefined): boolean => {
+  if (!node || node.type !== 'NewExpression') {
+    return false;
+  }
+
+  const constructorName = identifierName(
+    (node as unknown as { callee?: AstNode }).callee
+  );
+  return constructorName
+    ? NATIVE_ERROR_CONSTRUCTORS.has(constructorName)
+    : false;
+};
+
+const getFirstArgument = (node: AstNode): AstNode | undefined =>
+  (node as unknown as { arguments?: readonly AstNode[] }).arguments?.[0];
+
+const createDiagnostic = (
+  filePath: string,
+  sourceCode: string,
+  node: AstNode
+): WardenDiagnostic => ({
+  filePath,
+  line: offsetToLine(sourceCode, node.start),
+  message:
+    'Use a specific TrailsError subclass with Result.err(...) instead of native Error.',
+  rule: RULE_NAME,
+  severity: 'error',
+});
+
+export const noNativeErrorResult: WardenRule = {
+  check(sourceCode: string, filePath: string): readonly WardenDiagnostic[] {
+    if (isFrameworkInternalFile(filePath)) {
+      return [];
+    }
+
+    const ast = parse(filePath, sourceCode);
+    if (!ast) {
+      return [];
+    }
+
+    const diagnostics: WardenDiagnostic[] = [];
+    walk(ast, (node) => {
+      if (
+        isResultErrCall(node) &&
+        isNativeErrorConstruction(getFirstArgument(node))
+      ) {
+        diagnostics.push(createDiagnostic(filePath, sourceCode, node));
+      }
+    });
+
+    return diagnostics;
+  },
+  description:
+    'Require Result.err(...) calls to carry specific TrailsError subclasses instead of native Error.',
+  name: RULE_NAME,
+  severity: 'error',
+};

package/src/rules/no-redundant-result-error-wrap.ts

@@ -0,0 +1,331 @@
+import {
+  collectScopeFrameBindings,
+  findBlazeBodies,
+  findTrailDefinitions,
+  getMemberExpression,
+  identifierName,
+  isMemberAccessNonComputed,
+  offsetToLine,
+  parse,
+  walkWithScopes,
+} from './ast.js';
+import {
+  collectAllResultHelperNames,
+  collectNamespaceHelperImports,
+  collectResultTypeNames,
+  findNearestBindingScope,
+  isHelperCall,
+  isResultExpression,
+  trackScopedResultHelperDeclaration,
+} from './implementation-returns-result.js';
+import { isTestFile } from './scan.js';
+import type { AstNode } from './ast.js';
+import type {
+  MutableScopedHelperMap,
+  NamespaceHelperMap,
+  ScopedHelperMap,
+} from './implementation-returns-result.js';
+import type { WardenDiagnostic, WardenRule } from './types.js';
+
+const RULE_NAME = 'no-redundant-result-error-wrap';
+
+const getStaticMemberName = (node: AstNode | undefined): string | null => {
+  if (!node || !isMemberAccessNonComputed(node)) {
+    return null;
+  }
+  return identifierName((node as unknown as { property?: AstNode }).property);
+};
+
+const isResultObject = (node: AstNode | undefined): boolean => {
+  if (!node) {
+    return false;
+  }
+  if (identifierName(node) === 'Result') {
+    return true;
+  }
+  return getStaticMemberName(node) === 'Result';
+};
+
+const isResultErrCall = (node: AstNode): boolean => {
+  if (node.type !== 'CallExpression') {
+    return false;
+  }
+  const { callee } = node as unknown as { callee?: AstNode };
+  const member = getMemberExpression(callee);
+  if (!member || getStaticMemberName(callee) !== 'err') {
+    return false;
+  }
+  return isResultObject(member.object);
+};
+
+const getSingleArgument = (node: AstNode): AstNode | null => {
+  const args = (node as unknown as { arguments?: readonly AstNode[] })
+    .arguments;
+  return args?.length === 1 ? (args[0] ?? null) : null;
+};
+
+const getErrorSourceVariable = (node: AstNode | null): string | null => {
+  if (!node || getStaticMemberName(node) !== 'error') {
+    return null;
+  }
+  const member = getMemberExpression(node);
+  return identifierName(member?.object);
+};
+
+const isResultProducingExpression = (
+  node: AstNode,
+  helperNames: ReadonlySet<string>,
+  namespaceHelpers: NamespaceHelperMap,
+  scopes: readonly ReadonlySet<string>[],
+  scopedHelpers: ScopedHelperMap
+): boolean =>
+  isResultExpression(node) ||
+  isHelperCall(node, helperNames, namespaceHelpers, scopes, scopedHelpers);
+
+type ResultProvenance = Map<ReadonlySet<string>, Set<string>>;
+
+const markResultVariable = (
+  provenance: ResultProvenance,
+  scope: ReadonlySet<string>,
+  name: string
+): void => {
+  const names = provenance.get(scope);
+  if (names) {
+    names.add(name);
+    return;
+  }
+  provenance.set(scope, new Set([name]));
+};
+
+const clearResultVariable = (
+  provenance: ResultProvenance,
+  scope: ReadonlySet<string>,
+  name: string
+): void => {
+  provenance.get(scope)?.delete(name);
+};
+
+const hasResultProvenance = (
+  provenance: ResultProvenance,
+  scope: ReadonlySet<string>,
+  name: string
+): boolean => provenance.get(scope)?.has(name) ?? false;
+
+const createDiagnostic = (
+  filePath: string,
+  sourceCode: string,
+  node: AstNode,
+  trailId: string,
+  variableName: string
+): WardenDiagnostic => ({
+  filePath,
+  line: offsetToLine(sourceCode, node.start),
+  message: `Trail "${trailId}": Result.err(${variableName}.error) re-wraps a Result that already carries that error. Return ${variableName} directly to preserve the original Result boundary.`,
+  rule: RULE_NAME,
+  severity: 'warn',
+});
+
+const trackVariableDeclarator = (
+  node: AstNode,
+  provenance: ResultProvenance,
+  helperNames: ReadonlySet<string>,
+  namespaceHelpers: NamespaceHelperMap,
+  scopedHelpers: ScopedHelperMap,
+  scopes: readonly ReadonlySet<string>[]
+): void => {
+  const { id, init } = node as unknown as { id?: AstNode; init?: AstNode };
+  const name = identifierName(id);
+  if (!name) {
+    return;
+  }
+  const scope = findNearestBindingScope(name, scopes);
+  if (!scope) {
+    return;
+  }
+  if (
+    init &&
+    isResultProducingExpression(
+      init,
+      helperNames,
+      namespaceHelpers,
+      scopes,
+      scopedHelpers
+    )
+  ) {
+    markResultVariable(provenance, scope, name);
+    return;
+  }
+  clearResultVariable(provenance, scope, name);
+};
+
+const trackAssignmentExpression = (
+  node: AstNode,
+  provenance: ResultProvenance,
+  helperNames: ReadonlySet<string>,
+  namespaceHelpers: NamespaceHelperMap,
+  scopedHelpers: ScopedHelperMap,
+  scopes: readonly ReadonlySet<string>[]
+): void => {
+  const { left, operator, right } = node as unknown as {
+    left?: AstNode;
+    operator?: string;
+    right?: AstNode;
+  };
+  const name = identifierName(left);
+  if (!name) {
+    return;
+  }
+  const scope = findNearestBindingScope(name, scopes);
+  if (!scope) {
+    return;
+  }
+  if (
+    operator === '=' &&
+    right &&
+    isResultProducingExpression(
+      right,
+      helperNames,
+      namespaceHelpers,
+      scopes,
+      scopedHelpers
+    )
+  ) {
+    markResultVariable(provenance, scope, name);
+    return;
+  }
+  clearResultVariable(provenance, scope, name);
+};
+
+const checkReturnStatement = (
+  node: AstNode,
+  provenance: ResultProvenance,
+  scopes: readonly ReadonlySet<string>[],
+  filePath: string,
+  sourceCode: string,
+  trailId: string,
+  diagnostics: WardenDiagnostic[]
+): void => {
+  const { argument } = node as unknown as { argument?: AstNode };
+  if (!argument || !isResultErrCall(argument)) {
+    return;
+  }
+  const variableName = getErrorSourceVariable(getSingleArgument(argument));
+  if (!variableName) {
+    return;
+  }
+  const scope = findNearestBindingScope(variableName, scopes);
+  if (!scope || !hasResultProvenance(provenance, scope, variableName)) {
+    return;
+  }
+  diagnostics.push(
+    createDiagnostic(filePath, sourceCode, argument, trailId, variableName)
+  );
+};
+
+const checkBlazeBody = (
+  blaze: AstNode,
+  trailId: string,
+  filePath: string,
+  sourceCode: string,
+  helperNames: ReadonlySet<string>,
+  namespaceHelpers: NamespaceHelperMap,
+  resultTypeNames: ReadonlySet<string>,
+  diagnostics: WardenDiagnostic[]
+): void => {
+  const { body } = blaze as unknown as { body?: AstNode };
+  if (
+    !body ||
+    (body.type !== 'BlockStatement' && body.type !== 'FunctionBody')
+  ) {
+    return;
+  }
+
+  const provenance: ResultProvenance = new Map();
+  const scopedHelpers: MutableScopedHelperMap = new Map();
+  const implScope = collectScopeFrameBindings(blaze);
+  const initialScopes = implScope.size > 0 ? [implScope] : [];
+
+  walkWithScopes(
+    body,
+    (node, scopes) => {
+      if (node.type === 'VariableDeclarator') {
+        trackScopedResultHelperDeclaration(
+          node,
+          scopes,
+          sourceCode,
+          resultTypeNames,
+          scopedHelpers
+        );
+        trackVariableDeclarator(
+          node,
+          provenance,
+          helperNames,
+          namespaceHelpers,
+          scopedHelpers,
+          scopes
+        );
+        return;
+      }
+      if (node.type === 'AssignmentExpression') {
+        trackAssignmentExpression(
+          node,
+          provenance,
+          helperNames,
+          namespaceHelpers,
+          scopedHelpers,
+          scopes
+        );
+        return;
+      }
+      if (node.type === 'ReturnStatement') {
+        checkReturnStatement(
+          node,
+          provenance,
+          scopes,
+          filePath,
+          sourceCode,
+          trailId,
+          diagnostics
+        );
+      }
+    },
+    { initialScopes, stopAtNestedFunctions: true }
+  );
+};
+
+export const noRedundantResultErrorWrap: WardenRule = {
+  check(sourceCode: string, filePath: string): readonly WardenDiagnostic[] {
+    if (isTestFile(filePath)) {
+      return [];
+    }
+
+    const ast = parse(filePath, sourceCode);
+    if (!ast) {
+      return [];
+    }
+
+    const diagnostics: WardenDiagnostic[] = [];
+    const helperNames = collectAllResultHelperNames(ast, sourceCode, filePath);
+    const namespaceHelpers = collectNamespaceHelperImports(ast, filePath);
+    const resultTypeNames = collectResultTypeNames(ast);
+    for (const def of findTrailDefinitions(ast)) {
+      for (const blaze of findBlazeBodies(def.config)) {
+        checkBlazeBody(
+          blaze,
+          def.id,
+          filePath,
+          sourceCode,
+          helperNames,
+          namespaceHelpers,
+          resultTypeNames,
+          diagnostics
+        );
+      }
+    }
+    return diagnostics;
+  },
+  description:
+    'Warn when blazes re-wrap an existing Result error with Result.err(x.error) instead of returning the Result directly.',
+  name: RULE_NAME,
+  severity: 'warn',
+};