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

package/src/rules/trail-versioning-topo.ts

@@ -0,0 +1,172 @@
+import { deriveTopoGraph } from '@ontrails/topography';
+import type {
+  TopoGraph,
+  TopoGraphEntry,
+  TopoGraphForceEntry,
+  TopoGraphVersionEntry,
+} from '@ontrails/topography';
+import type { Topo } from '@ontrails/core';
+
+import type { TopoAwareWardenRule, WardenDiagnostic } from './types.js';
+
+const TOPO_FILE = '<topo>';
+
+const isArchived = (entry: TopoGraphVersionEntry): boolean =>
+  entry.status?.state === 'archived';
+
+const isDeprecatedWithoutGuidance = (entry: TopoGraphVersionEntry): boolean =>
+  entry.status?.state === 'deprecated' &&
+  entry.status.successor === undefined &&
+  entry.status.note === undefined &&
+  (entry.status.migration === undefined || entry.status.migration.length === 0);
+
+const versionNumbersFor = (entry: TopoGraphEntry): readonly number[] => [
+  ...(entry.version === undefined ? [] : [entry.version]),
+  ...Object.keys(entry.versions ?? {}).map(Number),
+];
+
+const versionEntryName = (trailId: string, version: string): string =>
+  `${trailId}@${version}`;
+
+const topoDiagnostic = (
+  rule: string,
+  severity: WardenDiagnostic['severity'],
+  message: string
+): WardenDiagnostic => ({
+  filePath: TOPO_FILE,
+  line: 1,
+  message,
+  rule,
+  severity,
+});
+
+const trailEntries = (graph: TopoGraph): readonly TopoGraphEntry[] =>
+  graph.entries.filter((entry) => entry.kind === 'trail');
+
+const graphFor = (
+  topo: Topo,
+  context: Parameters<TopoAwareWardenRule['checkTopo']>[1]
+): TopoGraph => context?.graph ?? deriveTopoGraph(topo);
+
+const forceKey = (force: TopoGraphForceEntry): string =>
+  JSON.stringify([
+    force.kind,
+    force.id,
+    force.change,
+    force.detail,
+    force.reason,
+    force.severity,
+    force.source,
+  ]);
+
+const pendingForceDiagnostic = (force: TopoGraphForceEntry): WardenDiagnostic =>
+  topoDiagnostic(
+    'pending-force',
+    'warn',
+    `Trail "${force.id}" has a pending forced topo break (${force.change}: ${force.detail}). Resolve or document the force event before release.`
+  );
+
+export const deprecationWithoutGuidance: TopoAwareWardenRule = {
+  checkTopo(topo, context) {
+    return trailEntries(graphFor(topo, context)).flatMap((entry) =>
+      Object.entries(entry.versions ?? {}).flatMap(([version, historical]) =>
+        isDeprecatedWithoutGuidance(historical)
+          ? [
+              topoDiagnostic(
+                'deprecation-without-guidance',
+                'error',
+                `Trail "${versionEntryName(entry.id, version)}" is deprecated without successor, migration, or note guidance. Add at least one guidance field to the version status.`
+              ),
+            ]
+          : []
+      )
+    );
+  },
+  description:
+    'Require deprecated trail version entries to carry successor, migration, or note guidance.',
+  name: 'deprecation-without-guidance',
+  severity: 'error',
+};
+
+export const versionGap: TopoAwareWardenRule = {
+  checkTopo(topo, context) {
+    const diagnostics: WardenDiagnostic[] = [];
+    for (const entry of trailEntries(graphFor(topo, context))) {
+      if (entry.version === undefined) {
+        continue;
+      }
+      const historicalVersions = new Set(
+        Object.keys(entry.versions ?? {}).map(Number)
+      );
+      if (historicalVersions.has(entry.version)) {
+        diagnostics.push(
+          topoDiagnostic(
+            'version-gap',
+            'error',
+            `Trail "${entry.id}" declares current version ${entry.version} both as current and as a historical entry. Remove the duplicate historical entry.`
+          )
+        );
+      }
+
+      const versions = new Set(versionNumbersFor(entry));
+      for (let version = 1; version <= entry.version; version += 1) {
+        if (!versions.has(version)) {
+          diagnostics.push(
+            topoDiagnostic(
+              'version-gap',
+              'error',
+              `Trail "${entry.id}" has a gap before current version ${entry.version}: missing version ${version}. Historical version coverage must be contiguous, including archived entries.`
+            )
+          );
+        }
+      }
+    }
+    return diagnostics;
+  },
+  description:
+    'Require trail version coverage to stay contiguous from v1 through the current version.',
+  name: 'version-gap',
+  severity: 'error',
+};
+
+export const versionWithoutExamples: TopoAwareWardenRule = {
+  checkTopo(topo, context) {
+    return trailEntries(graphFor(topo, context)).flatMap((entry) =>
+      Object.entries(entry.versions ?? {}).flatMap(([version, historical]) =>
+        !isArchived(historical) && (historical.exampleCount ?? 0) === 0
+          ? [
+              topoDiagnostic(
+                'version-without-examples',
+                'warn',
+                `Trail "${versionEntryName(entry.id, version)}" is a live historical version without examples. Add version-entry examples or archive the entry if it no longer participates in runtime negotiation.`
+              ),
+            ]
+          : []
+      )
+    );
+  },
+  description:
+    'Warn when live historical trail version entries do not include examples.',
+  name: 'version-without-examples',
+  severity: 'warn',
+};
+
+export const pendingForce: TopoAwareWardenRule = {
+  checkTopo(topo, context) {
+    const graph = graphFor(topo, context);
+    const diagnostics = new Map<string, WardenDiagnostic>();
+    for (const entry of trailEntries(graph)) {
+      for (const force of entry.forces ?? []) {
+        diagnostics.set(forceKey(force), pendingForceDiagnostic(force));
+      }
+    }
+    for (const force of graph.forces ?? []) {
+      diagnostics.set(forceKey(force), pendingForceDiagnostic(force));
+    }
+    return [...diagnostics.values()];
+  },
+  description:
+    'Warn when graph-only force audit events remain attached to trail entries or the topo graph.',
+  name: 'pending-force',
+  severity: 'warn',
+};

