@ontrails/warden 1.0.0-beta.30 → 1.0.0-beta.39

package/src/command.ts

@@ -12,8 +12,10 @@ import type {
   CliFlagValueAlias,
   CliFlagValueAliasDeclaration,
 } from '@ontrails/cli';
+import { resolveTrailsOverlays } from '@ontrails/adapter-kit';
 import type { Topo } from '@ontrails/core';
 import { AmbiguousError, NotFoundError } from '@ontrails/core';
+import type { TopoGraphOverlayRegistration } from '@ontrails/topographer';
 import {
   loadTrailsConfigValue,
   resolveTrailsProjectRoot,
@@ -26,6 +28,7 @@ import type {
   WardenDraftsMode,
   WardenFailOn,
   WardenFormat,
+  WardenScope,
   WardenLockMode,
 } from './config.js';
 import {
@@ -57,6 +60,7 @@ interface MutableWardenConfigLayer {
   drafts?: WardenDraftsMode | undefined;
   failOn?: WardenFailOn | undefined;
   format?: WardenFormat | undefined;
+  scope?: WardenScope | undefined;
   lock?: WardenLockMode | undefined;
   noLockMutation?: boolean | undefined;
 }
@@ -95,6 +99,12 @@ const splitApps = (value: string): readonly string[] =>
     .map((entry) => entry.trim())
     .filter((entry) => entry.length > 0);
 
+const splitCommaDelimitedValues = (value: string): readonly string[] =>
+  value
+    .split(',')
+    .map((entry) => entry.trim())
+    .filter((entry) => entry.length > 0);
+
 const isAllowedValue = <T extends string>(
   value: string,
   allowed: readonly T[]
@@ -248,6 +258,7 @@ const parseTokens = (
         'no-lock-mutation': { type: 'boolean' },
         'pre-push': { type: 'boolean' },
         'root-dir': { type: 'string' },
+        'scope-exclude': { multiple: true, type: 'string' },
         strict: { type: 'boolean' },
         ...valueAliasParseOptions,
       },
@@ -397,6 +408,19 @@ const applyCommandOption = (
     state.configPath = value;
     return;
   }
+  if (token.name === 'scope-exclude') {
+    if (value === undefined) {
+      state.diagnostics.push(
+        diagnostic({ message: '--scope-exclude requires a path glob.' })
+      );
+      return;
+    }
+    const existing = state.cli.scope?.exclude ?? [];
+    state.cli.scope = {
+      exclude: [...existing, ...splitCommaDelimitedValues(value)],
+    };
+    return;
+  }
   if (token.name === 'fix') {
     state.fix = true;
     return;
@@ -660,12 +684,22 @@ const resolveNamedAppModulePath = (
     : resolveFilesystemModulePath(rootDir, matched);
 };
 
-const importTopoFromModulePath = async (modulePath: string): Promise<Topo> => {
+interface LoadedWardenTopoModule {
+  /** App-module overlay registrations read through the shared channel. */
+  readonly overlays?: readonly TopoGraphOverlayRegistration[] | undefined;
+  readonly topo: Topo;
+}
+
+const importTopoFromModulePath = async (
+  modulePath: string
+): Promise<LoadedWardenTopoModule> => {
   const loaded = (await import(pathToFileURL(modulePath).href)) as Record<
     string,
     unknown
   >;
-  return extractTopo(modulePath, loaded);
+  const topo = extractTopo(modulePath, loaded);
+  const overlays = resolveTrailsOverlays(loaded, modulePath);
+  return overlays === undefined ? { topo } : { overlays, topo };
 };
 
 const topoLoadDiagnostic = ({
@@ -737,9 +771,11 @@ export const resolveWardenTopoTargets = async ({
     for (const appName of apps) {
       try {
         const modulePath = resolveNamedAppModulePath(rootDir, appName);
+        const loaded = await importTopoFromModulePath(modulePath);
         topos.push({
           name: appName,
-          topo: await importTopoFromModulePath(modulePath),
+          overlays: loaded.overlays,
+          topo: loaded.topo,
         });
       } catch (error) {
         diagnostics.push(
@@ -756,10 +792,16 @@ export const resolveWardenTopoTargets = async ({
 
   try {
     const modulePath = resolveDiscoveredModulePath(rootDir);
-    const topo = await importTopoFromModulePath(modulePath);
+    const loaded = await importTopoFromModulePath(modulePath);
     return {
       diagnostics,
-      topos: [{ name: topo.name, topo }],
+      topos: [
+        {
+          name: loaded.topo.name,
+          overlays: loaded.overlays,
+          topo: loaded.topo,
+        },
+      ],
     };
   } catch (error) {
     if (error instanceof NotFoundError) {
@@ -821,6 +863,7 @@ const buildRunOptions = ({
     lock: cli.lock,
     noLockMutation: cli.noLockMutation,
     rootDir,
+    scope: cli.scope,
     topos,
   }),
   env,

package/src/config.ts

@@ -10,6 +10,13 @@ export const wardenDraftsValues = ['include', 'exclude', 'only'] as const;
 
 const appNameSchema = z.string().min(1);
 
+const wardenScopeSchema = z
+  .object({
+    exclude: z.array(z.string().min(1)).default([]),
+  })
+  .strict()
+  .default({ exclude: [] });
+
 const wardenConfigObjectSchema = z
   .object({
     apps: z.array(appNameSchema).min(1).optional(),
@@ -18,6 +25,7 @@ const wardenConfigObjectSchema = z
     failOn: z.enum(wardenFailOnValues).default('error'),
     format: z.enum(wardenFormatValues).default('summary'),
     lock: z.enum(wardenLockValues).default('auto'),
+    scope: wardenScopeSchema,
   })
   .strict();
 
@@ -31,6 +39,7 @@ export type WardenDepth = (typeof wardenDepthValues)[number];
 export type WardenDraftsMode = (typeof wardenDraftsValues)[number];
 export type WardenFailOn = (typeof wardenFailOnValues)[number];
 export type WardenFormat = (typeof wardenFormatValues)[number];
+export type WardenScope = z.output<typeof wardenScopeSchema>;
 export type WardenLockMode = (typeof wardenLockValues)[number];
 
 export interface WardenConfigLayer extends Partial<WardenConfig> {

package/src/drift.ts

@@ -15,14 +15,33 @@ import {
   ValidationError,
 } from '@ontrails/core';
 import {
+  collectTopoGraphOverlays,
   createTopoStore,
   deriveTopoGraph,
   deriveTopoGraphHash,
   isTopoArtifactRegenerationError,
   readLockManifest,
+  readTopoGraph,
   readTrailsLock,
 } from '@ontrails/topographer';
-import type { LockManifest } from '@ontrails/topographer';
+import type {
+  DeriveTopoGraphOptions,
+  LockManifest,
+  TopoGraphOverlays,
+} from '@ontrails/topographer';
+
+/**
+ * Derive options `checkDrift` accepts so the fresh comparison graph carries
+ * the same app-module overlays the committed lock embeds.
+ *
+ * @example
+ * ```ts
+ * import type { CheckDriftOptions } from '@ontrails/warden';
+ *
+ * const options: CheckDriftOptions = { overlays: lease.overlays };
+ * ```
+ */
+export type CheckDriftOptions = Pick<DeriveTopoGraphOptions, 'overlays'>;
 
 /**
  * Result of a drift check comparing committed trails.lock against the current state.
@@ -36,6 +55,12 @@ export interface DriftResult {
   readonly committedHash: string | null;
   /** Hash computed from the current trail topology */
   readonly currentHash: string;
+  /**
+   * Overlay namespaces whose committed facts differ from the freshly derived
+   * facts, sorted lexicographically. Present only when the lock is stale and
+   * the caller supplied a topo plus derive options.
+   */
+  readonly driftedOverlayNamespaces?: readonly string[] | undefined;
 }
 
 interface BlockedLockRead {
@@ -91,14 +116,89 @@ const isBlockedLockRead = (
 ): result is BlockedLockRead =>
   result !== null && 'kind' in result && result.kind === 'blocked-lock-read';
 
+/**
+ * Read the committed lock's embedded graph overlays, tolerating both the v4
+ * root `trails.lock` envelope and the legacy `.trails/` artifact layout.
+ */
+const readCommittedGraphOverlays = async (
+  rootDir: string
+): Promise<TopoGraphOverlays | undefined> => {
+  const committedGraph =
+    (await readTopoGraph({ dir: rootDir })) ??
+    (await readTopoGraph({ dir: deriveTrailsDir({ rootDir }) }));
+  return committedGraph?.overlays;
+};
+
+/**
+ * Name the overlay namespaces whose committed facts drifted from the freshly
+ * derived facts. Compares canonical JSON per namespace across the union of
+ * committed and current namespaces; returns a sorted list.
+ */
+const collectDriftedOverlayNamespaces = async (
+  rootDir: string,
+  topo: Topo,
+  options: CheckDriftOptions
+): Promise<readonly string[]> => {
+  let committed: TopoGraphOverlays | undefined;
+  try {
+    committed = await readCommittedGraphOverlays(rootDir);
+  } catch {
+    return [];
+  }
+  const current = collectTopoGraphOverlays(topo, options.overlays);
+  const namespaces = new Set([
+    ...Object.keys(committed ?? {}),
+    ...Object.keys(current ?? {}),
+  ]);
+  return [...namespaces]
+    .filter(
+      (namespace) =>
+        JSON.stringify(committed?.[namespace]) !==
+        JSON.stringify(current?.[namespace])
+    )
+    .toSorted();
+};
+
+/**
+ * Format a stale drift result into one human-readable sentence.
+ *
+ * Names the drifted overlay namespaces when the drift check identified them,
+ * and always points at `trails compile` as the remediation.
+ *
+ * @example
+ * ```ts
+ * import { staleDriftMessage } from './drift.js';
+ *
+ * staleDriftMessage({
+ *   committedHash: 'aaa',
+ *   currentHash: 'bbb',
+ *   driftedOverlayNamespaces: ['surfaces'],
+ *   stale: true,
+ * });
+ * // => 'trails.lock is stale — drifted overlay namespaces: surfaces (regenerate with `trails compile`)'
+ * ```
+ */
+export const staleDriftMessage = (drift: DriftResult): string => {
+  const namespaces = drift.driftedOverlayNamespaces;
+  const detail =
+    namespaces !== undefined && namespaces.length > 0
+      ? ` — drifted overlay namespaces: ${namespaces.join(', ')}`
+      : '';
+  return `trails.lock is stale${detail} (regenerate with \`trails compile\`)`;
+};
+
 /**
  * Check whether the committed trails.lock is stale compared to the current topology.
  *
  * When no topo is provided, returns a clean result (no drift detectable without runtime info).
+ * When a topo is provided, `options.overlays` carries the app-module overlay
+ * registrations so the fresh comparison graph embeds the same namespaced
+ * facts the compile path writes into the committed lock.
  */
 export const checkDrift = async (
   rootDir: string,
-  topo?: Topo | undefined
+  topo?: Topo | undefined,
+  options?: CheckDriftOptions | undefined
 ): Promise<DriftResult> => {
   try {
     const lockManifest = await readCommittedLockManifest(rootDir);
@@ -127,15 +227,24 @@ export const checkDrift = async (
     const currentHash =
       topo === undefined
         ? (readStoredHash() ?? 'unknown')
-        : deriveTopoGraphHash(deriveTopoGraph(topo));
+        : deriveTopoGraphHash(deriveTopoGraph(topo, options));
+    const stale =
+      topoArtifact !== null &&
+      currentHash !== 'unknown' &&
+      topoArtifact.sha256 !== currentHash;
+    const driftedOverlayNamespaces =
+      stale && topo !== undefined && options !== undefined
+        ? await collectDriftedOverlayNamespaces(rootDir, topo, options)
+        : undefined;
 
     return {
       committedHash: topoArtifact?.sha256 ?? null,
       currentHash,
-      stale:
-        topoArtifact !== null &&
-        currentHash !== 'unknown' &&
-        topoArtifact.sha256 !== currentHash,
+      ...(driftedOverlayNamespaces === undefined ||
+      driftedOverlayNamespaces.length === 0
+        ? {}
+        : { driftedOverlayNamespaces }),
+      stale,
     };
   } catch (error) {
     if (

package/src/fix.ts

@@ -95,16 +95,22 @@ export const applySafeFixesToSource = (
   const applied: WardenDiagnostic[] = [];
   const skipped: WardenDiagnostic[] = [];
   const edits: ResolvedEdit[] = [];
+  const seenEdits = new Set<string>();
 
   for (const diagnostic of diagnostics) {
     if (hasSafeFixEdits(diagnostic)) {
       applied.push(diagnostic);
       for (const edit of diagnostic.fix.edits) {
-        edits.push({
+        const resolvedEdit = {
           end: edit.end,
           replacement: edit.replacement,
           start: edit.start,
-        });
+        };
+        const key = `${String(resolvedEdit.start)}\0${String(resolvedEdit.end)}\0${resolvedEdit.replacement}`;
+        if (!seenEdits.has(key)) {
+          seenEdits.add(key);
+          edits.push(resolvedEdit);
+        }
       }
     } else {
       skipped.push(diagnostic);

package/src/formatters.ts

@@ -7,6 +7,7 @@
  */
 
 import type { WardenReport } from './cli.js';
+import { staleDriftMessage } from './drift.js';
 import type { WardenGuidanceLink, WardenSeverity } from './rules/types.js';
 
 /** Map warden severity to GitHub Actions annotation level. */
@@ -35,9 +36,7 @@ export const formatGitHubAnnotations = (report: WardenReport): string => {
   if (report.drift?.blockedReason !== undefined) {
     lines.push(`::error::drift: ${report.drift.blockedReason}`);
   } else if (report.drift?.stale) {
-    lines.push(
-      '::error::drift: trails.lock is stale (regenerate with `trails compile`)'
-    );
+    lines.push(`::error::drift: ${staleDriftMessage(report.drift)}`);
   }
 
   return lines.join('\n');
@@ -144,11 +143,7 @@ const driftSection = (drift: WardenReport['drift']): readonly string[] => {
   if (!drift?.stale) {
     return [];
   }
-  return [
-    '',
-    '### Drift',
-    '- trails.lock is stale (regenerate with `trails compile`)',
-  ];
+  return ['', '### Drift', `- ${staleDriftMessage(drift)}`];
 };
 
 /** Render safe-fix counts when a fix pass was requested. */

package/src/index.ts

@@ -14,10 +14,12 @@ export type {
   ProjectContext,
   TopoAwareWardenRule,
   WardenDiagnostic,
+  WardenExportedSymbolDefinition,
   WardenFix,
   WardenFixCapability,
   WardenFixClass,
   WardenFixEdit,
+  WardenFixScanTargets,
   WardenFixSafety,
   WardenGuidance,
   WardenGuidanceLink,
@@ -34,8 +36,21 @@ export type {
 // Rule registry
 export {
   builtinWardenRuleMetadata,
+  formatGovernedVocabularyTransitionGuide,
+  getGovernedVocabularyTransition,
+  governedVocabularyLiteralRenameSchema,
+  governedVocabularyPreserveRuleSchema,
+  governedVocabularyRegistrySchema,
+  governedVocabularyScopeSchema,
+  governedVocabularySymbolRenameSchema,
+  governedVocabularyTargetSchema,
+  governedVocabularyTransitionSchema,
+  governedVocabularyTransitionStatuses,
+  governedVocabularyTransitions,
   getWardenRuleMetadata,
   listWardenRuleMetadata,
+  listGovernedVocabularyTransitions,
+  requireGovernedVocabularyTransition,
   wardenFixClasses,
   wardenFixSafeties,
   wardenRuleConcerns,
@@ -45,6 +60,15 @@ export {
   wardenRules,
   wardenTopoRules,
 } from './rules/index.js';
+export type {
+  GovernedVocabularyLiteralRename,
+  GovernedVocabularyPreserveRule,
+  GovernedVocabularyScope,
+  GovernedVocabularySymbolRename,
+  GovernedVocabularyTarget,
+  GovernedVocabularyTransition,
+  GovernedVocabularyTransitionInput,
+} from './rules/index.js';
 
 // Rule-scoped cache controls for long-lived consumers (watch mode, LSPs).
 export { clearImplementationReturnsResultCache } from './rules/implementation-returns-result.js';
@@ -100,6 +124,7 @@ export type {
   WardenDraftsMode,
   WardenFailOn,
   WardenFormat,
+  WardenScope,
   WardenLockMode,
   EffectiveWardenConfig,
   ResolveWardenConfigOptions,
@@ -116,7 +141,7 @@ export {
 } from './formatters.js';
 
 // Drift detection
-export type { DriftResult } from './drift.js';
+export type { CheckDriftOptions, DriftResult } from './drift.js';
 export { checkDrift } from './drift.js';
 
 // Project-local rule loading
@@ -174,6 +199,7 @@ export {
   deadPublicTrailTrail,
   deprecationWithoutGuidanceTrail,
   diagnosticSchema,
+  duplicateExportedSymbolTrail,
   duplicatePublicContractTrail,
   draftFileMarkingTrail,
   draftVisibleDebtTrail,
@@ -181,6 +207,7 @@ export {
   exampleValidTrail,
   firesDeclarationsTrail,
   forkWithoutPreservedBlazeTrail,
+  governedSymbolResidueTrail,
   implementationReturnsResultTrail,
   incompleteAccessorForStandardOpTrail,
   incompleteCrudTrail,
@@ -193,6 +220,7 @@ export {
   noDevPermitInSourceTrail,
   noDestructuredComposeTrail,
   noDirectImplementationCallTrail,
+  noLegacyCliAliasExportTrail,
   noLegacyLayerImportsTrail,
   noNativeErrorResultTrail,
   noRedundantResultErrorWrapTrail,
@@ -224,8 +252,10 @@ export {
   scheduledDestroyIntentTrail,
   signalGraphCoachingTrail,
   staticResourceAccessorPreferenceTrail,
-  surfaceFacetCoherenceTrail,
+  surfaceOverlayCoherenceTrail,
+  surfaceTrailheadCoherenceTrail,
   trailForkCoachingTrail,
+  trailheadOverrideDivergenceTrail,
   unmaterializedActivationSourceTrail,
   topoAwareRuleInput,
   unreachableDetourShadowingTrail,