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

package/src/rules/governed-symbol-residue.ts

@@ -0,0 +1,131 @@
+import {
+  identifierName,
+  offsetToLine,
+  parseWithDiagnostics,
+  walk,
+} from './ast.js';
+import type { AstNode } from './ast.js';
+import { listGovernedVocabularyTransitions } from './retired-vocabulary.js';
+import type {
+  GovernedVocabularySymbolRename,
+  GovernedVocabularyTransition,
+} from './retired-vocabulary.js';
+import type { WardenDiagnostic, WardenFix, WardenRule } from './types.js';
+
+const RULE_NAME = 'governed-symbol-residue';
+
+const ACTIVE_STATUSES = new Set<GovernedVocabularyTransition['status']>([
+  'active',
+  'complete',
+]);
+
+const FIX_OWNED_TRANSITION_IDS = new Set(['cross-compose']);
+
+const ALLOWED_SOURCE_PATH_SUFFIXES = [
+  '/packages/warden/src/rules/governed-symbol-residue.ts',
+  '/packages/warden/src/rules/retired-vocabulary.ts',
+] as const;
+
+const normalizePath = (filePath: string): string =>
+  filePath.replaceAll('\\', '/');
+
+const isAllowedSourcePath = (filePath: string): boolean =>
+  ALLOWED_SOURCE_PATH_SUFFIXES.some((suffix) =>
+    normalizePath(filePath).endsWith(suffix)
+  );
+
+const activeSymbolRenames = (): readonly GovernedVocabularySymbolRename[] =>
+  listGovernedVocabularyTransitions()
+    .filter(
+      (transition) =>
+        ACTIVE_STATUSES.has(transition.status) &&
+        !FIX_OWNED_TRANSITION_IDS.has(transition.id)
+    )
+    .flatMap((transition) => transition.symbolRenames);
+
+const renameBySourceSymbol = (): ReadonlyMap<
+  string,
+  GovernedVocabularySymbolRename
+> =>
+  new Map(
+    activeSymbolRenames().map((rename) => [rename.from, rename] as const)
+  );
+
+const safeFixFor = (
+  sourceCode: string,
+  node: AstNode,
+  rename: GovernedVocabularySymbolRename
+): WardenFix | undefined => {
+  const end = node.start + rename.from.length;
+  if (sourceCode.slice(node.start, end) !== rename.from) {
+    return undefined;
+  }
+  return {
+    class: 'term-rewrite',
+    edits: [
+      {
+        end,
+        replacement: rename.to,
+        start: node.start,
+      },
+    ],
+    reason: `Retired governed symbol '${rename.from}' has a mechanical replacement '${rename.to}'.`,
+    safety: 'safe',
+  };
+};
+
+const diagnosticFor = (
+  sourceCode: string,
+  filePath: string,
+  node: AstNode,
+  rename: GovernedVocabularySymbolRename
+): WardenDiagnostic => {
+  const fix = safeFixFor(sourceCode, node, rename);
+  return {
+    filePath,
+    ...(fix === undefined ? {} : { fix }),
+    line: offsetToLine(sourceCode, node.start),
+    message: `Retired governed symbol '${rename.from}' should migrate to '${rename.to}'.`,
+    rule: RULE_NAME,
+    severity: 'error',
+  };
+};
+
+export const governedSymbolResidue: WardenRule = {
+  check(sourceCode: string, filePath: string): readonly WardenDiagnostic[] {
+    if (isAllowedSourcePath(filePath)) {
+      return [];
+    }
+
+    const renames = renameBySourceSymbol();
+    if (renames.size === 0) {
+      return [];
+    }
+
+    const parsed = parseWithDiagnostics(filePath, sourceCode);
+    if (!parsed.ast || parsed.diagnostics.length > 0) {
+      return [];
+    }
+
+    const diagnostics: WardenDiagnostic[] = [];
+    walk(parsed.ast, (node) => {
+      const name = identifierName(node);
+      if (name === null) {
+        return;
+      }
+
+      const rename = renames.get(name);
+      if (rename === undefined) {
+        return;
+      }
+
+      diagnostics.push(diagnosticFor(sourceCode, filePath, node, rename));
+    });
+
+    return diagnostics;
+  },
+  description:
+    'Detect active governed vocabulary symbols that remain in source code.',
+  name: RULE_NAME,
+  severity: 'error',
+};

package/src/rules/index.ts

@@ -8,10 +8,12 @@ import { deadInternalTrail } from './dead-internal-trail.js';
 import { deadPublicTrail } from './dead-public-trail.js';
 import { draftFileMarking } from './draft-file-marking.js';
 import { draftVisibleDebt } from './draft-visible-debt.js';
