@ontrails/warden 1.0.0-beta.4 → 1.0.0-beta.41

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/topography';
+
+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-trailhead-coherence.ts

@@ -0,0 +1,366 @@
+import { matchesTrailPattern } from '@ontrails/core';
+
+import {
+  extractStringOrTemplateLiteral,
+  findConfigProperty,
+  getNodeArgument,
+  getNodeElements,
+  getNodeExpression,
+  getNodeId,
+  getNodeInit,
+  getNodeKey,
+  getNodeName,
+  getNodeProperties,
+  getNodeTypeAnnotation,
+  getNodeValue,
+  getNodeValueNode,
+  getPropertyName,
+  offsetToLine,
+  parse,
+  walk,
+} from '@ontrails/source';
+import type { AstNode } from '@ontrails/source';
+import type { WardenDiagnostic, WardenRule } from './types.js';
+
+const RULE_NAME = 'surface-trailhead-coherence';
+
+interface TrailheadSelector {
+  readonly trailheadId: string;
+  readonly node: AstNode;
+  readonly value: string;
+}
+
+const unwrapExpression = (node: AstNode | undefined): AstNode | undefined => {
+  let current = node;
+  while (
+    current?.type === 'TSAsExpression' ||
+    current?.type === 'TSSatisfiesExpression'
+  ) {
+    current = getNodeExpression(current) ?? getNodeArgument(current);
+  }
+  return current;
+};
+
+const objectProperties = (node: AstNode): readonly AstNode[] =>
+  node.type === 'ObjectExpression' ? (getNodeProperties(node) ?? []) : [];
+
+const propertyValue = (property: AstNode): AstNode | undefined =>
+  property.type === 'Property' ? getNodeValueNode(property) : undefined;
+
+const literalBooleanValue = (node: AstNode | undefined): boolean | null => {
+  if (node?.type !== 'Literal') {
+    return null;
+  }
+  const value = getNodeValue(node);
+  return typeof value === 'boolean' ? value : null;
+};
+
+const diagnostic = (
+  sourceCode: string,
+  filePath: string,
+  node: AstNode,
+  message: string
+): WardenDiagnostic => ({
+  filePath,
+  line: offsetToLine(sourceCode, node.start),
+  message,
+  rule: RULE_NAME,
+  severity: 'warn',
+});
+
+const isTrailheadDefinition = (node: AstNode): boolean =>
+  node.type === 'ObjectExpression' &&
+  findConfigProperty(node, 'trails') !== null;
+
+const isTrailheadMapCandidate = (node: AstNode): boolean =>
+  objectProperties(node).some((property) => {
+    const value = unwrapExpression(propertyValue(property));
+    return value !== undefined && isTrailheadDefinition(value);
+  });
+
+const isTrailheadMapBindingName = (name: string | null): boolean =>
+  name !== null &&
+  (name === 'trailheads' ||
+    name.endsWith('Trailheads') ||
+    name.endsWith('TrailheadMap'));
+
+const hasTrailheadMapTypeAnnotation = (
+  sourceCode: string,
+  node: AstNode
+): boolean => {
+  const typeAnnotation = getNodeTypeAnnotation(node);
+  return (
+    typeAnnotation !== undefined &&
+    /\b(?:McpSurfaceTrailheadMap|TrailheadMap)\b/.test(
+      sourceCode.slice(typeAnnotation.start, typeAnnotation.end)
+    )
+  );
+};
+
+const selectorNodes = (trailsNode: AstNode): readonly AstNode[] | null => {
+  const value = unwrapExpression(trailsNode);
+  if (!value) {
+    return null;
+  }
+  if (value.type === 'ArrayExpression') {
+    return getNodeElements(value).filter((element) => element !== null);
+  }
+  return [value];
+};
+
+const collectLiteralSelectors = (
+  sourceCode: string,
+  filePath: string,
+  trailheadId: string,
+  trailsProp: AstNode,
+  diagnostics: WardenDiagnostic[]
+): readonly TrailheadSelector[] => {
+  const trailsValue = propertyValue(trailsProp);
+  const nodes = trailsValue ? selectorNodes(trailsValue) : null;
+  if (nodes === null || nodes.length === 0) {
+    diagnostics.push(
+      diagnostic(
+        sourceCode,
+        filePath,
+        trailsProp,
+        `Surface trailhead "${trailheadId}" uses a dynamic trails selector. Keep trailhead selectors as string literals so Warden can check overlap and drift.`
+      )
+    );
+    return [];
+  }
+
+  const selectors: TrailheadSelector[] = [];
+  for (const node of nodes) {
+    const selectorValue = extractStringOrTemplateLiteral(node);
+    if (selectorValue === null) {
+      diagnostics.push(
+        diagnostic(
+          sourceCode,
+          filePath,
+          node,
+          `Surface trailhead "${trailheadId}" uses a dynamic trails selector. Keep trailhead selectors as string literals so Warden can check overlap and drift.`
+        )
+      );
+      continue;
+    }
+    selectors.push({ node, trailheadId, value: selectorValue });
+  }
+  return selectors;
+};
+
+const hasNonEmptyDescription = (definition: AstNode): boolean => {
+  const descriptionProp = findConfigProperty(definition, 'description');
+  const value = unwrapExpression(propertyValue(descriptionProp ?? definition));
+  const description = extractStringOrTemplateLiteral(value);
+  return typeof description === 'string' && description.trim().length > 0;
+};
+
+const literalStringProperty = (
+  definition: AstNode,
+  propertyName: string
+): string | null => {
+  const prop = findConfigProperty(definition, propertyName);
+  if (!prop) {
+    return null;
+  }
+  return extractStringOrTemplateLiteral(unwrapExpression(propertyValue(prop)));
+};
+
+const literalBooleanProperty = (
+  definition: AstNode,
+  propertyName: string
+): boolean | null => {
+  const prop = findConfigProperty(definition, propertyName);
+  if (!prop) {
+    return null;
+  }
+  return literalBooleanValue(unwrapExpression(propertyValue(prop)));
+};
+
+const selectorsMayOverlap = (
+  first: TrailheadSelector,
+  second: TrailheadSelector
+): boolean =>
+  first.value === second.value ||
+  matchesTrailPattern(first.value, second.value) ||
+  matchesTrailPattern(second.value, first.value);
+
+const diagnoseTrailheadDefinition = (
+  sourceCode: string,
+  filePath: string,
+  trailheadId: string,
+  definition: AstNode
+): {
+  readonly diagnostics: readonly WardenDiagnostic[];
+  readonly selectors: readonly TrailheadSelector[];
+} => {
+  const diagnostics: WardenDiagnostic[] = [];
+  const trailsProp = findConfigProperty(definition, 'trails');
+  const selectors =
+    trailsProp === null
+      ? []
+      : collectLiteralSelectors(
+          sourceCode,
+          filePath,
+          trailheadId,
+          trailsProp,
+          diagnostics
+        );
+
+  if (!hasNonEmptyDescription(definition)) {
+    diagnostics.push(
+      diagnostic(
+        sourceCode,
+        filePath,
+        definition,
+        `Surface trailhead "${trailheadId}" needs a non-empty description so MCP clients and agents can choose it without guessing.`
+      )
+    );
+  }
+
+  const visibility = literalStringProperty(definition, 'visibility');
+  const wideningAccepted = literalBooleanProperty(
+    definition,
+    'visibilityWideningAccepted'
+  );
+  if (visibility === 'public' && wideningAccepted !== true) {
+    diagnostics.push(
+      diagnostic(
+        sourceCode,
+        filePath,
+        definition,
+        `Surface trailhead "${trailheadId}" explicitly sets public visibility without visibilityWideningAccepted: true. Trailheads must not accidentally widen hidden trails.`
+      )
+    );
+  }
+
+  if (
+    wideningAccepted === true &&
+    !literalStringProperty(definition, 'descriptionStableThrough')
+  ) {
+    diagnostics.push(
+      diagnostic(
+        sourceCode,
+        filePath,
+        definition,
+        `Surface trailhead "${trailheadId}" accepts visibility widening but does not record descriptionStableThrough review metadata.`
+      )
+    );
+  }
+
+  return { diagnostics, selectors };
+};
+
+const diagnoseTrailheadMap = (
+  sourceCode: string,
+  filePath: string,
+  trailheadMap: AstNode
+): readonly WardenDiagnostic[] => {
+  const diagnostics: WardenDiagnostic[] = [];
+  const selectors: TrailheadSelector[] = [];
+
+  for (const property of objectProperties(trailheadMap)) {
+    const trailheadId = getPropertyName(getNodeKey(property));
+    const value = unwrapExpression(propertyValue(property));
+    if (!trailheadId || value === undefined || !isTrailheadDefinition(value)) {
+      continue;
+    }
+    const result = diagnoseTrailheadDefinition(
+      sourceCode,
+      filePath,
+      trailheadId,
+      value
+    );
+    diagnostics.push(...result.diagnostics);
+    selectors.push(...result.selectors);
+  }
+
+  for (let i = 0; i < selectors.length; i += 1) {
+    const first = selectors[i];
+    if (!first) {
+      continue;
+    }
+    for (let j = i + 1; j < selectors.length; j += 1) {
+      const second = selectors[j];
+      if (
+        !second ||
+        first.trailheadId === second.trailheadId ||
+        !selectorsMayOverlap(first, second)
+      ) {
+        continue;
+      }
+      diagnostics.push(
+        diagnostic(
+          sourceCode,
+          filePath,
+          second.node,
+          `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.`
+        )
+      );
+    }
+  }
+
+  return diagnostics;
+};
+
+export const surfaceTrailheadCoherence: WardenRule = {
+  check(sourceCode, filePath) {
+    const ast = parse(filePath, sourceCode);
+    if (!ast) {
+      return [];
+    }
+
+    const seen = new Set<number>();
+    const diagnostics: WardenDiagnostic[] = [];
+    const diagnoseCandidate = (node: AstNode | undefined): void => {
+      const unwrapped = unwrapExpression(node);
+      if (
+        unwrapped === undefined ||
+        unwrapped.type !== 'ObjectExpression' ||
+        seen.has(unwrapped.start) ||
+        !isTrailheadMapCandidate(unwrapped)
+      ) {
+        return;
+      }
+      seen.add(unwrapped.start);
+      diagnostics.push(
+        ...diagnoseTrailheadMap(sourceCode, filePath, unwrapped)
+      );
+    };
+
+    walk(ast, (node) => {
+      if (node.type === 'Property') {
+        const propertyName = getPropertyName(getNodeKey(node));
+        if (propertyName === 'trailheads') {
+          diagnoseCandidate(propertyValue(node));
+        }
+        return;
+      }
+
+      if (node.type === 'VariableDeclarator') {
+        const bindingName = getNodeName(getNodeId(node));
+        if (
+          typeof bindingName === 'string' &&
+          isTrailheadMapBindingName(bindingName)
+        ) {
+          diagnoseCandidate(getNodeInit(node) ?? undefined);
+        }
+        return;
+      }
+
+      if (
+        (node.type === 'TSAsExpression' ||
+          node.type === 'TSSatisfiesExpression') &&
+        hasTrailheadMapTypeAnnotation(sourceCode, node)
+      ) {
+        diagnoseCandidate(node);
+      }
+    });
+
+    return diagnostics;
+  },
+  description:
+    'Coach trailhead maps away from selector overlap, hidden visibility widening, and drift-prone dynamic selectors.',
+  name: RULE_NAME,
+  severity: 'warn',
+};