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

package/src/rules/circular-refs.ts

@@ -0,0 +1,154 @@
+import {
+  collectContourReferenceTargetsByName,
+  findContourDefinitions,
+  offsetToLine,
+  parse,
+} from './ast.js';
+import type { AstNode } from './ast.js';
+import { isTestFile } from './scan.js';
+import type {
+  ProjectAwareWardenRule,
+  ProjectContext,
+  WardenDiagnostic,
+} from './types.js';
+
+const mergeReferenceGraphs = (
+  localGraph: ReadonlyMap<string, readonly string[]>,
+  contextGraph?: ReadonlyMap<string, readonly string[]>
+): ReadonlyMap<string, readonly string[]> => {
+  const merged = new Map<string, Set<string>>();
+
+  const addTargets = (source: string, targets: readonly string[]): void => {
+    const existing = merged.get(source);
+    if (existing) {
+      for (const target of targets) {
+        existing.add(target);
+      }
+      return;
+    }
+
+    merged.set(source, new Set(targets));
+  };
+
+  for (const [source, targets] of contextGraph ?? []) {
+    addTargets(source, targets);
+  }
+
+  for (const [source, targets] of localGraph) {
+    addTargets(source, targets);
+  }
+
+  return new Map(
+    [...merged.entries()].map(([source, targets]) => [source, [...targets]])
+  );
+};
+
+const findCyclePath = (
+  start: string,
+  graph: ReadonlyMap<string, readonly string[]>,
+  current = start,
+  path: readonly string[] = [start],
+  active: ReadonlySet<string> = new Set([start])
+): readonly string[] | null => {
+  for (const target of graph.get(current) ?? []) {
+    if (target === start) {
+      return [...path, target];
+    }
+
+    if (active.has(target)) {
+      continue;
+    }
+
+    const cycle = findCyclePath(
+      start,
+      graph,
+      target,
+      [...path, target],
+      new Set([...active, target])
+    );
+    if (cycle) {
+      return cycle;
+    }
+  }
+
+  return null;
+};
+
+const buildCircularReferenceDiagnostic = (
+  contourName: string,
+  cyclePath: readonly string[],
+  filePath: string,
+  line: number
+): WardenDiagnostic => ({
+  filePath,
+  line,
+  message: `Contour "${contourName}" participates in circular contour references: ${cyclePath.join(' -> ')}. Break the cycle by removing one contour reference, or extract the shared shape into a new contour neither side depends on.`,
+  rule: 'circular-refs',
+  severity: 'warn',
+});
+
+const checkCircularReferences = (
+  ast: AstNode,
+  sourceCode: string,
+  filePath: string,
+  graph: ReadonlyMap<string, readonly string[]>
+): readonly WardenDiagnostic[] => {
+  if (isTestFile(filePath)) {
+    return [];
+  }
+
+  return findContourDefinitions(ast).flatMap((definition) => {
+    const cyclePath = findCyclePath(definition.name, graph);
+    if (!cyclePath) {
+      return [];
+    }
+
+    return [
+      buildCircularReferenceDiagnostic(
+        definition.name,
+        cyclePath,
+        filePath,
+        offsetToLine(sourceCode, definition.start)
+      ),
+    ];
+  });
+};
+
+/**
+ * Warns when contour references form a direct or transitive cycle.
+ */
+export const circularRefs: ProjectAwareWardenRule = {
+  check(sourceCode: string, filePath: string): readonly WardenDiagnostic[] {
+    const ast = parse(filePath, sourceCode);
+    if (!ast) {
+      return [];
+    }
+
+    const graph = collectContourReferenceTargetsByName(ast);
+    return checkCircularReferences(ast, sourceCode, filePath, graph);
+  },
+  checkWithContext(
+    sourceCode: string,
+    filePath: string,
+    context: ProjectContext
+  ): readonly WardenDiagnostic[] {
+    const ast = parse(filePath, sourceCode);
+    if (!ast) {
+      return [];
+    }
+
+    const localGraph = collectContourReferenceTargetsByName(
+      ast,
+      context.knownContourIds
+    );
+    return checkCircularReferences(
+      ast,
+      sourceCode,
+      filePath,
+      mergeReferenceGraphs(localGraph, context.contourReferencesByName)
+    );
+  },
+  description: 'Warn when contour references form direct or transitive cycles.',
+  name: 'circular-refs',
+  severity: 'warn',
+};

package/src/rules/cli-command-route-coherence.ts

