@ontrails/warden 1.0.0-beta.4 → 1.0.0-beta.42

package/src/rules/no-legacy-cli-alias-export.ts

@@ -0,0 +1,247 @@
+/**
+ * Flags leftover legacy app-module CLI alias exports removed in TRL-1207.
+ *
+ * Before the surfaces-overlay cutover, apps published CLI alias maps through
+ * a module-level export named `cliAliases` or `trailsCliAliases`. TRL-1207 is
+ * a hard cutover: app-owned CLI bindings now live in a
+ * `surfaceOverlay({ cli: { ... } })` envelope inside the app module's
+ * `trailsOverlays` array export, and the legacy export convention was
+ * deleted. This rule makes a leftover legacy export an error so stale app
+ * modules get a fix-forward diagnostic instead of silently losing their
+ * bindings.
+ *
+ * Detection is AST-scoped and export-shaped:
+ *
+ *   - `export const cliAliases = { ... }` (also `let`/`var`, destructured
+ *     bindings, and function/class declarations) is flagged.
+ *   - `export { cliAliases }` and `export { whatever as trailsCliAliases }`
+ *     specifiers are flagged, including re-export statements such as
+ *     `export { trailsCliAliases } from './app.js'`.
+ *   - A non-exported local `const cliAliases = ...` is legal and never
+ *     flagged, and the identifiers appearing only in strings or comments do
+ *     not match because the rule inspects export bindings, not raw text.
+ */
+
+import {
+  getNodeArgument,
+  getNodeBodyStatements,
+  getNodeDeclaration,
+  getNodeDeclarations,
+  getNodeElements,
+  getNodeExported,
+  getNodeExportKind,
+  getNodeId,
+  getNodeLeft,
+  getNodeProperties,
+  getNodeSpecifiers,
+  getNodeValueNode,
+  getStringValue,
+  identifierName,
+  isStringLiteral,
+  offsetToLine,
+  parse,
+} from '@ontrails/source';
+import type { AstNode } from '@ontrails/source';
+import type { WardenDiagnostic, WardenFix, WardenRule } from './types.js';
+
+const RULE_NAME = 'no-legacy-cli-alias-export';
+
+/** Legacy app-module CLI alias export names removed in TRL-1207. */
+const LEGACY_CLI_ALIAS_EXPORT_NAMES: ReadonlySet<string> = new Set([
+  'cliAliases',
+  'trailsCliAliases',
+]);
+
+/** Declaration node types that only propagate types, never value bindings. */
+const TYPE_ONLY_DECLARATION_TYPES: ReadonlySet<string> = new Set([
+  'TSInterfaceDeclaration',
+  'TSTypeAliasDeclaration',
+]);
+
+interface ExportedBinding {
+  readonly name: string;
+  readonly start: number;
+}
+
+/** Exported name of a specifier: identifier or string-literal alias. */
+const exportedSpecifierName = (node: AstNode | undefined): string | null =>
+  identifierName(node) ??
+  (node && isStringLiteral(node) ? getStringValue(node) : null);
+
+/**
+ * Expand one binding-pattern node into legacy-named bindings, pushing child
+ * patterns onto the worklist. Destructured exports such as
+ * `export const { cliAliases } = mod` still introduce a module-level exported
+ * value binding, so patterns cannot be skipped.
+ */
+const visitBindingPatternNode = (
+  node: AstNode,
+  into: ExportedBinding[],
+  worklist: AstNode[]
+): void => {
+  const name = identifierName(node);
+  if (name !== null) {
+    if (LEGACY_CLI_ALIAS_EXPORT_NAMES.has(name)) {
+      into.push({ name, start: node.start });
+    }
+    return;
+  }
+  if (node.type === 'AssignmentPattern') {
+    const left = getNodeLeft(node);
+    if (left) {
+      worklist.push(left);
+    }
+    return;
+  }
+  if (node.type === 'RestElement') {
+    const argument = getNodeArgument(node);
+    if (argument) {
+      worklist.push(argument);
+    }
+    return;
+  }
+  if (node.type === 'ObjectPattern') {
+    for (const property of getNodeProperties(node)) {
+      const value = getNodeValueNode(property) ?? getNodeArgument(property);
+      if (value) {
+        worklist.push(value);
+      }
+    }
+    return;
+  }
+  if (node.type === 'ArrayPattern') {
+    for (const element of getNodeElements(node)) {
+      if (element) {
+        worklist.push(element);
+      }
+    }
+  }
+};
+
+const collectLegacyPatternBindings = (
+  pattern: AstNode | undefined,
+  into: ExportedBinding[]
+): void => {
+  if (!pattern) {
+    return;
+  }
+  const worklist: AstNode[] = [pattern];
+  while (worklist.length > 0) {
+    const node = worklist.pop();
+    if (node) {
+      visitBindingPatternNode(node, into, worklist);
+    }
+  }
+};
+
+const collectLegacyDeclarationBindings = (
+  declaration: AstNode
+): readonly ExportedBinding[] => {
+  if (TYPE_ONLY_DECLARATION_TYPES.has(declaration.type)) {
+    return [];
+  }
+  const bindings: ExportedBinding[] = [];
+  if (declaration.type === 'VariableDeclaration') {
+    for (const declarator of getNodeDeclarations(declaration)) {
+      collectLegacyPatternBindings(getNodeId(declarator), bindings);
+    }
+    return bindings;
+  }
+  const name = identifierName(getNodeId(declaration));
+  if (name !== null && LEGACY_CLI_ALIAS_EXPORT_NAMES.has(name)) {
+    bindings.push({ name, start: declaration.start });
+  }
+  return bindings;
+};
+
+const collectLegacySpecifierBindings = (
+  statement: AstNode
+): readonly ExportedBinding[] => {
+  const bindings: ExportedBinding[] = [];
+  for (const specifier of getNodeSpecifiers(statement)) {
+    if (
+      specifier.type !== 'ExportSpecifier' ||
+      getNodeExportKind(specifier) === 'type'
+    ) {
+      continue;
+    }
+    const name = exportedSpecifierName(getNodeExported(specifier));
+    if (name !== null && LEGACY_CLI_ALIAS_EXPORT_NAMES.has(name)) {
+      bindings.push({ name, start: specifier.start });
+    }
+  }
+  return bindings;
+};
+
+const collectLegacyExportBindings = (
+  ast: AstNode
+): readonly ExportedBinding[] => {
+  const bindings: ExportedBinding[] = [];
+  for (const statement of getNodeBodyStatements(ast)) {
+    if (
+      statement.type !== 'ExportNamedDeclaration' ||
+      getNodeExportKind(statement) === 'type'
+    ) {
+      continue;
+    }
+    const declaration = getNodeDeclaration(statement);
+    if (declaration) {
+      bindings.push(...collectLegacyDeclarationBindings(declaration));
+      continue;
+    }
+    bindings.push(...collectLegacySpecifierBindings(statement));
+  }
+  return bindings;
+};
+
+const buildMessage = (name: string): string =>
+  `Legacy CLI alias export '${name}' was removed in the TRL-1207 surfaces-overlay cutover. Wrap the alias map into surfaceOverlay({ cli: { ... } }) from @ontrails/core inside the module's trailsOverlays array export.`;
+
+/**
+ * Build the fix metadata for a legacy CLI alias export finding.
+ *
+ * The rewrite is an export restructure, not a rename, so there is no
+ * mechanical single-span replacement: the fix carries no edits and Warden
+ * never applies it. Downstream, the `export-restructure` fix class routes the
+ * finding to the Regrade `export-restructure:cli-aliases` class (TRL-1210),
+ * which inverts the alias map into `surfaceOverlay({ cli: { ... } })`
+ * bindings inside the module's `trailsOverlays` array export.
+ */
+const buildFix = (name: string): WardenFix => ({
+  class: 'export-restructure',
+  reason: `Legacy CLI alias export '${name}' must be rewritten into a surfaceOverlay({ cli: { ... } }) entry inside the module's trailsOverlays array export; run the Regrade class export-restructure:cli-aliases (TRL-1210) to automate this restructure.`,
+  safety: 'review',
+});
+
+/**
+ * Flags exported bindings named `cliAliases` or `trailsCliAliases`, the
+ * legacy app-module CLI alias export convention deleted in TRL-1207.
+ */
+export const noLegacyCliAliasExport: WardenRule = {
+  check(sourceCode: string, filePath: string): readonly WardenDiagnostic[] {
+    if (
+      !(
+        sourceCode.includes('cliAliases') ||
+        sourceCode.includes('trailsCliAliases')
+      )
+    ) {
+      return [];
+    }
+    const ast = parse(filePath, sourceCode);
+    if (!ast) {
+      return [];
+    }
+    return collectLegacyExportBindings(ast).map((binding) => ({
+      filePath,
+      fix: buildFix(binding.name),
+      line: offsetToLine(sourceCode, binding.start),
+      message: buildMessage(binding.name),
+      rule: RULE_NAME,
+      severity: 'error',
+    }));
+  },
+  description:
+    'Disallow the legacy app-module CLI alias exports (cliAliases, trailsCliAliases) removed in the TRL-1207 surfaces-overlay cutover.',
+  name: RULE_NAME,
+  severity: 'error',
+};

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,118 @@
+import {
+  getNodeArguments,
+  getNodeCallee,
+  getNodeObject,
+  getNodeProperty,
+  identifierName,
+  offsetToLine,
+  parse,
+  walk,
+} from '@ontrails/source';
+import type { AstNode } from '@ontrails/source';
+import { isFrameworkInternalFile } from './scan.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(getNodeProperty(node));
+};
+
+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 = getNodeCallee(node);
+  if (!callee || getMemberPropertyName(callee) !== 'err') {
+    return false;
+  }
+
+  return isResultObject(getNodeObject(callee));
+};
+
+const isNativeErrorConstruction = (node: AstNode | undefined): boolean => {
+  if (!node || node.type !== 'NewExpression') {
+    return false;
+  }
+
+  const constructorName = identifierName(getNodeCallee(node));
+  return constructorName
+    ? NATIVE_ERROR_CONSTRUCTORS.has(constructorName)
+    : false;
+};
+
+const getFirstArgument = (node: AstNode): AstNode | undefined =>
+  getNodeArguments(node)?.[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',
+};