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

package/src/rules/entity-exists.ts

@@ -0,0 +1,254 @@
+import {
+  buildUserNamespaceContext,
+  collectEntityDefinitionIds,
+  collectImportAliasMap,
+  collectNamedEntityIds,
+  deriveEntityIdentifierName,
+  isUserNamespaceReceiverAllowed,
+} from './source/entities.js';
+import {
+  extractFirstStringArg,
+  findConfigProperty,
+  findTrailDefinitions,
+  getNodeCallee,
+  getNodeObject,
+  getNodeProperty,
+  identifierName,
+  isMemberAccessNonComputed,
+  offsetToLine,
+  parse,
+} from '@ontrails/source';
+import type { AstNode, TrailDefinition } from '@ontrails/source';
+import type { UserNamespaceContext } from './source/entities.js';
+import { mergeKnownEntityIds } from './entity-ids.js';
+import { isTestFile } from './scan.js';
+import type {
+  ProjectAwareWardenRule,
+  ProjectContext,
+  WardenDiagnostic,
+} from './types.js';
+
+const isEntityCall = (node: AstNode): boolean =>
+  node.type === 'CallExpression' &&
+  identifierName(getNodeCallee(node)) === 'entity';
+
+const getEntityElements = (config: AstNode): readonly AstNode[] => {
+  const entitiesProp = findConfigProperty(config, 'entities');
+  if (!entitiesProp) {
+    return [];
+  }
+
+  const arrayNode = entitiesProp.value;
+  if (!arrayNode || (arrayNode as AstNode).type !== 'ArrayExpression') {
+    return [];
+  }
+
+  const elements = (arrayNode as AstNode)['elements'] as
+    | readonly AstNode[]
+    | undefined;
+  return elements ?? [];
+};
+
+/**
+ * Resolve `entities.user` to its entity name. When `userNamespace` carries a
+ * scope-aware `safeMemberStarts` set, the member access must appear in it —
+ * rejecting cases where `entities` is shadowed by a local binding such as a
+ * function parameter or `const entities = ...`. Without the set, falls back
+ * to the bare name check for backward compatibility.
+ */
+const resolveNamespaceMemberEntityName = (
+  element: AstNode,
+  userNamespace: UserNamespaceContext
+): string | null => {
+  if (!isMemberAccessNonComputed(element)) {
+    return null;
+  }
+  const object = getNodeObject(element);
+  const property = getNodeProperty(element);
+  const receiver = object ? identifierName(object) : null;
+  if (
+    !receiver ||
+    !isUserNamespaceReceiverAllowed(receiver, element.start, userNamespace)
+  ) {
+    return null;
+  }
+  return property ? identifierName(property) : null;
+};
+
+const resolveDeclaredEntityName = (
+  element: AstNode,
+  entityIdsByName: ReadonlyMap<string, string>,
+  knownEntityIds?: ReadonlySet<string>,
+  importAliases?: ReadonlyMap<string, string>,
+  userNamespace?: UserNamespaceContext
+): string | null => {
+  if (element.type === 'Identifier') {
+    const name = identifierName(element);
+    return name
+      ? deriveEntityIdentifierName(
+          name,
+          entityIdsByName,
+          knownEntityIds,
+          importAliases
+        )
+      : null;
+  }
+
+  if (userNamespace && userNamespace.bindings.size > 0) {
+    const namespaceTarget = resolveNamespaceMemberEntityName(
+      element,
+      userNamespace
+    );
+    if (namespaceTarget) {
+      return namespaceTarget;
+    }
+  }
+
+  return isEntityCall(element) ? extractFirstStringArg(element) : null;
+};
+
+const extractDeclaredEntityNames = (
+  config: AstNode,
+  entityIdsByName: ReadonlyMap<string, string>,
+  knownEntityIds?: ReadonlySet<string>,
+  importAliases?: ReadonlyMap<string, string>,
+  userNamespace?: UserNamespaceContext
+): readonly string[] => [
+  ...new Set(
+    getEntityElements(config).flatMap((element) => {
+      const entityName = resolveDeclaredEntityName(
+        element,
+        entityIdsByName,
+        knownEntityIds,
+        importAliases,
+        userNamespace
+      );
+      return entityName ? [entityName] : [];
+    })
+  ),
+];
+
+const buildMissingEntityDiagnostic = (
+  trailId: string,
+  entityName: string,
+  filePath: string,
+  line: number
+): WardenDiagnostic => ({
+  filePath,
+  line,
+  message: `Trail "${trailId}" declares entity "${entityName}" which is not defined in the project. Define it with entity('${entityName}', ...) and include it in the topo, or fix the entities entry if this is a typo.`,
+  rule: 'entity-exists',
+  severity: 'error',
+});
+
+const buildDiagnosticsForDefinition = (
+  definition: TrailDefinition,
+  sourceCode: string,
+  filePath: string,
+  knownEntityIds: ReadonlySet<string>,
+  entityIdsByName: ReadonlyMap<string, string>,
+  importAliases: ReadonlyMap<string, string>,
+  userNamespace: UserNamespaceContext
+): readonly WardenDiagnostic[] => {
+  if (definition.kind !== 'trail') {
+    return [];
+  }
+
+  const line = offsetToLine(sourceCode, definition.start);
+  return extractDeclaredEntityNames(
+    definition.config,
+    entityIdsByName,
+    knownEntityIds,
+    importAliases,
+    userNamespace
+  ).flatMap((entityName) =>
+    knownEntityIds.has(entityName)
+      ? []
+      : [
+          buildMissingEntityDiagnostic(
+            definition.id,
+            entityName,
+            filePath,
+            line
+          ),
+        ]
+  );
+};
+
+const buildEntityDiagnostics = (
+  ast: AstNode,
+  sourceCode: string,
+  filePath: string,
+  knownEntityIds: ReadonlySet<string>
+): readonly WardenDiagnostic[] => {
+  const entityIdsByName = collectNamedEntityIds(ast);
+  const importAliases = collectImportAliasMap(ast);
+  const userNamespace = buildUserNamespaceContext(ast);
+
+  return findTrailDefinitions(ast).flatMap((definition) =>
+    buildDiagnosticsForDefinition(
+      definition,
+      sourceCode,
+      filePath,
+      knownEntityIds,
+      entityIdsByName,
+      importAliases,
+      userNamespace
+    )
+  );
+};
+
+const checkEntityDeclarations = (
+  ast: AstNode,
+  sourceCode: string,
+  filePath: string,
+  knownEntityIds: ReadonlySet<string>
+): readonly WardenDiagnostic[] => {
+  if (isTestFile(filePath)) {
+    return [];
+  }
+
+  return buildEntityDiagnostics(ast, sourceCode, filePath, knownEntityIds);
+};
+
+/**
+ * Checks that every entity declared in a trail `entities` array resolves to a
+ * known entity definition.
+ */
+export const entityExists: ProjectAwareWardenRule = {
+  check(sourceCode: string, filePath: string): readonly WardenDiagnostic[] {
+    const ast = parse(filePath, sourceCode);
+    if (!ast) {
+      return [];
+    }
+
+    return checkEntityDeclarations(
+      ast,
+      sourceCode,
+      filePath,
+      collectEntityDefinitionIds(ast)
+    );
+  },
+  checkWithContext(
+    sourceCode: string,
+    filePath: string,
+    context: ProjectContext
+  ): readonly WardenDiagnostic[] {
+    const ast = parse(filePath, sourceCode);
+    if (!ast) {
+      return [];
+    }
+
+    const localEntityIds = collectEntityDefinitionIds(ast);
+    return checkEntityDeclarations(
+      ast,
+      sourceCode,
+      filePath,
+      mergeKnownEntityIds(localEntityIds, context.knownEntityIds)
+    );
+  },
+  description:
+    'Ensure every entity declared on a trail resolves to a known entity definition.',
+  name: 'entity-exists',
+  severity: 'error',
+};

package/src/rules/entity-ids.ts

@@ -0,0 +1,15 @@
+/**
+ * Merge a file's locally-defined entity IDs with the project-wide set.
+ *
+ * Rules that run with a `ProjectContext` need to treat both local and
+ * project-wide entity definitions as "known" so that declarations and
+ * references resolve correctly. When no project context is available — e.g.
+ * single-file lint runs via `check` — the local set is returned as-is.
+ */
+export const mergeKnownEntityIds = (
+  localEntityIds: ReadonlySet<string>,
+  projectEntityIds?: ReadonlySet<string>
+): ReadonlySet<string> =>
+  projectEntityIds
+    ? new Set([...projectEntityIds, ...localEntityIds])
+    : localEntityIds;

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 '@ontrails/source';
+import type { AstNode } from '@ontrails/source';
+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',
+};