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

package/src/rules/no-legacy-cli-alias-export.ts

@@ -0,0 +1,247 @@
+/**
+ * Flags leftover legacy app-module CLI alias exports removed in TRL-1207.
+ *
+ * Before the surfaces-overlay cutover, apps published CLI alias maps through
+ * a module-level export named `cliAliases` or `trailsCliAliases`. TRL-1207 is
+ * a hard cutover: app-owned CLI bindings now live in a
+ * `surfaceOverlay({ cli: { ... } })` envelope inside the app module's
+ * `trailsOverlays` array export, and the legacy export convention was
+ * deleted. This rule makes a leftover legacy export an error so stale app
+ * modules get a fix-forward diagnostic instead of silently losing their
+ * bindings.
+ *
+ * Detection is AST-scoped and export-shaped:
+ *
+ *   - `export const cliAliases = { ... }` (also `let`/`var`, destructured
+ *     bindings, and function/class declarations) is flagged.
+ *   - `export { cliAliases }` and `export { whatever as trailsCliAliases }`
+ *     specifiers are flagged, including re-export statements such as
+ *     `export { trailsCliAliases } from './app.js'`.
+ *   - A non-exported local `const cliAliases = ...` is legal and never
+ *     flagged, and the identifiers appearing only in strings or comments do
+ *     not match because the rule inspects export bindings, not raw text.
+ */
+
+import {
+  getNodeArgument,
+  getNodeBodyStatements,
+  getNodeDeclaration,
+  getNodeDeclarations,
+  getNodeElements,
+  getNodeExported,
+  getNodeExportKind,
+  getNodeId,
+  getNodeLeft,
+  getNodeProperties,
+  getNodeSpecifiers,
+  getNodeValueNode,
+  getStringValue,
+  identifierName,
+  isStringLiteral,
+  offsetToLine,
+  parse,
+} from './ast.js';
+import type { AstNode } from './ast.js';
+import type { WardenDiagnostic, WardenFix, WardenRule } from './types.js';
+
+const RULE_NAME = 'no-legacy-cli-alias-export';
+
+/** Legacy app-module CLI alias export names removed in TRL-1207. */
+const LEGACY_CLI_ALIAS_EXPORT_NAMES: ReadonlySet<string> = new Set([
+  'cliAliases',
+  'trailsCliAliases',
+]);
+
+/** Declaration node types that only propagate types, never value bindings. */
+const TYPE_ONLY_DECLARATION_TYPES: ReadonlySet<string> = new Set([
+  'TSInterfaceDeclaration',
+  'TSTypeAliasDeclaration',
+]);
+
+interface ExportedBinding {
+  readonly name: string;
+  readonly start: number;
+}
+
+/** Exported name of a specifier: identifier or string-literal alias. */
+const exportedSpecifierName = (node: AstNode | undefined): string | null =>
+  identifierName(node) ??
+  (node && isStringLiteral(node) ? getStringValue(node) : null);
+
+/**
+ * Expand one binding-pattern node into legacy-named bindings, pushing child
+ * patterns onto the worklist. Destructured exports such as
+ * `export const { cliAliases } = mod` still introduce a module-level exported
+ * value binding, so patterns cannot be skipped.
+ */
+const visitBindingPatternNode = (
+  node: AstNode,
+  into: ExportedBinding[],
+  worklist: AstNode[]
+): void => {
+  const name = identifierName(node);
+  if (name !== null) {
+    if (LEGACY_CLI_ALIAS_EXPORT_NAMES.has(name)) {
+      into.push({ name, start: node.start });
+    }
+    return;
+  }
+  if (node.type === 'AssignmentPattern') {
+    const left = getNodeLeft(node);
+    if (left) {
+      worklist.push(left);
+    }
+    return;
+  }
+  if (node.type === 'RestElement') {
+    const argument = getNodeArgument(node);
+    if (argument) {
+      worklist.push(argument);
+    }
+    return;
+  }
+  if (node.type === 'ObjectPattern') {
+    for (const property of getNodeProperties(node)) {
+      const value = getNodeValueNode(property) ?? getNodeArgument(property);
+      if (value) {
+        worklist.push(value);
+      }
+    }
+    return;
+  }
+  if (node.type === 'ArrayPattern') {
+    for (const element of getNodeElements(node)) {
+      if (element) {
+        worklist.push(element);
+      }
+    }
+  }
+};
+
+const collectLegacyPatternBindings = (
+  pattern: AstNode | undefined,
+  into: ExportedBinding[]
+): void => {
+  if (!pattern) {
+    return;
+  }
+  const worklist: AstNode[] = [pattern];
+  while (worklist.length > 0) {
+    const node = worklist.pop();
+    if (node) {
+      visitBindingPatternNode(node, into, worklist);
+    }
+  }
+};
+
+const collectLegacyDeclarationBindings = (
+  declaration: AstNode
+): readonly ExportedBinding[] => {
+  if (TYPE_ONLY_DECLARATION_TYPES.has(declaration.type)) {
+    return [];
+  }
+  const bindings: ExportedBinding[] = [];
+  if (declaration.type === 'VariableDeclaration') {
+    for (const declarator of getNodeDeclarations(declaration)) {
+      collectLegacyPatternBindings(getNodeId(declarator), bindings);
+    }
+    return bindings;
+  }
+  const name = identifierName(getNodeId(declaration));
+  if (name !== null && LEGACY_CLI_ALIAS_EXPORT_NAMES.has(name)) {
+    bindings.push({ name, start: declaration.start });
+  }
+  return bindings;
+};
+
+const collectLegacySpecifierBindings = (
+  statement: AstNode
+): readonly ExportedBinding[] => {
+  const bindings: ExportedBinding[] = [];
+  for (const specifier of getNodeSpecifiers(statement)) {
+    if (
+      specifier.type !== 'ExportSpecifier' ||
+      getNodeExportKind(specifier) === 'type'
+    ) {
+      continue;
+    }
+    const name = exportedSpecifierName(getNodeExported(specifier));
+    if (name !== null && LEGACY_CLI_ALIAS_EXPORT_NAMES.has(name)) {
+      bindings.push({ name, start: specifier.start });
+    }
+  }
+  return bindings;
+};
+
+const collectLegacyExportBindings = (
+  ast: AstNode
+): readonly ExportedBinding[] => {
+  const bindings: ExportedBinding[] = [];
+  for (const statement of getNodeBodyStatements(ast)) {
+    if (
+      statement.type !== 'ExportNamedDeclaration' ||
+      getNodeExportKind(statement) === 'type'
+    ) {
+      continue;
+    }
+    const declaration = getNodeDeclaration(statement);
+    if (declaration) {
+      bindings.push(...collectLegacyDeclarationBindings(declaration));
+      continue;
+    }
+    bindings.push(...collectLegacySpecifierBindings(statement));
+  }
+  return bindings;
+};
+
+const buildMessage = (name: string): string =>
+  `Legacy CLI alias export '${name}' was removed in the TRL-1207 surfaces-overlay cutover. Wrap the alias map into surfaceOverlay({ cli: { ... } }) from @ontrails/core inside the module's trailsOverlays array export.`;
+
+/**
+ * Build the fix metadata for a legacy CLI alias export finding.
+ *
+ * The rewrite is an export restructure, not a rename, so there is no
+ * mechanical single-span replacement: the fix carries no edits and Warden
+ * never applies it. Downstream, the `export-restructure` fix class routes the
+ * finding to the Regrade `export-restructure:cli-aliases` class (TRL-1210),
+ * which inverts the alias map into `surfaceOverlay({ cli: { ... } })`
+ * bindings inside the module's `trailsOverlays` array export.
+ */
+const buildFix = (name: string): WardenFix => ({
+  class: 'export-restructure',
+  reason: `Legacy CLI alias export '${name}' must be rewritten into a surfaceOverlay({ cli: { ... } }) entry inside the module's trailsOverlays array export; run the Regrade class export-restructure:cli-aliases (TRL-1210) to automate this restructure.`,
+  safety: 'review',
+});
+
+/**
+ * Flags exported bindings named `cliAliases` or `trailsCliAliases`, the
+ * legacy app-module CLI alias export convention deleted in TRL-1207.
+ */
+export const noLegacyCliAliasExport: WardenRule = {
+  check(sourceCode: string, filePath: string): readonly WardenDiagnostic[] {
+    if (
+      !(
+        sourceCode.includes('cliAliases') ||
+        sourceCode.includes('trailsCliAliases')
+      )
+    ) {
+      return [];
+    }
+    const ast = parse(filePath, sourceCode);
+    if (!ast) {
+      return [];
+    }
+    return collectLegacyExportBindings(ast).map((binding) => ({
+      filePath,
+      fix: buildFix(binding.name),
+      line: offsetToLine(sourceCode, binding.start),
+      message: buildMessage(binding.name),
+      rule: RULE_NAME,
+      severity: 'error',
+    }));
+  },
+  description:
+    'Disallow the legacy app-module CLI alias exports (cliAliases, trailsCliAliases) removed in the TRL-1207 surfaces-overlay cutover.',
+  name: RULE_NAME,
+  severity: 'error',
+};

