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

package/src/rules/cli-command-route-coherence.ts

@@ -0,0 +1,177 @@
+import { deriveTrailCliCommandProjection } from '@ontrails/core';
+import type { CliCommandRoute, Topo } from '@ontrails/core';
+import type { TopoGraph } from '@ontrails/topographer';
+
+import type { TopoAwareWardenRule, WardenDiagnostic } from './types.js';
+
+const RULE_NAME = 'cli-command-route-coherence';
+const TOPO_FILE = '<topo>';
+
+interface RouteClaim {
+  readonly kind: CliCommandRoute['kind'];
+  readonly path: readonly string[];
+  readonly source: CliCommandRoute['source'];
+  readonly trailId: string;
+}
+
+const routeKey = (path: readonly string[]): string => path.join('\0');
+
+const renderPath = (path: readonly string[]): string => path.join(' ');
+
+const claimLabel = (claim: RouteClaim): string =>
+  `${claim.kind} route for trail "${claim.trailId}" (${claim.source})`;
+
+const buildProjectionDiagnostic = (
+  trailId: string,
+  error: unknown
+): WardenDiagnostic => ({
+  filePath: TOPO_FILE,
+  line: 1,
+  message: `CLI command route projection for trail "${trailId}" is invalid: ${
+    error instanceof Error ? error.message : String(error)
+  }`,
+  rule: RULE_NAME,
+  severity: 'error',
+});
+
+const buildCollisionDiagnostic = (
+  path: readonly string[],
+  claims: readonly RouteClaim[]
+): WardenDiagnostic => ({
+  filePath: TOPO_FILE,
+  line: 1,
+  message: `CLI command route collision on "${renderPath(path)}": ${claims
+    .toSorted((a, b) => a.trailId.localeCompare(b.trailId))
+    .map(claimLabel)
+    .join(
+      ', '
+    )}. Rename or remove one CLI alias so every accepted command path normalizes into exactly one trail contract.`,
+  rule: RULE_NAME,
+  severity: 'error',
+});
+
+const buildGraphTargetDiagnostic = (
+  entryId: string,
+  route: CliCommandRoute,
+  knownTrailIds: ReadonlySet<string>
+): WardenDiagnostic => ({
+  filePath: TOPO_FILE,
+  line: 1,
+  message: knownTrailIds.has(route.target)
+    ? `Serialized CLI command route "${renderPath(route.path)}" is stored under trail "${entryId}" but targets "${route.target}". Route facts must stay attached to their owning trail.`
+    : `Serialized CLI command route "${renderPath(route.path)}" targets unknown trail "${route.target}". Surface-owned aliases must target existing trail IDs.`,
+  rule: RULE_NAME,
+  severity: 'error',
+});
+
+const collectTopoClaims = (
+  topo: Topo
+): {
+  readonly claims: readonly RouteClaim[];
+  readonly diagnostics: readonly WardenDiagnostic[];
+} => {
+  const claims: RouteClaim[] = [];
+  const diagnostics: WardenDiagnostic[] = [];
+
+  for (const trail of topo.list()) {
+    try {
+      const projection = deriveTrailCliCommandProjection(trail);
+      for (const route of projection.routes) {
+        claims.push({
+          kind: route.kind,
+          path: route.path,
+          source: route.source,
+          trailId: trail.id,
+        });
+      }
+    } catch (error: unknown) {
+      diagnostics.push(buildProjectionDiagnostic(trail.id, error));
+    }
+  }
+
+  return { claims, diagnostics };
+};
+
+const collectGraphClaims = (
+  graph: TopoGraph | undefined
+): readonly RouteClaim[] => {
+  if (graph === undefined) {
+    return [];
+  }
+
+  const claims: RouteClaim[] = [];
+  for (const entry of graph.entries) {
+    if (entry.kind !== 'trail') {
+      continue;
+    }
+    for (const route of entry.cli?.routes ?? []) {
+      claims.push({
+        kind: route.kind,
+        path: route.path,
+        source: route.source,
+        trailId: entry.id,
+      });
+    }
+  }
+  return claims;
+};
+
+const collectCollisionDiagnostics = (
+  claims: readonly RouteClaim[]
+): readonly WardenDiagnostic[] => {
+  const claimsByRoute = new Map<string, RouteClaim[]>();
+  for (const claim of claims) {
+    const key = routeKey(claim.path);
+    const current = claimsByRoute.get(key) ?? [];
+    current.push(claim);
+    claimsByRoute.set(key, current);
+  }
+
+  return [...claimsByRoute.values()]
+    .filter((grouped) => grouped.length > 1)
+    .map((grouped) =>
+      buildCollisionDiagnostic(grouped[0]?.path ?? [], grouped)
+    );
+};
+
+const collectGraphTargetDiagnostics = (
+  graph: TopoGraph | undefined,
+  knownTrailIds: ReadonlySet<string>
+): readonly WardenDiagnostic[] => {
+  if (graph === undefined) {
+    return [];
+  }
+
+  const diagnostics: WardenDiagnostic[] = [];
+  for (const entry of graph.entries) {
+    if (entry.kind !== 'trail') {
+      continue;
+    }
+    for (const route of entry.cli?.routes ?? []) {
+      if (route.target !== entry.id || !knownTrailIds.has(route.target)) {
+        diagnostics.push(
+          buildGraphTargetDiagnostic(entry.id, route, knownTrailIds)
+        );
+      }
+    }
+  }
+  return diagnostics;
+};
+
+export const cliCommandRouteCoherence: TopoAwareWardenRule = {
+  checkTopo(topo, context) {
+    const { claims, diagnostics } = collectTopoClaims(topo);
+    const knownTrailIds = new Set(topo.trails.keys());
+    const routeClaims =
+      context?.graph === undefined ? claims : collectGraphClaims(context.graph);
+    return [
+      ...diagnostics,
+      ...collectCollisionDiagnostics(routeClaims),
+      ...collectGraphTargetDiagnostics(context?.graph, knownTrailIds),
+    ];
+  },
+  description:
+    'Ensure CLI command routes and aliases resolve to one coherent trail contract.',
+  name: RULE_NAME,
+  severity: 'error',
+};