+import { duplicateExportedSymbol } from './duplicate-exported-symbol.js';
 import { duplicatePublicContract } from './duplicate-public-contract.js';
 import { errorMappingCompleteness } from './error-mapping-completeness.js';
 import { exampleValid } from './example-valid.js';
 import { firesDeclarations } from './fires-declarations.js';
+import { governedSymbolResidue } from './governed-symbol-residue.js';
 import { implementationReturnsResult } from './implementation-returns-result.js';
 import { incompleteAccessorForStandardOp } from './incomplete-accessor-for-standard-op.js';
 import { incompleteCrud } from './incomplete-crud.js';
@@ -22,6 +24,7 @@ import { missingVisibility } from './missing-visibility.js';
 import { missingReconcile } from './missing-reconcile.js';
 import { noDevPermitInSource } from './no-dev-permit-in-source.js';
 import { noDestructuredCompose } from './no-destructured-compose.js';
+import { noLegacyCliAliasExport } from './no-legacy-cli-alias-export.js';
 import { noLegacyLayerImports } from './no-legacy-layer-imports.js';
 import { noDirectImplementationCall } from './no-direct-implementation-call.js';
 import { noNativeErrorResult } from './no-native-error-result.js';
@@ -50,8 +53,10 @@ import { resourceMockCoverage } from './resource-mock-coverage.js';
 import { scheduledDestroyIntent } from './scheduled-destroy-intent.js';
 import { signalGraphCoaching } from './signal-graph-coaching.js';
 import { staticResourceAccessorPreference } from './static-resource-accessor-preference.js';
-import { surfaceFacetCoherence } from './surface-facet-coherence.js';
+import { surfaceOverlayCoherence } from './surface-overlay-coherence.js';
+import { surfaceTrailheadCoherence } from './surface-trailhead-coherence.js';
 import { trailForkCoaching } from './trail-fork-coaching.js';
