@ontrails/warden 1.0.0-beta.13 → 1.0.0-beta.15

package/src/rules/circular-refs.ts

@@ -0,0 +1,154 @@
+import {
+  collectContourReferenceTargetsByName,
+  findContourDefinitions,
+  offsetToLine,
+  parse,
+} from './ast.js';
+import type { AstNode } from './ast.js';
+import { isTestFile } from './scan.js';
+import type {
+  ProjectAwareWardenRule,
+  ProjectContext,
+  WardenDiagnostic,
+} from './types.js';
+
+const mergeReferenceGraphs = (
+  localGraph: ReadonlyMap<string, readonly string[]>,
+  contextGraph?: ReadonlyMap<string, readonly string[]>
+): ReadonlyMap<string, readonly string[]> => {
+  const merged = new Map<string, Set<string>>();
+
+  const addTargets = (source: string, targets: readonly string[]): void => {
+    const existing = merged.get(source);
+    if (existing) {
+      for (const target of targets) {
+        existing.add(target);
+      }
+      return;
+    }
+
+    merged.set(source, new Set(targets));
+  };
+
+  for (const [source, targets] of contextGraph ?? []) {
+    addTargets(source, targets);
+  }
+
+  for (const [source, targets] of localGraph) {
+    addTargets(source, targets);
+  }
+
+  return new Map(
+    [...merged.entries()].map(([source, targets]) => [source, [...targets]])
+  );
+};
+
+const findCyclePath = (
+  start: string,
+  graph: ReadonlyMap<string, readonly string[]>,
+  current = start,
+  path: readonly string[] = [start],
+  active: ReadonlySet<string> = new Set([start])
+): readonly string[] | null => {
+  for (const target of graph.get(current) ?? []) {
+    if (target === start) {
+      return [...path, target];
+    }
+
+    if (active.has(target)) {
+      continue;
+    }
+
+    const cycle = findCyclePath(
+      start,
+      graph,
+      target,
+      [...path, target],
+      new Set([...active, target])
+    );
+    if (cycle) {
+      return cycle;
+    }
+  }
+
+  return null;
+};
+
+const buildCircularReferenceDiagnostic = (
+  contourName: string,
+  cyclePath: readonly string[],
+  filePath: string,
+  line: number
+): WardenDiagnostic => ({
+  filePath,
+  line,
+  message: `Contour "${contourName}" participates in circular contour references: ${cyclePath.join(' -> ')}.`,
+  rule: 'circular-refs',
+  severity: 'warn',
+});
+
+const checkCircularReferences = (
+  ast: AstNode,
+  sourceCode: string,
+  filePath: string,
+  graph: ReadonlyMap<string, readonly string[]>
+): readonly WardenDiagnostic[] => {
+  if (isTestFile(filePath)) {
+    return [];
+  }
+
+  return findContourDefinitions(ast).flatMap((definition) => {
+    const cyclePath = findCyclePath(definition.name, graph);
+    if (!cyclePath) {
+      return [];
+    }
+
+    return [
+      buildCircularReferenceDiagnostic(
+        definition.name,
+        cyclePath,
+        filePath,
+        offsetToLine(sourceCode, definition.start)
+      ),
+    ];
+  });
+};
+
+/**
+ * Warns when contour references form a direct or transitive cycle.
+ */
+export const circularRefs: ProjectAwareWardenRule = {
+  check(sourceCode: string, filePath: string): readonly WardenDiagnostic[] {
+    const ast = parse(filePath, sourceCode);
+    if (!ast) {
+      return [];
+    }
+
+    const graph = collectContourReferenceTargetsByName(ast);
+    return checkCircularReferences(ast, sourceCode, filePath, graph);
+  },
+  checkWithContext(
+    sourceCode: string,
+    filePath: string,
+    context: ProjectContext
+  ): readonly WardenDiagnostic[] {
+    const ast = parse(filePath, sourceCode);
+    if (!ast) {
+      return [];
+    }
+
+    const localGraph = collectContourReferenceTargetsByName(
+      ast,
+      context.knownContourIds
+    );
+    return checkCircularReferences(
+      ast,
+      sourceCode,
+      filePath,
+      mergeReferenceGraphs(localGraph, context.contourReferencesByName)
+    );
+  },
+  description: 'Warn when contour references form direct or transitive cycles.',
+  name: 'circular-refs',
+  severity: 'warn',
+};