package/src/rules/composes-declarations.ts

@@ -7,12 +7,31 @@
  */
 
 import {
-  findConfigProperty,
   findBlazeBodies,
+  findConfigProperty,
   findTrailDefinitions,
+  getNodeArguments,
+  getNodeBodyNode,
+  getNodeBodyStatements,
+  getNodeCallee,
+  getNodeDeclaration,
+  getNodeDeclarations,
+  getNodeId,
+  getNodeInit,
+  getNodeKey,
+  getNodeKind,
+  getNodeLeft,
+  getNodeName,
+  getNodeObject,
+  getNodeParams,
+  getNodeProperties,
+  getNodeProperty,
+  getNodeValue,
+  getNodeValueNode,
+  isShadowed,
   offsetToLine,
   parse,
-  walk,
+  walkWithScopes,
 } from './ast.js';
 import type { AstNode } from './ast.js';
 import { isTestFile } from './scan.js';
@@ -27,7 +46,7 @@ const identifierName = (node: AstNode | undefined): string | null => {
   if (node?.type !== 'Identifier') {
     return null;
   }
-  return (node as unknown as { name?: string }).name ?? null;
+  return getNodeName(node) ?? null;
 };
 
 // ---------------------------------------------------------------------------
@@ -40,14 +59,14 @@ const isStringLiteral = (node: AstNode): boolean => {
     return true;
   }
   if (node.type === 'Literal') {
-    return typeof (node as unknown as { value?: unknown }).value === 'string';
+    return typeof getNodeValue(node) === 'string';
   }
   return false;
 };
 
 /** Extract the string value from a string literal node. */
 const getStringValue = (node: AstNode): string | null => {
-  const val = (node as unknown as { value?: unknown }).value;
+  const val = getNodeValue(node);
   return typeof val === 'string' ? val : null;
 };
 