+import { trailheadOverrideDivergence } from './trailhead-override-divergence.js';
 import {
   forkWithoutPreservedBlaze,
   markerSchemaUnsupported,
@@ -81,6 +86,7 @@ export type {
   WardenFixSafety,
   WardenGuidance,
   WardenGuidanceLink,
+  WardenExportedSymbolDefinition,
   WardenRuleLifecycle,
   WardenRuleLifecycleState,
   WardenRuleConcern,
@@ -95,6 +101,30 @@ export type {
   WardenSeverity,
 } from './types.js';
 
+export {
+  formatGovernedVocabularyTransitionGuide,
+  getGovernedVocabularyTransition,
+  governedVocabularyLiteralRenameSchema,
+  governedVocabularyPreserveRuleSchema,
+  governedVocabularyRegistrySchema,
+  governedVocabularyScopeSchema,
+  governedVocabularySymbolRenameSchema,
+  governedVocabularyTargetSchema,
+  governedVocabularyTransitionSchema,
+  governedVocabularyTransitionStatuses,
+  governedVocabularyTransitions,
+  listGovernedVocabularyTransitions,
+  requireGovernedVocabularyTransition,
+} from './retired-vocabulary.js';
+export type {
+  GovernedVocabularyLiteralRename,
+  GovernedVocabularyPreserveRule,
+  GovernedVocabularyScope,
+  GovernedVocabularySymbolRename,
+  GovernedVocabularyTarget,
+  GovernedVocabularyTransition,
+  GovernedVocabularyTransitionInput,
+} from './retired-vocabulary.js';
 export {
   builtinWardenRuleMetadata,
   getWardenRuleMetadata,
@@ -119,10 +149,12 @@ export { deadInternalTrail } from './dead-internal-trail.js';
 export { deadPublicTrail } from './dead-public-trail.js';
 export { draftFileMarking } from './draft-file-marking.js';
 export { draftVisibleDebt } from './draft-visible-debt.js';
+export { duplicateExportedSymbol } from './duplicate-exported-symbol.js';
 export { duplicatePublicContract } from './duplicate-public-contract.js';
 export { errorMappingCompleteness } from './error-mapping-completeness.js';
 export { exampleValid } from './example-valid.js';
 export { firesDeclarations } from './fires-declarations.js';
+export { governedSymbolResidue } from './governed-symbol-residue.js';
 export { incompleteAccessorForStandardOp } from './incomplete-accessor-for-standard-op.js';
 export { incompleteCrud } from './incomplete-crud.js';
 export { intentPropagation } from './intent-propagation.js';
@@ -133,6 +165,7 @@ export { missingReconcile } from './missing-reconcile.js';
 export { onReferencesExist } from './on-references-exist.js';
 export { noDevPermitInSource } from './no-dev-permit-in-source.js';
 export { noDestructuredCompose } from './no-destructured-compose.js';
+export { noLegacyCliAliasExport } from './no-legacy-cli-alias-export.js';
 export { noLegacyLayerImports } from './no-legacy-layer-imports.js';
 export { noDirectImplementationCall } from './no-direct-implementation-call.js';
 export { noNativeErrorResult } from './no-native-error-result.js';
@@ -159,8 +192,10 @@ export { resourceMockCoverage } from './resource-mock-coverage.js';
 export { scheduledDestroyIntent } from './scheduled-destroy-intent.js';
 export { signalGraphCoaching } from './signal-graph-coaching.js';
 export { staticResourceAccessorPreference } from './static-resource-accessor-preference.js';
-export { surfaceFacetCoherence } from './surface-facet-coherence.js';
+export { surfaceOverlayCoherence } from './surface-overlay-coherence.js';
+export { surfaceTrailheadCoherence } from './surface-trailhead-coherence.js';
 export { trailForkCoaching } from './trail-fork-coaching.js';
+export { trailheadOverrideDivergence } from './trailhead-override-divergence.js';
 export {
   forkWithoutPreservedBlaze,
   markerSchemaUnsupported,
@@ -192,9 +227,11 @@ export const wardenRules: ReadonlyMap<string, WardenRule> = new Map<
   [deadPublicTrail.name, deadPublicTrail],
   [draftFileMarking.name, draftFileMarking],
   [draftVisibleDebt.name, draftVisibleDebt],
+  [duplicateExportedSymbol.name, duplicateExportedSymbol],
   [errorMappingCompleteness.name, errorMappingCompleteness],
   [exampleValid.name, exampleValid],
   [firesDeclarations.name, firesDeclarations],
+  [governedSymbolResidue.name, governedSymbolResidue],
   [incompleteCrud.name, incompleteCrud],
   [intentPropagation.name, intentPropagation],
   [layerFieldNameDrift.name, layerFieldNameDrift],
@@ -214,12 +251,14 @@ export const wardenRules: ReadonlyMap<string, WardenRule> = new Map<
   [resourceMockCoverage.name, resourceMockCoverage],
   [preferSchemaInference.name, preferSchemaInference],
   [staticResourceAccessorPreference.name, staticResourceAccessorPreference],
-  [surfaceFacetCoherence.name, surfaceFacetCoherence],
+  [surfaceTrailheadCoherence.name, surfaceTrailheadCoherence],
   [trailForkCoaching.name, trailForkCoaching],
+  [trailheadOverrideDivergence.name, trailheadOverrideDivergence],
   [validDescribeRefs.name, validDescribeRefs],
   [noDevPermitInSource.name, noDevPermitInSource],
   [noDestructuredCompose.name, noDestructuredCompose],
   [noDirectImplementationCall.name, noDirectImplementationCall],
+  [noLegacyCliAliasExport.name, noLegacyCliAliasExport],
   [noLegacyLayerImports.name, noLegacyLayerImports],
   [noNativeErrorResult.name, noNativeErrorResult],
   [noRedundantResultErrorWrap.name, noRedundantResultErrorWrap],
@@ -261,6 +300,7 @@ export const wardenTopoRules: ReadonlyMap<string, TopoAwareWardenRule> =
     [publicUnionOutputDiscriminants.name, publicUnionOutputDiscriminants],
     [scheduledDestroyIntent.name, scheduledDestroyIntent],
     [signalGraphCoaching.name, signalGraphCoaching],
+    [surfaceOverlayCoherence.name, surfaceOverlayCoherence],
     [unmaterializedActivationSource.name, unmaterializedActivationSource],
     [validDetourContract.name, validDetourContract],
     [deprecationWithoutGuidance.name, deprecationWithoutGuidance],

package/src/rules/metadata.ts

@@ -44,6 +44,7 @@ export const wardenRuleLifecycleStates = [
 ] as const satisfies readonly WardenRuleLifecycleState[];
 
 export const wardenFixClasses = [
+  'export-restructure',
   'term-rewrite',
 ] as const satisfies readonly WardenFixClass[];
 
@@ -76,10 +77,12 @@ const concernByRuleName: Partial<Record<string, WardenRuleConcern>> = {
   'deprecation-without-guidance': 'lifecycle',
   'draft-file-marking': 'lifecycle',
   'draft-visible-debt': 'lifecycle',
+  'duplicate-exported-symbol': 'general',
   'duplicate-public-contract': 'meta',
   'error-mapping-completeness': 'results',
   'fires-declarations': 'signals',
   'fork-without-preserved-blaze': 'lifecycle',
+  'governed-symbol-residue': 'lifecycle',
   'implementation-returns-result': 'results',
   'intent-propagation': 'composition',
   'library-projection-coherence': 'meta',
@@ -89,6 +92,7 @@ const concernByRuleName: Partial<Record<string, WardenRuleConcern>> = {
   'no-destructured-compose': 'composition',
   'no-dev-permit-in-source': 'permits',
   'no-direct-implementation-call': 'composition',
+  'no-legacy-cli-alias-export': 'general',
   'no-native-error-result': 'results',
   'no-redundant-result-error-wrap': 'results',
   'no-retired-cross-vocabulary': 'composition',
@@ -109,8 +113,10 @@ const concernByRuleName: Partial<Record<string, WardenRuleConcern>> = {
   'scheduled-destroy-intent': 'lifecycle',
   'signal-graph-coaching': 'signals',
   'static-resource-accessor-preference': 'resources',
-  'surface-facet-coherence': 'meta',
+  'surface-overlay-coherence': 'meta',
+  'surface-trailhead-coherence': 'meta',
   'trail-fork-coaching': 'meta',
+  'trailhead-override-divergence': 'meta',
   'unmaterialized-activation-source': 'lifecycle',
   'valid-detour-contract': 'results',
   'version-gap': 'lifecycle',
@@ -220,6 +226,26 @@ const builtinWardenRuleMetadataInput = {
     invariant: 'Draft-authored IDs remain visible debt.',
     tier: 'source-static',
   },
+  'duplicate-exported-symbol': {
+    ...durableRepoLocal,
+    guidance: {
+      docs: [
+        {
+          label: 'Package ownership',
+          path: 'docs/contributing/package-ownership.md',
+        },
+      ],
+      relatedRules: [
+        'resolved-import-boundary',
+        'public-internal-deep-imports',
+      ],
+      summary:
+        'Keep exported symbol ownership from drifting across first-party packages.',
+    },
+    invariant:
+      'First-party packages should not define the same exported symbol name in parallel.',
+    tier: 'project-static',
+  },
   'duplicate-public-contract': {
     ...durableExternal,
     guidance: {
@@ -265,6 +291,13 @@ const builtinWardenRuleMetadataInput = {
     invariant: 'Fork version entries preserve their historical blaze.',
     tier: 'source-static',
   },
+  'governed-symbol-residue': {
+    ...durableExternal,
+    fix: { class: 'term-rewrite', safety: 'safe' },
+    invariant:
+      'Active governed vocabulary symbol renames do not leave retired identifiers in source.',
+    tier: 'source-static',
+  },
   'implementation-returns-result': {
     ...durableExternal,
     invariant: 'Blazes return Result values.',
@@ -300,7 +333,10 @@ const builtinWardenRuleMetadataInput = {
           path: 'docs/adr/drafts/20260612-library-surface-and-compiler.md',
         },
       ],
-      relatedRules: ['cli-command-route-coherence', 'surface-facet-coherence'],
+      relatedRules: [
+        'cli-command-route-coherence',
+        'surface-trailhead-coherence',
+      ],
       steps: [
         'Rename one source trail or add an explicit library export override before generating a package.',
         'Keep serialized library projection exports attached to existing trail IDs.',
@@ -346,6 +382,18 @@ const builtinWardenRuleMetadataInput = {
     invariant: 'Application code composes trails through ctx.compose().',
     tier: 'source-static',
   },
+  'no-legacy-cli-alias-export': {
+    fix: { class: 'export-restructure', safety: 'review' },
+    invariant:
+      'Legacy app-module CLI alias exports (cliAliases, trailsCliAliases) removed in the TRL-1207 surfaces-overlay cutover do not reappear in committed source.',
+    lifecycle: {
+      retireWhen:
+        'TRL-1207 surfaces-overlay migration window closes and supported apps have moved CLI bindings into surfaceOverlay entries in their trailsOverlays exports.',
+      state: 'temporary',
+    },
+    scope: 'external',
+    tier: 'source-static',
+  },
   'no-legacy-layer-imports': {
     fix: { class: 'term-rewrite', safety: 'review' },
     invariant:
@@ -605,19 +653,38 @@ const builtinWardenRuleMetadataInput = {
     scope: 'advisory',
     tier: 'source-static',
   },
-  'surface-facet-coherence': {
+  'surface-overlay-coherence': {
+    ...durableExternal,
+    guidance: {
+      relatedRules: [
+        'cli-command-route-coherence',
+        'surface-trailhead-coherence',
+      ],
+      steps: [
+        'Point every binding selector at an existing trail id or dotted trail-id glob.',
+        'Narrow overlapping grouped bindings so each trail has one grouped owner per surface.',
+        'Rename bindings that shadow canonical CLI command paths or derived MCP tool names.',
+      ],
+      summary:
+        'Keep surface overlay bindings pointed at real trails without shadowing canonical surface entries.',
+    },
+    invariant:
+      'Surface overlay bindings resolve to real trails without group overlap or canonical-entry shadowing.',
+    tier: 'topo-aware',
+  },
+  'surface-trailhead-coherence': {
     ...durableExternal,
     guidance: {
       docs: [
         {
           label: 'Trailheads ADR',
-          path: 'docs/adr/drafts/20260603-surface-facets-shape-dense-topos.md',
+          path: 'docs/adr/drafts/20260603-surface-trailheads-shape-dense-topos.md',
         },
       ],
       steps: [
-        'Keep facet selectors as explicit string literals or literal arrays when possible.',
-        'Ensure each public trail belongs to one facet owner.',
-        'Record explicit visibility-widening acceptance and stable-description metadata when a facet intentionally widens visibility.',
+        'Keep trailhead selectors as explicit string literals or literal arrays when possible.',
+        'Ensure each public trail belongs to one trailhead owner.',
+        'Record explicit visibility-widening acceptance and stable-description metadata when a trailhead intentionally widens visibility.',
       ],
       summary:
         'Keep trailhead maps reviewable before they reach MCP projection.',
@@ -639,12 +706,15 @@ const builtinWardenRuleMetadataInput = {
           path: 'docs/surfaces/surface-accommodations.md',
         },
       ],
-      relatedRules: ['surface-facet-coherence', 'cli-command-route-coherence'],
+      relatedRules: [
+        'surface-trailhead-coherence',
+        'cli-command-route-coherence',
+      ],
       steps: [
         'Check the semantic fork boundary: intent, permits, outputs, errors, lifecycle, and side effects.',
         'Check the structural fork boundary: selected trail identity stays visible instead of hiding behind action vocabulary.',
         'Split real capability forks into distinct trails or a composing trail.',
-        'Use a facet only when one surface entry needs to group multiple trails while preserving selected member identity.',
+        'Use a trailhead only when one surface entry needs to group multiple trails while preserving selected member identity.',
       ],
       summary:
         'Keep surface accommodations from hiding several capabilities behind one branching trail input.',
@@ -654,6 +724,30 @@ const builtinWardenRuleMetadataInput = {
     scope: 'advisory',
     tier: 'source-static',
   },
+  'trailhead-override-divergence': {
+    ...durableExternal,
+    guidance: {
+      docs: [
+        {
+          label: 'Surface Accommodations',
+          path: 'docs/surfaces/surface-accommodations.md',
+        },
+      ],
+      relatedRules: [
+        'surface-overlay-coherence',
+        'surface-trailhead-coherence',
+      ],
+      steps: [
+        'Author the grouped entry as an mcp list binding in surfaceOverlay({ mcp }) so the lock carries the default.',
+        'Keep the call-site trailhead map aligned with the authored binding names and member selectors, or rename one side to make the intentional divergence explicit.',
+      ],
+      summary:
+        'Keep call-site MCP trailhead overrides aligned with the authored overlay default.',
+    },
+    invariant:
+      'Call-site MCP trailhead maps stay aligned with authored surfaces overlay mcp bindings.',
+    tier: 'project-static',
+  },
   'unmaterialized-activation-source': {
     ...durableExternal,
     invariant:
@@ -715,7 +809,7 @@ const builtinWardenRuleMetadataInput = {
 
 export type BuiltinWardenRuleName = keyof typeof builtinWardenRuleMetadataInput;
 
-const withFacetDefaults = (
+const withRuleDefaults = (
   name: string,
   metadata: BuiltinWardenRuleMetadataInput
 ): WardenRuleMetadata => ({
@@ -727,7 +821,7 @@ const withFacetDefaults = (
 export const builtinWardenRuleMetadata = Object.fromEntries(
   Object.entries(builtinWardenRuleMetadataInput).map(([name, metadata]) => [
     name,
-    withFacetDefaults(name, metadata),
+    withRuleDefaults(name, metadata),
   ])
 ) as Readonly<Record<BuiltinWardenRuleName, WardenRuleMetadata>>;