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

package/src/cli.ts

@@ -8,20 +8,29 @@
 import { resolve } from 'node:path';
 
 import type { Topo } from '@ontrails/core';
+import { getContourReferences } from '@ontrails/core';
 
 import type { DriftResult } from './drift.js';
 import { checkDrift } from './drift.js';
 import {
-  collectProvisionDefinitionIds,
-  findConfigProperty,
+  collectContourDefinitionIds,
+  collectContourReferenceTargetsByName,
+  collectCrudTableIds as collectCrudTableIdsFromAst,
+  collectCrossTargetTrailIds,
+  collectOnTargetSignalIds as collectOnTargetSignalIdsFromAst,
+  collectReconcileTableIds as collectReconcileTableIdsFromAst,
+  collectResourceDefinitionIds,
+  collectSignalDefinitionIds,
+  collectTrailIntentsById,
   findTrailDefinitions,
   parse,
-  walk,
 } from './rules/ast.js';
-import { wardenRules } from './rules/index.js';
+import { collectFileCrudCoverage } from './rules/incomplete-crud.js';
+import { wardenRules, wardenTopoRules } from './rules/index.js';
 import type {
   ProjectAwareWardenRule,
   ProjectContext,
+  TopoAwareWardenRule,
   WardenDiagnostic,
   WardenRule,
 } from './rules/types.js';
