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

package/src/rules/surface-overlay-coherence.ts

@@ -0,0 +1,262 @@
+/**
+ * Coach the app-authored `surfaces` overlay toward coherent bindings.
+ *
+ * Reads the `surfaces` namespace from the serialized graph overlays and
+ * checks, per surface key, that every binding selector matches at least one
+ * trail, that grouped bindings do not overlap on expanded members, and that
+ * binding names do not shadow real surface entries (single-segment CLI
+ * routes, derived MCP tool names).
+ *
+ * Activation note: standard `trails warden` runs fire this rule. Warden's
+ * fresh topo loading collects the app-module overlays export through the
+ * shared `resolveTrailsOverlays` channel compile uses (TRL-1209 drift
+ * symmetry), so the topo-aware rule context graph carries the same overlays
+ * the committed lock embeds. Callers that supply a precomputed graph
+ * (committed locks, tests, the rule trail) keep working unchanged.
+ */
+
+import {
+  SURFACES_OVERLAY_NAMESPACE,
+  classifySurfaceBinding,
+  deriveMcpToolName,
+  matchesTrailPattern,
+  surfaceBindingsFromLockOverlays,
+} from '@ontrails/core';
+import type {
+  SurfaceBindings,
+  SurfaceOverlayBindings,
+  Topo,
+} from '@ontrails/core';
+import type { TopoGraph } from '@ontrails/topographer';
+
+import type { TopoAwareWardenRule, WardenDiagnostic } from './types.js';
+
+const RULE_NAME = 'surface-overlay-coherence';
+const TOPO_FILE = '<topo>';
+
+const SURFACE_KEYS = ['cli', 'http', 'mcp', 'ws'] as const;
+type SurfaceKey = (typeof SURFACE_KEYS)[number];
+
+const warn = (message: string): WardenDiagnostic => ({
+  filePath: TOPO_FILE,
+  line: 1,
+  message,
+  rule: RULE_NAME,
+  severity: 'warn',
+});
+
+const memberRefs = (value: SurfaceBindings[string]): readonly string[] => {
+  const shape = classifySurfaceBinding(value);
+  return shape.kind === 'synonym' ? [shape.trail] : shape.members;
+};
+
+const expandRefs = (
+  refs: readonly string[],
+  trailIds: readonly string[]
+): ReadonlySet<string> => {
+  const matched = new Set<string>();
+  for (const ref of refs) {
+    for (const trailId of trailIds) {
+      if (matchesTrailPattern(trailId, ref)) {
+        matched.add(trailId);
+      }
+    }
+  }
+  return matched;
+};
+
+const zeroMatchDiagnostics = (
+  surfaceKey: SurfaceKey,
+  bindings: SurfaceBindings,
+  trailIds: readonly string[]
+): readonly WardenDiagnostic[] => {
+  const diagnostics: WardenDiagnostic[] = [];
+  for (const [name, value] of Object.entries(bindings)) {
+    for (const ref of memberRefs(value)) {
+      if (!trailIds.some((trailId) => matchesTrailPattern(trailId, ref))) {
+        diagnostics.push(
+          warn(
+            `Surface overlay binding "${name}" on "${surfaceKey}" references "${ref}", which matches no trails in the topo. Point the binding at an existing trail id or dotted trail-id glob.`
+          )
+        );
+      }
+    }
+  }
+  return diagnostics;
+};
+
+interface ExpandedGroup {
+  readonly name: string;
+  readonly trailIds: ReadonlySet<string>;
+}
+
+const groupOverlapDiagnostics = (
+  surfaceKey: SurfaceKey,
+  bindings: SurfaceBindings,
+  trailIds: readonly string[]
+): readonly WardenDiagnostic[] => {
+  const groups: ExpandedGroup[] = [];
+  for (const [name, value] of Object.entries(bindings)) {
+    const shape = classifySurfaceBinding(value);
+    if (shape.kind === 'group') {
+      groups.push({ name, trailIds: expandRefs(shape.members, trailIds) });
+    }
+  }
+
+  const diagnostics: WardenDiagnostic[] = [];
+  for (let i = 0; i < groups.length; i += 1) {
+    const first = groups[i];
+    if (!first) {
+      continue;
+    }
+    for (let j = i + 1; j < groups.length; j += 1) {
+      const second = groups[j];
+      if (!second) {
+        continue;
+      }
+      const [sharedId] = [...second.trailIds]
+        .filter((trailId) => first.trailIds.has(trailId))
+        .toSorted();
+      if (sharedId !== undefined) {
+        diagnostics.push(
+          warn(
+            `Surface overlay group "${second.name}" on "${surfaceKey}" overlaps group "${first.name}" on trail "${sharedId}". Narrow one group so each trail has one grouped owner per surface.`
+          )
+        );
+      }
+    }
+  }
+  return diagnostics;
+};
+
+const cliCollisionDiagnostics = (
+  bindings: SurfaceBindings,
+  graph: TopoGraph
+): readonly WardenDiagnostic[] => {
+  const routeByName = new Map<
+    string,
+    { readonly kind: string; readonly trailId: string }
+  >();
+  for (const entry of graph.entries) {
+    if (entry.kind !== 'trail') {
+      continue;
+    }
+    const path = entry.cli?.path;
+    const segment = path?.length === 1 ? path[0] : undefined;
+    if (segment !== undefined) {
+      routeByName.set(segment, { kind: 'canonical', trailId: entry.id });
+    }
+    for (const route of entry.cli?.routes ?? []) {
+      // Surface-sourced alias routes are the projections of the overlay
+      // bindings themselves (TRL-1207), so a binding can never "shadow"
+      // one — only canonical paths and trail-owned aliases are real
+      // entries a binding name could collide with.
+      if (route.source === 'surface') {
+        continue;
+      }
+      const routeSegment = route.path.length === 1 ? route.path[0] : undefined;
+      if (routeSegment !== undefined && !routeByName.has(routeSegment)) {
+        routeByName.set(routeSegment, {
+          kind: route.kind,
+          trailId: entry.id,
+        });
+      }
+    }
+  }
+
+  const diagnostics: WardenDiagnostic[] = [];
+  for (const name of Object.keys(bindings)) {
+    const route = routeByName.get(name);
+    if (route !== undefined) {
+      diagnostics.push(
+        warn(
+          `Surface overlay binding "${name}" on "cli" shadows the ${route.kind} CLI route "${name}" for trail "${route.trailId}". Rename the binding so it does not shadow a real entry.`
+        )
+      );
+    }
+  }
+  return diagnostics;
+};
+
+const mcpCollisionDiagnostics = (
+  bindings: SurfaceBindings,
+  appName: string,
+  graph: TopoGraph
+): readonly WardenDiagnostic[] => {
+  const trailIdByToolName = new Map<string, string>();
+  for (const entry of graph.entries) {
+    if (entry.kind === 'trail') {
+      trailIdByToolName.set(deriveMcpToolName(appName, entry.id), entry.id);
+    }
+  }
+
+  const diagnostics: WardenDiagnostic[] = [];
+  for (const name of Object.keys(bindings)) {
+    const trailId = trailIdByToolName.get(name);
+    if (trailId !== undefined) {
+      diagnostics.push(
+        warn(
+          `Surface overlay binding "${name}" on "mcp" shadows the derived MCP tool name "${name}" for trail "${trailId}". Rename the binding so it does not shadow a real entry.`
+        )
+      );
+    }
+  }
+  return diagnostics;
+};
+
+const collectSurfaceDiagnostics = (
+  topo: Topo,
+  graph: TopoGraph,
+  overlayBindings: SurfaceOverlayBindings
+): readonly WardenDiagnostic[] => {
+  const trailIds = [...topo.trails.keys()];
+  const diagnostics: WardenDiagnostic[] = [];
+  for (const surfaceKey of SURFACE_KEYS) {
+    const bindings = overlayBindings[surfaceKey];
+    if (bindings === undefined) {
+      continue;
+    }
+    diagnostics.push(
+      ...zeroMatchDiagnostics(surfaceKey, bindings, trailIds),
+      ...groupOverlapDiagnostics(surfaceKey, bindings, trailIds)
+    );
+    if (surfaceKey === 'cli') {
+      diagnostics.push(...cliCollisionDiagnostics(bindings, graph));
+    }
+    if (surfaceKey === 'mcp') {
+      diagnostics.push(...mcpCollisionDiagnostics(bindings, topo.name, graph));
+    }
+  }
+  return diagnostics;
+};
+
+export const surfaceOverlayCoherence: TopoAwareWardenRule = {
+  checkTopo(topo, context) {
+    const graph = context?.graph;
+    if (graph?.overlays === undefined) {
+      return [];
+    }
+
+    let overlayBindings: SurfaceOverlayBindings | undefined;
+    try {
+      overlayBindings = surfaceBindingsFromLockOverlays(graph.overlays);
+    } catch (error: unknown) {
+      return [
+        warn(
+          `The "${SURFACES_OVERLAY_NAMESPACE}" overlay in the serialized graph is invalid: ${
+            error instanceof Error ? error.message : String(error)
+          }`
+        ),
+      ];
+    }
+    if (overlayBindings === undefined) {
+      return [];
+    }
+
+    return collectSurfaceDiagnostics(topo, graph, overlayBindings);
+  },
+  description:
+    'Keep app-authored surface overlay bindings pointed at real trails without group overlap or canonical-entry shadowing.',
+  name: RULE_NAME,
+  severity: 'warn',
+};