package/src/rules/{context-no-trailhead-types.ts → context-no-surface-types.ts}

@@ -1,5 +1,5 @@
 /**
- * Detects imports of trailhead-specific modules and types in trail files.
+ * Detects imports of surface-specific modules and types in trail files.
  *
  * Uses AST parsing for accurate detection — no false positives from
  * imports in comments or strings.
@@ -40,6 +40,67 @@ interface ImportSpecifier {
   readonly imported?: { readonly name?: string };
 }
 
+const isBareTrailCallee = (callee: AstNode): boolean => {
+  if (callee.type !== 'Identifier') {
+    return false;
+  }
+  return (callee as unknown as { name?: string }).name === 'trail';
+};
+
+const isNamespacedTrailCallee = (callee: AstNode): boolean => {
+  if (
+    callee.type !== 'MemberExpression' &&
+    callee.type !== 'StaticMemberExpression'
+  ) {
+    return false;
+  }
+  // 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) {
+    return false;
+  }
+  const prop = (callee as unknown as { property?: AstNode }).property;
+  if (prop?.type !== 'Identifier') {
+    return false;
+  }
+  return (prop as unknown as { name?: string }).name === 'trail';
+};
+
+/**
+ * True when `ast` contains a `trail(...)` call expression — i.e. this file
+ * looks like a trail definition. AST-based replacement for the legacy
+ * `/\btrail\s*\(/.test(sourceCode)` gate, which fired on string literals,
+ * comments, and docstrings.
+ *
+ * @remarks
+ * Both bare-identifier `trail(...)` and namespaced `ns.trail(...)` callees
+ * are recognized, so files using either `import { trail }` or
+ * `import * as ns from '@ontrails/core'` are detected as trail definitions.
+ *
+ * The inner `if (found)` guard skips further work in each callback invocation,
+ * but the shared `walk` helper in `./ast.ts` exposes no abort mechanism, so
+ * the full tree is still traversed once a match is seen. Acceptable: `walk`
+ * is cheap and this rule only runs on files that already matched a path
+ * filter upstream.
+ */
+const hasTrailCall = (ast: AstNode): boolean => {
+  let found = false;
+  walk(ast, (node) => {
+    if (found || node.type !== 'CallExpression') {
+      return;
+    }
+    const { callee } = node as unknown as { callee?: AstNode };
+    if (!callee) {
+      return;
+    }
+    if (isBareTrailCallee(callee) || isNamespacedTrailCallee(callee)) {
+      found = true;
+    }
+  });
+  return found;
+};
+
 const makeDiag = (
   filePath: string,
   sourceCode: string,
@@ -49,7 +110,7 @@ const makeDiag = (
   filePath,
   line: offsetToLine(sourceCode, node.start),
   message,
-  rule: 'context-no-trailhead-types',
+  rule: 'context-no-surface-types',
   severity: 'error',
 });
 
@@ -92,7 +153,7 @@ const checkSpecifiersForSurfaceTypes = (
     filePath,
     sourceCode,
     node,
-    `Do not import trailhead type "${typeName}" in trail implementation files.`
+    `Do not import surface type "${typeName}" in trail implementation files.`
   );
 };
 
@@ -111,7 +172,7 @@ const classifyImport = (
       filePath,
       sourceCode,
       node,
-      `Do not import from trailhead module "${moduleName}" in trail implementation files.`
+      `Do not import from surface module "${moduleName}" in trail implementation files.`
     );
   }
 
@@ -119,18 +180,17 @@ const classifyImport = (
 };
 
 /**
- * Detects imports of trailhead-specific types in trail implementation files.
+ * Detects imports of surface-specific types in trail implementation files.
  */
