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

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,17 +38,72 @@ 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 };
 }
 
+const isBareTrailCallee = (callee: AstNode): boolean => {
+  if (callee.type !== 'Identifier') {
+    return false;
+  }
+  return getNodeName(callee) === '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 (getNodeComputed(callee) === true) {
+    return false;
+  }
+  const prop = getNodeProperty(callee);
+  if (prop?.type !== 'Identifier') {
+    return false;
+  }
+  return getNodeName(prop) === '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 = getNodeCallee(node);
+    if (!callee) {
+      return;
+    }
+    if (isBareTrailCallee(callee) || isNamespacedTrailCallee(callee)) {
+      found = true;
+    }
+  });
+  return found;
+};
+
 const makeDiag = (
   filePath: string,
   sourceCode: string,
@@ -92,7 +156,7 @@ const checkSpecifiersForSurfaceTypes = (
     filePath,
     sourceCode,
     node,
-    `Do not import surface type "${typeName}" in trail implementation files.`
+    `Do not import surface type "${typeName}" in trail files.`
   );
 };
 
@@ -111,7 +175,7 @@ const classifyImport = (
       filePath,
       sourceCode,
       node,
-      `Do not import from surface module "${moduleName}" in trail implementation files.`
+      `Do not import from surface module "${moduleName}" in trail files.`
     );
   }
 
