@ontrails/warden 1.0.0-beta.13 → 1.0.0-beta.15

package/src/rules/draft-file-marking.ts

@@ -0,0 +1,160 @@
+import { isDraftId } from '@ontrails/core';
+
+import { isDraftMarkedFile } from '../draft.js';
+import {
+  collectFrameworkDraftPrefixConstantOffsets,
+  findStringLiterals,
+  hasIgnoreCommentOnLine,
+  offsetToLine,
+  parse,
+  splitSourceLines,
+} from './ast.js';
+import type { StringLiteralMatch } from './ast.js';
+import type { WardenDiagnostic, WardenRule } from './types.js';
+
+const messageForMissingMarker = (draftId: string): string =>
+  `Draft id "${draftId}" appears in source, but the file is not draft-marked. ` +
+  'Rename it with an _draft. prefix or a .draft. trailing segment.';
+
+const makeDiagnostic = (
+  sourceCode: string,
+  filePath: string,
+  start: number,
+  message: string,
+  severity: WardenDiagnostic['severity']
+): WardenDiagnostic => ({
+  filePath,
+  line: offsetToLine(sourceCode, start),
+  message,
+  rule: 'draft-file-marking',
+  severity,
+});
+
+const collectDraftMatches = (
+  sourceCode: string,
+  filePath: string,
+  ast: NonNullable<ReturnType<typeof parse>>
+): StringLiteralMatch[] => {
+  const frameworkConstantOffsets = collectFrameworkDraftPrefixConstantOffsets(
+    ast,
+    filePath
+  );
+  const lines = splitSourceLines(sourceCode);
+  return findStringLiterals(ast, (value) => isDraftId(value)).filter(
+    (match) => {
+      if (frameworkConstantOffsets.has(match.start)) {
+        return false;
+      }
+      if (
+        hasIgnoreCommentOnLine(lines, offsetToLine(sourceCode, match.start))
+      ) {
+        return false;
+      }
+      return true;
+    }
+  );
+};
+
+const draftMissingMarkerDiagnostic = (
+  sourceCode: string,
+  filePath: string,
+  ast: NonNullable<ReturnType<typeof parse>>
+): WardenDiagnostic | null => {
+  const draftMatches = collectDraftMatches(sourceCode, filePath, ast);
+  if (!draftMatches.length || isDraftMarkedFile(filePath)) {
+    return null;
+  }
+
+  const [first] = draftMatches;
+  if (!first) {
+    return null;
+  }
+
+  return makeDiagnostic(
+    sourceCode,
+    filePath,
+    first.start,
+    messageForMissingMarker(first.value),
+    'error'
+  );
+};
+
+const draftMarkedWithoutIdsDiagnostic = (
+  filePath: string,
+  ast: NonNullable<ReturnType<typeof parse>>
+): WardenDiagnostic | null => {
+  // Deciding whether the file's `_draft.` marker is still warranted is a
+  // question about *all* draft ids present in source, not just the unsuppressed
+  // ones. Pragma-suppressed ids still justify a draft-marked filename — a user
+  // intentionally silencing them has not removed the draft content. We
+  // therefore filter only the framework-constant declarations (which are not
+  // draft ids at all) and bypass the pragma filter that `collectDraftMatches`
+  // applies.
+  const frameworkConstantOffsets = collectFrameworkDraftPrefixConstantOffsets(
+    ast,
+    filePath
+  );
+  const unsuppressedDraftIds = findStringLiterals(ast, (value) =>
+    isDraftId(value)
+  ).filter((match) => !frameworkConstantOffsets.has(match.start));
+
+  if (unsuppressedDraftIds.length > 0) {
+    return null;
+  }
+
+  if (!isDraftMarkedFile(filePath)) {
+    return null;
+  }
+
+  return {
+    filePath,
+    line: 1,
+    message:
+      'File is draft-marked but no longer contains draft ids. Remove the draft filename marker or finish the promotion cleanup.',
+    rule: 'draft-file-marking',
+    severity: 'warn',
+  };
+};
+
+const collectDraftFileMarkingDiagnostics = (
+  sourceCode: string,
+  filePath: string,
+  ast: NonNullable<ReturnType<typeof parse>>
+): WardenDiagnostic[] => {
+  const missingMarkerDiagnostic = draftMissingMarkerDiagnostic(
+    sourceCode,
+    filePath,
+    ast
+  );
+  if (missingMarkerDiagnostic) {
+    return [missingMarkerDiagnostic];
+  }
+
+  const markedWithoutIdsDiagnostic = draftMarkedWithoutIdsDiagnostic(
+    filePath,
+    ast
+  );
+  if (markedWithoutIdsDiagnostic) {
+    return [markedWithoutIdsDiagnostic];
+  }
+
+  return [];
+};
+
+/**
+ * Ensures files containing draft ids are visibly marked as draft-bearing files.
+ */
+export const draftFileMarking: WardenRule = {
+  check(sourceCode: string, filePath: string): readonly WardenDiagnostic[] {
+    const ast = parse(filePath, sourceCode);
+    if (!ast) {
+      return [];
+    }
+
+    return collectDraftFileMarkingDiagnostics(sourceCode, filePath, ast);
+  },
+  description:
+    'Require draft-bearing files to use _draft.* or *.draft.* filename markers.',
+  name: 'draft-file-marking',
+  severity: 'error',
+};