package/src/rules/{surface-facet-coherence.ts → surface-trailhead-coherence.ts}

@@ -22,10 +22,10 @@ import {
 import type { AstNode } from './ast.js';
 import type { WardenDiagnostic, WardenRule } from './types.js';
 
-const RULE_NAME = 'surface-facet-coherence';
+const RULE_NAME = 'surface-trailhead-coherence';
 
-interface FacetSelector {
-  readonly facetId: string;
+interface TrailheadSelector {
+  readonly trailheadId: string;
   readonly node: AstNode;
   readonly value: string;
 }
@@ -68,28 +68,30 @@ const diagnostic = (
   severity: 'warn',
 });
 
-const isFacetDefinition = (node: AstNode): boolean =>
+const isTrailheadDefinition = (node: AstNode): boolean =>
   node.type === 'ObjectExpression' &&
   findConfigProperty(node, 'trails') !== null;
 
-const isFacetMapCandidate = (node: AstNode): boolean =>
+const isTrailheadMapCandidate = (node: AstNode): boolean =>
   objectProperties(node).some((property) => {
     const value = unwrapExpression(propertyValue(property));
-    return value !== undefined && isFacetDefinition(value);
+    return value !== undefined && isTrailheadDefinition(value);
   });
 
-const isFacetMapBindingName = (name: string | null): boolean =>
+const isTrailheadMapBindingName = (name: string | null): boolean =>
   name !== null &&
-  (name === 'facets' || name.endsWith('Facets') || name.endsWith('FacetMap'));
+  (name === 'trailheads' ||
+    name.endsWith('Trailheads') ||
+    name.endsWith('TrailheadMap'));
 
-const hasFacetMapTypeAnnotation = (
+const hasTrailheadMapTypeAnnotation = (
   sourceCode: string,
   node: AstNode
 ): boolean => {
   const typeAnnotation = getNodeTypeAnnotation(node);
   return (
     typeAnnotation !== undefined &&
-    /\b(?:McpSurfaceFacetMap|TopoGraphFacetDeclaration|FacetMap)\b/.test(
+    /\b(?:McpSurfaceTrailheadMap|TrailheadMap)\b/.test(
       sourceCode.slice(typeAnnotation.start, typeAnnotation.end)
     )
   );
@@ -109,10 +111,10 @@ const selectorNodes = (trailsNode: AstNode): readonly AstNode[] | null => {
 const collectLiteralSelectors = (
   sourceCode: string,
   filePath: string,
-  facetId: string,
+  trailheadId: string,
   trailsProp: AstNode,
   diagnostics: WardenDiagnostic[]
-): readonly FacetSelector[] => {
+): readonly TrailheadSelector[] => {
   const trailsValue = propertyValue(trailsProp);
   const nodes = trailsValue ? selectorNodes(trailsValue) : null;
   if (nodes === null || nodes.length === 0) {
@@ -121,13 +123,13 @@ const collectLiteralSelectors = (
         sourceCode,
         filePath,
         trailsProp,
-        `Surface facet "${facetId}" uses a dynamic trails selector. Keep facet selectors as string literals so Warden can check overlap and drift.`
+        `Surface trailhead "${trailheadId}" uses a dynamic trails selector. Keep trailhead selectors as string literals so Warden can check overlap and drift.`
       )
     );
     return [];
   }
 
-  const selectors: FacetSelector[] = [];
+  const selectors: TrailheadSelector[] = [];
   for (const node of nodes) {
     const selectorValue = extractStringOrTemplateLiteral(node);
     if (selectorValue === null) {
@@ -136,12 +138,12 @@ const collectLiteralSelectors = (
           sourceCode,
           filePath,
           node,
-          `Surface facet "${facetId}" uses a dynamic trails selector. Keep facet selectors as string literals so Warden can check overlap and drift.`
+          `Surface trailhead "${trailheadId}" uses a dynamic trails selector. Keep trailhead selectors as string literals so Warden can check overlap and drift.`
         )
       );
       continue;
     }
-    selectors.push({ facetId, node, value: selectorValue });
+    selectors.push({ node, trailheadId, value: selectorValue });
   }
   return selectors;
 };
@@ -176,21 +178,21 @@ const literalBooleanProperty = (
 };
 
 const selectorsMayOverlap = (
-  first: FacetSelector,
-  second: FacetSelector
+  first: TrailheadSelector,
+  second: TrailheadSelector
 ): boolean =>
   first.value === second.value ||
   matchesTrailPattern(first.value, second.value) ||
   matchesTrailPattern(second.value, first.value);
 
-const diagnoseFacetDefinition = (
+const diagnoseTrailheadDefinition = (
   sourceCode: string,
   filePath: string,
-  facetId: string,
+  trailheadId: string,
   definition: AstNode
 ): {
   readonly diagnostics: readonly WardenDiagnostic[];
-  readonly selectors: readonly FacetSelector[];
+  readonly selectors: readonly TrailheadSelector[];
 } => {
   const diagnostics: WardenDiagnostic[] = [];
   const trailsProp = findConfigProperty(definition, 'trails');
@@ -200,7 +202,7 @@ const diagnoseFacetDefinition = (
       : collectLiteralSelectors(
           sourceCode,
           filePath,
-          facetId,
+          trailheadId,
           trailsProp,
           diagnostics
         );
@@ -211,7 +213,7 @@ const diagnoseFacetDefinition = (
         sourceCode,
         filePath,
         definition,
-        `Surface facet "${facetId}" needs a non-empty description so MCP clients and agents can choose it without guessing.`
+        `Surface trailhead "${trailheadId}" needs a non-empty description so MCP clients and agents can choose it without guessing.`
       )
     );
   }
@@ -227,7 +229,7 @@ const diagnoseFacetDefinition = (
         sourceCode,
         filePath,
         definition,
-        `Surface facet "${facetId}" explicitly sets public visibility without visibilityWideningAccepted: true. Facets must not accidentally widen hidden trails.`
+        `Surface trailhead "${trailheadId}" explicitly sets public visibility without visibilityWideningAccepted: true. Trailheads must not accidentally widen hidden trails.`
       )
     );
   }
@@ -241,7 +243,7 @@ const diagnoseFacetDefinition = (
         sourceCode,
         filePath,
         definition,
-        `Surface facet "${facetId}" accepts visibility widening but does not record descriptionStableThrough review metadata.`
+        `Surface trailhead "${trailheadId}" accepts visibility widening but does not record descriptionStableThrough review metadata.`
       )
     );
   }