package/src/rules/trailhead-override-divergence.ts

@@ -0,0 +1,356 @@
+/**
+ * Warn when a call-site MCP trailhead map diverges from the app-authored
+ * `surfaces` overlay's `mcp` list bindings.
+ *
+ * The overlay is the authored, lockable default; a call-site trailhead map
+ * is a supported override-in-context that wins at runtime. Divergence between
+ * the two is legal but must be visible: an agent reading the committed lock
+ * would otherwise trust grouped entries the running surface does not project.
+ *
+ * Rule-kind note: no Warden rule kind currently sees both the serialized
+ * graph overlays and source ASTs directly. This rule is the closest honest
+ * shape — a project-aware source rule whose `ProjectContext` carries
+ * per-app authored `mcp` binding sets resolved from the run's topo targets
+ * (graph overlays when available, else app-module overlay registrations).
+ * A call-site map is attributed to an app only when one of its literal
+ * member selectors matches a trail id in that app's topo, so one app's
+ * authored bindings never flag another app's call-site map. Without
+ * context (`check` without context, or a run with no topo targets) the
+ * rule stays silent rather than guessing.
+ */
+
+import { classifySurfaceBinding, matchesTrailPattern } from '@ontrails/core';
+import type { SurfaceBindings } from '@ontrails/core';
+
+import {
+  extractStringOrTemplateLiteral,
+  findConfigProperty,
+  getNodeArgument,
+  getNodeElements,
+  getNodeExpression,
+  getNodeId,
+  getNodeInit,
+  getNodeKey,
+  getNodeName,
+  getNodeProperties,
+  getNodeTypeAnnotation,
+  getNodeValueNode,
+  getPropertyName,
+  offsetToLine,
+  parse,
+  walk,
+} from '@ontrails/source';
+import type { AstNode } from '@ontrails/source';
+import type {
+  AuthoredMcpSurfaceBindingSet,
+  ProjectAwareWardenRule,
+  ProjectContext,
+  WardenDiagnostic,
+} from './types.js';
+
+const RULE_NAME = 'trailhead-override-divergence';
+
+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 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 diagnostic = (
+  sourceCode: string,
+  filePath: string,
+  node: AstNode,
+  message: string
+): WardenDiagnostic => ({
+  filePath,
+  line: offsetToLine(sourceCode, node.start),
+  message,
+  rule: RULE_NAME,
+  severity: 'warn',
+});
+
+/**
+ * Collect the literal selector strings of one trailhead definition. Returns
+ * `null` when any selector is dynamic — `surface-trailhead-coherence`
+ * already flags those, so this rule skips the comparison instead of
+ * double-reporting.
+ */
+const literalSelectors = (definition: AstNode): readonly string[] | null => {
+  const trailsProp = findConfigProperty(definition, 'trails');
+  const trailsValue = trailsProp ? propertyValue(trailsProp) : undefined;
+  const value = unwrapExpression(trailsValue);
+  if (!value) {
+    return null;
+  }
+  const nodes =
+    value.type === 'ArrayExpression'
+      ? getNodeElements(value).filter((element) => element !== null)
+      : [value];
+  const selectors: string[] = [];
+  for (const node of nodes) {
+    const selector = extractStringOrTemplateLiteral(node);
+    if (selector === null) {
+      return null;
+    }
+    selectors.push(selector);
+  }
+  return selectors;
+};
+
+const authoredGroupSelectors = (
+  bindings: SurfaceBindings
+): ReadonlyMap<string, readonly string[]> => {
+  const groups = new Map<string, readonly string[]>();
+  for (const [name, value] of Object.entries(bindings)) {
+    const shape = classifySurfaceBinding(value);
+    if (shape.kind === 'group') {
+      groups.set(name, shape.members);
+    }
+  }
+  return groups;
+};
+
+const sameSelectorSet = (
+  first: readonly string[],
+  second: readonly string[]
+): boolean => {
+  const firstSet = new Set(first);
+  const secondSet = new Set(second);
+  return (
+    firstSet.size === secondSet.size &&
+    [...firstSet].every((selector) => secondSet.has(selector))
+  );
+};
+
+const formatSelectors = (selectors: readonly string[]): string =>
+  [...new Set(selectors)]
+    .toSorted()
+    .map((selector) => `"${selector}"`)
+    .join(', ');
+
+/**
+ * Attribute a call-site trailhead map to a binding set: the map belongs to
+ * an app when at least one of its literal member selectors matches a trail
+ * id registered in that app's topo.
+ */
+const mapBelongsToSet = (
+  trailheadMap: AstNode,
+  set: AuthoredMcpSurfaceBindingSet
+): boolean =>
+  objectProperties(trailheadMap).some((property) => {
+    const value = unwrapExpression(propertyValue(property));
+    if (value === undefined || !isTrailheadDefinition(value)) {
+      return false;
+    }
+    const selectors = literalSelectors(value);
+    return (
+      selectors !== null &&
+      selectors.some((selector) =>
+        set.trailIds.some((trailId) => matchesTrailPattern(trailId, selector))
+      )
+    );
+  });
+
+const diagnoseTrailheadMap = (
+  sourceCode: string,
+  filePath: string,
+  trailheadMap: AstNode,
+  set: AuthoredMcpSurfaceBindingSet,
+  groups: ReadonlyMap<string, readonly string[]>
+): readonly WardenDiagnostic[] => {
+  const diagnostics: WardenDiagnostic[] = [];
+  const groupNames = [...groups.keys()].toSorted();
+
+  for (const property of objectProperties(trailheadMap)) {
+    const trailheadId = getPropertyName(getNodeKey(property));
+    const value = unwrapExpression(propertyValue(property));
+    if (!trailheadId || value === undefined || !isTrailheadDefinition(value)) {
+      continue;
+    }
+
+    const authored = groups.get(trailheadId);
+    if (authored === undefined) {
+      diagnostics.push(
+        diagnostic(
+          sourceCode,
+          filePath,
+          property,
+          `Call-site MCP trailhead "${trailheadId}" has no matching mcp list binding in app "${set.appName}"'s surfaceOverlay (authored groups: ${groupNames.length > 0 ? groupNames.map((name) => `"${name}"`).join(', ') : 'none'}). The call-site map overrides the lockable default at runtime — author the same binding in surfaceOverlay({ mcp }) or rename one side.`
+        )
+      );
+      continue;
+    }
+
+    const selectors = literalSelectors(value);
+    if (selectors === null) {
+      continue;
+    }
+    if (!sameSelectorSet(selectors, authored)) {
+      diagnostics.push(
+        diagnostic(
+          sourceCode,
+          filePath,
+          property,
+          `Call-site MCP trailhead "${trailheadId}" selects [${formatSelectors(selectors)}] but app "${set.appName}"'s surfaceOverlay mcp binding "${trailheadId}" authors [${formatSelectors(authored)}]. The call-site map overrides the lockable default at runtime — align the member selectors or make the intentional divergence explicit by renaming one side.`
+        )
+      );
+    }
+  }
+
+  // The override replaces the authored default whole-map at runtime, so an
+  // authored group missing from the call-site map is silently dropped while
+  // the committed lock still advertises it.
+  const callSiteNames = new Set(
+    objectProperties(trailheadMap).flatMap((property) => {
+      const name = getPropertyName(getNodeKey(property));
+      const value = unwrapExpression(propertyValue(property));
+      return name && value !== undefined && isTrailheadDefinition(value)
+        ? [name]
+        : [];
+    })
+  );
+  for (const name of groupNames) {
+    if (!callSiteNames.has(name)) {
+      diagnostics.push(
+        diagnostic(
+          sourceCode,
+          filePath,
+          trailheadMap,
+          `App "${set.appName}"'s surfaceOverlay mcp binding "${name}" is not carried by this call-site trailhead map, so it will not be projected at runtime while the committed lock still advertises it. Add "${name}" to the call-site map or remove it from the authored overlay.`
+        )
+      );
+    }
+  }
+
+  return diagnostics;
+};
+
+/**
+ * Warn when a source file's call-site MCP trailhead map diverges from the
+ * app-authored `surfaces` overlay's `mcp` list bindings.
+ */
+export const trailheadOverrideDivergence: ProjectAwareWardenRule = {
+  check(): readonly WardenDiagnostic[] {
+    // Without project context there are no authored bindings to compare
+    // against; stay silent instead of guessing.
+    return [];
+  },
+  checkWithContext(
+    sourceCode: string,
+    filePath: string,
+    context: ProjectContext
+  ): readonly WardenDiagnostic[] {
+    const sets = (context.authoredMcpSurfaceBindingSets ?? [])
+      .map((set) => ({
+        groups: authoredGroupSelectors(set.bindings),
+        set,
+      }))
+      .filter(({ groups }) => groups.size > 0);
+    if (sets.length === 0) {
+      return [];
+    }
+
+    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);
+      for (const { set, groups } of sets) {
+        if (!mapBelongsToSet(unwrapped, set)) {
+          continue;
+        }
+        diagnostics.push(
+          ...diagnoseTrailheadMap(sourceCode, filePath, unwrapped, set, groups)
+        );
+      }
+    };
+
+    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:
+    'Call-site MCP trailhead maps stay aligned with the app-authored surfaces overlay mcp bindings they override.',
+  name: RULE_NAME,
+  severity: 'warn',
+};