@ontrails/warden 1.0.0-beta.2 → 1.0.0-beta.21

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

@@ -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,
@@ -92,7 +153,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 +172,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 +180,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 +203,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,
+  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. 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,154 @@
+import {
+  collectComposeTargetTrailIds,
+  findConfigProperty,
+  findTrailDefinitions,
+  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' &&
+    (internalValue as unknown as { value: boolean }).value === 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>
+): 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)) {
+      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
+    );
+  },
+  description:
+    'Warn when an internal trail has no compositions anywhere in the project and no on: activation.',
+  name: 'dead-internal-trail',
+  severity: 'warn',
+};

package/src/rules/draft-file-marking.ts

@@ -0,0 +1,160 @@
+import { isDraftId } from '@ontrails/core';
+
+import { isDraftMarkedFile } from '../draft.js';
+import {
+  collectFrameworkDraftPrefixConstantOffsets,
+  findStringLiterals,
+  hasIgnoreCommentOnLine,
+  offsetToLine,
+  parse,
+  splitSourceLines,
+} from './ast.js';
+import type { StringLiteralMatch } from './ast.js';
+import type { WardenDiagnostic, WardenRule } from './types.js';
+
+const messageForMissingMarker = (draftId: string): string =>
+  `Draft id "${draftId}" appears in source, but the file is not draft-marked. ` +
+  'Rename it with an _draft. prefix or a .draft. trailing segment.';
+
+const makeDiagnostic = (
+  sourceCode: string,
+  filePath: string,
+  start: number,
+  message: string,
+  severity: WardenDiagnostic['severity']
+): WardenDiagnostic => ({
+  filePath,
+  line: offsetToLine(sourceCode, start),
+  message,
+  rule: 'draft-file-marking',
+  severity,
+});
+
+const collectDraftMatches = (
+  sourceCode: string,
+  filePath: string,
+  ast: NonNullable<ReturnType<typeof parse>>
+): StringLiteralMatch[] => {
+  const frameworkConstantOffsets = collectFrameworkDraftPrefixConstantOffsets(
+    ast,
+    filePath
+  );
+  const lines = splitSourceLines(sourceCode);
+  return findStringLiterals(ast, (value) => isDraftId(value)).filter(
+    (match) => {
+      if (frameworkConstantOffsets.has(match.start)) {
+        return false;
+      }
+      if (
+        hasIgnoreCommentOnLine(lines, offsetToLine(sourceCode, match.start))
+      ) {
+        return false;
+      }
+      return true;
+    }
+  );
+};
+
+const draftMissingMarkerDiagnostic = (
+  sourceCode: string,
+  filePath: string,
+  ast: NonNullable<ReturnType<typeof parse>>
+): WardenDiagnostic | null => {
+  const draftMatches = collectDraftMatches(sourceCode, filePath, ast);
+  if (!draftMatches.length || isDraftMarkedFile(filePath)) {
+    return null;
+  }
+
+  const [first] = draftMatches;
+  if (!first) {
+    return null;
+  }
+
+  return makeDiagnostic(
+    sourceCode,
+    filePath,
+    first.start,
+    messageForMissingMarker(first.value),
+    'error'
+  );
+};
+
+const draftMarkedWithoutIdsDiagnostic = (
+  filePath: string,
+  ast: NonNullable<ReturnType<typeof parse>>
+): WardenDiagnostic | null => {
+  // Deciding whether the file's `_draft.` marker is still warranted is a
+  // question about *all* draft ids present in source, not just the unsuppressed
+  // ones. Pragma-suppressed ids still justify a draft-marked filename — a user
+  // intentionally silencing them has not removed the draft content. We
+  // therefore filter only the framework-constant declarations (which are not
+  // draft ids at all) and bypass the pragma filter that `collectDraftMatches`
+  // applies.
+  const frameworkConstantOffsets = collectFrameworkDraftPrefixConstantOffsets(
+    ast,
+    filePath
+  );
+  const unsuppressedDraftIds = findStringLiterals(ast, (value) =>
+    isDraftId(value)
+  ).filter((match) => !frameworkConstantOffsets.has(match.start));
+
+  if (unsuppressedDraftIds.length > 0) {
+    return null;
+  }
+
+  if (!isDraftMarkedFile(filePath)) {
+    return null;
+  }
+
+  return {
+    filePath,
+    line: 1,
+    message:
+      'File is draft-marked but no longer contains draft ids. Remove the draft filename marker or finish the promotion cleanup.',
+    rule: 'draft-file-marking',
+    severity: 'warn',
+  };
+};
+
+const collectDraftFileMarkingDiagnostics = (
+  sourceCode: string,
+  filePath: string,
+  ast: NonNullable<ReturnType<typeof parse>>
+): WardenDiagnostic[] => {
+  const missingMarkerDiagnostic = draftMissingMarkerDiagnostic(
+    sourceCode,
+    filePath,
+    ast
+  );
+  if (missingMarkerDiagnostic) {
+    return [missingMarkerDiagnostic];
+  }
+
+  const markedWithoutIdsDiagnostic = draftMarkedWithoutIdsDiagnostic(
+    filePath,
+    ast
+  );
+  if (markedWithoutIdsDiagnostic) {
+    return [markedWithoutIdsDiagnostic];
+  }
+
+  return [];
+};
+
+/**
+ * Ensures files containing draft ids are visibly marked as draft-bearing files.
+ */
+export const draftFileMarking: WardenRule = {
+  check(sourceCode: string, filePath: string): readonly WardenDiagnostic[] {
+    const ast = parse(filePath, sourceCode);
+    if (!ast) {
+      return [];
+    }
+
+    return collectDraftFileMarkingDiagnostics(sourceCode, filePath, ast);
+  },
+  description:
+    'Require draft-bearing files to use _draft.* or *.draft.* filename markers.',
+  name: 'draft-file-marking',
+  severity: 'error',
+};