-export const contextNoTrailheadTypes: WardenRule = {
+export const contextNoSurfaceTypes: WardenRule = {
   check(sourceCode: string, filePath: string): readonly WardenDiagnostic[] {
-    if (!/\btrail\s*\(/.test(sourceCode)) {
-      return [];
-    }
-
     const ast = parse(filePath, sourceCode);
     if (!ast) {
       return [];
     }
+    if (!hasTrailCall(ast)) {
+      return [];
+    }
 
     const diagnostics: WardenDiagnostic[] = [];
     walk(ast, (node) => {
@@ -143,8 +203,8 @@ export const contextNoTrailheadTypes: WardenRule = {
     return diagnostics;
   },
   description:
-    'Disallow trailhead-specific type imports (Request, Response, McpSession, etc.) in trail implementation files.',
-  name: 'context-no-trailhead-types',
+    'Disallow surface-specific type imports (Request, Response, McpSession, etc.) in trail implementation files.',
+  name: 'context-no-surface-types',
 
   severity: 'error',
 };

package/src/rules/contour-exists.ts

@@ -0,0 +1,251 @@
+import {
+  buildUserNamespaceContext,
+  collectContourDefinitionIds,
+  collectImportAliasMap,
+  collectNamedContourIds,
+  extractFirstStringArg,
+  findConfigProperty,
+  findTrailDefinitions,
+  identifierName,
+  isMemberAccessNonComputed,
+  isUserNamespaceReceiverAllowed,
+  offsetToLine,
+  parse,
+  deriveContourIdentifierName,
+} from './ast.js';
+import type { AstNode, TrailDefinition, UserNamespaceContext } from './ast.js';
+import { mergeKnownContourIds } from './contour-ids.js';
+import { isTestFile } from './scan.js';
+import type {
+  ProjectAwareWardenRule,
+  ProjectContext,
+  WardenDiagnostic,
+} from './types.js';
+
+const isContourCall = (node: AstNode): boolean =>
+  node.type === 'CallExpression' &&
+  identifierName((node as unknown as { callee?: AstNode }).callee) ===
+    'contour';
+
+const getContourElements = (config: AstNode): readonly AstNode[] => {
+  const contoursProp = findConfigProperty(config, 'contours');
+  if (!contoursProp) {
+    return [];
+  }
+
+  const arrayNode = contoursProp.value;
+  if (!arrayNode || (arrayNode as AstNode).type !== 'ArrayExpression') {
+    return [];
+  }
+
+  const elements = (arrayNode as AstNode)['elements'] as
+    | readonly AstNode[]
+    | undefined;
+  return elements ?? [];
+};
+
+/**
+ * Resolve `contours.user` to its contour name. When `userNamespace` carries a
+ * scope-aware `safeMemberStarts` set, the member access must appear in it —
+ * rejecting cases where `contours` is shadowed by a local binding such as a
+ * function parameter or `const contours = ...`. Without the set, falls back
+ * to the bare name check for backward compatibility.
+ */
+const resolveNamespaceMemberContourName = (
+  element: AstNode,
+  userNamespace: UserNamespaceContext
+): string | null => {
+  if (!isMemberAccessNonComputed(element)) {
+    return null;
+  }
+  const { object, property } = element as unknown as {
+    readonly object?: AstNode;
+    readonly property?: AstNode;
+  };
+  const receiver = object ? identifierName(object) : null;
+  if (
+    !receiver ||
+    !isUserNamespaceReceiverAllowed(receiver, element.start, userNamespace)
+  ) {
+    return null;
+  }
+  return property ? identifierName(property) : null;
+};
+
+const resolveDeclaredContourName = (
+  element: AstNode,
+  contourIdsByName: ReadonlyMap<string, string>,
+  knownContourIds?: ReadonlySet<string>,
+  importAliases?: ReadonlyMap<string, string>,
+  userNamespace?: UserNamespaceContext
+): string | null => {
+  if (element.type === 'Identifier') {
+    const name = identifierName(element);
+    return name
+      ? deriveContourIdentifierName(
+          name,
+          contourIdsByName,
+          knownContourIds,
+          importAliases
+        )
+      : null;
+  }
+
+  if (userNamespace && userNamespace.bindings.size > 0) {
+    const namespaceTarget = resolveNamespaceMemberContourName(
+      element,
+      userNamespace
+    );
+    if (namespaceTarget) {
+      return namespaceTarget;
+    }
+  }
+
+  return isContourCall(element) ? extractFirstStringArg(element) : null;
+};
+
+const extractDeclaredContourNames = (
+  config: AstNode,
+  contourIdsByName: ReadonlyMap<string, string>,
+  knownContourIds?: ReadonlySet<string>,
+  importAliases?: ReadonlyMap<string, string>,
+  userNamespace?: UserNamespaceContext
+): readonly string[] => [
+  ...new Set(
+    getContourElements(config).flatMap((element) => {
+      const contourName = resolveDeclaredContourName(
+        element,
+        contourIdsByName,
+        knownContourIds,
+        importAliases,
+        userNamespace
+      );
+      return contourName ? [contourName] : [];
+    })
+  ),
+];
+
+const buildMissingContourDiagnostic = (
+  trailId: string,
+  contourName: string,
+  filePath: string,
+  line: number
+): WardenDiagnostic => ({
+  filePath,
+  line,
+  message: `Trail "${trailId}" declares contour "${contourName}" which is not defined in the project.`,
+  rule: 'contour-exists',
+  severity: 'error',
+});
+
+const buildDiagnosticsForDefinition = (
+  definition: TrailDefinition,
+  sourceCode: string,
+  filePath: string,
+  knownContourIds: ReadonlySet<string>,
+  contourIdsByName: ReadonlyMap<string, string>,
+  importAliases: ReadonlyMap<string, string>,
+  userNamespace: UserNamespaceContext
+): readonly WardenDiagnostic[] => {
+  if (definition.kind !== 'trail') {
+    return [];
+  }
+
+  const line = offsetToLine(sourceCode, definition.start);
+  return extractDeclaredContourNames(
+    definition.config,
+    contourIdsByName,
+    knownContourIds,
+    importAliases,
+    userNamespace
+  ).flatMap((contourName) =>
+    knownContourIds.has(contourName)
+      ? []
+      : [
+          buildMissingContourDiagnostic(
+            definition.id,
+            contourName,
+            filePath,
+            line
+          ),
+        ]
+  );
+};
+
+const buildContourDiagnostics = (
+  ast: AstNode,
+  sourceCode: string,
+  filePath: string,
+  knownContourIds: ReadonlySet<string>
+): readonly WardenDiagnostic[] => {
+  const contourIdsByName = collectNamedContourIds(ast);
+  const importAliases = collectImportAliasMap(ast);
+  const userNamespace = buildUserNamespaceContext(ast);
+
+  return findTrailDefinitions(ast).flatMap((definition) =>
+    buildDiagnosticsForDefinition(
+      definition,
+      sourceCode,
+      filePath,
+      knownContourIds,
+      contourIdsByName,
+      importAliases,
+      userNamespace
+    )
+  );
+};
+
+const checkContourDeclarations = (
+  ast: AstNode,
+  sourceCode: string,
+  filePath: string,
+  knownContourIds: ReadonlySet<string>
+): readonly WardenDiagnostic[] => {
+  if (isTestFile(filePath)) {
+    return [];
+  }
+
+  return buildContourDiagnostics(ast, sourceCode, filePath, knownContourIds);
+};
+
+/**
+ * Checks that every contour declared in a trail `contours` array resolves to a
+ * known contour definition.
+ */
+export const contourExists: ProjectAwareWardenRule = {
+  check(sourceCode: string, filePath: string): readonly WardenDiagnostic[] {
+    const ast = parse(filePath, sourceCode);
+    if (!ast) {
+      return [];
+    }
+
+    return checkContourDeclarations(
+      ast,
+      sourceCode,
+      filePath,
+      collectContourDefinitionIds(ast)
+    );
+  },
+  checkWithContext(
+    sourceCode: string,
+    filePath: string,
+    context: ProjectContext
+  ): readonly WardenDiagnostic[] {
+    const ast = parse(filePath, sourceCode);
+    if (!ast) {
+      return [];
+    }
+
+    const localContourIds = collectContourDefinitionIds(ast);
+    return checkContourDeclarations(
+      ast,
+      sourceCode,
+      filePath,
+      mergeKnownContourIds(localContourIds, context.knownContourIds)
+    );
+  },
+  description:
+    'Ensure every contour declared on a trail resolves to a known contour definition.',
+  name: 'contour-exists',
+  severity: 'error',
+};

package/src/rules/contour-ids.ts

@@ -0,0 +1,15 @@
+/**
+ * Merge a file's locally-defined contour IDs with the project-wide set.
+ *
+ * Rules that run with a `ProjectContext` need to treat both local and
+ * project-wide contour definitions as "known" so that declarations and
+ * references resolve correctly. When no project context is available — e.g.
+ * single-file lint runs via `check` — the local set is returned as-is.
+ */
+export const mergeKnownContourIds = (
+  localContourIds: ReadonlySet<string>,
+  projectContourIds?: ReadonlySet<string>
+): ReadonlySet<string> =>
+  projectContourIds
+    ? new Set([...projectContourIds, ...localContourIds])
+    : localContourIds;