package/src/rules/no-retired-cross-vocabulary.ts

@@ -8,17 +8,25 @@
  */
 import { resolve, sep } from 'node:path';
 
+import { requireGovernedVocabularyTransition } from './retired-vocabulary.js';
 import type { WardenDiagnostic, WardenFix, WardenRule } from './types.js';
 
 const RULE_NAME = 'no-retired-cross-vocabulary';
 
-const SAFE_REWRITES = [
-  { from: 'ctx.cross', to: 'ctx.compose' },
-  { from: 'crossInput', to: 'composeInput' },
-  { from: 'crosses', to: 'composes' },
-] as const;
+const CROSS_COMPOSE_TRANSITION =
+  requireGovernedVocabularyTransition('cross-compose');
 
-const REVIEW_TERMS = ['Cross', 'cross'] as const;
+if (CROSS_COMPOSE_TRANSITION.target.kind !== 'single') {
+  throw new Error('cross-compose transition must have a single target.');
+}
+
+const COMPOSE_TARGET = CROSS_COMPOSE_TRANSITION.target.to;
+
+const SAFE_REWRITES = Object.entries(
+  CROSS_COMPOSE_TRANSITION.safeRewriteForms
+).map(([from, to]) => ({ from, to }));
+
+const REVIEW_TERMS = CROSS_COMPOSE_TRANSITION.reviewForms;
 
 const IDENTIFIER_CHAR = /[$0-9A-Z_a-z]/u;
 