@@ -194,12 +213,8 @@ const extractMemberPair = (
     return null;
   }
 
-  const objName = identifierName(
-    (callee as unknown as { object?: AstNode }).object
-  );
-  const propName = identifierName(
-    (callee as unknown as { property?: AstNode }).property
-  );
+  const objName = identifierName(getNodeObject(callee));
+  const propName = identifierName(getNodeProperty(callee));
 
   return objName && propName ? { objName, propName } : null;
 };
@@ -219,7 +234,7 @@ const extractContextParamName = (blazeBody: AstNode): string | null => {
   }
   const [, param] = params;
   if (param?.type === 'AssignmentPattern') {
-    const { left } = param as unknown as { left?: AstNode };
+    const left = getNodeLeft(param);
     return identifierName(left);
   }
   return identifierName(param);
@@ -230,10 +245,8 @@ const extractComposeLocalName = (prop: AstNode): string | null => {
   if (prop.type !== 'Property') {
     return null;
   }
-  const { key, value } = prop as unknown as {
-    readonly key?: AstNode;
-    readonly value?: AstNode;
-  };
+  const key = getNodeKey(prop);
+  const value = getNodeValueNode(prop);
   const keyName = identifierName(key);
   if (keyName !== 'compose') {
     return null;
@@ -246,9 +259,7 @@ const collectComposeNamesFromPattern = (
   pattern: AstNode,
   names: Set<string>
 ): void => {
-  const { properties } = pattern as unknown as {
-    readonly properties?: readonly AstNode[];
-  };
+  const properties = getNodeProperties(pattern);
   for (const prop of properties ?? []) {
     const localName = extractComposeLocalName(prop);
     if (localName) {
@@ -436,10 +447,8 @@ const getCtxDestructurePattern = (
   if (node.type !== 'VariableDeclarator') {
     return null;
   }
-  const { id, init } = node as unknown as {
-    readonly id?: AstNode;
-    readonly init?: AstNode;
-  };
+  const id = getNodeId(node);
+  const init = getNodeInit(node);
   if (!id || id.type !== 'ObjectPattern' || !init) {
     return null;
   }
@@ -448,11 +457,14 @@ const getCtxDestructurePattern = (
 };
 
 const getTopLevelStatements = (body: AstNode): readonly AstNode[] => {
-  const blockBody = (body as unknown as { body?: AstNode }).body;
+  if (body.type === 'BlockStatement') {
+    return getNodeBodyStatements(body);
+  }
+  const blockBody = getNodeBodyNode(body);
   if (!blockBody || blockBody.type !== 'BlockStatement') {
     return [];
   }
-  return (blockBody as unknown as { body?: readonly AstNode[] }).body ?? [];
+  return getNodeBodyStatements(blockBody);
 };
 
 const collectComposeNamesFromDeclaration = (
@@ -463,13 +475,11 @@ const collectComposeNamesFromDeclaration = (
   if (stmt.type !== 'VariableDeclaration') {
     return;
   }
-  const { kind } = stmt as unknown as { readonly kind?: string };
+  const kind = getNodeKind(stmt);
   if (kind !== 'const') {
     return;
   }
-  const declarations =
-    (stmt as unknown as { readonly declarations?: readonly AstNode[] })
-      .declarations ?? [];
+  const declarations = getNodeDeclarations(stmt);
   for (const decl of declarations) {
     const pattern = getCtxDestructurePattern(decl, ctxNames);
     if (pattern) {
@@ -489,6 +499,109 @@ const collectDestructuredComposeNames = (
   return names;
 };
 
+interface ComposeHelper {
+  readonly body: AstNode;
+  readonly params: readonly AstNode[];
+}
+
+const isFunctionLikeNode = (
+  node: AstNode | null | undefined
+): node is AstNode =>
+  node !== null &&
+  node !== undefined &&
+  (node.type === 'ArrowFunctionExpression' ||
+    node.type === 'FunctionDeclaration' ||
+    node.type === 'FunctionExpression');
+
+const helperFromFunctionNode = (
+  node: AstNode | null | undefined
+): ComposeHelper | null => {
+  if (!isFunctionLikeNode(node)) {
+    return null;
+  }
+  const body = getNodeBodyNode(node);
+  return body ? { body, params: getNodeParams(node) } : null;
+};
+
+const addFunctionHelper = (
+  node: AstNode,
+  helpers: Map<string, ComposeHelper>
+): void => {
+  if (node.type !== 'FunctionDeclaration') {
+    return;
+  }
+  const name = identifierName(getNodeId(node));
+  const helper = helperFromFunctionNode(node);
+  if (name && helper) {
+    helpers.set(name, helper);
+  }
+};
+
+const addVariableHelpers = (
+  node: AstNode,
+  helpers: Map<string, ComposeHelper>
+): void => {
+  if (node.type !== 'VariableDeclaration' || getNodeKind(node) !== 'const') {
+    return;
+  }
+  for (const declaration of getNodeDeclarations(node)) {
+    const name = identifierName(getNodeId(declaration));
+    const helper = helperFromFunctionNode(getNodeInit(declaration));
+    if (name && helper) {
+      helpers.set(name, helper);
+    }
+  }
+};
+
+const unwrapTopLevelDeclaration = (node: AstNode): AstNode =>
+  node.type === 'ExportNamedDeclaration'
+    ? (getNodeDeclaration(node) ?? node)
+    : node;
+
+const collectComposeHelpers = (
+  ast: AstNode
+): ReadonlyMap<string, ComposeHelper> => {
+  const helpers = new Map<string, ComposeHelper>();
+  for (const statement of getNodeBodyStatements(ast)) {
+    const declaration = unwrapTopLevelDeclaration(statement);
+    addFunctionHelper(declaration, helpers);
+    addVariableHelpers(declaration, helpers);
+  }
+  return helpers;
+};
+
+const collectHelperCtxNames = (
+  call: AstNode,
+  helper: ComposeHelper,
+  ctxNames: ReadonlySet<string>
+): ReadonlySet<string> => {
+  const names = new Set<string>();
+  const args = getNodeArguments(call);
+  for (const [index, param] of helper.params.entries()) {
+    const argName = identifierName(args[index]);
+    const paramName = identifierName(param);
+    if (argName && paramName && ctxNames.has(argName)) {
+      names.add(paramName);
+    }
+  }
+  return names;
+};
+
+const findHelperCall = (
+  node: AstNode | null | undefined,
+  helpers: ReadonlyMap<string, ComposeHelper>
+): { readonly helper: ComposeHelper; readonly name: string } | null => {
+  if (node?.type !== 'CallExpression') {
+    return null;
+  }
+  const calleeName = identifierName(getNodeCallee(node));
+  if (!calleeName) {
+    return null;
+  }
+  const helper = helpers.get(calleeName);
+  return helper ? { helper, name: calleeName } : null;
+};
+
 interface CalledComposes {
   /** Statically resolved trail IDs from string literal arguments. */
   readonly ids: ReadonlySet<string>;
@@ -504,31 +617,67 @@ interface CalledComposes {
 const collectComposeCallsFromBody = (
   body: AstNode,
   ids: Set<string>,
-  sourceCode: string
+  sourceCode: string,
+  helpers: ReadonlyMap<string, ComposeHelper>,
+  inheritedCtxNames?: ReadonlySet<string>,
+  visitedHelpers = new Set<string>()
 ): boolean => {
-  const ctxNames = buildCtxNames(body);
+  const ctxNames = inheritedCtxNames ?? buildCtxNames(body);
   const composeLocalNames = collectDestructuredComposeNames(body, ctxNames);
+  const helperNames = new Set(helpers.keys());
   let foundUnresolved = false;
 
-  walk(body, (node) => {
-    const extracted = extractComposeCall(
-      node,
-      ctxNames,
-      composeLocalNames,
-      sourceCode
-    );
-    if (!extracted) {
-      return;
-    }
-
-    if (extracted.hasUnresolved) {
-      foundUnresolved = true;
-    }
-
-    for (const id of extracted.ids) {
-      ids.add(id);
-    }
-  });
+  walkWithScopes(
+    body,
+    (node, scopeStack) => {
+      const extracted = extractComposeCall(
+        node,
+        ctxNames,
+        composeLocalNames,
+        sourceCode
+      );
+      if (extracted) {
+        if (extracted.hasUnresolved) {
+          foundUnresolved = true;
+        }
+
+        for (const id of extracted.ids) {
+          ids.add(id);
+        }
+      }
+
+      const helperCall = findHelperCall(node, helpers);
+      if (
+        !helperCall ||
+        visitedHelpers.has(helperCall.name) ||
+        isShadowed(helperCall.name, scopeStack)
+      ) {
+        return;
+      }
+      const helperCtxNames = collectHelperCtxNames(
+        node,
+        helperCall.helper,
+        ctxNames
+      );
+      if (helperCtxNames.size === 0) {
+        return;
+      }
+      visitedHelpers.add(helperCall.name);
+      if (
+        collectComposeCallsFromBody(
+          helperCall.helper.body,
+          ids,
+          sourceCode,
+          helpers,
+          helperCtxNames,
+          visitedHelpers
+        )
+      ) {
+        foundUnresolved = true;
+      }
+    },
+    { initialScopes: [helperNames] }
+  );
 
   return foundUnresolved;
 };
@@ -536,13 +685,15 @@ const collectComposeCallsFromBody = (
 /** Walk blaze bodies and collect all statically resolvable ctx.compose() trail IDs. */
 const extractCalledComposes = (
   config: AstNode,
+  ast: AstNode,
   sourceCode: string
 ): CalledComposes => {
   const ids = new Set<string>();
   let hasUnresolved = false;
+  const helpers = collectComposeHelpers(ast);
 
   for (const body of findBlazeBodies(config)) {
-    if (collectComposeCallsFromBody(body, ids, sourceCode)) {
+    if (collectComposeCallsFromBody(body, ids, sourceCode, helpers)) {
       hasUnresolved = true;
     }
   }
@@ -558,16 +709,13 @@ const buildUndeclaredDiagnostic = (
   trailId: string,
   composedId: string,
   filePath: string,
-  line: number,
-  softened = false
+  line: number
 ): WardenDiagnostic => ({
   filePath,
   line,
-  message: softened
-    ? `Trail "${trailId}": ctx.compose('${composedId}') called but '${composedId}' is not declared in composes (may be declared via trail object references). Add the string id to composes, or use the same trail object form in both composes and ctx.compose(...).`
-    : `Trail "${trailId}": ctx.compose('${composedId}') called but '${composedId}' is not declared in composes. Add it to the trail composes array: composes: ['${composedId}', ...].`,
+  message: `Trail "${trailId}": ctx.compose('${composedId}') called but '${composedId}' is not declared in composes. Add it to the trail composes array: composes: ['${composedId}', ...].`,
   rule: 'composes-declarations',
-  severity: softened ? 'warn' : 'error',
+  severity: 'error',
 });
 
 const buildUnusedDiagnostic = (
@@ -595,20 +743,13 @@ const reportUndeclared = (
     trailId: string;
     filePath: string;
     line: number;
-    softened?: boolean;
   },
   diagnostics: WardenDiagnostic[]
 ): void => {
   for (const id of called) {
     if (!declared.has(id)) {
       diagnostics.push(
-        buildUndeclaredDiagnostic(
-          ctx.trailId,
-          id,
-          ctx.filePath,
-          ctx.line,
-          ctx.softened
-        )
+        buildUndeclaredDiagnostic(ctx.trailId, id, ctx.filePath, ctx.line)
       );
     }
   }
@@ -632,12 +773,13 @@ const reportUnused = (
 
 const checkTrailDefinition = (
   def: { id: string; config: AstNode; start: number },
+  ast: AstNode,
   filePath: string,
   sourceCode: string,
   diagnostics: WardenDiagnostic[]
 ): void => {
   const declared = extractDeclaredComposes(def.config, sourceCode);
-  const called = extractCalledComposes(def.config, sourceCode);
+  const called = extractCalledComposes(def.config, ast, sourceCode);
 
   if (
     declared.ids.size === 0 &&
@@ -651,16 +793,7 @@ const checkTrailDefinition = (
   const line = offsetToLine(sourceCode, def.start);
   const ctx = { filePath, line, trailId: def.id };
 
-  // When the declared array contains trail object references we can't resolve,
-  // downgrade "undeclared" diagnostics from error to warn. The developer still
-  // sees genuinely undeclared calls, but we can't statically prove the call
-  // isn't covered by a trail object entry the runtime will normalize.
-  reportUndeclared(
-    called.ids,
-    declared.ids,
-    { ...ctx, softened: declared.hasUnresolved },
-    diagnostics
-  );
+  reportUndeclared(called.ids, declared.ids, ctx, diagnostics);
 
   // When all ctx.compose() calls are statically resolved, report unused
   // declarations. When some calls use trail object references (unresolved),
@@ -692,7 +825,7 @@ export const composesDeclarations: WardenRule = {
     const diagnostics: WardenDiagnostic[] = [];
 
     for (const def of findTrailDefinitions(ast)) {
-      checkTrailDefinition(def, filePath, sourceCode, diagnostics);
+      checkTrailDefinition(def, ast, filePath, sourceCode, diagnostics);
     }
 
     return diagnostics;

package/src/rules/context-no-surface-types.ts

@@ -5,7 +5,16 @@
  * imports in comments or strings.
  */
 
-import { offsetToLine, parse, walk } from './ast.js';
+import {
+  getNodeCallee,
+  getNodeComputed,
+  getNodeName,
+  getNodeProperty,
+  offsetToLine,
+  parse,
+  walk,
+} from './ast.js';
+import type { AstNode } from './ast.js';
 import type { WardenDiagnostic, WardenRule } from './types.js';
 
 const SURFACE_MODULES = new Set([
@@ -29,12 +38,6 @@ const SURFACE_TYPE_NAMES = new Set([
   'ServerResponse',
 ]);
 
-interface AstNode {
-  readonly type: string;
-  readonly start: number;
-  readonly [key: string]: unknown;
-}
-
 interface ImportSpecifier {
   readonly local?: { readonly name?: string };
   readonly imported?: { readonly name?: string };
@@ -44,7 +47,7 @@ const isBareTrailCallee = (callee: AstNode): boolean => {
   if (callee.type !== 'Identifier') {
     return false;
   }
-  return (callee as unknown as { name?: string }).name === 'trail';
+  return getNodeName(callee) === 'trail';
 };
 
 const isNamespacedTrailCallee = (callee: AstNode): boolean => {
@@ -57,14 +60,14 @@ const isNamespacedTrailCallee = (callee: AstNode): boolean => {
   // Skip computed access like `ns[trail]()` — the bracketed expression may
   // resolve to any runtime value, not the `trail` primitive, even when it
   // happens to be an identifier literally named `trail`.
-  if ((callee as unknown as { computed?: boolean }).computed === true) {
+  if (getNodeComputed(callee) === true) {
     return false;
   }
-  const prop = (callee as unknown as { property?: AstNode }).property;
+  const prop = getNodeProperty(callee);
   if (prop?.type !== 'Identifier') {
     return false;
   }
-  return (prop as unknown as { name?: string }).name === 'trail';
+  return getNodeName(prop) === 'trail';
 };
 
 /**
@@ -90,7 +93,7 @@ const hasTrailCall = (ast: AstNode): boolean => {
     if (found || node.type !== 'CallExpression') {
       return;
     }
-    const { callee } = node as unknown as { callee?: AstNode };
+    const callee = getNodeCallee(node);
     if (!callee) {
       return;
     }