@ontrails/warden 1.0.0-beta.3 → 1.0.0-beta.30

package/src/rules/error-mapping-completeness.ts

@@ -0,0 +1,290 @@
+/**
+ * Validates that registered surface error mappers cover every error category.
+ *
+ * Scans `createSurfaceErrorMapper(...)` calls, then resolves simple object
+ * literals, identifier bindings, and object-property references in the same
+ * file so incomplete mapper registrations are caught before they ship.
+ */
+
+import { codesByCategory, errorClasses } from '@ontrails/core';
+import type { ErrorCategory } from '@ontrails/core';
+
+import {
+  getNodeKey,
+  getNodeValueNode,
+  getStringValue,
+  identifierName,
+  isStringLiteral,
+  offsetToLine,
+  parse,
+  walk,
+} from './ast.js';
+import type { AstNode } from './ast.js';
+import { isTestFile } from './scan.js';
+import type { WardenDiagnostic, WardenRule } from './types.js';
+
+const MEMBER_EXPRESSION_TYPES = new Set([
+  'MemberExpression',
+  'StaticMemberExpression',
+]);
+
+const MAPPER_FACTORY_NAMES = new Set(['createSurfaceErrorMapper']);
+
+const mappedErrorClassCategories = new Set(
+  errorClasses.flatMap((entry) =>
+    entry.category === 'dynamic' ? [] : [entry.category]
+  )
+);
+
+const requiredErrorCategories = (
+  Object.keys(codesByCategory) as ErrorCategory[]
+).filter((category) => mappedErrorClassCategories.has(category));
+
+const getPropertyName = (node: AstNode | undefined): string | null => {
+  if (!node) {
+    return null;
+  }
+
+  return (
+    identifierName(node) ??
+    (isStringLiteral(node) ? getStringValue(node) : null)
+  );
+};
+
+const collectObjectBindings = (ast: AstNode): ReadonlyMap<string, AstNode> => {
+  const bindings = new Map<string, AstNode>();
+
+  walk(ast, (node) => {
+    if (node.type !== 'VariableDeclarator') {
+      return;
+    }
+
+    const { id, init } = node as { id?: AstNode; init?: AstNode };
+    const bindingName = identifierName(id);
+
+    if (bindingName && init?.type === 'ObjectExpression') {
+      bindings.set(bindingName, init);
+    }
+  });
+
+  return bindings;
+};
+
+const getObjectProperties = (objectNode: AstNode): readonly AstNode[] =>
+  objectNode.type === 'ObjectExpression'
+    ? ((objectNode['properties'] as readonly AstNode[] | undefined) ?? [])
+    : [];
+
+const findObjectPropertyValue = (
+  objectNode: AstNode,
+  propertyName: string
+): AstNode | null => {
+  for (const property of getObjectProperties(objectNode)) {
+    if (property.type !== 'Property') {
+      continue;
+    }
+
+    const key = getPropertyName(getNodeKey(property));
+    if (key === propertyName) {
+      return getNodeValueNode(property) ?? null;
+    }
+  }
+
+  return null;
+};
+
+const resolveIdentifierObject = (
+  node: AstNode,
+  bindings: ReadonlyMap<string, AstNode>
+): AstNode | null =>
+  bindings.get((node as { name?: string }).name ?? '') ?? null;
+
+const resolveMemberObject = (
+  node: AstNode,
+  bindings: ReadonlyMap<string, AstNode>,
+  depth: number,
+  resolve: (
+    node: AstNode | undefined,
+    bindings: ReadonlyMap<string, AstNode>,
+    depth?: number
+  ) => AstNode | null
+): AstNode | null => {
+  const { object, property } = node as { object?: AstNode; property?: AstNode };
+  const propertyName = getPropertyName(property);
+  if (!propertyName) {
+    return null;
+  }
+
+  const objectNode = resolve(object, bindings, depth + 1);
+  return objectNode
+    ? resolve(
+        findObjectPropertyValue(objectNode, propertyName) ?? undefined,
+        bindings,
+        depth + 1
+      )
+    : null;
+};
+
+const resolveObjectExpression = function resolveObjectExpression(
+  node: AstNode | undefined,
+  bindings: ReadonlyMap<string, AstNode>,
+  depth = 0
+): AstNode | null {
+  if (!node || depth > 4) {
+    return null;
+  }
+
+  if (node.type === 'ObjectExpression') {
+    return node;
+  }
+
+  if (node.type === 'Identifier') {
+    return resolveIdentifierObject(node, bindings);
+  }
+
+  return MEMBER_EXPRESSION_TYPES.has(node.type)
+    ? resolveMemberObject(node, bindings, depth, resolveObjectExpression)
+    : null;
+};
+
+const addMappedCategory = (
+  categories: Set<string>,
+  property: AstNode
+): boolean => {
+  if (property.type === 'SpreadElement') {
+    return false;
+  }
+
+  if (property.type !== 'Property') {
+    return true;
+  }
+
+  const key = getPropertyName(getNodeKey(property));
+  if (key) {
+    categories.add(key);
+  }
+
+  return true;
+};
+
+const collectMappedCategories = (
+  mapperObject: AstNode
+): ReadonlySet<string> | null => {
+  if (mapperObject.type !== 'ObjectExpression') {
+    return null;
+  }
+
+  const categories = new Set<string>();
+  for (const property of getObjectProperties(mapperObject)) {
+    if (!addMappedCategory(categories, property)) {
+      return null;
+    }
+  }
+
+  return categories;
+};
+
+const createDiagnostic = (
+  filePath: string,
+  line: number,
+  missingCategories: readonly string[]
+): WardenDiagnostic => ({
+  filePath,
+  line,
+  message: `Surface error mapper is missing mappings for: ${missingCategories.join(', ')}. Registered createSurfaceErrorMapper() calls must cover every ErrorCategory.`,
+  rule: 'error-mapping-completeness',
+  severity: 'error',
+});
+
+const getCallArgs = (node: AstNode): readonly AstNode[] =>
+  (node as { arguments?: readonly AstNode[] }).arguments ?? [];
+
+const getCallCallee = (node: AstNode): AstNode | undefined =>
+  (node as { callee?: AstNode }).callee;
+
+const isMapperFactoryCall = (node: AstNode): boolean =>
+  node.type === 'CallExpression' &&
+  MAPPER_FACTORY_NAMES.has(identifierName(getCallCallee(node)) ?? '');
+
+const findMissingCategories = (
+  mappedCategories: ReadonlySet<string>
+): readonly string[] =>
+  requiredErrorCategories.filter((category) => !mappedCategories.has(category));
+
+const resolveMappedCategories = (
+  node: AstNode,
+  bindings: ReadonlyMap<string, AstNode>
+): ReadonlySet<string> | null => {
+  const [firstArg] = getCallArgs(node);
+  const mapperObject = resolveObjectExpression(firstArg, bindings);
+  return mapperObject ? collectMappedCategories(mapperObject) : null;
+};
+
+const inspectMapperCall = (
+  node: AstNode,
+  bindings: ReadonlyMap<string, AstNode>,
+  filePath: string,
+  sourceCode: string
+): WardenDiagnostic | null => {
+  if (!isMapperFactoryCall(node)) {
+    return null;
+  }
+
+  const mappedCategories = resolveMappedCategories(node, bindings);
+  if (!mappedCategories) {
+    return null;
+  }
+
+  const missingCategories = findMissingCategories(mappedCategories);
+  if (missingCategories.length === 0) {
+    return null;
+  }
+
+  return createDiagnostic(
+    filePath,
+    offsetToLine(sourceCode, node.start),
+    missingCategories
+  );
+};
+
+/**
+ * Flags registered surface error mapper calls that omit error categories.
+ */
+export const errorMappingCompleteness: WardenRule = {
+  check(sourceCode: string, filePath: string): readonly WardenDiagnostic[] {
+    if (
+      isTestFile(filePath) ||
+      ![...MAPPER_FACTORY_NAMES].some((factoryName) =>
+        sourceCode.includes(factoryName)
+      )
+    ) {
+      return [];
+    }
+
+    const ast = parse(filePath, sourceCode);
+    if (!ast) {
+      return [];
+    }
+
+    const bindings = collectObjectBindings(ast);
+    const diagnostics: WardenDiagnostic[] = [];
+
+    walk(ast, (node) => {
+      const diagnostic = inspectMapperCall(
+        node,
+        bindings,
+        filePath,
+        sourceCode
+      );
+      if (diagnostic) {
+        diagnostics.push(diagnostic);
+      }
+    });
+
+    return diagnostics;
+  },
+  description:
+    'Require registered surface error mappers to cover every ErrorCategory.',
+  name: 'error-mapping-completeness',
+  severity: 'error',
+};

