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

package/src/rules/dead-public-trail.ts

@@ -0,0 +1,258 @@
+import {
+  collectComposeTargetTrailIds,
+  findConfigProperty,
+  findTrailDefinitions,
+  getNodeDeclaration,
+  getNodeDeclarations,
+  getNodeId,
+  getNodeInit,
+  getNodeLocal,
+  getNodeName,
+  getNodeSpecifiers,
+  getNodeValue,
+  getStringValue,
+  isStringLiteral,
+  offsetToLine,
+  parse,
+  walkWithParents,
+} from './ast.js';
+import type { AstNode, AstParentContext } from './ast.js';
+import { isTestFile } from './scan.js';
+import type {
+  ProjectAwareWardenRule,
+  ProjectContext,
+  WardenDiagnostic,
+} from './types.js';
+
+const RULE_NAME = 'dead-public-trail';
+
+const isNonEmptyActivationValue = (onValue: AstNode): boolean => {
+  if (onValue.type === 'Identifier') {
+    return true;
+  }
+  if (onValue.type !== 'ArrayExpression') {
+    return false;
+  }
+  const elements = onValue['elements'] as readonly AstNode[] | undefined;
+  return (elements?.length ?? 0) > 0;
+};
+
+const hasOnActivation = (config: AstNode): boolean => {
+  const onProp = findConfigProperty(config, 'on');
+  const onValue = onProp?.value as AstNode | undefined;
+  return onValue ? isNonEmptyActivationValue(onValue) : false;
+};
+
+const hasExplicitInternalVisibility = (config: AstNode): boolean => {
+  const visibilityProp = findConfigProperty(config, 'visibility');
+  const visibilityValue = visibilityProp?.value as AstNode | undefined;
+  return (
+    !!visibilityValue &&
+    isStringLiteral(visibilityValue) &&
+    getStringValue(visibilityValue) === 'internal'
+  );
+};
+
+const hasLegacyMetaInternal = (config: AstNode): boolean => {
+  const metaProp = findConfigProperty(config, 'meta');
+  const metaValue = metaProp?.value as AstNode | undefined;
+  if (!metaValue || metaValue.type !== 'ObjectExpression') {
+    return false;
+  }
+  const internalProp = findConfigProperty(metaValue, 'internal');
+  const internalValue = internalProp?.value as AstNode | undefined;
+  return (
+    internalValue?.type === 'BooleanLiteral' &&
+    getNodeValue(internalValue) === true
+  );
+};
+
+const isInternalTrail = (config: AstNode): boolean =>
+  hasExplicitInternalVisibility(config) || hasLegacyMetaInternal(config);
+
+const isExportDeclaration = (node: AstNode | null | undefined): boolean =>
+  node?.type === 'ExportNamedDeclaration' ||
+  node?.type === 'ExportDefaultDeclaration';
+
+const identifierName = (node: AstNode | undefined): string | null =>
+  node?.type === 'Identifier' ? (getNodeName(node) ?? null) : null;
+
+const trailBindingStarts = (ast: AstNode): ReadonlyMap<string, number> => {
+  const trailStarts = new Set(
+    findTrailDefinitions(ast)
+      .filter((definition) => definition.kind === 'trail')
+      .map((definition) => definition.start)
+  );
+  const bindings = new Map<string, number>();
+
+  walkWithParents(ast, (node: AstNode) => {
+    if (node.type !== 'VariableDeclarator') {
+      return;
+    }
+    const id = getNodeId(node);
+    const init = getNodeInit(node);
+    const name = identifierName(id);
+    if (name && init && trailStarts.has(init.start)) {
+      bindings.set(name, init.start);
+    }
+  });
+
+  return bindings;
+};
+
+const addExportedSpecifierStarts = (
+  node: AstNode,
+  bindings: ReadonlyMap<string, number>,
+  exported: Set<number>
+): void => {
+  const specifiers = getNodeSpecifiers(node) ?? [];
+  for (const specifier of specifiers) {
+    const local = getNodeLocal(specifier);
+    const name = identifierName(local);
+    const start = name ? bindings.get(name) : undefined;
+    if (start !== undefined) {
+      exported.add(start);
+    }
+  }
+};
+
+const exportedTrailStarts = (ast: AstNode): ReadonlySet<number> => {
+  const exported = new Set<number>();
+  const bindings = trailBindingStarts(ast);
+
+  walkWithParents(ast, (node: AstNode, context: AstParentContext) => {
+    if (node.type !== 'CallExpression') {
+      return;
+    }
+
+    // Catch `export default trail(...)`. Exported variable declarations are
+    // handled by the VariableDeclaration walk below.
+    if (isExportDeclaration(context.parent)) {
+      exported.add(node.start);
+    }
+  });
+
+  walkWithParents(ast, (node: AstNode, context: AstParentContext) => {
+    if (node.type !== 'VariableDeclaration') {
+      return;
+    }
+    if (!isExportDeclaration(context.parent)) {
+      return;
+    }
+    const declarations = getNodeDeclarations(node) ?? [];
+    for (const declaration of declarations) {
+      const init = getNodeInit(declaration);
+      if (init?.type === 'CallExpression') {
+        exported.add(init.start);
+      }
+    }
+  });
+
+  walkWithParents(ast, (node: AstNode) => {
+    if (node.type === 'ExportNamedDeclaration') {
+      addExportedSpecifierStarts(node, bindings, exported);
+      return;
+    }
+
+    if (node.type !== 'ExportDefaultDeclaration') {
+      return;
+    }
+    const declaration = getNodeDeclaration(node);
+    const name = identifierName(declaration);
+    const start = name ? bindings.get(name) : undefined;
+    if (start !== undefined) {
+      exported.add(start);
+    }
+  });
+
+  return exported;
+};
+
+const buildDiagnostic = (
+  trailId: string,
+  filePath: string,
+  line: number
+): WardenDiagnostic => ({
+  filePath,
+  line,
+  message: `Exported public trail "${trailId}" is not registered in a configured app topo, composed by another trail, or activated by on:. Anchor the contract in a topo, compose it, mark it internal, or remove the public export.`,
+  rule: RULE_NAME,
+  severity: 'warn',
+});
+
+const unionComposeTargetIds = (
+  ast: AstNode | null,
+  sourceCode: string,
+  context: ProjectContext
+): ReadonlySet<string> => {
+  const local = ast
+    ? collectComposeTargetTrailIds(ast, sourceCode)
+    : new Set<string>();
+  return context.composeTargetTrailIds
+    ? new Set([...context.composeTargetTrailIds, ...local])
+    : local;
+};
+
+const checkDeadPublicTrails = (
+  ast: AstNode | null,
+  sourceCode: string,
+  filePath: string,
+  context: ProjectContext
+): readonly WardenDiagnostic[] => {
+  if (isTestFile(filePath) || !ast || !context.topoTrailIds) {
+    return [];
+  }
+
+  const exportedStarts = exportedTrailStarts(ast);
+  const composeTargetTrailIds = unionComposeTargetIds(ast, sourceCode, context);
+  const diagnostics: WardenDiagnostic[] = [];
+
+  for (const def of findTrailDefinitions(ast)) {
+    if (
+      def.kind !== 'trail' ||
+      isInternalTrail(def.config) ||
+      !exportedStarts.has(def.start)
+    ) {
+      continue;
+    }
+
+    if (
+      hasOnActivation(def.config) ||
+      composeTargetTrailIds.has(def.id) ||
+      context.topoTrailIds.has(def.id)
+    ) {
+      continue;
+    }
+
+    diagnostics.push(
+      buildDiagnostic(def.id, filePath, offsetToLine(sourceCode, def.start))
+    );
+  }
+
+  return diagnostics;
+};
+
+export const deadPublicTrail: ProjectAwareWardenRule = {
+  check(sourceCode: string, filePath: string): readonly WardenDiagnostic[] {
+    const ast = parse(filePath, sourceCode);
+    return checkDeadPublicTrails(ast, sourceCode, filePath, {
+      knownTrailIds: new Set<string>(),
+    });
+  },
+  checkWithContext(
+    sourceCode: string,
+    filePath: string,
+    context: ProjectContext
+  ): readonly WardenDiagnostic[] {
+    return checkDeadPublicTrails(
+      parse(filePath, sourceCode),
+      sourceCode,
+      filePath,
+      context
+    );
+  },
+  description:
+    'Warn when an exported public trail is neither registered in configured app topos nor reachable through composition or activation.',
+  name: RULE_NAME,
+  severity: 'warn',
+};

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 surfaces, 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 compile, surface 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/duplicate-public-contract.ts