@@ -28,6 +36,8 @@ const ALLOWED_PATH_SUFFIXES: readonly string[] = [
   '/docs/adr/0049-composition-is-compose-not-cross.md',
   '/packages/warden/src/rules/no-retired-cross-vocabulary.ts',
   '/packages/warden/src/rules/metadata.ts',
+  '/packages/warden/src/rules/retired-vocabulary.ts',
+  '/packages/warden/src/trails/governed-symbol-residue.trail.ts',
   '/packages/warden/src/trails/no-retired-cross-vocabulary.trail.ts',
   '/scripts/vocab-cutover-rewrite.ts',
 ];
@@ -40,7 +50,7 @@ interface SafeRewriteMatch {
 
 interface ReviewMatch {
   readonly index: number;
-  readonly term: (typeof REVIEW_TERMS)[number];
+  readonly term: string;
 }
 
 const normalizePath = (filePath: string): string =>
@@ -150,7 +160,7 @@ const safeFix = (match: SafeRewriteMatch): WardenFix => ({
 
 const reviewFix = (term: string): WardenFix => ({
   class: 'term-rewrite',
-  reason: `Retired composition vocabulary '${term}' appears in a larger or ambiguous form. Review before migrating to compose vocabulary.`,
+  reason: `Retired composition vocabulary '${term}' appears in a larger or ambiguous form. Review before migrating to ${COMPOSE_TARGET} vocabulary.`,
   safety: 'review',
 });
 
@@ -158,7 +168,7 @@ const safeMessage = (match: SafeRewriteMatch): string =>
   `Retired composition vocabulary '${match.from}' should be '${match.to}' after the beta.19 compose cutover.`;
 
 const reviewMessage = (term: string): string =>
-  `Retired composition vocabulary '${term}' needs review before migrating to compose vocabulary.`;
+  `Retired composition vocabulary '${term}' needs review before migrating to ${COMPOSE_TARGET} vocabulary.`;
 
 export const noRetiredCrossVocabulary: WardenRule = {
   check(sourceCode: string, filePath: string): readonly WardenDiagnostic[] {

package/src/rules/public-export-example-coverage.ts

@@ -113,6 +113,11 @@ export const PUBLIC_API_EXAMPLE_TARGETS: readonly PublicApiPackageTarget[] = [
     minimumExports: ['createApp', 'surface'],
     packageName: '@ontrails/hono',
   },
+  {
+    indexPath: 'adapters/cloudflare/src/index.ts',
+    minimumExports: ['createWorkersHandler', 'cloudflareKv'],
+    packageName: '@ontrails/cloudflare',
+  },
 ] as const;
 
 export interface ResolvedPublicApiTarget extends PublicApiPackageTarget {

package/src/rules/registry-names.ts

@@ -16,10 +16,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';
@@ -30,6 +32,7 @@ import { missingReconcile } from './missing-reconcile.js';
 import { missingVisibility } from './missing-visibility.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';
@@ -58,8 +61,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,
@@ -94,12 +99,14 @@ export const registeredRuleNames: readonly string[] = [
   deadInternalTrail.name,
   deadPublicTrail.name,
   deprecationWithoutGuidance.name,
+  duplicateExportedSymbol.name,
   duplicatePublicContract.name,
   draftFileMarking.name,
   draftVisibleDebt.name,
   errorMappingCompleteness.name,
   exampleValid.name,
   firesDeclarations.name,
+  governedSymbolResidue.name,
   forkWithoutPreservedBlaze.name,
   implementationReturnsResult.name,
   incompleteAccessorForStandardOp.name,
@@ -112,6 +119,7 @@ export const registeredRuleNames: readonly string[] = [
   missingVisibility.name,
   noDevPermitInSource.name,
   noDestructuredCompose.name,
+  noLegacyCliAliasExport.name,
   noLegacyLayerImports.name,
   noDirectImplementationCall.name,
   noNativeErrorResult.name,
@@ -141,8 +149,10 @@ export const registeredRuleNames: readonly string[] = [
   scheduledDestroyIntent.name,
   signalGraphCoaching.name,
   staticResourceAccessorPreference.name,
-  surfaceFacetCoherence.name,
+  surfaceOverlayCoherence.name,
+  surfaceTrailheadCoherence.name,
   trailForkCoaching.name,
+  trailheadOverrideDivergence.name,
   unmaterializedActivationSource.name,
   unreachableDetourShadowing.name,
   validDetourContract.name,