@@ -36,8 +45,25 @@ export interface WardenOptions {
   readonly lintOnly?: boolean | undefined;
   /** Only run drift detection, skip lint rules */
   readonly driftOnly?: boolean | undefined;
-  /** App topology for drift detection. When provided, enables real trailhead lock comparison. */
+  /**
+   * App topology for drift detection. When provided, enables real trailhead
+   * lock comparison and unlocks the topo-aware rule dispatch path.
+   *
+   * @remarks
+   * Topo-aware rules (both built-in `wardenTopoRules` and `extraTopoRules`)
+   * only fire when a `Topo` is supplied. Runs without a topo silently skip
+   * topo-aware dispatch — callers that depend on a topo-aware rule firing
+   * must pass `topo` explicitly.
+   */
   readonly topo?: Topo | undefined;
+  /**
+   * Extra topo-aware rules to run in addition to the built-in registry.
+   *
+   * Primarily a test hook — production callers should register rules via
+   * `wardenTopoRules` in `rules/index.ts`. These rules are only invoked
+   * when `topo` is also supplied (see `topo` remarks).
+   */
+  readonly extraTopoRules?: readonly TopoAwareWardenRule[] | undefined;
 }
 
 /**
@@ -92,6 +118,103 @@ interface SourceFile {
   readonly sourceCode: string;
 }
 
+interface MutableProjectContext {
+  contourReferencesByName: Map<string, Set<string>>;
+  crudTableIds: Set<string>;
+  crossTargetTrailIds: Set<string>;
+  crudCoverageByEntity: Map<string, Set<string>>;
+  knownContourIds: Set<string>;
+  knownResourceIds: Set<string>;
+  knownSignalIds: Set<string>;
+  knownTrailIds: Set<string>;
+  onTargetSignalIds: Set<string>;
+  reconcileTableIds: Set<string>;
+  trailIntentsById: Map<string, 'destroy' | 'read' | 'write'>;
+}
+
+const createMutableProjectContext = (): MutableProjectContext => ({
+  contourReferencesByName: new Map<string, Set<string>>(),
+  crossTargetTrailIds: new Set<string>(),
+  crudCoverageByEntity: new Map<string, Set<string>>(),
+  crudTableIds: new Set<string>(),
+  knownContourIds: new Set<string>(),
+  knownResourceIds: new Set<string>(),
+  knownSignalIds: new Set<string>(),
+  knownTrailIds: new Set<string>(),
+  onTargetSignalIds: new Set<string>(),
+  reconcileTableIds: new Set<string>(),
+  trailIntentsById: new Map<string, 'destroy' | 'read' | 'write'>(),
+});
+
+const addContourReferenceTargets = (
+  context: MutableProjectContext,
+  contourName: string,
+  targets: readonly string[]
+): void => {
+  const existing = context.contourReferencesByName.get(contourName);
+  if (existing) {
+    for (const target of targets) {
+      existing.add(target);
+    }
+    return;
+  }
+
+  context.contourReferencesByName.set(contourName, new Set(targets));
+};
+
+const toProjectContext = (context: MutableProjectContext): ProjectContext => ({
+  ...(context.contourReferencesByName.size > 0
+    ? {
+        contourReferencesByName: new Map(
+          [...context.contourReferencesByName.entries()].map(
+            ([name, targets]) => [name, [...targets]]
+          )
+        ),
+      }
+    : {}),
+  ...(context.crudTableIds.size > 0
+    ? { crudTableIds: context.crudTableIds }
+    : {}),
+  ...(context.crudCoverageByEntity.size > 0
+    ? {
+        crudCoverageByEntity: new Map(
+          [...context.crudCoverageByEntity.entries()].map(
+            ([entityId, operations]) => [
+              entityId,
+              new Set(operations) as ReadonlySet<string>,
+            ]
+          )
+        ),
+      }
+    : {}),
+  crossTargetTrailIds: context.crossTargetTrailIds,
+  knownContourIds: context.knownContourIds,
+  knownResourceIds: context.knownResourceIds,
+  knownSignalIds: context.knownSignalIds,
+  knownTrailIds: context.knownTrailIds,
+  ...(context.onTargetSignalIds.size > 0
+    ? { onTargetSignalIds: context.onTargetSignalIds }
+    : {}),
+  ...(context.reconcileTableIds.size > 0
+    ? { reconcileTableIds: context.reconcileTableIds }
+    : {}),
+  trailIntentsById: context.trailIntentsById,
+});
+
+const collectKnownContourIds = (
+  sourceCode: string,
+  filePath: string,
+  knownContourIds: Set<string>
+): void => {
+  const ast = parse(filePath, sourceCode);
+  if (!ast) {
+    return;
+  }
+  for (const id of collectContourDefinitionIds(ast)) {
+    knownContourIds.add(id);
+  }
+};
+
 const collectKnownTrailIds = (
   sourceCode: string,
   filePath: string,
@@ -106,44 +229,122 @@ const collectKnownTrailIds = (
   }
 };
 
-const collectDetourTargetTrailIds = (
+const collectCrossedTrailIds = (
   sourceCode: string,
   filePath: string,
-  detourTargetTrailIds: Set<string>
+  crossTargetTrailIds: Set<string>
 ): void => {
   const ast = parse(filePath, sourceCode);
   if (!ast) {
     return;
   }
-  for (const def of findTrailDefinitions(ast)) {
-    const detoursProp = findConfigProperty(def.config, 'detours');
-    if (!detoursProp) {
-      continue;
+  for (const id of collectCrossTargetTrailIds(ast, sourceCode)) {
+    crossTargetTrailIds.add(id);
+  }
+};
+
+const collectKnownResourceIds = (
+  sourceCode: string,
+  filePath: string,
+  knownResourceIds: Set<string>
+): void => {
+  const ast = parse(filePath, sourceCode);
+  if (!ast) {
+    return;
+  }
+  for (const id of collectResourceDefinitionIds(ast)) {
+    knownResourceIds.add(id);
+  }
+};
+
+const collectKnownSignalIds = (
+  sourceCode: string,
+  filePath: string,
+  knownSignalIds: Set<string>
+): void => {
+  const ast = parse(filePath, sourceCode);
+  if (!ast) {
+    return;
+  }
+  for (const id of collectSignalDefinitionIds(ast)) {
+    knownSignalIds.add(id);
+  }
+};
+
+const collectTrailIntents = (
+  sourceCode: string,
+  filePath: string,
+  trailIntentsById: Map<string, 'destroy' | 'read' | 'write'>
+): void => {
+  const ast = parse(filePath, sourceCode);
+  if (!ast) {
+    return;
+  }
+  for (const [id, intent] of collectTrailIntentsById(ast)) {
+    trailIntentsById.set(id, intent);
+  }
+};
+
+const collectCrudTableIds = (
+  sourceCode: string,
+  filePath: string,
+  crudTableIds: Set<string>
+): void => {
+  const ast = parse(filePath, sourceCode);
+  if (!ast) {
+    return;
+  }
+  for (const id of collectCrudTableIdsFromAst(ast)) {
+    crudTableIds.add(id);
+  }
+};
+
+const collectOnTargetSignalIds = (
+  sourceCode: string,
+  filePath: string,
+  onTargetSignalIds: Set<string>
+): void => {
+  const ast = parse(filePath, sourceCode);
+  if (!ast) {
+    return;
+  }
+  for (const id of collectOnTargetSignalIdsFromAst(ast, sourceCode)) {
+    onTargetSignalIds.add(id);
+  }
+};
+
+const collectCrudCoverageByEntity = (
+  sourceCode: string,
+  filePath: string,
+  coverageByEntity: Map<string, Set<string>>
+): void => {
+  const ast = parse(filePath, sourceCode);
+  if (!ast) {
+    return;
+  }
+  for (const [entityId, operations] of collectFileCrudCoverage(
+    ast,
+    sourceCode
+  )) {
+    const bucket = coverageByEntity.get(entityId) ?? new Set<string>();
+    for (const operation of operations) {
+      bucket.add(operation);
     }
-    // Walk the detours value for string literals that look like trail IDs
-    walk(detoursProp, (node) => {
-      if (node.type !== 'Literal') {
-        return;
-      }
-      const val = (node as unknown as { value?: string }).value;
-      if (val && val.includes('.')) {
-        detourTargetTrailIds.add(val);
-      }
-    });
+    coverageByEntity.set(entityId, bucket);
   }
 };
 
-const collectKnownProvisionIds = (
+const collectReconcileTableIds = (
   sourceCode: string,
   filePath: string,
-  knownProvisionIds: Set<string>
+  reconcileTableIds: Set<string>
 ): void => {
   const ast = parse(filePath, sourceCode);
   if (!ast) {
     return;
   }
-  for (const id of collectProvisionDefinitionIds(ast)) {
-    knownProvisionIds.add(id);
+  for (const id of collectReconcileTableIdsFromAst(ast)) {
+    reconcileTableIds.add(id);
   }
 };
 
@@ -166,92 +367,231 @@ const loadSourceFiles = async (
   return sourceFiles;
 };
 
-const collectTopoDetourTargetTrailIds = (
-  appTopo: Topo
-): ReadonlySet<string> => {
-  const detourTargetTrailIds = new Set<string>();
+const collectTopoKnownIds = (
+  appTopo: Topo,
+  context: MutableProjectContext
+): void => {
+  for (const name of appTopo.contours.keys()) {
+    context.knownContourIds.add(name);
+  }
 
+  for (const id of appTopo.trails.keys()) {
+    context.knownTrailIds.add(id);
+  }
+
+  for (const id of appTopo.resources.keys()) {
+    context.knownResourceIds.add(id);
+  }
+
+  for (const id of appTopo.signals.keys()) {
+    context.knownSignalIds.add(id);
+  }
+};
+
+const collectTopoCrossesAndIntents = (
+  appTopo: Topo,
+  context: MutableProjectContext
+): void => {
   for (const trail of appTopo.trails.values()) {
-    const detours = (trail as unknown as Record<string, unknown>)['detours'] as
-      | Readonly<Record<string, readonly string[]>>
-      | undefined;
-    if (!detours) {
-      continue;
-    }
-    for (const targets of Object.values(detours)) {
-      for (const id of targets) {
-        detourTargetTrailIds.add(id);
-      }
+    context.trailIntentsById.set(trail.id, trail.intent);
+    for (const crossedTrailId of trail.crosses) {
+      context.crossTargetTrailIds.add(crossedTrailId);
     }
   }
+};
+
+const collectTopoContourReferences = (
+  appTopo: Topo,
+  context: MutableProjectContext
+): void => {
+  for (const contour of appTopo.listContours()) {
+    addContourReferenceTargets(
+      context,
+      contour.name,
+      getContourReferences(contour).map((reference) => reference.contour)
+    );
+  }
+};
 
-  return detourTargetTrailIds;
+const collectTopoTrailContext = (
+  appTopo: Topo,
+  context: MutableProjectContext
+): void => {
+  collectTopoKnownIds(appTopo, context);
+  collectTopoCrossesAndIntents(appTopo, context);
+  collectTopoContourReferences(appTopo, context);
 };
 
-const buildProjectContextFromTopo = (appTopo: Topo): ProjectContext => {
-  const knownTrailIds = new Set<string>(appTopo.trails.keys());
-  const knownProvisionIds = new Set<string>(appTopo.provisions.keys());
-  const detourTargetTrailIds = collectTopoDetourTargetTrailIds(appTopo);
+const collectFileKnownIds = (
+  sourceFile: SourceFile,
+  context: MutableProjectContext
+): void => {
+  collectKnownContourIds(
+    sourceFile.sourceCode,
+    sourceFile.filePath,
+    context.knownContourIds
+  );
+  collectKnownTrailIds(
+    sourceFile.sourceCode,
+    sourceFile.filePath,
+    context.knownTrailIds
+  );
+  collectKnownResourceIds(
+    sourceFile.sourceCode,
+    sourceFile.filePath,
+    context.knownResourceIds
+  );
+  collectKnownSignalIds(
+    sourceFile.sourceCode,
+    sourceFile.filePath,
+    context.knownSignalIds
+  );
+};
 
-  return {
-    detourTargetTrailIds,
-    knownProvisionIds,
-    knownTrailIds,
-  };
+const collectFileTrailRelationships = (
+  sourceFile: SourceFile,
+  context: MutableProjectContext
+): void => {
+  collectCrossedTrailIds(
+    sourceFile.sourceCode,
+    sourceFile.filePath,
+    context.crossTargetTrailIds
+  );
+  collectTrailIntents(
+    sourceFile.sourceCode,
+    sourceFile.filePath,
+    context.trailIntentsById
+  );
+};
+
+const collectFileSupplementalProjectContext = (
+  sourceFile: SourceFile,
+  context: MutableProjectContext
+): void => {
+  collectCrudTableIds(
+    sourceFile.sourceCode,
+    sourceFile.filePath,
+    context.crudTableIds
+  );
+  collectOnTargetSignalIds(
+    sourceFile.sourceCode,
+    sourceFile.filePath,
+    context.onTargetSignalIds
+  );
+  collectReconcileTableIds(
+    sourceFile.sourceCode,
+    sourceFile.filePath,
+    context.reconcileTableIds
+  );
+  collectCrudCoverageByEntity(
+    sourceFile.sourceCode,
+    sourceFile.filePath,
+    context.crudCoverageByEntity
+  );
 };
 
-const buildProjectContextFromFiles = (
-  sourceFiles: readonly SourceFile[]
+const collectFileProjectContext = (
+  sourceFile: SourceFile,
+  context: MutableProjectContext
+): void => {
+  collectFileKnownIds(sourceFile, context);
+  collectFileTrailRelationships(sourceFile, context);
+  collectFileSupplementalProjectContext(sourceFile, context);
+};
+
+const collectFileContourReferences = (
+  sourceFile: SourceFile,
+  context: MutableProjectContext
+): void => {
+  const ast = parse(sourceFile.filePath, sourceFile.sourceCode);
+  if (!ast) {
+    return;
+  }
+
+  const referencesByName = collectContourReferenceTargetsByName(
+    ast,
+    context.knownContourIds
+  );
+  for (const [contourName, targets] of referencesByName) {
+    addContourReferenceTargets(context, contourName, targets);
+  }
+};
+
+const buildProjectContext = (
+  sourceFiles: readonly SourceFile[],
+  appTopo?: Topo | undefined
 ): ProjectContext => {
-  const knownTrailIds = new Set<string>();
-  const knownProvisionIds = new Set<string>();
-  const detourTargetTrailIds = new Set<string>();
+  const context = createMutableProjectContext();
+
+  if (appTopo) {
+    collectTopoTrailContext(appTopo, context);
+    for (const sourceFile of sourceFiles) {
+      collectFileSupplementalProjectContext(sourceFile, context);
+    }
+  } else {
+    for (const sourceFile of sourceFiles) {
+      collectFileProjectContext(sourceFile, context);
+    }
+  }
 
   for (const sourceFile of sourceFiles) {
-    collectKnownTrailIds(
-      sourceFile.sourceCode,
-      sourceFile.filePath,
-      knownTrailIds
-    );
-    collectKnownProvisionIds(
-      sourceFile.sourceCode,
-      sourceFile.filePath,
-      knownProvisionIds
-    );
-    collectDetourTargetTrailIds(
-      sourceFile.sourceCode,
-      sourceFile.filePath,
-      detourTargetTrailIds
-    );
+    collectFileContourReferences(sourceFile, context);
   }
 
-  return {
-    detourTargetTrailIds,
-    knownProvisionIds,
-    knownTrailIds,
-  };
+  return toProjectContext(context);
 };
 
 const isProjectAwareRule = (rule: WardenRule): rule is ProjectAwareWardenRule =>
   'checkWithContext' in rule;
 
+const topoRuleFailureDiagnostic = (
+  rule: TopoAwareWardenRule,
+  error: unknown
+): WardenDiagnostic => {
+  const cause = error instanceof Error ? error : new Error(String(error));
+  return {
+    filePath: '<topo>',
+    line: 1,
+    message: `Topo-aware rule "${rule.name}" threw: ${cause.message}`,
+    rule: rule.name,
+    severity: 'error',
+  };
+};
+
 /**
- * Lint all files against all warden rules.
+ * Run all registered topo-aware rules against the resolved topo.
+ *
+ * Topo-aware rules fire exactly once per run (not per file) because they
+ * inspect the compiled trail graph, not source text.
  */