@@ -0,0 +1,91 @@
+import { deriveTopoGraph } from '@ontrails/topographer';
+import type { TopoGraph, TopoGraphEntry } from '@ontrails/topographer';
+
+import type { TopoAwareWardenRule, WardenDiagnostic } from './types.js';
+
+const RULE_NAME = 'duplicate-public-contract';
+const TOPO_FILE = '<topo>';
+
+const resolveGraph = (
+  topo: Parameters<TopoAwareWardenRule['checkTopo']>[0],
+  graph: TopoGraph | undefined
+): TopoGraph => graph ?? deriveTopoGraph(topo);
+
+const canonicalize = (value: unknown): unknown => {
+  if (Array.isArray(value)) {
+    return value.map(canonicalize);
+  }
+  if (value && typeof value === 'object') {
+    return Object.fromEntries(
+      Object.entries(value as Record<string, unknown>)
+        .filter(([, entryValue]) => entryValue !== undefined)
+        .toSorted(([left], [right]) => left.localeCompare(right))
+        .map(([key, entryValue]) => [key, canonicalize(entryValue)])
+    );
+  }
+  return value;
+};
+
+const contractFingerprint = (entry: TopoGraphEntry): string =>
+  JSON.stringify(
+    canonicalize({
+      composes: entry.composes,
+      detours: entry.detours,
+      dryRunCapable: entry.dryRunCapable,
+      fires: entry.fires,
+      idempotent: entry.idempotent,
+      input: entry.input,
+      intent: entry.intent,
+      meta: entry.meta,
+      on: entry.on,
+      output: entry.output,
+      permit: entry.permit,
+      resources: entry.resources,
+    })
+  );
+
+const isCandidate = (entry: TopoGraphEntry): boolean =>
+  entry.kind === 'trail' &&
+  !entry.id.startsWith('warden.rule.') &&
+  entry.deprecated !== true &&
+  entry.meta?.['internal'] !== true &&
+  entry.input !== undefined &&
+  entry.output !== undefined &&
+  Boolean(entry.cli || entry.surfaces.length > 0);
+
+const renderTrailIds = (trailIds: readonly string[]): string =>
+  trailIds
+    .toSorted((left, right) => left.localeCompare(right))
+    .map((trailId) => `"${trailId}"`)
+    .join(', ');
+
+const buildDiagnostic = (trailIds: readonly string[]): WardenDiagnostic => ({
+  filePath: TOPO_FILE,
+  line: 1,
+  message: `Likely duplicate public trail contracts ${renderTrailIds(trailIds)} share the same input, output, intent, permits, resources, composes, signals, and detours. Keep one contract with aliases/input mappings, compose a distinct wrapper, or document why these public contracts are separate.`,
+  rule: RULE_NAME,
+  severity: 'warn',
+});
+
+export const duplicatePublicContract: TopoAwareWardenRule = {
+  checkTopo(topo, context) {
+    const graph = resolveGraph(topo, context?.graph);
+    const groups = new Map<string, string[]>();
+
+    for (const entry of graph.entries) {
+      if (!isCandidate(entry)) {
+        continue;
+      }
+      const key = contractFingerprint(entry);
+      groups.set(key, [...(groups.get(key) ?? []), entry.id]);
+    }
+
+    return [...groups.values()]
+      .filter((trailIds) => trailIds.length > 1)
+      .map(buildDiagnostic);
+  },
+  description:
+    'Warn when public surface trails expose the same normalized contract facts.',
+  name: RULE_NAME,
+  severity: 'warn',
+};