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

package/src/cli.ts

@@ -10,8 +10,24 @@ import { resolve } from 'node:path';
 import type { Topo } from '@ontrails/core';
 import { getContourReferences } from '@ontrails/core';
 
+import type {
+  EffectiveWardenConfig,
+  WardenConfigInput,
+  WardenConfigLayer,
+  WardenDepth,
+  WardenFailOn,
+  WardenFormat,
+  WardenLockMode,
+} from './config.js';
+import { resolveWardenConfig } from './config.js';
+import { isDraftMarkedFile } from './draft.js';
 import type { DriftResult } from './drift.js';
 import { checkDrift } from './drift.js';
+import {
+  collectProjectDocumentationImportResolutions,
+  collectProjectImportResolutions,
+  collectPublicWorkspaces,
+} from './project-context.js';
 import {
   collectContourDefinitionIds,
   collectContourReferenceTargetsByName,
@@ -27,27 +43,66 @@ import {
 } from './rules/ast.js';
 import { collectFileCrudCoverage } from './rules/incomplete-crud.js';
 import { wardenRules, wardenTopoRules } from './rules/index.js';
+import { getWardenRuleMetadata } from './rules/metadata.js';
 import type {
   ProjectAwareWardenRule,
   ProjectContext,
   TopoAwareWardenRule,
   WardenDiagnostic,
+  WardenGuidanceLink,
   WardenRule,
+  WardenRuleTier,
 } from './rules/types.js';
+import type { WardenImportResolution } from './resolve.js';
+
+/**
+ * Resolved topo input for Warden runs that govern multiple apps.
+ */
+export interface WardenTopoTarget {
+  /** Stable app/topo label used to tag topo-aware diagnostics. */
+  readonly name?: string | undefined;
+  /** Resolved topo module to inspect. */
+  readonly topo: Topo;
+}
 
 /**
- * Options for the warden CLI runner.
+ * Options for the shared Warden runner.
  */
-export interface WardenOptions {
+export interface WardenRunOptions {
   /** Root directory to scan for TypeScript files. Defaults to cwd. */
   readonly rootDir?: string | undefined;
+  /** Warden config section from `trails.config.ts`, if already loaded. */
+  readonly config?: WardenConfigInput | undefined;
+  /** CLI/config-layer app names carried through shared resolution. */
+  readonly apps?: readonly string[] | undefined;
+  /** Cumulative analysis depth for the final M1 surfaces. */
+  readonly depth?: WardenDepth | undefined;
+  /** Draft-state handling mode for final M1 surfaces. */
+  readonly drafts?: EffectiveWardenConfig['drafts'] | undefined;
+  /** Failure threshold used to compute `report.passed`. */
+  readonly failOn?: WardenFailOn | undefined;
+  /** Output format requested by the caller. */
+  readonly format?: WardenFormat | undefined;
+  /** Lockfile mode requested by the caller. */
+  readonly lock?: WardenLockMode | undefined;
+  /** Suppress lockfile mutation for CI/pre-push callers. */
+  readonly noLockMutation?: boolean | undefined;
+  /** Environment layer for config resolution. Pass `process.env` at process boundaries. */
+  readonly env?: Record<string, string | undefined> | undefined;
   /** Only run lint rules, skip drift detection */
   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 and unlocks the topo-aware rule dispatch path.
+   * Run a single Warden tier. Defaults to all lint tiers plus drift.
+   *
+   * Selecting a non-drift tier skips drift detection; selecting `drift` skips
+   * lint rule dispatch. `lintOnly` and `driftOnly` remain compatibility shims.
+   */
+  readonly tier?: WardenRuleTier | undefined;
+  /**
+   * App topology for drift detection. When provided, enables real topology
+   * drift comparison and unlocks the topo-aware rule dispatch path.
    *
    * @remarks
    * Topo-aware rules (both built-in `wardenTopoRules` and `extraTopoRules`)
@@ -56,6 +111,12 @@ export interface WardenOptions {
    * must pass `topo` explicitly.
    */
   readonly topo?: Topo | undefined;
+  /**
+   * Multiple resolved topos to govern in one invocation.
+   *
+   * Source/project rules run once; topo-aware rules run once per target.
+   */
+  readonly topos?: readonly WardenTopoTarget[] | undefined;
   /**
    * Extra topo-aware rules to run in addition to the built-in registry.
    *
@@ -66,6 +127,9 @@ export interface WardenOptions {
   readonly extraTopoRules?: readonly TopoAwareWardenRule[] | undefined;
 }
 
+/** Backwards-compatible name for older consumers. */
+export type WardenOptions = WardenRunOptions;
+
 /**
  * Result of a warden run.
  */
@@ -80,33 +144,138 @@ export interface WardenReport {
   readonly drift: DriftResult | null;
   /** Whether the warden run passed (no errors, no drift) */
   readonly passed: boolean;
+  /** Effective shared config consumed by this run. */
+  readonly effectiveConfig?: EffectiveWardenConfig | undefined;
+  /** Resolved topo/app labels governed by this run. */
+  readonly topoNames?: readonly string[] | undefined;
 }
 
 /**
- * Collect all .ts files under a directory, excluding node_modules, dist, and .git.
+ * Collect Warden scan targets under a directory, excluding generated and test
+ * surfaces that should not contribute most committed-source diagnostics.
  */
-const isSourceFile = (match: string): boolean =>
-  !match.endsWith('.d.ts') &&
-  !match.startsWith('node_modules/') &&
-  !match.startsWith('dist/') &&
-  !match.startsWith('.git/') &&
-  !match.includes('__tests__/') &&
-  !match.includes('__test__/') &&
-  !match.endsWith('.test.ts') &&
-  !match.endsWith('.spec.ts');
-
-const collectTsFiles = (dir: string): readonly string[] => {
+const isInfrastructureScanTarget = (match: string): boolean =>
+  match.endsWith('.d.ts') ||
+  match.startsWith('node_modules/') ||
+  match.startsWith('dist/') ||
+  match.startsWith('.git/');
+
+const isTestScanTarget = (match: string): boolean =>
+  match.includes('__tests__/') ||
+  match.includes('__test__/') ||
+  match.endsWith('.test.ts') ||
+  match.endsWith('.spec.ts');
+
+const isAllowedScanTarget = (match: string): boolean =>
+  !isInfrastructureScanTarget(match) && !isTestScanTarget(match);
+
+const isDevPermitTestScanTarget = (match: string): boolean =>
+  !isInfrastructureScanTarget(match) && isTestScanTarget(match);
+
+const collectFilesMatching = (
+  dir: string,
+  pattern: string,
+  dot = false
+): readonly string[] => {
+  const glob = new Bun.Glob(pattern);
+  let matches: IterableIterator<string>;
+  try {
+    matches = glob.scanSync({ cwd: dir, dot, onlyFiles: true });
+  } catch {
+    return [];
+  }
+
+  const files: string[] = [];
+  for (const match of matches) {
+    if (isAllowedScanTarget(match)) {
+      files.push(`${dir}/${match}`);
+    }
+  }
+  return files;
+};
+
+const collectTsFiles = (dir: string): readonly string[] =>
+  collectFilesMatching(dir, '**/*.ts');
+
+const draftModeIncludesFile = (
+  filePath: string,
+  drafts: EffectiveWardenConfig['drafts']
+): boolean => {
+  const isDraftFile = isDraftMarkedFile(filePath);
+  if (drafts === 'exclude') {
+    return !isDraftFile;
+  }
+  if (drafts === 'only') {
+    return isDraftFile;
+  }
+  return true;
+};
+
+const filterSourceFilesByDraftMode = (
+  sourceFiles: readonly SourceFile[],
+  drafts: EffectiveWardenConfig['drafts']
+): readonly SourceFile[] =>
+  drafts === 'include'
+    ? sourceFiles
+    : sourceFiles.filter((sourceFile) =>
+        draftModeIncludesFile(sourceFile.filePath, drafts)
+      );
+
+const collectDevPermitTestFiles = (dir: string): readonly string[] => {
   const glob = new Bun.Glob('**/*.ts');
   let matches: IterableIterator<string>;
   try {
-    matches = glob.scanSync({ cwd: dir, dot: false, onlyFiles: true });
+    matches = glob.scanSync({ cwd: dir, onlyFiles: true });
+  } catch {
+    return [];
+  }
+
+  const files: string[] = [];
+  for (const match of matches) {
+    if (isDevPermitTestScanTarget(match)) {
+      files.push(`${dir}/${match}`);
+    }
+  }
+  return files;
+};
+
+const collectTextScanFiles = (dir: string): readonly string[] => [
+  ...collectFilesMatching(dir, '**/*.sh', true),
+  ...collectFilesMatching(dir, '**/*.bash', true),
+  ...collectFilesMatching(dir, '**/*.zsh', true),
+  ...collectFilesMatching(dir, '**/*.yml', true),
+  ...collectFilesMatching(dir, '**/*.yaml', true),
+  ...collectFilesMatching(dir, '**/package.json', true),
+];
+
+const isDocumentationScanTarget = (match: string): boolean => {
+  if (match === 'README.md') {
+    return true;
+  }
+  if (/^(?:packages|adapters|apps)\/[^/]+\/README\.md$/.test(match)) {
+    return true;
+  }
+  return (
+    match.startsWith('docs/') &&
+    !match.startsWith('docs/adr/') &&
+    !match.startsWith('docs/migration/') &&
+    !match.startsWith('docs/releases/') &&
+    match.endsWith('.md')
+  );
+};
+
+const collectDocumentationFiles = (dir: string): readonly string[] => {
+  const glob = new Bun.Glob('**/*.md');
+  let matches: IterableIterator<string>;
+  try {
+    matches = glob.scanSync({ cwd: dir, onlyFiles: true });
   } catch {
     return [];
   }
 
   const files: string[] = [];
   for (const match of matches) {
-    if (isSourceFile(match)) {
+    if (isAllowedScanTarget(match) && isDocumentationScanTarget(match)) {
       files.push(`${dir}/${match}`);
     }
   }
@@ -115,6 +284,7 @@ const collectTsFiles = (dir: string): readonly string[] => {
 
 interface SourceFile {
   readonly filePath: string;
+  readonly kind: 'documentation' | 'text' | 'typescript';
   readonly sourceCode: string;
 }
 
@@ -127,7 +297,13 @@ interface MutableProjectContext {
   knownResourceIds: Set<string>;
   knownSignalIds: Set<string>;
   knownTrailIds: Set<string>;
+  importResolutionsByFile: Map<string, readonly WardenImportResolution[]>;
+  documentedImportResolutionsByFile: Map<
+    string,
+    readonly WardenImportResolution[]
+  >;
   onTargetSignalIds: Set<string>;
+  publicWorkspaces: ReturnType<typeof collectPublicWorkspaces>;
   reconcileTableIds: Set<string>;
   trailIntentsById: Map<string, 'destroy' | 'read' | 'write'>;
 }
@@ -137,11 +313,17 @@ const createMutableProjectContext = (): MutableProjectContext => ({
   crossTargetTrailIds: new Set<string>(),
   crudCoverageByEntity: new Map<string, Set<string>>(),
   crudTableIds: new Set<string>(),
+  documentedImportResolutionsByFile: new Map<
+    string,
+    readonly WardenImportResolution[]
+  >(),
+  importResolutionsByFile: new Map<string, readonly WardenImportResolution[]>(),
   knownContourIds: new Set<string>(),
   knownResourceIds: new Set<string>(),
   knownSignalIds: new Set<string>(),
   knownTrailIds: new Set<string>(),
   onTargetSignalIds: new Set<string>(),
+  publicWorkspaces: new Map(),
   reconcileTableIds: new Set<string>(),
   trailIntentsById: new Map<string, 'destroy' | 'read' | 'write'>(),
 });
@@ -192,9 +374,21 @@ const toProjectContext = (context: MutableProjectContext): ProjectContext => ({
   knownResourceIds: context.knownResourceIds,
   knownSignalIds: context.knownSignalIds,
   knownTrailIds: context.knownTrailIds,
+  ...(context.importResolutionsByFile.size > 0
+    ? { importResolutionsByFile: context.importResolutionsByFile }
+    : {}),
+  ...(context.documentedImportResolutionsByFile.size > 0
+    ? {
+        documentedImportResolutionsByFile:
+          context.documentedImportResolutionsByFile,
+      }
+    : {}),
   ...(context.onTargetSignalIds.size > 0
     ? { onTargetSignalIds: context.onTargetSignalIds }
     : {}),
+  ...(context.publicWorkspaces.size > 0
+    ? { publicWorkspaces: context.publicWorkspaces }
+    : {}),
   ...(context.reconcileTableIds.size > 0
     ? { reconcileTableIds: context.reconcileTableIds }
     : {}),
@@ -357,6 +551,43 @@ const loadSourceFiles = async (
     try {
       sourceFiles.push({
         filePath,
+        kind: 'typescript',
+        sourceCode: await Bun.file(filePath).text(),
+      });
+    } catch {
+      continue;
+    }
+  }
+
+  for (const filePath of collectTextScanFiles(rootDir)) {
+    try {
+      sourceFiles.push({
+        filePath,
+        kind: 'text',
+        sourceCode: await Bun.file(filePath).text(),
+      });
+    } catch {
+      continue;
+    }
+  }
+
+  for (const filePath of collectDocumentationFiles(rootDir)) {
+    try {
+      sourceFiles.push({
+        filePath,
+        kind: 'documentation',
+        sourceCode: await Bun.file(filePath).text(),
+      });
+    } catch {
+      continue;
+    }
+  }
+
+  for (const filePath of collectDevPermitTestFiles(rootDir)) {
+    try {
+      sourceFiles.push({
+        filePath,
+        kind: 'text',
         sourceCode: await Bun.file(filePath).text(),
       });
     } catch {
@@ -517,26 +748,70 @@ const collectFileContourReferences = (
   }
 };
 
+const collectFileImportResolutions = (
+  rootDir: string,
+  sourceFiles: readonly SourceFile[],
+  context: MutableProjectContext
+): void => {
+  const resolutionsByFile = collectProjectImportResolutions({
+    rootDir,
+    sourceFiles,
+  });
+  for (const [filePath, resolutions] of resolutionsByFile) {
+    context.importResolutionsByFile.set(filePath, resolutions);
+  }
+};
+
+const collectFileDocumentedImportResolutions = (
+  rootDir: string,
+  sourceFiles: readonly SourceFile[],
+  context: MutableProjectContext
+): void => {
+  const resolutionsByFile = collectProjectDocumentationImportResolutions({
+    rootDir,
+    sourceFiles,
+  });
+  for (const [filePath, resolutions] of resolutionsByFile) {
+    context.documentedImportResolutionsByFile.set(filePath, resolutions);
+  }
+};
+
 const buildProjectContext = (
   sourceFiles: readonly SourceFile[],
-  appTopo?: Topo | undefined
+  rootDir: string,
+  appTopos: readonly Topo[] = []
 ): ProjectContext => {
   const context = createMutableProjectContext();
+  const typeScriptSourceFiles = sourceFiles.filter(
+    (sourceFile) => sourceFile.kind === 'typescript'
+  );
+  const documentationSourceFiles = sourceFiles.filter(
+    (sourceFile) => sourceFile.kind === 'documentation'
+  );
+  context.publicWorkspaces = collectPublicWorkspaces(rootDir);
 
-  if (appTopo) {
-    collectTopoTrailContext(appTopo, context);
-    for (const sourceFile of sourceFiles) {
+  if (appTopos.length > 0) {
+    for (const appTopo of appTopos) {
+      collectTopoTrailContext(appTopo, context);
+    }
+    for (const sourceFile of typeScriptSourceFiles) {
       collectFileSupplementalProjectContext(sourceFile, context);
     }
   } else {
-    for (const sourceFile of sourceFiles) {
+    for (const sourceFile of typeScriptSourceFiles) {
       collectFileProjectContext(sourceFile, context);
     }
   }
 
-  for (const sourceFile of sourceFiles) {
+  for (const sourceFile of typeScriptSourceFiles) {
     collectFileContourReferences(sourceFile, context);
   }
+  collectFileImportResolutions(rootDir, typeScriptSourceFiles, context);
+  collectFileDocumentedImportResolutions(
+    rootDir,
+    documentationSourceFiles,
+    context
+  );
 
   return toProjectContext(context);
 };
@@ -544,6 +819,117 @@ const buildProjectContext = (
 const isProjectAwareRule = (rule: WardenRule): rule is ProjectAwareWardenRule =>
   'checkWithContext' in rule;
 
+const createOptionsDiagnostic = (message: string): WardenDiagnostic => ({
+  filePath: '<warden-options>',
+  line: 1,
+  message,
+  rule: 'warden-options',
+  severity: 'error',
+});
+
+interface WardenRuleSelector {
+  readonly depth?: WardenDepth | undefined;
+  readonly tier?: WardenRuleTier | undefined;
+}
+
+const depthIncludesTier = (
+  depth: WardenDepth,
+  tier: WardenRuleTier
+): boolean => {
+  switch (depth) {
+    case 'source': {
+      return tier === 'source-static';
+    }
+    case 'project': {
+      return tier === 'source-static' || tier === 'project-static';
+    }
+    case 'topo': {
+      return (
+        tier === 'source-static' ||
+        tier === 'project-static' ||
+        tier === 'topo-aware'
+      );
+    }
+    case 'all': {
+      return true;
+    }
+    default: {
+      return false;
+    }
+  }
+};
+
+const ruleMatchesTier = (
+  metadata: ReturnType<typeof getWardenRuleMetadata>,
+  tier: WardenRuleTier | undefined
+): boolean => {
+  if (!tier) {
+    return true;
+  }
+
+  if (!metadata) {
+    return false;
+  }
+
+  return tier === 'advisory'
+    ? metadata.scope === 'advisory'
+    : metadata.tier === tier;
+};
+
+const ruleMatchesDepth = (
+  metadata: ReturnType<typeof getWardenRuleMetadata>,
+  depth: WardenDepth | undefined
+): boolean => {
+  if (!depth) {
+    return true;
+  }
+
+  if (!metadata) {
+    return false;
+  }
+
+  if (metadata.scope === 'advisory') {
+    return depth === 'all';
+  }
+
+  return depthIncludesTier(depth, metadata.tier);
+};
+
+const isSelectedRule = (
+  rule: WardenRule | TopoAwareWardenRule,
+  selector: WardenRuleSelector
+): boolean => {
+  const metadata = getWardenRuleMetadata(rule);
+  return selector.tier
+    ? ruleMatchesTier(metadata, selector.tier)
+    : ruleMatchesDepth(metadata, selector.depth);
+};
+
+const isSelectedTopoRule = (
+  rule: TopoAwareWardenRule,
+  selector: WardenRuleSelector
+): boolean => {
+  const metadata = getWardenRuleMetadata(rule);
+  if (selector.tier) {
+    return metadata
+      ? ruleMatchesTier(metadata, selector.tier)
+      : selector.tier === 'topo-aware';
+  }
+
+  return metadata ? ruleMatchesDepth(metadata, selector.depth) : true;
+};
+
+const withDiagnosticGuidance = (
+  diagnostic: WardenDiagnostic
+): WardenDiagnostic => {
+  if (diagnostic.guidance !== undefined) {
+    return diagnostic;
+  }
+
+  const guidance = getWardenRuleMetadata(diagnostic.rule)?.guidance;
+  return guidance === undefined ? diagnostic : { ...diagnostic, guidance };
+};
+
 const topoRuleFailureDiagnostic = (
   rule: TopoAwareWardenRule,
   error: unknown
@@ -566,13 +952,14 @@ const topoRuleFailureDiagnostic = (
  */
 const lintTopo = async (
   appTopo: Topo,
-  extraTopoRules: readonly TopoAwareWardenRule[]
+  extraTopoRules: readonly TopoAwareWardenRule[],
+  selector: WardenRuleSelector
 ): Promise<readonly WardenDiagnostic[]> => {
   const diagnostics: WardenDiagnostic[] = [];
   const rules: readonly TopoAwareWardenRule[] = [
     ...wardenTopoRules.values(),
     ...extraTopoRules,
-  ];
+  ].filter((rule) => isSelectedTopoRule(rule, selector));
   for (const rule of rules) {
     try {
       diagnostics.push(...(await rule.checkTopo(appTopo)));
@@ -585,11 +972,31 @@ const lintTopo = async (
 
 const lintSourceFiles = (
   sourceFiles: readonly SourceFile[],
-  context: ProjectContext
+  context: ProjectContext,
+  selector: WardenRuleSelector
 ): readonly WardenDiagnostic[] => {
   const diagnostics: WardenDiagnostic[] = [];
   for (const sourceFile of sourceFiles) {
     for (const rule of wardenRules.values()) {
+      if (
+        sourceFile.kind === 'text' &&
+        rule.name !== 'no-dev-permit-in-source' &&
+        rule.name !== 'public-internal-deep-imports'
+      ) {
+        continue;
+      }
+
+      if (
+        sourceFile.kind === 'documentation' &&
+        rule.name !== 'public-internal-deep-imports'
+      ) {
+        continue;
+      }
+
+      if (!isSelectedRule(rule, selector)) {
+        continue;
+      }
+
       if (isProjectAwareRule(rule)) {
         diagnostics.push(
           ...rule.checkWithContext(
@@ -608,58 +1015,323 @@ const lintSourceFiles = (
   return diagnostics;
 };
 
+const tagTopoDiagnostic = (
+  diagnostic: WardenDiagnostic,
+  topoName: string | undefined
+): WardenDiagnostic =>
+  topoName === undefined ? diagnostic : { ...diagnostic, topoName };
+
+const lintTopoTargets = async (
+  topoTargets: readonly WardenTopoTarget[],
+  extraTopoRules: readonly TopoAwareWardenRule[],
+  selector: WardenRuleSelector,
+  tagDiagnostics: boolean
+): Promise<readonly WardenDiagnostic[]> => {
+  const diagnostics: WardenDiagnostic[] = [];
+
+  for (const target of topoTargets) {
+    const topoDiagnostics = await lintTopo(
+      target.topo,
+      extraTopoRules,
+      selector
+    );
+    const topoName = target.name ?? target.topo.name;
+    diagnostics.push(
+      ...(tagDiagnostics
+        ? topoDiagnostics.map((diagnostic) =>
+            tagTopoDiagnostic(diagnostic, topoName)
+          )
+        : topoDiagnostics)
+    );
+  }
+
+  return diagnostics;
+};
+
+const selectorIncludesTopoRules = (selector: WardenRuleSelector): boolean => {
+  if (selector.tier) {
+    return selector.tier === 'advisory';
+  }
+
+  return !selector.depth || depthIncludesTier(selector.depth, 'topo-aware');
+};
+
 /**
  * Lint all files against all warden rules.
  */
 const lintFiles = async (
   rootDir: string,
-  appTopo?: Topo | undefined,
-  extraTopoRules: readonly TopoAwareWardenRule[] = []
+  drafts: EffectiveWardenConfig['drafts'],
+  topoTargets: readonly WardenTopoTarget[],
+  extraTopoRules: readonly TopoAwareWardenRule[],
+  selector: WardenRuleSelector
 ): Promise<WardenDiagnostic[]> => {
-  const sourceFiles = await loadSourceFiles(rootDir);
-  const context = buildProjectContext(sourceFiles, appTopo);
+  if (selector.tier === 'topo-aware') {
+    return [
+      ...(await lintTopoTargets(topoTargets, extraTopoRules, selector, true)),
+    ];
+  }
+
+  const sourceFiles = filterSourceFilesByDraftMode(
+    await loadSourceFiles(rootDir),
+    drafts
+  );
+  const context = buildProjectContext(
+    sourceFiles,
+    rootDir,
+    topoTargets.map((target) => target.topo)
+  );
   const allDiagnostics: WardenDiagnostic[] = [
-    ...lintSourceFiles(sourceFiles, context),
+    ...lintSourceFiles(sourceFiles, context, selector),
   ];
 
-  if (appTopo) {
-    allDiagnostics.push(...(await lintTopo(appTopo, extraTopoRules)));
+  if (
+    topoTargets.length > 0 &&
+    (selector.tier === undefined || selector.tier === 'advisory') &&
+    selectorIncludesTopoRules(selector)
+  ) {
+    allDiagnostics.push(
+      ...(await lintTopoTargets(
+        topoTargets,
+        extraTopoRules,
+        selector,
+        topoTargets.length > 1
+      ))
+    );
   }
 
   return allDiagnostics;
 };
 
+const topoTargetsFromOptions = (
+  options: WardenRunOptions
+): readonly WardenTopoTarget[] => {
+  if (options.topos !== undefined && options.topos.length > 0) {
+    return options.topos;
+  }
+
+  return options.topo ? [{ name: options.topo.name, topo: options.topo }] : [];
+};
+
+const aggregateDriftHash = (
+  topoTargets: readonly WardenTopoTarget[],
+  driftResults: readonly DriftResult[]
+): string => {
+  const currentHashes = new Set(
+    driftResults.map((result) => result.currentHash)
+  );
+  const [onlyHash] = currentHashes;
+  if (currentHashes.size === 1 && onlyHash !== undefined) {
+    return onlyHash;
+  }
+
+  const payload = driftResults
+    .map((result, index) => {
+      const target = topoTargets[index];
+      return {
+        currentHash: result.currentHash,
+        topoName: target?.name ?? target?.topo.name ?? `topo-${String(index)}`,
+      };
+    })
+    .toSorted((left, right) => left.topoName.localeCompare(right.topoName));
+  const hasher = new Bun.CryptoHasher('sha256');
+  hasher.update(JSON.stringify(payload));
+  return hasher.digest('hex');
+};
+
+const describeTopoDriftHash = (
+  topoTargets: readonly WardenTopoTarget[],
+  driftResults: readonly DriftResult[]
+): string =>
+  driftResults
+    .map((result, index) => {
+      const target = topoTargets[index];
+      const topoName =
+        target?.name ?? target?.topo.name ?? `topo-${String(index)}`;
+      return `${topoName}=${result.committedHash ?? '<none>'}`;
+    })
+    .join(', ');
+
+const checkDriftForTopoTargets = async (
+  rootDir: string,
+  topoTargets: readonly WardenTopoTarget[]
+): Promise<DriftResult> => {
+  if (topoTargets.length <= 1) {
+    return checkDrift(rootDir, topoTargets[0]?.topo);
+  }
+
+  const driftResults = await Promise.all(
+    topoTargets.map((target) => checkDrift(rootDir, target.topo))
+  );
+  const committedHashes = new Set(
+    driftResults.map((result) => result.committedHash)
+  );
+  if (committedHashes.size > 1) {
+    return {
+      blockedReason: `multi-topo drift expected one committed trails.lock hash but found conflicting hashes: ${describeTopoDriftHash(topoTargets, driftResults)}`,
+      committedHash: null,
+      currentHash: 'blocked',
+      stale: true,
+    };
+  }
+  const committedHash = driftResults[0]?.committedHash ?? null;
+  const blockedReasons = driftResults.flatMap((result, index) => {
+    if (result.blockedReason === undefined) {
+      return [];
+    }
+    const target = topoTargets[index];
+    const topoName =
+      target?.name ?? target?.topo.name ?? `topo-${String(index)}`;
+    return [`${topoName}: ${result.blockedReason}`];
+  });
+
+  if (blockedReasons.length > 0) {
+    return {
+      blockedReason: blockedReasons.join('; '),
+      committedHash,
+      currentHash: 'blocked',
+      stale: true,
+    };
+  }
+
+  const currentHash = aggregateDriftHash(topoTargets, driftResults);
+  return {
+    committedHash,
+    currentHash,
+    stale: committedHash !== null && committedHash !== currentHash,
+  };
+};
+
+const shouldRunLint = (options: WardenRunOptions): boolean =>
+  options.tier ? options.tier !== 'drift' : !options.driftOnly;
+
+const shouldRunDrift = (
+  options: WardenRunOptions,
+  effectiveConfig: EffectiveWardenConfig
+): boolean => {
+  if (effectiveConfig.lock === 'skip') {
+    return false;
+  }
+
+  if (options.tier) {
+    return options.tier === 'drift';
+  }
+
+  if (options.lintOnly) {
+    return false;
+  }
+
+  return options.driftOnly || effectiveConfig.depth === 'all';
+};
+
+const reportPassed = ({
+  drift,
+  errorCount,
+  failOn,
+  warnCount,
+}: {
+  readonly drift: DriftResult | null;
+  readonly errorCount: number;
+  readonly failOn: WardenFailOn;
+  readonly warnCount: number;
+}): boolean =>
+  errorCount === 0 &&
+  (failOn === 'error' || warnCount === 0) &&
+  !(drift?.stale ?? false) &&
+  drift?.blockedReason === undefined;
+
+const buildCliConfigLayer = (options: WardenRunOptions): WardenConfigLayer => ({
+  ...(options.apps ? { apps: [...options.apps] } : {}),
+  ...(options.depth ? { depth: options.depth } : {}),
+  ...(options.drafts ? { drafts: options.drafts } : {}),
+  ...(options.failOn ? { failOn: options.failOn } : {}),
+  ...(options.format ? { format: options.format } : {}),
+  ...(options.lock ? { lock: options.lock } : {}),
+  ...(options.noLockMutation === undefined
+    ? {}
+    : { noLockMutation: options.noLockMutation }),
+});
+
 /**
  * Run all warden checks and return a structured report.
  */
 export const runWarden = async (
-  options: WardenOptions = {}
+  options: WardenRunOptions = {}
 ): Promise<WardenReport> => {
   const rootDir = resolve(options.rootDir ?? process.cwd());
-  const allDiagnostics = options.driftOnly
-    ? []
-    : await lintFiles(rootDir, options.topo, options.extraTopoRules ?? []);
-  const drift = options.lintOnly
-    ? null
-    : await checkDrift(rootDir, options.topo);
+  const { diagnostics: configDiagnostics, effectiveConfig } =
+    resolveWardenConfig({
+      cli: buildCliConfigLayer(options),
+      config: options.config,
+      env: options.env,
+    });
+  const optionDiagnostics =
+    !options.tier && options.lintOnly && options.driftOnly
+      ? [
+          createOptionsDiagnostic(
+            'lintOnly and driftOnly cannot both be true. Use tier to select a single Warden mode.'
+          ),
+        ]
+      : [];
+  const topoTargets = topoTargetsFromOptions(options);
+  const selector = {
+    depth: options.tier ? undefined : effectiveConfig.depth,
+    tier: options.tier,
+  } satisfies WardenRuleSelector;
+  const runLint = shouldRunLint(options);
+  const runDrift = shouldRunDrift(options, effectiveConfig);
+
+  const rawDiagnostics = [
+    ...configDiagnostics,
+    ...optionDiagnostics,
+    ...(runLint
+      ? await lintFiles(
+          rootDir,
+          effectiveConfig.drafts,
+          topoTargets,
+          options.extraTopoRules ?? [],
+          selector
+        )
+      : []),
+  ];
+  const allDiagnostics = rawDiagnostics.map(withDiagnosticGuidance);
+  const drift = runDrift
+    ? await checkDriftForTopoTargets(rootDir, topoTargets)
+    : null;
 
   const errorCount = allDiagnostics.filter(
     (d) => d.severity === 'error'
   ).length;
   const warnCount = allDiagnostics.filter((d) => d.severity === 'warn').length;
+  const topoNames =
+    topoTargets.length > 0
+      ? topoTargets.map((target) => target.name ?? target.topo.name)
+      : undefined;
 
   return {
     diagnostics: allDiagnostics,
     drift,
+    effectiveConfig,
     errorCount,
-    passed:
-      errorCount === 0 &&
-      !(drift?.stale ?? false) &&
-      drift?.blockedReason === undefined,
+    passed: reportPassed({
+      drift,
+      errorCount,
+      failOn: effectiveConfig.failOn,
+      warnCount,
+    }),
+    ...(topoNames === undefined ? {} : { topoNames }),
     warnCount,
   };
 };
 
+const formatPlainGuidanceLink = (link: WardenGuidanceLink): string => {
+  const target = link.path ?? link.url;
+  if (target === undefined || target === link.label) {
+    return link.label;
+  }
+  return `${link.label} (${target})`;
+};
+
 /**
  * Format the lint section of the report.
  */
@@ -677,6 +1349,25 @@ const formatLintSection = (report: WardenReport): string[] => {
     lines.push(
       `  ${d.filePath}:${String(d.line)}  [${prefix}] ${d.rule}  ${d.message}`
     );
+    if (d.guidance !== undefined) {
+      lines.push(`    Next: ${d.guidance.summary}`);
+      for (const [index, step] of (d.guidance.steps ?? []).entries()) {
+        lines.push(`    ${String(index + 1)}. ${step}`);
+      }
+      if (d.guidance.commands !== undefined) {
+        lines.push(
+          `    Commands: ${d.guidance.commands.map((cmd) => `\`${cmd}\``).join(', ')}`
+        );
+      }
+      if (d.guidance.docs !== undefined) {
+        lines.push(
+          `    Docs: ${d.guidance.docs.map(formatPlainGuidanceLink).join(', ')}`
+        );
+      }
+      if (d.guidance.relatedRules !== undefined) {
+        lines.push(`    Related: ${d.guidance.relatedRules.join(', ')}`);
+      }
+    }
   }
 
   return lines;
@@ -693,7 +1384,7 @@ const formatDriftSection = (drift: DriftResult | null): string[] => {
     return [`Drift: blocked (${drift.blockedReason})`, ''];
   }
   const label = drift.stale
-    ? 'Drift: trails.lock is stale (regenerate with `trails topo export`)'
+    ? 'Drift: trails.lock is stale (regenerate with `trails topo compile`)'
     : 'Drift: clean';
   return [label, ''];
 };
@@ -709,6 +1400,9 @@ const formatResultLine = (report: WardenReport): string => {
   if (report.errorCount > 0) {
     parts.push(`${report.errorCount} errors`);
   }
+  if (report.warnCount > 0 && report.effectiveConfig?.failOn === 'warning') {
+    parts.push(`${report.warnCount} warnings`);
+  }
   if (report.drift?.blockedReason !== undefined) {
     parts.push('established exports blocked');
   } else if (report.drift?.stale) {