@@ -119,18 +183,17 @@ const classifyImport = (
 };
 
 /**
- * Detects imports of surface-specific types in trail implementation files.
+ * Detects imports of surface-specific types in trail files.
  */
 export const contextNoSurfaceTypes: WardenRule = {
   check(sourceCode: string, filePath: string): readonly WardenDiagnostic[] {
-    if (!/\b(?:trail|hike)\s*\(/.test(sourceCode)) {
-      return [];
-    }
-
     const ast = parse(filePath, sourceCode);
     if (!ast) {
       return [];
     }
+    if (!hasTrailCall(ast)) {
+      return [];
+    }
 
     const diagnostics: WardenDiagnostic[] = [];
     walk(ast, (node) => {
@@ -143,7 +206,7 @@ export const contextNoSurfaceTypes: WardenRule = {
     return diagnostics;
   },
   description:
-    'Disallow surface-specific type imports (Request, Response, McpSession, etc.) in trail implementation files.',
+    'Disallow surface-specific type imports (Request, Response, McpSession, etc.) in trail files.',
   name: 'context-no-surface-types',
 
   severity: 'error',

package/src/rules/contour-exists.ts

@@ -0,0 +1,251 @@
+import {
+  buildUserNamespaceContext,
+  collectContourDefinitionIds,
+  collectImportAliasMap,
+  collectNamedContourIds,
+  deriveContourIdentifierName,
+  extractFirstStringArg,
+  findConfigProperty,
+  findTrailDefinitions,
+  getNodeCallee,
+  getNodeObject,
+  getNodeProperty,
+  identifierName,
+  isMemberAccessNonComputed,
+  isUserNamespaceReceiverAllowed,
+  offsetToLine,
+  parse,
+} 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(getNodeCallee(node)) === '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 = getNodeObject(element);
+  const property = getNodeProperty(element);
+  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. Define it with contour('${contourName}', ...) and include it in the topo, or fix the contours entry if this is a typo.`,
+  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;

package/src/rules/dead-internal-trail.ts

@@ -0,0 +1,161 @@
+import {
+  collectComposeTargetTrailIds,
+  findConfigProperty,
+  findTrailDefinitions,
+  getNodeValue,
+  getStringValue,
+  isStringLiteral,
+  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 isNonEmptyActivationValue = (onValue: AstNode): boolean => {
+  // Identifier reference (e.g. `on: signalsArray`) — conservatively treat as
+  // having activation to avoid false positives. We can't cheaply resolve what
+  // the identifier binds to, so assume it's a non-empty activation.
+  if (onValue.type === 'Identifier') {
+    return true;
+  }
+  if (onValue.type !== 'ArrayExpression') {
+    return false;
+  }
+  const elements = onValue['elements'] as readonly AstNode[] | undefined;
+  return (elements?.length ?? 0) > 0;
+};
+
+const hasOnActivation = (config: AstNode): boolean => {
+  const onProp = findConfigProperty(config, 'on');
+  const onValue = onProp?.value as AstNode | undefined;
+  return onValue ? isNonEmptyActivationValue(onValue) : false;
+};
+
+const hasExplicitInternalVisibility = (config: AstNode): boolean => {
+  const visibilityProp = findConfigProperty(config, 'visibility');
+  const visibilityValue = visibilityProp?.value as AstNode | undefined;
+  return (
+    !!visibilityValue &&
+    isStringLiteral(visibilityValue) &&
+    getStringValue(visibilityValue) === 'internal'
+  );
+};
+
+/** Check legacy `meta: { internal: true }` convention (mirrors runtime effectiveVisibility). */
+const hasLegacyMetaInternal = (config: AstNode): boolean => {
+  const metaProp = findConfigProperty(config, 'meta');
+  const metaValue = metaProp?.value as AstNode | undefined;
+  if (!metaValue || metaValue.type !== 'ObjectExpression') {
+    return false;
+  }
+  const internalProp = findConfigProperty(metaValue, 'internal');
+  const internalValue = internalProp?.value as AstNode | undefined;
+  return (
+    internalValue?.type === 'BooleanLiteral' &&
+    getNodeValue(internalValue) === true
+  );
+};
+
+const isInternalTrail = (config: AstNode): boolean =>
+  hasExplicitInternalVisibility(config) || hasLegacyMetaInternal(config);
+
+const buildDeadInternalTrailDiagnostic = (
+  trailId: string,
+  filePath: string,
+  line: number
+): WardenDiagnostic => ({
+  filePath,
+  line,
+  message: `Trail "${trailId}" is marked visibility: 'internal' but nothing composes it and it has no on: activation. Internal trails should stay reachable through ctx.compose() or reactive activation.`,
+  rule: 'dead-internal-trail',
+  severity: 'warn',
+});
+
+const checkDeadInternalTrails = (
+  ast: AstNode | null,
+  sourceCode: string,
+  filePath: string,
+  composedTrailIds: ReadonlySet<string>,
+  topoTrailIds?: ReadonlySet<string> | undefined
+): readonly WardenDiagnostic[] => {
+  if (isTestFile(filePath) || !ast) {
+    return [];
+  }
+
+  const diagnostics: WardenDiagnostic[] = [];
+
+  for (const def of findTrailDefinitions(ast)) {
+    if (def.kind !== 'trail' || !isInternalTrail(def.config)) {
+      continue;
+    }
+
+    if (
+      hasOnActivation(def.config) ||
+      composedTrailIds.has(def.id) ||
+      topoTrailIds?.has(def.id)
+    ) {
+      continue;
+    }
+
+    diagnostics.push(
+      buildDeadInternalTrailDiagnostic(
+        def.id,
+        filePath,
+        offsetToLine(sourceCode, def.start)
+      )
+    );
+  }
+
+  return diagnostics;
+};
+
+export const deadInternalTrail: ProjectAwareWardenRule = {
+  check(sourceCode: string, filePath: string): readonly WardenDiagnostic[] {
+    const ast = parse(filePath, sourceCode);
+    return checkDeadInternalTrails(
+      ast,
+      sourceCode,
+      filePath,
+      ast ? collectComposeTargetTrailIds(ast, sourceCode) : new Set<string>()
+    );
+  },
+  checkWithContext(
+    sourceCode: string,
+    filePath: string,
+    context: ProjectContext
+  ): readonly WardenDiagnostic[] {
+    const ast = parse(filePath, sourceCode);
+    const localComposeTargetTrailIds = ast
+      ? collectComposeTargetTrailIds(ast, sourceCode)
+      : new Set<string>();
+    // Union project-wide compose evidence with the file-local evidence rather
+    // than preferring one over the other. The project context only collects
+    // compose edges from registered app topos, so a trail defined in a package
+    // that is scanned but not part of any registered topo (e.g. an internal
+    // child composed in its own module) would be absent from the context set
+    // yet present in the local set. Preferring the context set alone produced a
+    // false dead-internal-trail warning for those same-file compositions.
+    const composeTargetTrailIds = context.composeTargetTrailIds
+      ? new Set<string>([
+          ...context.composeTargetTrailIds,
+          ...localComposeTargetTrailIds,
+        ])
+      : localComposeTargetTrailIds;
+    return checkDeadInternalTrails(
+      ast,
+      sourceCode,
+      filePath,
+      composeTargetTrailIds,
+      context.topoTrailIds
+    );
+  },
+  description:
+    'Warn when an internal trail has no compositions anywhere in the project and no on: activation.',
+  name: 'dead-internal-trail',
+  severity: 'warn',
+};