@@ -0,0 +1,177 @@
+import { deriveTrailCliCommandProjection } from '@ontrails/core';
+import type { CliCommandRoute, Topo } from '@ontrails/core';
+import type { TopoGraph } from '@ontrails/topographer';
+
+import type { TopoAwareWardenRule, WardenDiagnostic } from './types.js';
+
+const RULE_NAME = 'cli-command-route-coherence';
+const TOPO_FILE = '<topo>';
+
+interface RouteClaim {
+  readonly kind: CliCommandRoute['kind'];
+  readonly path: readonly string[];
+  readonly source: CliCommandRoute['source'];
+  readonly trailId: string;
+}
+
+const routeKey = (path: readonly string[]): string => path.join('\0');
+
+const renderPath = (path: readonly string[]): string => path.join(' ');
+
+const claimLabel = (claim: RouteClaim): string =>
+  `${claim.kind} route for trail "${claim.trailId}" (${claim.source})`;
+
+const buildProjectionDiagnostic = (
+  trailId: string,
+  error: unknown
+): WardenDiagnostic => ({
+  filePath: TOPO_FILE,
+  line: 1,
+  message: `CLI command route projection for trail "${trailId}" is invalid: ${
+    error instanceof Error ? error.message : String(error)
+  }`,
+  rule: RULE_NAME,
+  severity: 'error',
+});
+
+const buildCollisionDiagnostic = (
+  path: readonly string[],
+  claims: readonly RouteClaim[]
+): WardenDiagnostic => ({
+  filePath: TOPO_FILE,
+  line: 1,
+  message: `CLI command route collision on "${renderPath(path)}": ${claims
+    .toSorted((a, b) => a.trailId.localeCompare(b.trailId))
+    .map(claimLabel)
+    .join(
+      ', '
+    )}. Rename or remove one CLI alias so every accepted command path normalizes into exactly one trail contract.`,
+  rule: RULE_NAME,
+  severity: 'error',
+});
+
+const buildGraphTargetDiagnostic = (
+  entryId: string,
+  route: CliCommandRoute,
+  knownTrailIds: ReadonlySet<string>
+): WardenDiagnostic => ({
+  filePath: TOPO_FILE,
+  line: 1,
+  message: knownTrailIds.has(route.target)
+    ? `Serialized CLI command route "${renderPath(route.path)}" is stored under trail "${entryId}" but targets "${route.target}". Route facts must stay attached to their owning trail.`
+    : `Serialized CLI command route "${renderPath(route.path)}" targets unknown trail "${route.target}". Surface-owned aliases must target existing trail IDs.`,
+  rule: RULE_NAME,
+  severity: 'error',
+});
+
+const collectTopoClaims = (
+  topo: Topo
+): {
+  readonly claims: readonly RouteClaim[];
+  readonly diagnostics: readonly WardenDiagnostic[];
+} => {
+  const claims: RouteClaim[] = [];
+  const diagnostics: WardenDiagnostic[] = [];
+
+  for (const trail of topo.list()) {
+    try {
+      const projection = deriveTrailCliCommandProjection(trail);
+      for (const route of projection.routes) {
+        claims.push({
+          kind: route.kind,
+          path: route.path,
+          source: route.source,
+          trailId: trail.id,
+        });
+      }
+    } catch (error: unknown) {
+      diagnostics.push(buildProjectionDiagnostic(trail.id, error));
+    }
+  }
+
+  return { claims, diagnostics };
+};
+
+const collectGraphClaims = (
+  graph: TopoGraph | undefined
+): readonly RouteClaim[] => {
+  if (graph === undefined) {
+    return [];
+  }
+
+  const claims: RouteClaim[] = [];
+  for (const entry of graph.entries) {
+    if (entry.kind !== 'trail') {
+      continue;
+    }
+    for (const route of entry.cli?.routes ?? []) {
+      claims.push({
+        kind: route.kind,
+        path: route.path,
+        source: route.source,
+        trailId: entry.id,
+      });
+    }
+  }
+  return claims;
+};
+
+const collectCollisionDiagnostics = (
+  claims: readonly RouteClaim[]
+): readonly WardenDiagnostic[] => {
+  const claimsByRoute = new Map<string, RouteClaim[]>();
+  for (const claim of claims) {
+    const key = routeKey(claim.path);
+    const current = claimsByRoute.get(key) ?? [];
+    current.push(claim);
+    claimsByRoute.set(key, current);
+  }
+
+  return [...claimsByRoute.values()]
+    .filter((grouped) => grouped.length > 1)
+    .map((grouped) =>
+      buildCollisionDiagnostic(grouped[0]?.path ?? [], grouped)
+    );
+};
+
+const collectGraphTargetDiagnostics = (
+  graph: TopoGraph | undefined,
+  knownTrailIds: ReadonlySet<string>
+): readonly WardenDiagnostic[] => {
+  if (graph === undefined) {
+    return [];
+  }
+
+  const diagnostics: WardenDiagnostic[] = [];
+  for (const entry of graph.entries) {
+    if (entry.kind !== 'trail') {
+      continue;
+    }
+    for (const route of entry.cli?.routes ?? []) {
+      if (route.target !== entry.id || !knownTrailIds.has(route.target)) {
+        diagnostics.push(
+          buildGraphTargetDiagnostic(entry.id, route, knownTrailIds)
+        );
+      }
+    }
+  }
+  return diagnostics;
+};
+
+export const cliCommandRouteCoherence: TopoAwareWardenRule = {
+  checkTopo(topo, context) {
+    const { claims, diagnostics } = collectTopoClaims(topo);
+    const knownTrailIds = new Set(topo.trails.keys());
+    const routeClaims =
+      context?.graph === undefined ? claims : collectGraphClaims(context.graph);
+    return [
+      ...diagnostics,
+      ...collectCollisionDiagnostics(routeClaims),
+      ...collectGraphTargetDiagnostics(context?.graph, knownTrailIds),
+    ];
+  },
+  description:
+    'Ensure CLI command routes and aliases resolve to one coherent trail contract.',
+  name: RULE_NAME,
+  severity: 'error',
+};