@ontrails/warden 0.2.0

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

@@ -0,0 +1,382 @@
+import { getMemberExpression } from './source/stores.js';
+import {
+  collectScopeFrameBindings,
+  findImplementationBodies,
+  findTrailDefinitions,
+  getNodeArgument,
+  getNodeArguments,
+  getNodeBodyNode,
+  getNodeCallee,
+  getNodeId,
+  getNodeInit,
+  getNodeLeft,
+  getNodeOperator,
+  getNodeProperty,
+  getNodeRight,
+  identifierName,
+  isMemberAccessNonComputed,
+  offsetToLine,
+  parse,
+  walkWithParents,
+  walkWithScopes,
+} from '@ontrails/source';
+import type { AstNode, AstParentContext } from '@ontrails/source';
+import {
+  collectAllResultHelperNames,
+  collectDirectResultAssignments,
+  collectNamespaceHelperImports,
+  collectResultTypeNames,
+  findNearestBindingScope,
+  isResultProducingExpression,
+  trackScopedResultHelperDeclaration,
+} from './implementation-returns-result.js';
+import { isTestFile } from './scan.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(getNodeProperty(node));
+};
+
+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 = getNodeCallee(node);
+  const member = getMemberExpression(callee);
+  if (!member || getStaticMemberName(callee) !== 'err') {
+    return false;
+  }
+  return isResultObject(member.object);
+};
+
+const getSingleArgument = (node: AstNode): AstNode | null => {
+  const args = getNodeArguments(node);
+  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);
+};
+
+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,
+  ownerLabel: string,
+  variableName: string
+): WardenDiagnostic => ({
+  filePath,
+  line: offsetToLine(sourceCode, node.start),
+  message: `${ownerLabel}: 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 = getNodeId(node);
+  const init = getNodeInit(node);
+  const name = identifierName(id);
+  if (!name) {
+    return;
+  }
+  const scope = findNearestBindingScope(name, scopes);
+  if (!scope) {
+    return;
+  }
+  if (
+    init &&
+    isResultProducingExpression(
+      init,
+      helperNames,
+      provenance,
+      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,
+  directAssignments: ReadonlySet<AstNode>,
+  scopes: readonly ReadonlySet<string>[]
+): void => {
+  const left = getNodeLeft(node);
+  const name = identifierName(left);
+  if (!name) {
+    return;
+  }
+  const scope = findNearestBindingScope(name, scopes);
+  if (!scope) {
+    return;
+  }
+  const right = getNodeRight(node);
+  const resultRhs =
+    getNodeOperator(node) === '=' &&
+    right &&
+    isResultProducingExpression(
+      right,
+      helperNames,
+      provenance,
+      namespaceHelpers,
+      scopes,
+      scopedHelpers
+    );
+  if (
+    resultRhs &&
+    (hasResultProvenance(provenance, scope, name) ||
+      directAssignments.has(node))
+  ) {
+    markResultVariable(provenance, scope, name);
+    return;
+  }
+  clearResultVariable(provenance, scope, name);
+};
+
+const checkReturnStatement = (
+  node: AstNode,
+  provenance: ResultProvenance,
+  scopes: readonly ReadonlySet<string>[],
+  filePath: string,
+  sourceCode: string,
+  ownerLabel: string,
+  diagnostics: WardenDiagnostic[]
+): void => {
+  const argument = getNodeArgument(node);
+  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, ownerLabel, variableName)
+  );
+};
+
+const functionBody = (node: AstNode): AstNode | null => {
+  const body = getNodeBodyNode(node);
+  return body &&
+    (body.type === 'BlockStatement' || body.type === 'FunctionBody')
+    ? body
+    : null;
+};
+
+const checkFunctionBody = (
+  owner: AstNode,
+  ownerLabel: string,
+  filePath: string,
+  sourceCode: string,
+  helperNames: ReadonlySet<string>,
+  namespaceHelpers: NamespaceHelperMap,
+  resultTypeNames: ReadonlySet<string>,
+  diagnostics: WardenDiagnostic[]
+): void => {
+  const body = functionBody(owner);
+  if (!body) {
+    return;
+  }
+
+  const provenance: ResultProvenance = new Map();
+  const scopedHelpers: MutableScopedHelperMap = new Map();
+  const implScope = collectScopeFrameBindings(owner);
+  const initialScopes = implScope.size > 0 ? [implScope] : [];
+  const directAssignments = collectDirectResultAssignments(body);
+
+  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,
+          directAssignments,
+          scopes
+        );
+        return;
+      }
+      if (node.type === 'ReturnStatement') {
+        checkReturnStatement(
+          node,
+          provenance,
+          scopes,
+          filePath,
+          sourceCode,
+          ownerLabel,
+          diagnostics
+        );
+      }
+    },
+    { initialScopes, stopAtNestedFunctions: true }
+  );
+};
+
+const isFunctionLike = (node: AstNode): boolean =>
+  node.type === 'FunctionDeclaration' ||
+  node.type === 'FunctionExpression' ||
+  node.type === 'ArrowFunctionExpression';
+
+const functionName = (node: AstNode, context: AstParentContext): string => {
+  const declaredName = identifierName(getNodeId(node));
+  if (declaredName) {
+    return declaredName;
+  }
+  if (context.parent?.type === 'VariableDeclarator') {
+    const assignedName = identifierName(getNodeId(context.parent));
+    if (assignedName) {
+      return assignedName;
+    }
+  }
+  return 'anonymous function';
+};
+
+const functionOwnerLabel = (node: AstNode, context: AstParentContext): string =>
+  `Function "${functionName(node, context)}"`;
+
+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);
+    const implementationStarts = new Set<number>();
+    for (const def of findTrailDefinitions(ast)) {
+      for (const implementation of findImplementationBodies(def.config)) {
+        implementationStarts.add(implementation.start);
+        checkFunctionBody(
+          implementation,
+          `Trail "${def.id}"`,
+          filePath,
+          sourceCode,
+          helperNames,
+          namespaceHelpers,
+          resultTypeNames,
+          diagnostics
+        );
+      }
+    }
+    walkWithParents(ast, (node, context) => {
+      if (!isFunctionLike(node) || implementationStarts.has(node.start)) {
+        return;
+      }
+      checkFunctionBody(
+        node,
+        functionOwnerLabel(node, context),
+        filePath,
+        sourceCode,
+        helperNames,
+        namespaceHelpers,
+        resultTypeNames,
+        diagnostics
+      );
+    });
+    return diagnostics;
+  },
+  description:
+    'Warn when code re-wraps an existing Result error with Result.err(x.error) instead of returning the Result directly.',
+  name: RULE_NAME,
+  severity: 'warn',
+};

package/src/rules/no-retired-cross-vocabulary.ts

@@ -0,0 +1,203 @@
+/**
+ * Flags retired `cross` composition vocabulary after the beta.19 compose cutover.
+ *
+ * Exact authored terms that have a mechanical successor carry safe
+ * `term-rewrite` edits. Larger identifiers and type prefixes remain
+ * review-required because the text-only rule cannot prove the intended symbol
+ * boundary.
+ */
+import { resolve, sep } from 'node:path';
+
+import { requireGovernedVocabularyTransition } from './retired-vocabulary.js';
+import type { WardenDiagnostic, WardenFix, WardenRule } from './types.js';
+
+const RULE_NAME = 'no-retired-cross-vocabulary';
+
+const CROSS_COMPOSE_TRANSITION =
+  requireGovernedVocabularyTransition('cross-compose');
+
+if (CROSS_COMPOSE_TRANSITION.target.kind !== 'single') {
+  throw new Error('cross-compose transition must have a single target.');
+}
+
+const COMPOSE_TARGET = CROSS_COMPOSE_TRANSITION.target.to;
+
+const SAFE_REWRITES = Object.entries(
+  CROSS_COMPOSE_TRANSITION.safeRewriteForms
+).map(([from, to]) => ({ from, to }));
+
+const REVIEW_TERMS = CROSS_COMPOSE_TRANSITION.reviewForms;
+
+const IDENTIFIER_CHAR = /[$0-9A-Z_a-z]/u;
+
+const ALLOWED_PATH_SUFFIXES: readonly string[] = [
+  '/docs/migration/cross-to-compose.md',
+  '/docs/releases/beta15-to-beta19.md',
+  '/docs/adr/0049-composition-is-compose-not-cross.md',
+  '/packages/warden/src/rules/no-retired-cross-vocabulary.ts',
+  '/packages/warden/src/rules/metadata.ts',
+  '/packages/warden/src/rules/retired-vocabulary.ts',
+  '/packages/warden/src/trails/governed-symbol-residue.trail.ts',
+  '/packages/warden/src/trails/no-retired-cross-vocabulary.trail.ts',
+];
+
+interface SafeRewriteMatch {
+  readonly from: string;
+  readonly index: number;
+  readonly to: string;
+}
+
+interface ReviewMatch {
+  readonly index: number;
+  readonly term: string;
+}
+
+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));
+};
+
+const isIdentifierChar = (value: string): boolean =>
+  value !== '' && IDENTIFIER_CHAR.test(value);
+
+const isReviewPrefix = (
+  sourceCode: string,
+  index: number,
+  term: string
+): boolean => !(term === 'cross' && sourceCode.startsWith('crosses', index));
+
+const isStandaloneSpan = (
+  sourceCode: string,
+  start: number,
+  end: number
+): boolean => {
+  const before = start === 0 ? '' : (sourceCode[start - 1] ?? '');
+  const after = sourceCode[end] ?? '';
+  return !(isIdentifierChar(before) || isIdentifierChar(after));
+};
+
+const findSafeRewriteMatches = (
+  sourceCode: string
+): readonly SafeRewriteMatch[] => {
+  const matches: SafeRewriteMatch[] = [];
+  for (const rewrite of SAFE_REWRITES) {
+    let fromIndex = 0;
+    while (fromIndex < sourceCode.length) {
+      const index = sourceCode.indexOf(rewrite.from, fromIndex);
+      if (index === -1) {
+        break;
+      }
+      const end = index + rewrite.from.length;
+      if (isStandaloneSpan(sourceCode, index, end)) {
+        matches.push({ ...rewrite, index });
+      }
+      fromIndex = end;
+    }
+  }
+  return matches.toSorted((a, b) => a.index - b.index);
+};
+
+const findReviewMatches = (sourceCode: string): readonly ReviewMatch[] => {
+  const safeSpans = findSafeRewriteMatches(sourceCode).map((match) => ({
+    end: match.index + match.from.length,
+    start: match.index,
+  }));
+  const isInsideSafeSpan = (index: number): boolean =>
+    safeSpans.some((span) => index >= span.start && index < span.end);
+
+  const matches: ReviewMatch[] = [];
+  for (const term of REVIEW_TERMS) {
+    let fromIndex = 0;
+    while (fromIndex < sourceCode.length) {
+      const index = sourceCode.indexOf(term, fromIndex);
+      if (index === -1) {
+        break;
+      }
+      const end = index + term.length;
+      if (!isInsideSafeSpan(index)) {
+        const before = index === 0 ? '' : (sourceCode[index - 1] ?? '');
+        const after = sourceCode[end] ?? '';
+        if (
+          !isIdentifierChar(before) &&
+          isIdentifierChar(after) &&
+          isReviewPrefix(sourceCode, index, term)
+        ) {
+          matches.push({ index, term });
+        }
+      }
+      fromIndex = end;
+    }
+  }
+  return matches.toSorted((a, b) => a.index - b.index);
+};
+
+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 safeFix = (match: SafeRewriteMatch): WardenFix => ({
+  class: 'term-rewrite',
+  edits: [
+    {
+      end: match.index + match.from.length,
+      replacement: match.to,
+      start: match.index,
+    },
+  ],
+  reason: `Retired composition vocabulary '${match.from}' has a mechanical beta.19 replacement '${match.to}'.`,
+  safety: 'safe',
+});
+
+const reviewFix = (term: string): WardenFix => ({
+  class: 'term-rewrite',
+  reason: `Retired composition vocabulary '${term}' appears in a larger or ambiguous form. Review before migrating to ${COMPOSE_TARGET} vocabulary.`,
+  safety: 'review',
+});
+
+const safeMessage = (match: SafeRewriteMatch): string =>
+  `Retired composition vocabulary '${match.from}' should be '${match.to}' after the beta.19 compose cutover.`;
+
+const reviewMessage = (term: string): string =>
+  `Retired composition vocabulary '${term}' needs review before migrating to ${COMPOSE_TARGET} vocabulary.`;
+
+export const noRetiredCrossVocabulary: WardenRule = {
+  check(sourceCode: string, filePath: string): readonly WardenDiagnostic[] {
+    if (isAllowedFile(filePath)) {
+      return [];
+    }
+
+    const reviewMatches = findReviewMatches(sourceCode);
+    if (reviewMatches.length > 0) {
+      return reviewMatches.map((match) => ({
+        filePath,
+        fix: reviewFix(match.term),
+        line: lineForOffset(sourceCode, match.index),
+        message: reviewMessage(match.term),
+        rule: RULE_NAME,
+        severity: 'error',
+      }));
+    }
+
+    return findSafeRewriteMatches(sourceCode).map((match) => ({
+      filePath,
+      fix: safeFix(match),
+      line: lineForOffset(sourceCode, match.index),
+      message: safeMessage(match),
+      rule: RULE_NAME,
+      severity: 'error',
+    }));
+  },
+  description:
+    'Disallow retired cross composition vocabulary after the beta.19 compose cutover.',
+  name: RULE_NAME,
+  severity: 'error',
+};