package/src/rules/example-valid.ts

@@ -0,0 +1,395 @@
+import { contour } from '@ontrails/core';
+import { z } from 'zod';
+
+import {
+  extractStringLiteral,
+  findConfigProperty,
+  findContourDefinitions,
+  getNodeExpression,
+  getNodeObject,
+  getNodeProperty,
+  getStringValue,
+  identifierName,
+  offsetToLine,
+  parse,
+} from './ast.js';
+import type { AstNode, ContourDefinition } from './ast.js';
+import { isTestFile } from './scan.js';
+import type { WardenDiagnostic, WardenRule } from './types.js';
+
+class UnsupportedContourEvaluationError extends Error {}
+
+type ContourEvaluationEnvironment = ReadonlyMap<string, unknown>;
+
+const buildInvalidExampleDiagnostic = (
+  contourName: string,
+  message: string,
+  filePath: string,
+  line: number
+): WardenDiagnostic => ({
+  filePath,
+  line,
+  message: `Contour "${contourName}" has invalid examples: ${message}`,
+  rule: 'example-valid',
+  severity: 'error',
+});
+
+const getPropertyName = (node: unknown): string | null => {
+  if (typeof node !== 'object' || node === null) {
+    return null;
+  }
+
+  const { name } = node as { readonly name?: unknown };
+  if (typeof name === 'string') {
+    return name;
+  }
+
+  return extractStringLiteral(node as AstNode);
+};
+
+const requireNode = (node: AstNode | undefined): AstNode => {
+  if (!node) {
+    throw new UnsupportedContourEvaluationError(
+      'Missing node in contour evaluation.'
+    );
+  }
+
+  return node;
+};
+
+type ContourNodeEvaluator = (
+  node: AstNode,
+  env: ContourEvaluationEnvironment
+) => unknown;
+
+// The evaluator table is declared before `evaluateNode` so the recursive
+// dispatch can read it at call time without any forward references. Entries
+// are registered below once each per-type evaluator is defined.
+const contourNodeEvaluators = new Map<string, ContourNodeEvaluator>();
+
+const evaluateNode: ContourNodeEvaluator = (
+  node: AstNode,
+  env: ContourEvaluationEnvironment
+): unknown => {
+  const evaluator = contourNodeEvaluators.get(node.type);
+  if (evaluator) {
+    return evaluator(node, env);
+  }
+
+  throw new UnsupportedContourEvaluationError(
+    `Unsupported AST node "${node.type}" in contour evaluation.`
+  );
+};
+
+const evaluateArrayExpression: ContourNodeEvaluator = (
+  node: AstNode,
+  env: ContourEvaluationEnvironment
+): readonly unknown[] => {
+  const elements = node['elements'] as readonly AstNode[] | undefined;
+  return (elements ?? []).map((element) => evaluateNode(element, env));
+};
+
+const evaluateLiteralExpression: ContourNodeEvaluator = (
+  node: AstNode
+): unknown => getStringValue(node) ?? node.value;
+
+const evaluateIdentifierExpression: ContourNodeEvaluator = (
+  node: AstNode,
+  env: ContourEvaluationEnvironment
+): unknown => {
+  const name = identifierName(node);
+  if (name === 'undefined') {
+    return undefined;
+  }
+
+  if (name === 'z') {
+    return z;
+  }
+
+  if (!name || !env.has(name)) {
+    throw new UnsupportedContourEvaluationError(
+      `Unknown identifier "${name ?? '<unknown>'}" in contour evaluation.`
+    );
+  }
+
+  return env.get(name);
+};
+
+const evaluateWrappedExpression: ContourNodeEvaluator = (
+  node: AstNode,
+  env: ContourEvaluationEnvironment
+): unknown => evaluateNode(requireNode(getNodeExpression(node)), env);
+
+const evaluateNullExpression: ContourNodeEvaluator = (): null => null;
+
+const evaluateObjectExpression: ContourNodeEvaluator = (
+  node: AstNode,
+  env: ContourEvaluationEnvironment
+): Record<string, unknown> => {
+  const properties = node['properties'] as readonly AstNode[] | undefined;
+  const value: Record<string, unknown> = {};
+
+  for (const property of properties ?? []) {
+    if (property.type !== 'Property') {
+      throw new UnsupportedContourEvaluationError(
+        `Unsupported object property type "${property.type}".`
+      );
+    }
+
+    const propertyName = getPropertyName(property.key);
+    if (!propertyName) {
+      throw new UnsupportedContourEvaluationError(
+        'Unsupported object property key in contour evaluation.'
+      );
+    }
+
+    value[propertyName] = evaluateNode(
+      requireNode(property.value as AstNode | undefined),
+      env
+    );
+  }
+
+  return value;
+};
+
+const evaluateCallArguments = (
+  node: AstNode,
+  env: ContourEvaluationEnvironment
+): readonly unknown[] =>
+  ((node['arguments'] as readonly AstNode[] | undefined) ?? []).map((arg) =>
+    evaluateNode(arg, env)
+  );
+
+const resolveContourFallbackOptions = (
+  shape: unknown
+): Parameters<typeof contour>[2] | null =>
+  typeof shape === 'object' &&
+  shape !== null &&
+  Object.hasOwn(shape, 'id') &&
+  (shape as z.ZodRawShape)['id'] !== undefined
+    ? ({ identity: 'id' } as Parameters<typeof contour>[2])
+    : null;
+
+const resolveContourOptions = (
+  shape: unknown,
+  options: unknown
+): Parameters<typeof contour>[2] => {
+  if (options === undefined) {
+    const fallbackOptions = resolveContourFallbackOptions(shape);
+    if (fallbackOptions !== null) {
+      return fallbackOptions;
+    }
+
+    throw new UnsupportedContourEvaluationError(
+      'Contour evaluator requires literal options, or an `id` field when options are omitted.'
+    );
+  }
+
+  if (typeof options !== 'object' || options === null) {
+    throw new UnsupportedContourEvaluationError(
+      'Contour evaluator requires literal options when provided.'
+    );
+  }
+
+  return options as Parameters<typeof contour>[2];
+};
+
+const evaluateContourCall = (args: readonly unknown[]): unknown => {
+  const [name, shape, options] = args;
+  if (typeof name !== 'string') {
+    throw new UnsupportedContourEvaluationError(
+      'Contour evaluator requires a literal name.'
+    );
+  }
+
+  return contour(
+    name,
+    shape as z.ZodRawShape,
+    resolveContourOptions(shape, options)
+  );
+};
+
+const evaluateMemberCall = (
+  callee: AstNode,
+  args: readonly unknown[],
+  env: ContourEvaluationEnvironment
+): unknown => {
+  const receiver = evaluateNode(requireNode(getNodeObject(callee)), env);
+  const propertyName = getPropertyName(getNodeProperty(callee));
+  if (!propertyName) {
+    throw new UnsupportedContourEvaluationError(
+      'Unsupported member property in contour evaluation.'
+    );
+  }
+
+  const method = (receiver as Record<string, unknown>)[propertyName];
+  if (typeof method !== 'function') {
+    throw new UnsupportedContourEvaluationError(
+      `Contour evaluator could not call "${propertyName}".`
+    );
+  }
+
+  return Reflect.apply(method, receiver, args);
+};
+
+const evaluateCallExpression: ContourNodeEvaluator = (
+  node: AstNode,
+  env: ContourEvaluationEnvironment
+): unknown => {
+  const args = evaluateCallArguments(node, env);
+  const callee = requireNode(node['callee'] as AstNode | undefined);
+
+  if (callee.type === 'Identifier') {
+    const calleeName = identifierName(callee);
+    if (calleeName !== 'contour') {
+      throw new UnsupportedContourEvaluationError(
+        `Unsupported contour evaluator call "${calleeName ?? '<unknown>'}".`
+      );
+    }
+
+    return evaluateContourCall(args);
+  }
+
+  if (
+    callee.type !== 'MemberExpression' &&
+    callee.type !== 'StaticMemberExpression'
+  ) {
+    throw new UnsupportedContourEvaluationError(
+      `Unsupported callee type "${callee.type}".`
+    );
+  }
+
+  return evaluateMemberCall(callee, args, env);
+};
+
+const EVALUATOR_REGISTRATIONS: readonly (readonly [
+  string,
+  ContourNodeEvaluator,
+])[] = [
+  ['ArrayExpression', evaluateArrayExpression],
+  ['BooleanLiteral', evaluateLiteralExpression],
+  ['Literal', evaluateLiteralExpression],
+  ['NumericLiteral', evaluateLiteralExpression],
+  ['StringLiteral', evaluateLiteralExpression],
+  ['CallExpression', evaluateCallExpression],
+  ['Identifier', evaluateIdentifierExpression],
+  ['NullLiteral', evaluateNullExpression],
+  ['ObjectExpression', evaluateObjectExpression],
+  ['ParenthesizedExpression', evaluateWrappedExpression],
+  ['TSAsExpression', evaluateWrappedExpression],
+  ['TSSatisfiesExpression', evaluateWrappedExpression],
+];
+
+for (const [type, evaluator] of EVALUATOR_REGISTRATIONS) {
+  contourNodeEvaluators.set(type, evaluator);
+}
+
+const hasExamples = (definition: ContourDefinition): boolean =>
+  definition.options !== null &&
+  findConfigProperty(definition.options, 'examples') !== null;
+
+const evaluateContourDefinition = (
+  definition: ContourDefinition,
+  env: ContourEvaluationEnvironment
+): unknown => evaluateNode(definition.call, env);
+
+const buildContourExampleErrorDiagnostic = (
+  definition: ContourDefinition,
+  error: unknown,
+  sourceCode: string,
+  filePath: string
+): WardenDiagnostic | null => {
+  if (
+    error instanceof UnsupportedContourEvaluationError ||
+    !hasExamples(definition) ||
+    !(error instanceof Error)
+  ) {
+    return null;
+  }
+
+  return buildInvalidExampleDiagnostic(
+    definition.name,
+    error.message,
+    filePath,
+    offsetToLine(sourceCode, definition.start)
+  );
+};
+
+const evaluateContourExamples = (
+  definition: ContourDefinition,
+  env: Map<string, unknown>,
+  sourceCode: string,
+  filePath: string
+): WardenDiagnostic | null => {
+  try {
+    const value = evaluateContourDefinition(definition, env);
+    if (definition.bindingName) {
+      env.set(definition.bindingName, value);
+    }
+
+    return null;
+  } catch (error) {
+    return buildContourExampleErrorDiagnostic(
+      definition,
+      error,
+      sourceCode,
+      filePath
+    );
+  }
+};
+
+const collectContourExampleDiagnostics = (
+  definitions: readonly ContourDefinition[],
+  sourceCode: string,
+  filePath: string
+): readonly WardenDiagnostic[] => {
+  const diagnostics: WardenDiagnostic[] = [];
+  const env = new Map<string, unknown>();
+
+  for (const definition of definitions) {
+    const diagnostic = evaluateContourExamples(
+      definition,
+      env,
+      sourceCode,
+      filePath
+    );
+    if (diagnostic) {
+      diagnostics.push(diagnostic);
+    }
+  }
+
+  return diagnostics;
+};
+
+const checkContourExamples = (
+  sourceCode: string,
+  filePath: string
+): readonly WardenDiagnostic[] => {
+  if (isTestFile(filePath)) {
+    return [];
+  }
+
+  const ast = parse(filePath, sourceCode);
+  if (!ast) {
+    return [];
+  }
+
+  return collectContourExampleDiagnostics(
+    findContourDefinitions(ast),
+    sourceCode,
+    filePath
+  );
+};
+
+/**
+ * Checks that contour examples validate against their schema.
+ */
+export const exampleValid: WardenRule = {
+  check(sourceCode: string, filePath: string): readonly WardenDiagnostic[] {
+    return checkContourExamples(sourceCode, filePath);
+  },
+  description:
+    'Ensure every contour example validates against the declared contour schema.',
+  name: 'example-valid',
+  severity: 'error',
+};