-const lintFiles = async (
-  rootDir: string,
-  appTopo?: Topo | undefined
-): Promise<WardenDiagnostic[]> => {
-  const allDiagnostics: WardenDiagnostic[] = [];
-  const sourceFiles = await loadSourceFiles(rootDir);
-  const context = appTopo
-    ? buildProjectContextFromTopo(appTopo)
-    : buildProjectContextFromFiles(sourceFiles);
+const lintTopo = async (
+  appTopo: Topo,
+  extraTopoRules: readonly TopoAwareWardenRule[]
+): Promise<readonly WardenDiagnostic[]> => {
+  const diagnostics: WardenDiagnostic[] = [];
+  const rules: readonly TopoAwareWardenRule[] = [
+    ...wardenTopoRules.values(),
+    ...extraTopoRules,
+  ];
+  for (const rule of rules) {
+    try {
+      diagnostics.push(...(await rule.checkTopo(appTopo)));
+    } catch (error) {
+      diagnostics.push(topoRuleFailureDiagnostic(rule, error));
+    }
+  }
+  return diagnostics;
+};
 
+const lintSourceFiles = (
+  sourceFiles: readonly SourceFile[],
+  context: ProjectContext
+): readonly WardenDiagnostic[] => {
+  const diagnostics: WardenDiagnostic[] = [];
   for (const sourceFile of sourceFiles) {
     for (const rule of wardenRules.values()) {
       if (isProjectAwareRule(rule)) {
-        allDiagnostics.push(
+        diagnostics.push(
           ...rule.checkWithContext(
             sourceFile.sourceCode,
             sourceFile.filePath,
@@ -260,12 +600,31 @@ const lintFiles = async (
         );
         continue;
       }
-
-      allDiagnostics.push(
+      diagnostics.push(
         ...rule.check(sourceFile.sourceCode, sourceFile.filePath)
       );
     }
   }
+  return diagnostics;
+};
+
+/**
+ * Lint all files against all warden rules.
+ */
+const lintFiles = async (
+  rootDir: string,
+  appTopo?: Topo | undefined,
+  extraTopoRules: readonly TopoAwareWardenRule[] = []
+): Promise<WardenDiagnostic[]> => {
+  const sourceFiles = await loadSourceFiles(rootDir);
+  const context = buildProjectContext(sourceFiles, appTopo);
+  const allDiagnostics: WardenDiagnostic[] = [
+    ...lintSourceFiles(sourceFiles, context),
+  ];
+
+  if (appTopo) {
+    allDiagnostics.push(...(await lintTopo(appTopo, extraTopoRules)));
+  }
 
   return allDiagnostics;
 };
@@ -279,7 +638,7 @@ export const runWarden = async (
   const rootDir = resolve(options.rootDir ?? process.cwd());
   const allDiagnostics = options.driftOnly
     ? []
-    : await lintFiles(rootDir, options.topo);
+    : await lintFiles(rootDir, options.topo, options.extraTopoRules ?? []);
   const drift = options.lintOnly
     ? null
     : await checkDrift(rootDir, options.topo);
@@ -293,7 +652,10 @@ export const runWarden = async (
     diagnostics: allDiagnostics,
     drift,
     errorCount,
-    passed: errorCount === 0 && !(drift?.stale ?? false),
+    passed:
+      errorCount === 0 &&
+      !(drift?.stale ?? false) &&
+      drift?.blockedReason === undefined,
     warnCount,
   };
 };
@@ -327,8 +689,11 @@ const formatDriftSection = (drift: DriftResult | null): string[] => {
   if (drift === null) {
     return [];
   }
+  if (drift.blockedReason !== undefined) {
+    return [`Drift: blocked (${drift.blockedReason})`, ''];
+  }
   const label = drift.stale
-    ? 'Drift: trailhead.lock is stale (regenerate with `trails survey generate`)'
+    ? 'Drift: trails.lock is stale (regenerate with `trails topo export`)'
     : 'Drift: clean';
   return [label, ''];
 };
@@ -344,7 +709,9 @@ const formatResultLine = (report: WardenReport): string => {
   if (report.errorCount > 0) {
     parts.push(`${report.errorCount} errors`);
   }
-  if (report.drift?.stale) {
+  if (report.drift?.blockedReason !== undefined) {
+    parts.push('established exports blocked');
+  } else if (report.drift?.stale) {
     parts.push('drift detected');
   }
   return `Result: FAIL (${parts.join(', ')})`;

package/src/draft.ts

@@ -0,0 +1,22 @@
+import { basename } from 'node:path';
+
+export const DRAFT_FILE_PREFIX = '_draft.';
+export const DRAFT_FILE_SEGMENT = '.draft.';
+
+const DRAFT_TRAILING_SEGMENT = /\.draft(?=\.[^.]+$)/;
+
+export const isDraftMarkedFile = (filePath: string): boolean => {
+  const fileName = basename(filePath);
+  return (
+    fileName.startsWith(DRAFT_FILE_PREFIX) ||
+    fileName.includes(DRAFT_FILE_SEGMENT)
+  );
+};
+
+export const stripDraftFileMarkers = (fileName: string): string => {
+  if (fileName.startsWith(DRAFT_FILE_PREFIX)) {
+    return fileName.slice(DRAFT_FILE_PREFIX.length);
+  }
+
+  return fileName.replace(DRAFT_TRAILING_SEGMENT, '');
+};