package/src/rules/draft-visible-debt.ts

@@ -0,0 +1,87 @@
+import { isDraftId } from '@ontrails/core';
+
+import {
+  collectFrameworkDraftPrefixConstantOffsets,
+  findStringLiterals,
+  hasIgnoreCommentOnLine,
+  offsetToLine,
+  parse,
+  splitSourceLines,
+} from './ast.js';
+import type { WardenDiagnostic, WardenRule } from './types.js';
+
+const createDiagnostic = (
+  sourceCode: string,
+  filePath: string,
+  match: { start: number; value: string }
+): WardenDiagnostic => ({
+  filePath,
+  line: offsetToLine(sourceCode, match.start),
+  message:
+    `Draft id "${match.value}" is still visible debt. ` +
+    'Established trailheads, lock export, and OpenAPI generation will reject it until it is promoted.',
+  rule: 'draft-visible-debt',
+  severity: 'warn',
+});
+
+const isSuppressedMatch = (
+  match: { start: number },
+  sourceCode: string,
+  lines: readonly string[],
+  frameworkConstantOffsets: ReadonlySet<number>
+): boolean =>
+  frameworkConstantOffsets.has(match.start) ||
+  hasIgnoreCommentOnLine(lines, offsetToLine(sourceCode, match.start));
+
+const collectDraftVisibleDebtDiagnostics = (
+  sourceCode: string,
+  filePath: string,
+  ast: NonNullable<ReturnType<typeof parse>>
+): WardenDiagnostic[] => {
+  const frameworkConstantOffsets = collectFrameworkDraftPrefixConstantOffsets(
+    ast,
+    filePath
+  );
+  const lines = splitSourceLines(sourceCode);
+  const seen = new Set<string>();
+
+  return findStringLiterals(ast, (value) => isDraftId(value)).flatMap(
+    (match) => {
+      if (
+        isSuppressedMatch(match, sourceCode, lines, frameworkConstantOffsets)
+      ) {
+        return [];
+      }
+      const key = `${match.value}:${String(match.start)}`;
+      if (seen.has(key)) {
+        return [];
+      }
+      seen.add(key);
+      return [createDiagnostic(sourceCode, filePath, match)];
+    }
+  );
+};
+
+/**
+ * Warns when draft ids are still present so the debt stays visible during
+ * review even when the file is correctly marked.
+ *
+ * Severity is intentionally `warn`, not `error`. The hard rejection layer for
+ * draft state leaking into established outputs is `validateEstablishedTopo` at
+ * runtime — it blocks topo export, trailhead projection, and lockfile writes.
+ * This rule surfaces the debt for human reviewers without duplicating that layer.
+ */
+export const draftVisibleDebt: WardenRule = {
+  check(sourceCode: string, filePath: string): readonly WardenDiagnostic[] {
+    const ast = parse(filePath, sourceCode);
+    if (!ast) {
+      return [];
+    }
+
+    return collectDraftVisibleDebtDiagnostics(sourceCode, filePath, ast);
+  },
+  description:
+    'Warn when draft ids remain in source so the debt stays visible during review.',
+  name: 'draft-visible-debt',
+  severity: 'warn',
+};

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

@@ -0,0 +1,273 @@
+/**
+ * Validates that registered transport error mappers cover every error category.
+ *
+ * Scans `createTransportErrorMapper(...)` calls and resolves simple object
+ * literals, identifier bindings, and object-property references in the same
+ * file so incomplete mapper registrations are caught before they ship.
+ */
+
+import { errorCategories } from '@ontrails/core';
+
+import {
+  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 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((property as unknown as { key?: AstNode }).key);
+    if (key === propertyName) {
+      return (property as unknown as { value?: AstNode }).value ?? 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((property as unknown as { key?: AstNode }).key);
+  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: `Transport error mapper is missing mappings for: ${missingCategories.join(', ')}. Registered createTransportErrorMapper() 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' &&
+  identifierName(getCallCallee(node)) === 'createTransportErrorMapper';
+
+const findMissingCategories = (
+  mappedCategories: ReadonlySet<string>
+): readonly string[] =>
+  errorCategories.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 `createTransportErrorMapper()` registrations that omit error categories.
+ */
+export const errorMappingCompleteness: WardenRule = {
+  check(sourceCode: string, filePath: string): readonly WardenDiagnostic[] {
+    if (
+      isTestFile(filePath) ||
+      !sourceCode.includes('createTransportErrorMapper')
+    ) {
+      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 transport error mappers to cover every ErrorCategory.',
+  name: 'error-mapping-completeness',
+  severity: 'error',
+};