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

package/src/rules/cross-declarations.ts

@@ -61,10 +61,7 @@ const getStringValue = (node: AstNode): string | null => {
  * Returns the string value if a simple `const <name> = '...'` or `"..."` is
  * found in the source. Returns null for anything more complex.
  */
-const resolveConstString = (
-  name: string,
-  sourceCode: string
-): string | null => {
+const deriveConstString = (name: string, sourceCode: string): string | null => {
   const pattern = new RegExp(
     `const\\s+${name}\\s*=\\s*(?:'([^']*)'|"([^"]*)")`
   );
@@ -84,11 +81,11 @@ const resolveIdentifierElement = (
   if (!name) {
     return null;
   }
-  return resolveConstString(name, sourceCode);
+  return deriveConstString(name, sourceCode);
 };
 
 /** Resolve an array element to a static trail ID when possible. */
-const resolveCrossElementId = (
+const deriveCrossElementId = (
   element: AstNode,
   sourceCode: string
 ): string | null => {
@@ -125,28 +122,62 @@ const getCrossElements = (config: AstNode): readonly AstNode[] | null => {
   return elements ?? null;
 };
 
-/** Collect string IDs from array elements, resolving identifiers when possible. */
-const collectStringIds = (
+interface DeclaredCrosses {
+  /** Statically resolved trail IDs from string literals / const identifiers. */
+  readonly ids: ReadonlySet<string>;
+  /**
+   * True if any element could not be statically resolved (e.g. trail object
+   * reference like `crosses: [showGist]`). When true, "undeclared" diagnostics
+   * are softened from error to warn since the declared set is incomplete.
+   */
+  readonly hasUnresolved: boolean;
+}
+
+/**
+ * Collect string IDs from array elements, resolving identifiers when possible.
+ *
+ * Trail-object references (`crosses: [showGist]`) cannot be resolved at lint
+ * time; they're normalized at runtime by `trail()`. When any entry is
+ * unresolved, `hasUnresolved` is set so callers can soften diagnostics.
+ */
+/** Classify a single element and accumulate into the id set. */
+const classifyCrossElement = (
+  element: AstNode,
+  sourceCode: string,
+  ids: Set<string>
+): boolean => {
+  const resolved = deriveCrossElementId(element, sourceCode);
+  if (!resolved) {
+    // Element could not be statically resolved
+    return true;
+  }
+  ids.add(resolved);
+  return false;
+};
+
+const resolveDeclaredCrossElements = (
   elements: readonly AstNode[],
   sourceCode: string
-): Set<string> => {
+): DeclaredCrosses => {
   const ids = new Set<string>();
+  let hasUnresolved = false;
   for (const element of elements) {
-    const resolved = resolveCrossElementId(element, sourceCode);
-    if (resolved) {
-      ids.add(resolved);
+    if (classifyCrossElement(element, sourceCode, ids)) {
+      hasUnresolved = true;
     }
   }
-  return ids;
+  return { hasUnresolved, ids };
 };
 
-/** Extract string literal elements from a `crosses: [...]` array property. */
+/** Extract declared crosses from a `crosses: [...]` array. */
 const extractDeclaredCrosses = (
   config: AstNode,
   sourceCode: string
-): ReadonlySet<string> => {
+): DeclaredCrosses => {
   const elements = getCrossElements(config);
-  return elements ? collectStringIds(elements, sourceCode) : new Set();
+  return elements
+    ? resolveDeclaredCrossElements(elements, sourceCode)
+    : { hasUnresolved: false, ids: new Set() };
 };
 
 // ---------------------------------------------------------------------------
@@ -173,33 +204,25 @@ const extractMemberPair = (
   return objName && propName ? { objName, propName } : null;
 };
 
-/** Extract the first argument string from a CallExpression's arguments list. */
-const extractFirstStringArg = (node: AstNode): string | null => {
-  const args = node['arguments'] as readonly AstNode[] | undefined;
-  if (!args || args.length === 0) {
-    return null;
-  }
-
-  const [firstArg] = args;
-  if (!firstArg || !isStringLiteral(firstArg)) {
-    return null;
-  }
-
-  return getStringValue(firstArg);
-};
-
 /**
  * Extract the second parameter name from a blaze function node.
  *
- * Handles `(input, ctx) => ...`, `async (input, context) => ...`, and
- * `function(input, ctx) { ... }` forms.
+ * Handles `(input, ctx) => ...`, `async (input, context) => ...`,
+ * `function(input, ctx) { ... }`, and defaulted params like
+ * `(input, ctx = fallback) => ...` (AssignmentPattern whose `.left` is the
+ * Identifier).
  */
 const extractContextParamName = (blazeBody: AstNode): string | null => {
   const params = blazeBody['params'] as readonly AstNode[] | undefined;
   if (!params || params.length < 2) {
     return null;
   }
-  return identifierName(params[1]);
+  const [, param] = params;
+  if (param?.type === 'AssignmentPattern') {
+    const { left } = param as unknown as { left?: AstNode };
+    return identifierName(left);
+  }
+  return identifierName(param);
 };
 
 /** Check if a callee is a member-style cross call: <ctxName>.cross(...). */
@@ -211,38 +234,151 @@ const isMemberCrossCall = (
   return !!pair && ctxNames.has(pair.objName) && pair.propName === 'cross';
 };
 
-/**
- * Check if a node is a `<ctxName>.cross(...)` call and return the string trail ID.
- *
- * Also matches bare `cross(...)` calls from destructuring.
- */
-const extractCrossCallId = (
+interface ExtractedCrossCall {
+  readonly ids: readonly string[];
+  readonly hasUnresolved: boolean;
+}
+
+const unresolvedCross = (): ExtractedCrossCall => ({
+  hasUnresolved: true,
+  ids: [],
+});
+
+const resolveBatchCrossTupleTarget = (
+  element: AstNode,
+  sourceCode: string
+): string | null => {
+  if (element.type !== 'ArrayExpression') {
+    return null;
+  }
+
+  const tupleElements = element['elements'] as readonly AstNode[] | undefined;
+  const [target] = tupleElements ?? [];
+  return target ? deriveCrossElementId(target, sourceCode) : null;
+};
+
+const collectBatchCrossId = (
+  element: AstNode,
+  sourceCode: string,
+  ids: string[]
+): boolean => {
+  const resolved = resolveBatchCrossTupleTarget(element, sourceCode);
+  if (!resolved) {
+    return true;
+  }
+  ids.push(resolved);
+  return false;
+};
+
+/** Extract statically-resolved trail IDs from `ctx.cross([[trail, input], ...])`. */
+const extractBatchCrossIds = (
+  firstArg: AstNode | undefined,
+  sourceCode: string
+): ExtractedCrossCall | null => {
+  if (firstArg?.type !== 'ArrayExpression') {
+    return null;
+  }
+
+  const elements = firstArg['elements'] as readonly AstNode[] | undefined;
+  const ids: string[] = [];
+  let hasUnresolved = false;
+
+  for (const element of elements ?? []) {
+    if (collectBatchCrossId(element, sourceCode, ids)) {
+      hasUnresolved = true;
+    }
+  }
+
+  return { hasUnresolved, ids };
+};
+
+const extractDirectCrossIds = (
+  firstArg: AstNode | undefined
+): ExtractedCrossCall | null => {
+  if (!firstArg || !isStringLiteral(firstArg)) {
+    return null;
+  }
+
+  const value = getStringValue(firstArg);
+  return value ? { hasUnresolved: false, ids: [value] } : unresolvedCross();
+};
+
+const isCrossCallExpression = (
+  callee: AstNode,
+  ctxNames: ReadonlySet<string>
+): boolean =>
+  isMemberCrossCall(callee, ctxNames) || identifierName(callee) === 'cross';
+
+const extractCrossFirstArg = (node: AstNode): AstNode | undefined => {
+  const args = node['arguments'] as readonly AstNode[] | undefined;
+  return args?.[0];
+};
+
+const resolveCrossCallNode = (
   node: AstNode,
   ctxNames: ReadonlySet<string>
-): string | null => {
+): AstNode | null => {
   if (node.type !== 'CallExpression') {
     return null;
   }
 
   const callee = node['callee'] as AstNode | undefined;
-  if (!callee) {
+  if (!callee || !isCrossCallExpression(callee, ctxNames)) {
     return null;
   }
 
-  if (isMemberCrossCall(callee, ctxNames)) {
-    return extractFirstStringArg(node);
+  return node;
+};
+
+const resolveCrossCallTargets = (
+  firstArg: AstNode | undefined,
+  sourceCode: string
+): ExtractedCrossCall => {
+  const direct = extractDirectCrossIds(firstArg);
+  if (direct) {
+    return direct;
   }
 
-  if (identifierName(callee) === 'cross') {
-    return extractFirstStringArg(node);
+  const batch = extractBatchCrossIds(firstArg, sourceCode);
+  return batch ?? unresolvedCross();
+};
+
+/**
+ * Check if a node is a `<ctxName>.cross(...)` call and return any statically
+ * resolvable target IDs.
+ *
+ * Also matches bare `cross(...)` calls from destructuring. When the first
+ * argument is a non-string expression (e.g. a trail object identifier like
+ * `ctx.cross(showGist, input)`), marks the call as unresolved so callers can
+ * track that a cross call exists but its target cannot be statically resolved.
+ */
+const extractCrossCall = (
+  node: AstNode,
+  ctxNames: ReadonlySet<string>,
+  sourceCode: string
+): ExtractedCrossCall | null => {
+  const crossCall = resolveCrossCallNode(node, ctxNames);
+  if (!crossCall) {
+    return null;
   }
 
-  return null;
+  return resolveCrossCallTargets(extractCrossFirstArg(crossCall), sourceCode);
 };
 
-/** Build the set of context parameter names to match against. */
+/**
+ * Build the set of context parameter names to match against.
+ *
+ * Returns ONLY the actual second-parameter name from the blaze signature.
+ * No seeded defaults: if the blaze has no second parameter, the returned set
+ * is empty and no `ctx.cross(...)` / `context.cross(...)` calls are tracked
+ * for that blaze. An unrelated closure-scoped `ctx` identifier is not the
+ * trail context and must not be treated as one.
+ *
+ * Mirrors `fires-declarations.ts` and `resource-declarations.ts` for the same
+ * reason.
+ */
 const buildCtxNames = (body: AstNode): ReadonlySet<string> => {
-  const ctxNames = new Set(['ctx', 'context']);
+  const ctxNames = new Set<string>();
   const paramName = extractContextParamName(body);
   if (paramName) {
     ctxNames.add(paramName);
@@ -250,22 +386,59 @@ const buildCtxNames = (body: AstNode): ReadonlySet<string> => {
   return ctxNames;
 };
 
+interface CalledCrosses {
+  /** Statically resolved trail IDs from string literal arguments. */
+  readonly ids: ReadonlySet<string>;
+  /**
+   * True if any `ctx.cross()` call used a non-string first argument (e.g.
+   * `ctx.cross(showGist, input)`). When true, "unused declaration"
+   * diagnostics are softened since the call may target a declared entry.
+   */
+  readonly hasUnresolved: boolean;
+}
+
+/** Collect cross call results from a single blaze body. */
+const collectCrossCallsFromBody = (
+  body: AstNode,
+  ids: Set<string>,
+  sourceCode: string
+): boolean => {
+  const ctxNames = buildCtxNames(body);
+  let foundUnresolved = false;
+
+  walk(body, (node) => {
+    const extracted = extractCrossCall(node, ctxNames, sourceCode);
+    if (!extracted) {
+      return;
+    }
+
+    if (extracted.hasUnresolved) {
+      foundUnresolved = true;
+    }
+
+    for (const id of extracted.ids) {
+      ids.add(id);
+    }
+  });
+
+  return foundUnresolved;
+};
+
 /** Walk blaze bodies and collect all statically resolvable ctx.cross() trail IDs. */
-const extractCalledCrosses = (config: AstNode): ReadonlySet<string> => {
+const extractCalledCrosses = (
+  config: AstNode,
+  sourceCode: string
+): CalledCrosses => {
   const ids = new Set<string>();
+  let hasUnresolved = false;
 
   for (const body of findBlazeBodies(config)) {
-    const ctxNames = buildCtxNames(body);
-
-    walk(body, (node) => {
-      const id = extractCrossCallId(node, ctxNames);
-      if (id) {
-        ids.add(id);
-      }
-    });
+    if (collectCrossCallsFromBody(body, ids, sourceCode)) {
+      hasUnresolved = true;
+    }
   }
 
-  return ids;
+  return { hasUnresolved, ids };
 };
 
 // ---------------------------------------------------------------------------
@@ -276,13 +449,16 @@ const buildUndeclaredDiagnostic = (
   trailId: string,
   crossedId: string,
   filePath: string,
-  line: number
+  line: number,
+  softened = false
 ): WardenDiagnostic => ({
   filePath,
   line,
-  message: `Trail "${trailId}": ctx.cross('${crossedId}') called but '${crossedId}' is not declared in crosses`,
+  message: softened
+    ? `Trail "${trailId}": ctx.cross('${crossedId}') called but '${crossedId}' is not declared in crosses (may be declared via trail object references)`
+    : `Trail "${trailId}": ctx.cross('${crossedId}') called but '${crossedId}' is not declared in crosses`,
   rule: 'cross-declarations',
-  severity: 'error',
+  severity: softened ? 'warn' : 'error',
 });
 
 const buildUnusedDiagnostic = (
@@ -306,13 +482,24 @@ const buildUnusedDiagnostic = (
 const reportUndeclared = (
   called: ReadonlySet<string>,
   declared: ReadonlySet<string>,
-  ctx: { trailId: string; filePath: string; line: number },
+  ctx: {
+    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)
+        buildUndeclaredDiagnostic(
+          ctx.trailId,
+          id,
+          ctx.filePath,
+          ctx.line,
+          ctx.softened
+        )
       );
     }
   }
@@ -341,17 +528,38 @@ const checkTrailDefinition = (
   diagnostics: WardenDiagnostic[]
 ): void => {
   const declared = extractDeclaredCrosses(def.config, sourceCode);
-  const called = extractCalledCrosses(def.config);
-
-  if (declared.size === 0 && called.size === 0) {
+  const called = extractCalledCrosses(def.config, sourceCode);
+
+  if (
+    declared.ids.size === 0 &&
+    !declared.hasUnresolved &&
+    called.ids.size === 0 &&
+    !called.hasUnresolved
+  ) {
     return;
   }
 
   const line = offsetToLine(sourceCode, def.start);
   const ctx = { filePath, line, trailId: def.id };
 
-  reportUndeclared(called, declared, ctx, diagnostics);
-  reportUnused(declared, called, ctx, diagnostics);
+  // 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
+  );
+
+  // When all ctx.cross() calls are statically resolved, report unused
+  // declarations. When some calls use trail object references (unresolved),
+  // skip — a declared string like 'gist.show' might be the target of an
+  // unresolved `ctx.cross(showGist)` call, producing false positives.
+  if (!called.hasUnresolved) {
+    reportUnused(declared.ids, called.ids, ctx, diagnostics);
+  }
 };
 
 // ---------------------------------------------------------------------------

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

@@ -0,0 +1,141 @@
+import {
+  collectCrossTargetTrailIds,
+  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 crosses it and it has no on: activation. Internal trails should stay reachable through ctx.cross() or reactive activation.`,
+  rule: 'dead-internal-trail',
+  severity: 'warn',
+});
+
+const checkDeadInternalTrails = (
+  ast: AstNode | null,
+  sourceCode: string,
+  filePath: string,
+  crossedTrailIds: 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) || crossedTrailIds.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 ? collectCrossTargetTrailIds(ast, sourceCode) : new Set<string>()
+    );
+  },
+  checkWithContext(
+    sourceCode: string,
+    filePath: string,
+    context: ProjectContext
+  ): readonly WardenDiagnostic[] {
+    const ast = parse(filePath, sourceCode);
+    const localCrossTargetTrailIds = ast
+      ? collectCrossTargetTrailIds(ast, sourceCode)
+      : new Set<string>();
+    return checkDeadInternalTrails(
+      ast,
+      sourceCode,
+      filePath,
+      context.crossTargetTrailIds ?? localCrossTargetTrailIds
+    );
+  },
+  description:
+    'Warn when an internal trail has no crossings anywhere in the project and no on: activation.',
+  name: 'dead-internal-trail',
+  severity: 'warn',
+};