@ontrails/warden 1.0.0-beta.23 → 1.0.0-beta.29

package/src/rules/index.ts

@@ -1,11 +1,14 @@
 import { activationOrphan } from './activation-orphan.js';
+import { cliCommandRouteCoherence } from './cli-command-route-coherence.js';
 import { circularRefs } from './circular-refs.js';
 import { contourExists } from './contour-exists.js';
 import { contextNoSurfaceTypes } from './context-no-surface-types.js';
 import { composesDeclarations } from './composes-declarations.js';
 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 { 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';
@@ -14,6 +17,7 @@ import { incompleteAccessorForStandardOp } from './incomplete-accessor-for-stand
 import { incompleteCrud } from './incomplete-crud.js';
 import { intentPropagation } from './intent-propagation.js';
 import { layerFieldNameDrift } from './layer-field-name-drift.js';
+import { libraryProjectionCoherence } from './library-projection-coherence.js';
 import { missingVisibility } from './missing-visibility.js';
 import { missingReconcile } from './missing-reconcile.js';
 import { noDevPermitInSource } from './no-dev-permit-in-source.js';
@@ -47,6 +51,7 @@ 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 { trailForkCoaching } from './trail-fork-coaching.js';
 import {
   forkWithoutPreservedBlaze,
   markerSchemaUnsupported,
@@ -103,20 +108,24 @@ export {
 export type { BuiltinWardenRuleName } from './metadata.js';
 
 export { activationOrphan } from './activation-orphan.js';
+export { cliCommandRouteCoherence } from './cli-command-route-coherence.js';
 export { noThrowInImplementation } from './no-throw-in-implementation.js';
 export { circularRefs } from './circular-refs.js';
 export { contourExists } from './contour-exists.js';
 export { contextNoSurfaceTypes } from './context-no-surface-types.js';
 export { composesDeclarations } from './composes-declarations.js';
 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 { 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 { incompleteAccessorForStandardOp } from './incomplete-accessor-for-standard-op.js';
 export { incompleteCrud } from './incomplete-crud.js';
 export { intentPropagation } from './intent-propagation.js';
+export { libraryProjectionCoherence } from './library-projection-coherence.js';
 export { layerFieldNameDrift } from './layer-field-name-drift.js';
 export { missingVisibility } from './missing-visibility.js';
 export { missingReconcile } from './missing-reconcile.js';
@@ -150,6 +159,7 @@ 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 { trailForkCoaching } from './trail-fork-coaching.js';
 export {
   forkWithoutPreservedBlaze,
   markerSchemaUnsupported,
@@ -178,6 +188,7 @@ export const wardenRules: ReadonlyMap<string, WardenRule> = new Map<
   [contextNoSurfaceTypes.name, contextNoSurfaceTypes],
   [composesDeclarations.name, composesDeclarations],
   [deadInternalTrail.name, deadInternalTrail],
+  [deadPublicTrail.name, deadPublicTrail],
   [draftFileMarking.name, draftFileMarking],
   [draftVisibleDebt.name, draftVisibleDebt],
   [errorMappingCompleteness.name, errorMappingCompleteness],
@@ -203,6 +214,7 @@ export const wardenRules: ReadonlyMap<string, WardenRule> = new Map<
   [preferSchemaInference.name, preferSchemaInference],
   [staticResourceAccessorPreference.name, staticResourceAccessorPreference],
   [surfaceFacetCoherence.name, surfaceFacetCoherence],
+  [trailForkCoaching.name, trailForkCoaching],
   [validDescribeRefs.name, validDescribeRefs],
   [noDevPermitInSource.name, noDevPermitInSource],
   [noDestructuredCompose.name, noDestructuredCompose],
@@ -239,7 +251,10 @@ export const wardenRules: ReadonlyMap<string, WardenRule> = new Map<
 export const wardenTopoRules: ReadonlyMap<string, TopoAwareWardenRule> =
   new Map<string, TopoAwareWardenRule>([
     [activationOrphan.name, activationOrphan],
+    [cliCommandRouteCoherence.name, cliCommandRouteCoherence],
+    [duplicatePublicContract.name, duplicatePublicContract],
     [incompleteAccessorForStandardOp.name, incompleteAccessorForStandardOp],
+    [libraryProjectionCoherence.name, libraryProjectionCoherence],
     [permitGovernance.name, permitGovernance],
     [publicOutputSchema.name, publicOutputSchema],
     [publicUnionOutputDiscriminants.name, publicUnionOutputDiscriminants],

package/src/rules/layer-field-name-drift.ts

@@ -1,6 +1,14 @@
 import { sep } from 'node:path';
 
-import { identifierName, offsetToLine, parse, walk } from './ast.js';
+import {
+  getNodeCallee,
+  getNodeId,
+  getNodeInit,
+  identifierName,
+  offsetToLine,
+  parse,
+  walk,
+} from './ast.js';
 import type { AstNode } from './ast.js';
 import type { WardenDiagnostic, WardenRule } from './types.js';
 
@@ -37,7 +45,7 @@ const isSetConstruction = (node: AstNode | undefined): boolean => {
   if (node?.type !== 'NewExpression') {
     return false;
   }
-  const { callee } = node as unknown as { callee?: AstNode };
+  const callee = getNodeCallee(node);
   return identifierName(callee) === 'Set';
 };
 
@@ -73,10 +81,8 @@ export const layerFieldNameDrift: WardenRule = {
       if (node.type !== 'VariableDeclarator') {
         return;
       }
-      const { id, init } = node as unknown as {
-        id?: AstNode;
-        init?: AstNode;
-      };
+      const id = getNodeId(node);
+      const init = getNodeInit(node);
       const name = identifierName(id);
       if (
         name &&

package/src/rules/library-projection-coherence.ts

@@ -0,0 +1,100 @@
+import { deriveTopoGraph } from '@ontrails/topographer';
+import type {
+  TopoGraph,
+  TopoGraphLibraryProjection,
+} from '@ontrails/topographer';
+
+import type { TopoAwareWardenRule, WardenDiagnostic } from './types.js';
+
+const RULE_NAME = 'library-projection-coherence';
+const TOPO_FILE = '<topo>';
+
+const resolveGraph = (
+  topo: Parameters<TopoAwareWardenRule['checkTopo']>[0],
+  graph: TopoGraph | undefined
+): TopoGraph => graph ?? deriveTopoGraph(topo);
+
+const renderTrailIds = (trailIds: readonly string[]): string =>
+  trailIds
+    .toSorted((left, right) => left.localeCompare(right))
+    .map((trailId) => `"${trailId}"`)
+    .join(', ');
+
+const collisionDiagnostic = (
+  exportName: string,
+  trailIds: readonly string[]
+): WardenDiagnostic => ({
+  filePath: TOPO_FILE,
+  line: 1,
+  message: `Library projection export collision on "${exportName}": trails ${renderTrailIds(trailIds)} derive the same package export. Rename one trail or add a library export override before materializing the generated package.`,
+  rule: RULE_NAME,
+  severity: 'error',
+});
+
+const missingTargetDiagnostic = (
+  exportName: string,
+  trailId: string
+): WardenDiagnostic => ({
+  filePath: TOPO_FILE,
+  line: 1,
+  message: `Library projection export "${exportName}" targets unknown trail "${trailId}". Resolved library exports must stay attached to existing trail contracts.`,
+  rule: RULE_NAME,
+  severity: 'error',
+});
+
+const duplicateExportDiagnostic = (
+  exportName: string,
+  trailIds: readonly string[]
+): WardenDiagnostic => ({
+  filePath: TOPO_FILE,
+  line: 1,
+  message: `Library projection contains duplicate export "${exportName}" for trails ${renderTrailIds(trailIds)}. The resolved projection should record the collision and keep only one emitted export.`,
+  rule: RULE_NAME,
+  severity: 'error',
+});
+
+const collectDuplicateExportDiagnostics = (
+  projection: TopoGraphLibraryProjection
+): readonly WardenDiagnostic[] => {
+  const trailIdsByExport = new Map<string, string[]>();
+  for (const entry of projection.exports) {
+    const trailIds = trailIdsByExport.get(entry.exportName) ?? [];
+    trailIds.push(entry.trailId);
+    trailIdsByExport.set(entry.exportName, trailIds);
+  }
+  return [...trailIdsByExport.entries()]
+    .filter(([, trailIds]) => trailIds.length > 1)
+    .map(([exportName, trailIds]) =>
+      duplicateExportDiagnostic(exportName, trailIds)
+    );
+};
+
+const collectMissingTargetDiagnostics = (
+  projection: TopoGraphLibraryProjection,
+  knownTrailIds: ReadonlySet<string>
+): readonly WardenDiagnostic[] =>
+  projection.exports
+    .filter((entry) => !knownTrailIds.has(entry.trailId))
+    .map((entry) => missingTargetDiagnostic(entry.exportName, entry.trailId));
+
+export const libraryProjectionCoherence: TopoAwareWardenRule = {
+  checkTopo(topo, context) {
+    const graph = resolveGraph(topo, context?.graph);
+    if (!graph.library) {
+      return [];
+    }
+
+    const knownTrailIds = new Set(topo.trails.keys());
+    return [
+      ...graph.library.collisions.map((collision) =>
+        collisionDiagnostic(collision.exportName, collision.trailIds)
+      ),
+      ...collectDuplicateExportDiagnostics(graph.library),
+      ...collectMissingTargetDiagnostics(graph.library, knownTrailIds),
+    ];
+  },
+  description:
+    'Ensure resolved library projection exports are collision-free and target existing trails.',
+  name: RULE_NAME,
+  severity: 'error',
+};

package/src/rules/metadata.ts

@@ -68,17 +68,21 @@ const depthByTier = {
 
 const concernByRuleName: Partial<Record<string, WardenRuleConcern>> = {
   'activation-orphan': 'signals',
+  'cli-command-route-coherence': 'meta',
   'composes-declarations': 'composition',
   'context-no-surface-types': 'composition',
   'dead-internal-trail': 'composition',
+  'dead-public-trail': 'composition',
   'deprecation-without-guidance': 'lifecycle',
   'draft-file-marking': 'lifecycle',
   'draft-visible-debt': 'lifecycle',
+  'duplicate-public-contract': 'meta',
   'error-mapping-completeness': 'results',
   'fires-declarations': 'signals',
   'fork-without-preserved-blaze': 'lifecycle',
   'implementation-returns-result': 'results',
   'intent-propagation': 'composition',
+  'library-projection-coherence': 'meta',
   'marker-schema-unsupported': 'lifecycle',
   'missing-reconcile': 'resources',
   'missing-visibility': 'composition',
@@ -106,6 +110,7 @@ const concernByRuleName: Partial<Record<string, WardenRuleConcern>> = {
   'signal-graph-coaching': 'signals',
   'static-resource-accessor-preference': 'resources',
   'surface-facet-coherence': 'meta',
+  'trail-fork-coaching': 'meta',
   'unmaterialized-activation-source': 'lifecycle',
   'valid-detour-contract': 'results',
   'version-gap': 'lifecycle',
@@ -151,6 +156,23 @@ const builtinWardenRuleMetadataInput = {
     invariant: 'Contour reference graphs must be acyclic.',
     tier: 'project-static',
   },
+  'cli-command-route-coherence': {
+    ...durableExternal,
+    guidance: {
+      docs: [
+        {
+          label: 'CLI command routes ADR',
+          path: 'docs/adr/drafts/20260613-cli-command-routes.md',
+        },
+      ],
+      relatedRules: ['webhook-route-collision'],
+      summary:
+        'Keep every CLI command route and alias normalized into one trail contract.',
+    },
+    invariant:
+      'CLI command routes and aliases resolve to one coherent trail contract.',
+    tier: 'topo-aware',
+  },
   'composes-declarations': {
     ...durableExternal,
     invariant: 'Declared composes stay aligned with ctx.compose() usage.',
@@ -171,6 +193,17 @@ const builtinWardenRuleMetadataInput = {
     invariant: 'Internal trails should be reachable through declared composes.',
     tier: 'project-static',
   },
+  'dead-public-trail': {
+    ...durableExternal,
+    guidance: {
+      relatedRules: ['dead-internal-trail', 'duplicate-public-contract'],
+      summary:
+        'Anchor exported public trails in a topo, composition edge, or activation source.',
+    },
+    invariant:
+      'Exported public trails are anchored in configured app topos, composition, or activation.',
+    tier: 'project-static',
+  },
   'deprecation-without-guidance': {
     ...durableExternal,
     invariant:
@@ -187,6 +220,23 @@ const builtinWardenRuleMetadataInput = {
     invariant: 'Draft-authored IDs remain visible debt.',
     tier: 'source-static',
   },
+  'duplicate-public-contract': {
+    ...durableExternal,
+    guidance: {
+      docs: [
+        {
+          label: 'Surface accommodations',
+          path: 'docs/surfaces/surface-accommodations.md',
+        },
+      ],
+      relatedRules: ['cli-command-route-coherence', 'trail-fork-coaching'],
+      summary:
+        'Keep duplicate public contract facts from drifting into separate capabilities.',
+    },
+    invariant:
+      'Public surface trails should not expose duplicate normalized contract facts.',
+    tier: 'topo-aware',
+  },
   'error-mapping-completeness': {
     ...durableExtension,
     invariant: 'Registered surface error mappers cover every error category.',
@@ -241,6 +291,28 @@ const builtinWardenRuleMetadataInput = {
       'Layer input field reserved names are shared across surface projections.',
     tier: 'source-static',
   },
+  'library-projection-coherence': {
+    ...durableExternal,
+    guidance: {
+      docs: [
+        {
+          label: 'Library Surface ADR',
+          path: 'docs/adr/drafts/20260612-library-surface-and-compiler.md',
+        },
+      ],
+      relatedRules: ['cli-command-route-coherence', 'surface-facet-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.',
+        'Run the generated-package smoke after repairing projection drift.',
+      ],
+      summary:
+        'Keep resolved library projection exports collision-free and attached to one trail contract.',
+    },
+    invariant:
+      'Resolved library projection exports are collision-free and target existing trails.',
+    tier: 'topo-aware',
+  },
   'marker-schema-unsupported': {
     ...durableExternal,
     invariant:
@@ -554,6 +626,34 @@ const builtinWardenRuleMetadataInput = {
       'Surface facet maps avoid selector overlap, hidden visibility widening, and drift-prone dynamic selectors.',
     tier: 'source-static',
   },
+  'trail-fork-coaching': {
+    ...durableExternal,
+    guidance: {
+      docs: [
+        {
+          label: 'ADR-0050 Surface Accommodations',
+          path: 'docs/adr/0050-surface-accommodations-preserve-trail-identity.md',
+        },
+        {
+          label: 'Surface Accommodations',
+          path: 'docs/surfaces/surface-accommodations.md',
+        },
+      ],
+      relatedRules: ['surface-facet-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.',
+      ],
+      summary:
+        'Keep surface accommodations from hiding several capabilities behind one branching trail input.',
+    },
+    invariant:
+      'Trails avoid hiding distinct capabilities behind branching action or operation inputs.',
+    scope: 'advisory',
+    tier: 'source-static',
+  },
   'unmaterialized-activation-source': {
     ...durableExternal,
     invariant:
@@ -601,7 +701,8 @@ const builtinWardenRuleMetadataInput = {
   },
   'warden-rules-use-ast': {
     ...durableRepoLocal,
-    invariant: 'Warden source rules use AST helpers instead of ad hoc parsing.',
+    invariant:
+      'Warden source rules use AST helpers instead of ad hoc parsing or raw node-field casts.',
     tier: 'source-static',
   },
   'webhook-route-collision': {

package/src/rules/no-destructured-compose.ts

@@ -1,6 +1,14 @@
 import {
   findBlazeBodies,
   findTrailDefinitions,
+  getNodeComputed,
+  getNodeId,
+  getNodeInit,
+  getNodeLeft,
+  getNodeOperator,
+  getNodeParams,
+  getNodeProperties,
+  getNodeRight,
   getStringValue,
   identifierName,
   isShadowed,
@@ -19,7 +27,7 @@ const diagnosticMessage = (trailId: string): string =>
   `Trail "${trailId}" destructures compose from the blaze context. Use ctx.compose(...) directly so composition stays visible and Warden can recognize composed Result values.`;
 
 const propertyKeyName = (property: AstNode): string | null => {
-  if ((property as unknown as { computed?: boolean }).computed === true) {
+  if (getNodeComputed(property) === true) {
     return null;
   }
 
@@ -38,9 +46,7 @@ const findComposeBinding = (pattern: AstNode | undefined): AstNode | null => {
     return null;
   }
 
-  const properties =
-    (pattern as unknown as { properties?: readonly AstNode[] }).properties ??
-    [];
+  const properties = getNodeProperties(pattern) ?? [];
 
   for (const property of properties) {
     if (
@@ -55,7 +61,7 @@ const findComposeBinding = (pattern: AstNode | undefined): AstNode | null => {
 };
 
 const blazeParams = (blaze: AstNode): readonly AstNode[] =>
-  (blaze as unknown as { params?: readonly AstNode[] }).params ?? [];
+  getNodeParams(blaze) ?? [];
 
 const destructuredComposeFromVariableDeclarator = (
   node: AstNode,
@@ -65,10 +71,8 @@ const destructuredComposeFromVariableDeclarator = (
     return null;
   }
 
-  const { id, init } = node as unknown as {
-    readonly id?: AstNode;
-    readonly init?: AstNode;
-  };
+  const id = getNodeId(node);
+  const init = getNodeInit(node);
 
   if (identifierName(init) !== contextName) {
     return null;
@@ -85,11 +89,9 @@ const destructuredComposeFromAssignment = (
     return null;
   }
 
-  const { left, operator, right } = node as unknown as {
-    readonly left?: AstNode;
-    readonly operator?: string;
-    readonly right?: AstNode;
-  };
+  const left = getNodeLeft(node);
+  const operator = getNodeOperator(node);
+  const right = getNodeRight(node);
 
   if (operator !== '=' || identifierName(right) !== contextName) {
     return null;

package/src/rules/no-native-error-result.ts

@@ -1,4 +1,13 @@
-import { identifierName, offsetToLine, parse, walk } from './ast.js';
+import {
+  getNodeArguments,
+  getNodeCallee,
+  getNodeObject,
+  getNodeProperty,
+  identifierName,
+  offsetToLine,
+  parse,
+  walk,
+} from './ast.js';
 import { isFrameworkInternalFile } from './scan.js';
 import type { AstNode } from './ast.js';
 import type { WardenDiagnostic, WardenRule } from './types.js';
@@ -24,7 +33,7 @@ const getMemberPropertyName = (node: AstNode): string | null => {
     return null;
   }
 
-  return identifierName((node as unknown as { property?: AstNode }).property);
+  return identifierName(getNodeProperty(node));
 };
 
 const isResultObject = (node: AstNode | undefined): boolean => {
@@ -44,12 +53,12 @@ const isResultErrCall = (node: AstNode): boolean => {
     return false;
   }
 
-  const { callee } = node as unknown as { callee?: AstNode };
+  const callee = getNodeCallee(node);
   if (!callee || getMemberPropertyName(callee) !== 'err') {
     return false;
   }
 
-  return isResultObject((callee as unknown as { object?: AstNode }).object);
+  return isResultObject(getNodeObject(callee));
 };
 
 const isNativeErrorConstruction = (node: AstNode | undefined): boolean => {
@@ -57,16 +66,14 @@ const isNativeErrorConstruction = (node: AstNode | undefined): boolean => {
     return false;
   }
 
-  const constructorName = identifierName(
-    (node as unknown as { callee?: AstNode }).callee
-  );
+  const constructorName = identifierName(getNodeCallee(node));
   return constructorName
     ? NATIVE_ERROR_CONSTRUCTORS.has(constructorName)
     : false;
 };
 
 const getFirstArgument = (node: AstNode): AstNode | undefined =>
-  (node as unknown as { arguments?: readonly AstNode[] }).arguments?.[0];
+  getNodeArguments(node)?.[0];
 
 const createDiagnostic = (
   filePath: string,