@@ -249,24 +251,24 @@ const diagnoseFacetDefinition = (
   return { diagnostics, selectors };
 };
 
-const diagnoseFacetMap = (
+const diagnoseTrailheadMap = (
   sourceCode: string,
   filePath: string,
-  facetMap: AstNode
+  trailheadMap: AstNode
 ): readonly WardenDiagnostic[] => {
   const diagnostics: WardenDiagnostic[] = [];
-  const selectors: FacetSelector[] = [];
+  const selectors: TrailheadSelector[] = [];
 
-  for (const property of objectProperties(facetMap)) {
-    const facetId = getPropertyName(getNodeKey(property));
+  for (const property of objectProperties(trailheadMap)) {
+    const trailheadId = getPropertyName(getNodeKey(property));
     const value = unwrapExpression(propertyValue(property));
-    if (!facetId || value === undefined || !isFacetDefinition(value)) {
+    if (!trailheadId || value === undefined || !isTrailheadDefinition(value)) {
       continue;
     }
-    const result = diagnoseFacetDefinition(
+    const result = diagnoseTrailheadDefinition(
       sourceCode,
       filePath,
-      facetId,
+      trailheadId,
       value
     );
     diagnostics.push(...result.diagnostics);
@@ -282,7 +284,7 @@ const diagnoseFacetMap = (
       const second = selectors[j];
       if (
         !second ||
-        first.facetId === second.facetId ||
+        first.trailheadId === second.trailheadId ||
         !selectorsMayOverlap(first, second)
       ) {
         continue;
@@ -292,7 +294,7 @@ const diagnoseFacetMap = (
           sourceCode,
           filePath,
           second.node,
-          `Surface facet selector "${second.value}" in "${second.facetId}" overlaps selector "${first.value}" in "${first.facetId}". Narrow one facet so each public trail has one MCP owner.`
+          `Surface trailhead selector "${second.value}" in "${second.trailheadId}" overlaps selector "${first.value}" in "${first.trailheadId}". Narrow one trailhead so each public trail has one MCP owner.`
         )
       );
     }
@@ -301,7 +303,7 @@ const diagnoseFacetMap = (
   return diagnostics;
 };
 
-export const surfaceFacetCoherence: WardenRule = {
+export const surfaceTrailheadCoherence: WardenRule = {
   check(sourceCode, filePath) {
     const ast = parse(filePath, sourceCode);
     if (!ast) {
@@ -316,18 +318,20 @@ export const surfaceFacetCoherence: WardenRule = {
         unwrapped === undefined ||
         unwrapped.type !== 'ObjectExpression' ||
         seen.has(unwrapped.start) ||
-        !isFacetMapCandidate(unwrapped)
+        !isTrailheadMapCandidate(unwrapped)
       ) {
         return;
       }
       seen.add(unwrapped.start);
-      diagnostics.push(...diagnoseFacetMap(sourceCode, filePath, unwrapped));
+      diagnostics.push(
+        ...diagnoseTrailheadMap(sourceCode, filePath, unwrapped)
+      );
     };
 
     walk(ast, (node) => {
       if (node.type === 'Property') {
         const propertyName = getPropertyName(getNodeKey(node));
-        if (propertyName === 'facets') {
+        if (propertyName === 'trailheads') {
           diagnoseCandidate(propertyValue(node));
         }
         return;
@@ -337,7 +341,7 @@ export const surfaceFacetCoherence: WardenRule = {
         const bindingName = getNodeName(getNodeId(node));
         if (
           typeof bindingName === 'string' &&
-          isFacetMapBindingName(bindingName)
+          isTrailheadMapBindingName(bindingName)
         ) {
           diagnoseCandidate(getNodeInit(node) ?? undefined);
         }
@@ -347,7 +351,7 @@ export const surfaceFacetCoherence: WardenRule = {
       if (
         (node.type === 'TSAsExpression' ||
           node.type === 'TSSatisfiesExpression') &&
-        hasFacetMapTypeAnnotation(sourceCode, node)
+        hasTrailheadMapTypeAnnotation(sourceCode, node)
       ) {
         diagnoseCandidate(node);
       }