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

package/src/rules/fires-declarations.ts

@@ -0,0 +1,735 @@
+/**
+ * Validates that `ctx.fire()` calls match the declared `fires` array.
+ *
+ * Statically analyzes trail `blaze` functions to find `ctx.fire(signal, ...)`
+ * calls and compares locally-resolved `Signal` values against the `fires: [...]`
+ * declaration in the trail config. Reports errors for undeclared fires, string
+ * fire calls that no longer match the public runtime API, and warnings for
+ * unused declarations.
+ *
+ * Mirrors `composes-declarations` structurally — same extraction, same reporting
+ * shape, same const-identifier resolution, same context-parameter handling.
+ */
+
+import {
+  buildSignalIdentifierResolver,
+  deriveConstString,
+  extractStringLiteral,
+  findBlazeBodies,
+  findConfigProperty,
+  findTrailDefinitions,
+  getNodeBodyNode,
+  getNodeBodyStatements,
+  getNodeDeclarations,
+  getNodeId,
+  getNodeInit,
+  getNodeKey,
+  getNodeKind,
+  getNodeLeft,
+  getNodeObject,
+  getNodeProperties,
+  getNodeProperty,
+  getNodeValueNode,
+  identifierName,
+  offsetToLine,
+  parse,
+  walkScope,
+} from './ast.js';
+import type { AstNode, SignalIdentifierResolver } from './ast.js';
+import { isTestFile } from './scan.js';
+import type { WardenDiagnostic, WardenRule } from './types.js';
+
+// ---------------------------------------------------------------------------
+// Const identifier resolution
+// ---------------------------------------------------------------------------
+
+/**
+ * Resolve an array element to a static signal ID when possible.
+ *
+ * Returns null for entries the rule can't statically resolve. Unresolved entries
+ * are not proof of missingness, but they also do not suppress diagnostics for
+ * statically resolved `ctx.fire()` calls that target different signals.
+ */
+const resolveFireElementId = (
+  element: AstNode,
+  sourceCode: string,
+  signalIds: SignalIdentifierResolver
+): string | null => {
+  const literalValue = extractStringLiteral(element);
+  if (literalValue !== null) {
+    return literalValue;
+  }
+
+  if (element.type === 'Identifier') {
+    const name = identifierName(element);
+    if (name) {
+      const resolved = signalIds.resolve(element);
+      if (resolved.kind === 'signal' || resolved.kind === 'string') {
+        return resolved.id;
+      }
+      if (resolved.kind === 'shadowed') {
+        return null;
+      }
+      return deriveConstString(name, sourceCode);
+    }
+  }
+
+  return null;
+};
+
+// ---------------------------------------------------------------------------
+// Declared fires extraction
+// ---------------------------------------------------------------------------
+
+/** Extract the ArrayExpression elements from a config's `fires` property. */
+const getFiresElements = (config: AstNode): readonly AstNode[] | null => {
+  const firesProp = findConfigProperty(config, 'fires');
+  if (!firesProp) {
+    return null;
+  }
+
+  const arrayNode = firesProp.value;
+  if (!arrayNode || (arrayNode as AstNode).type !== 'ArrayExpression') {
+    return null;
+  }
+
+  const elements = (arrayNode as AstNode)['elements'] as
+    | readonly AstNode[]
+    | undefined;
+  return elements ?? null;
+};
+
+interface DeclaredFires {
+  /** Statically resolved signal ids from string literals / const identifiers. */
+  readonly ids: ReadonlySet<string>;
+  /** True if any element could not be statically resolved (e.g. Signal value). */
+  readonly hasUnresolved: boolean;
+}
+
+/**
+ * Extract declared fires from a `fires: [...]` array.
+ *
+ * Object-form entries (`fires: [someSignal]`) can be unresolved at lint time
+ * when they come from imports the rule cannot prove. Those unresolved entries
+ * do not soften concrete undeclared `ctx.fire()` calls; this mirrors
+ * `composes-declarations` and keeps real drift hard-failing.
+ */
+const resolveDeclaredFiresElements = (
+  elements: readonly AstNode[],
+  sourceCode: string,
+  signalIds: SignalIdentifierResolver
+): DeclaredFires => {
+  const ids = new Set<string>();
+  let hasUnresolved = false;
+  for (const element of elements) {
+    const resolved = resolveFireElementId(element, sourceCode, signalIds);
+    if (resolved) {
+      ids.add(resolved);
+    } else {
+      hasUnresolved = true;
+    }
+  }
+  return { hasUnresolved, ids };
+};
+
+const extractDeclaredFires = (
+  config: AstNode,
+  sourceCode: string,
+  signalIds: SignalIdentifierResolver
+): DeclaredFires => {
+  const elements = getFiresElements(config);
+  return elements
+    ? resolveDeclaredFiresElements(elements, sourceCode, signalIds)
+    : { hasUnresolved: false, ids: new Set() };
+};
+
+// ---------------------------------------------------------------------------
+// Called fires extraction — member expression helpers
+// ---------------------------------------------------------------------------
+
+const MEMBER_TYPES = new Set(['StaticMemberExpression', 'MemberExpression']);
+
+/** Extract object and property Identifier names from a MemberExpression. */
+const extractMemberPair = (
+  callee: AstNode
+): { objName: string; propName: string } | null => {
+  if (!MEMBER_TYPES.has(callee.type)) {
+    return null;
+  }
+
+  const objName = identifierName(getNodeObject(callee));
+  const propName = identifierName(getNodeProperty(callee));
+
+  return objName && propName ? { objName, propName } : null;
+};
+
+/**
+ * Extract the second parameter node from a blaze function node.
+ *
+ * Handles `(input, ctx) => ...`, `async (input, context) => ...`,
+ * `function(input, ctx) { ... }`, and parameter-level destructuring
+ * like `(input, { fire }) => ...`.
+ */
+const extractContextParamNode = (blazeBody: AstNode): AstNode | null => {
+  const params = blazeBody['params'] as readonly AstNode[] | undefined;
+  if (!params || params.length < 2) {
+    return null;
+  }
+  return params[1] ?? null;
+};
+
+/** Extract the local name bound to `fire` inside an ObjectPattern Property. */
+const extractFireLocalName = (prop: AstNode): string | null => {
+  if (prop.type !== 'Property') {
+    return null;
+  }
+  const key = getNodeKey(prop);
+  const value = getNodeValueNode(prop);
+  const keyName = identifierName(key);
+  if (keyName !== 'fire') {
+    return null;
+  }
+  // `{ fire }` → key and value are the same Identifier (shorthand).
+  // `{ fire: emit }` → value is a distinct Identifier.
+  return identifierName(value) ?? keyName;
+};
+
+/** Collect `fire` local names from an ObjectPattern's properties into `names`. */
+const collectFireNamesFromPattern = (
+  pattern: AstNode,
+  names: Set<string>
+): void => {
+  const properties = getNodeProperties(pattern);
+  if (!properties) {
+    return;
+  }
+  for (const prop of properties) {
+    const localName = extractFireLocalName(prop);
+    if (localName) {
+      names.add(localName);
+    }
+  }
+};
+
+/**
+ * Extract the second parameter name from a blaze function node.
+ *
+ * Returns null when the parameter is not a plain Identifier (e.g. when the
+ * author destructures `{ fire }` in the parameter list). Parameter-level
+ * destructuring is handled separately by `collectParamFireNames`.
+ *
+ * Also handles defaulted parameters like `(input, ctx = fallback) => ...`
+ * (AssignmentPattern whose `.left` is the Identifier). Without this, valid
+ * signatures would silently drop out of ctx-access analysis.
+ */
+const extractContextParamName = (blazeBody: AstNode): string | null => {
+  const param = extractContextParamNode(blazeBody);
+  if (!param) {
+    return null;
+  }
+  if (param.type === 'AssignmentPattern') {
+    const left = getNodeLeft(param);
+    return identifierName(left);
+  }
+  return identifierName(param);
+};
+
+/**
+ * Collect `fire` local names bound via parameter-level destructuring.
+ *
+ * Recognizes `(input, { fire }) => ...` and `(input, { fire: emit }) => ...`.
+ * When the blaze author destructures in the parameter list, there is no
+ * enclosing `ctx` identifier to track — we seed the fire local set directly
+ * from the ObjectPattern in `params[1]`.
+ */
+const collectParamFireNames = (body: AstNode): ReadonlySet<string> => {
+  const param = extractContextParamNode(body);
+  if (!param || param.type !== 'ObjectPattern') {
+    return new Set();
+  }
+  const names = new Set<string>();
+  collectFireNamesFromPattern(param, names);
+  return names;
+};
+
+/** Check if a callee is a member-style fire call: <ctxName>.fire(...). */
+const isMemberFireCall = (
+  callee: AstNode,
+  ctxNames: ReadonlySet<string>
+): boolean => {
+  const pair = extractMemberPair(callee);
+  return !!pair && ctxNames.has(pair.objName) && pair.propName === 'fire';
+};
+
+/**
+ * Check if a node is a `<ctxName>.fire(...)` call.
+ *
+ * Also matches bare `<fireLocalName>(...)` calls, but only when the local name
+ * was verifiably destructured from the trail context (e.g. `const { fire } = ctx`
+ * or `const { fire: emit } = ctx`). Unrelated local `fire()` helpers are
+ * ignored — see `collectDestructuredFireNames`.
+ */
+const isTrackedFireCallee = (
+  callee: AstNode,
+  ctxNames: ReadonlySet<string>,
+  fireLocalNames: ReadonlySet<string>
+): boolean => {
+  if (isMemberFireCall(callee, ctxNames)) {
+    return true;
+  }
+  const calleeName = identifierName(callee);
+  return !!calleeName && fireLocalNames.has(calleeName);
+};
+
+interface FireCallArg {
+  readonly id: string | null;
+  readonly stringId: string | null;
+  readonly unresolved: boolean;
+}
+
+const firstCallArg = (node: AstNode): AstNode | null => {
+  const args = node['arguments'] as readonly AstNode[] | undefined;
+  return args?.[0] ?? null;
+};
+
+const resolveFireCallArg = (
+  arg: AstNode | null,
+  sourceCode: string,
+  signalIds: SignalIdentifierResolver
+): FireCallArg => {
+  if (!arg) {
+    return { id: null, stringId: null, unresolved: true };
+  }
+
+  const stringId = extractStringLiteral(arg);
+  if (stringId !== null) {
+    return { id: stringId, stringId, unresolved: false };
+  }
+
+  if (arg.type === 'Identifier') {
+    const name = identifierName(arg);
+    if (!name) {
+      return { id: null, stringId: null, unresolved: true };
+    }
+    const resolved = signalIds.resolve(arg);
+    if (resolved.kind === 'signal') {
+      return { id: resolved.id, stringId: null, unresolved: false };
+    }
+    if (resolved.kind === 'string') {
+      return { id: resolved.id, stringId: resolved.id, unresolved: false };
+    }
+    if (resolved.kind === 'shadowed') {
+      return { id: null, stringId: null, unresolved: true };
+    }
+    const constStringId = deriveConstString(name, sourceCode);
+    if (constStringId) {
+      return { id: constStringId, stringId: constStringId, unresolved: false };
+    }
+  }
+
+  return { id: null, stringId: null, unresolved: true };
+};
+
+const extractFireCallId = (
+  node: AstNode,
+  ctxNames: ReadonlySet<string>,
+  fireLocalNames: ReadonlySet<string>,
+  sourceCode: string,
+  signalIds: SignalIdentifierResolver
+): FireCallArg | null => {
+  if (node.type !== 'CallExpression') {
+    return null;
+  }
+  const callee = node['callee'] as AstNode | undefined;
+  if (!callee) {
+    return null;
+  }
+  return isTrackedFireCallee(callee, ctxNames, fireLocalNames)
+    ? resolveFireCallArg(firstCallArg(node), sourceCode, signalIds)
+    : null;
+};
+
+/**
+ * Walk a blaze body and collect local names bound to `ctx.fire` via destructure.
+ *
+ * Recognizes:
+ *   - `const { fire } = ctx;` → adds `fire`
+ *   - `const { fire: emit } = context;` → adds `emit`
+ *
+ * Only destructures whose init is one of the tracked ctx parameter names are
+ * accepted. This prevents unrelated local `fire` helpers from being treated as
+ * calls into the trail context.
+ */
+/** Check if a VariableDeclarator destructures from a known ctx identifier. */
+const getCtxDestructurePattern = (
+  node: AstNode,
+  ctxNames: ReadonlySet<string>
+): AstNode | null => {
+  if (node.type !== 'VariableDeclarator') {
+    return null;
+  }
+  const id = getNodeId(node);
+  const init = getNodeInit(node);
+  if (!id || id.type !== 'ObjectPattern' || !init) {
+    return null;
+  }
+  const initName = identifierName(init);
+  if (!initName || !ctxNames.has(initName)) {
+    return null;
+  }
+  return id;
+};
+
+/**
+ * Collect `fire` local names destructured from ctx at the TOP LEVEL of the
+ * blaze body. Destructures inside nested functions are intentionally ignored
+ * to avoid leaking nested-scope bindings into the outer blaze scope — a
+ * `const { fire } = ctx` inside a nested helper should not cause an outer
+ * bare `fire('x')` to be treated as a ctx-bound call.
+ *
+ * Tradeoff: nested-scope destructures lose tracking entirely. Calls inside
+ * nested functions that rely on their own destructure will not be analyzed.
+ * This is a conservative precision loss; a full scope walker is a follow-up.
+ *
+ * Tradeoff: only `const` destructures are tracked. `let` and `var` bindings
+ * allow reassignment (`let { fire } = ctx; fire = other; fire('x')`) which
+ * this flow-insensitive walker cannot follow. Skipping them trades a small
+ * amount of precision — `let { fire } = ctx` is rare — for eliminating a
+ * class of false positives. The runtime + signal-id compose-check still
+ * validate real undeclared fires.
+ */
+/** Get the top-level statements of a blaze function's BlockStatement body. */
+const getTopLevelStatements = (body: AstNode): readonly AstNode[] => {
+  const blockBody = getNodeBodyNode(body);
+  if (!blockBody || blockBody.type !== 'BlockStatement') {
+    return [];
+  }
+  return getNodeBodyStatements(blockBody);
+};
+
+/** Collect fire-local names from a single top-level VariableDeclaration. */
+const collectFireNamesFromDeclaration = (
+  stmt: AstNode,
+  ctxNames: ReadonlySet<string>,
+  names: Set<string>
+): void => {
+  if (stmt.type !== 'VariableDeclaration') {
+    return;
+  }
+  // Only track `const` destructures. `let` and `var` allow reassignment that
+  // a single-pass walker cannot track, so `let { fire } = ctx; fire = other;
+  // fire('x')` would otherwise be a false positive. Skipping non-const is a
+  // small precision loss (see TSDoc on `collectDestructuredFireNames`) in
+  // exchange for eliminating that class of false positives.
+  const kind = getNodeKind(stmt);
+  if (kind !== 'const') {
+    return;
+  }
+  const declarations = getNodeDeclarations(stmt) ?? [];
+  for (const decl of declarations) {
+    const pattern = getCtxDestructurePattern(decl, ctxNames);
+    if (pattern) {
+      collectFireNamesFromPattern(pattern, names);
+    }
+  }
+};
+
+const collectDestructuredFireNames = (
+  body: AstNode,
+  ctxNames: ReadonlySet<string>
+): ReadonlySet<string> => {
+  const names = new Set<string>();
+  for (const stmt of getTopLevelStatements(body)) {
+    collectFireNamesFromDeclaration(stmt, ctxNames, names);
+  }
+  return names;
+};
+
+/**
+ * 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.fire(...)` / `context.fire(...)` calls are tracked
+ * for that blaze. An unrelated closure-scoped `ctx` identifier is not the
+ * trail context and must not be treated as one.
+ */
+const buildCtxNames = (body: AstNode): ReadonlySet<string> => {
+  const ctxNames = new Set<string>();
+  const paramName = extractContextParamName(body);
+  if (paramName) {
+    ctxNames.add(paramName);
+  }
+  return ctxNames;
+};
+
+/**
+ * Walk blaze bodies and collect all statically resolvable ctx.fire() signal IDs.
+ *
+ * Traversal uses `walkScope`, which stops at nested function boundaries
+ * (FunctionDeclaration, FunctionExpression, ArrowFunctionExpression). This
+ * mirrors the top-level-only behavior of `collectDestructuredFireNames` and
+ * avoids false positives when a nested function parameter shadows `ctx` or a
+ * destructured `fire` local:
+ *
+ * ```ts
+ * blaze: async (_, ctx) => {
+ *   const { fire } = ctx;
+ *   function nested(fire) { fire(orderPlaced); } // ignored — shadowed
+ *   function other(ctx)  { ctx.fire(orderPlaced); } // ignored — shadowed
+ *   return Result.ok({});
+ * }
+ * ```
+ *
+ * Tradeoff: legitimate helper-scoped fire calls are not statically analyzed
+ * today. This includes both direct `ctx.fire(...)` inside a nested helper and
+ * helper-local destructures like `const { fire } = ctx` inside that helper.
+ * The runtime + signal-id compose-check still validate them; the warden just
+ * can't prove them at lint time. A fuller helper-aware scope walker remains
+ * follow-up work if this precision loss becomes meaningful in practice.
+ */
+interface CalledFires {
+  readonly hasUnresolved: boolean;
+  readonly ids: ReadonlySet<string>;
+  readonly stringIds: ReadonlySet<string>;
+}
+
+const mergeCalledFires = (
+  target: {
+    hasUnresolved: boolean;
+    ids: Set<string>;
+    stringIds: Set<string>;
+  },
+  source: CalledFires
+): void => {
+  for (const id of source.ids) {
+    target.ids.add(id);
+  }
+  for (const id of source.stringIds) {
+    target.stringIds.add(id);
+  }
+  target.hasUnresolved = target.hasUnresolved || source.hasUnresolved;
+};
+
+const extractCalledFiresFromBody = (
+  body: AstNode,
+  sourceCode: string,
+  signalIds: SignalIdentifierResolver
+): CalledFires => {
+  const ids = new Set<string>();
+  const stringIds = new Set<string>();
+  let hasUnresolved = false;
+  const ctxNames = buildCtxNames(body);
+  const bodyFireNames = collectDestructuredFireNames(body, ctxNames);
+  const paramFireNames = collectParamFireNames(body);
+  const fireLocalNames = new Set<string>([...bodyFireNames, ...paramFireNames]);
+
+  walkScope(body, (node) => {
+    const call = extractFireCallId(
+      node,
+      ctxNames,
+      fireLocalNames,
+      sourceCode,
+      signalIds
+    );
+    if (!call) {
+      return;
+    }
+    if (call.id) {
+      ids.add(call.id);
+    }
+    if (call.stringId) {
+      stringIds.add(call.stringId);
+    }
+    if (call.unresolved) {
+      hasUnresolved = true;
+    }
+  });
+
+  return { hasUnresolved, ids, stringIds };
+};
+
+const extractCalledFires = (
+  config: AstNode,
+  sourceCode: string,
+  signalIds: SignalIdentifierResolver
+): CalledFires => {
+  const ids = new Set<string>();
+  const stringIds = new Set<string>();
+  const merged = { hasUnresolved: false, ids, stringIds };
+
+  for (const body of findBlazeBodies(config)) {
+    mergeCalledFires(
+      merged,
+      extractCalledFiresFromBody(body, sourceCode, signalIds)
+    );
+  }
+
+  return { hasUnresolved: merged.hasUnresolved, ids, stringIds };
+};
+
+// ---------------------------------------------------------------------------
+// Diagnostic builders
+// ---------------------------------------------------------------------------
+
+const buildUndeclaredDiagnostic = (
+  trailId: string,
+  signalId: string,
+  filePath: string,
+  line: number
+): WardenDiagnostic => ({
+  filePath,
+  line,
+  message: `Trail "${trailId}": ctx.fire('${signalId}') called but '${signalId}' is not declared in fires`,
+  rule: 'fires-declarations',
+  severity: 'error',
+});
+
+const buildStringFireDiagnostic = (
+  trailId: string,
+  signalId: string,
+  filePath: string,
+  line: number
+): WardenDiagnostic => ({
+  filePath,
+  line,
+  message: `Trail "${trailId}": ctx.fire('${signalId}') uses a string signal id; pass the Signal value to ctx.fire(signal, payload)`,
+  rule: 'fires-declarations',
+  severity: 'error',
+});
+
+const buildUnusedDiagnostic = (
+  trailId: string,
+  signalId: string,
+  filePath: string,
+  line: number
+): WardenDiagnostic => ({
+  filePath,
+  line,
+  message: `Trail "${trailId}": '${signalId}' declared in fires but ctx.fire('${signalId}') never called`,
+  rule: 'fires-declarations',
+  severity: 'warn',
+});
+
+// ---------------------------------------------------------------------------
+// Comparison
+// ---------------------------------------------------------------------------
+
+/** Emit error for each called ID not present in declared set. */
+const reportUndeclared = (
+  called: ReadonlySet<string>,
+  declared: ReadonlySet<string>,
+  ctx: {
+    trailId: string;
+    filePath: string;
+    line: number;
+  },
+  diagnostics: WardenDiagnostic[]
+): void => {
+  for (const id of called) {
+    if (!declared.has(id)) {
+      diagnostics.push(
+        buildUndeclaredDiagnostic(ctx.trailId, id, ctx.filePath, ctx.line)
+      );
+    }
+  }
+};
+
+/**
+ * Emit warning for each declared ID not present in called set.
+ *
+ * Unused string-literal declarations remain warnings: a declared string that is
+ * never called is visible cleanup debt even when other object-form declarations
+ * are unresolved.
+ */
+const reportUnused = (
+  declared: ReadonlySet<string>,
+  called: ReadonlySet<string>,
+  ctx: { trailId: string; filePath: string; line: number },
+  diagnostics: WardenDiagnostic[]
+): void => {
+  for (const id of declared) {
+    if (!called.has(id)) {
+      diagnostics.push(
+        buildUnusedDiagnostic(ctx.trailId, id, ctx.filePath, ctx.line)
+      );
+    }
+  }
+};
+
+const reportStringFireCalls = (
+  stringIds: ReadonlySet<string>,
+  ctx: { trailId: string; filePath: string; line: number },
+  diagnostics: WardenDiagnostic[]
+): void => {
+  for (const id of stringIds) {
+    diagnostics.push(
+      buildStringFireDiagnostic(ctx.trailId, id, ctx.filePath, ctx.line)
+    );
+  }
+};
+
+const checkTrailDefinition = (
+  def: { id: string; config: AstNode; start: number },
+  filePath: string,
+  sourceCode: string,
+  signalIds: SignalIdentifierResolver,
+  diagnostics: WardenDiagnostic[]
+): void => {
+  const declared = extractDeclaredFires(def.config, sourceCode, signalIds);
+  const called = extractCalledFires(def.config, sourceCode, signalIds);
+
+  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 };
+  const signalValueCalledIds = new Set(
+    [...called.ids].filter((id) => !called.stringIds.has(id))
+  );
+
+  reportStringFireCalls(called.stringIds, ctx, diagnostics);
+  reportUndeclared(signalValueCalledIds, declared.ids, ctx, diagnostics);
+  reportUnused(declared.ids, called.ids, ctx, diagnostics);
+};
+
+// ---------------------------------------------------------------------------
+// Rule
+// ---------------------------------------------------------------------------
+
+/**
+ * Validates that `ctx.fire()` calls align with declared `fires` arrays.
+ */
+export const firesDeclarations: WardenRule = {
+  check(sourceCode: string, filePath: string): readonly WardenDiagnostic[] {
+    if (isTestFile(filePath)) {
+      return [];
+    }
+
+    const ast = parse(filePath, sourceCode);
+    if (!ast) {
+      return [];
+    }
+    const signalIds = buildSignalIdentifierResolver(ast);
+
+    const diagnostics: WardenDiagnostic[] = [];
+
+    for (const def of findTrailDefinitions(ast)) {
+      if (def.kind === 'trail') {
+        checkTrailDefinition(def, filePath, sourceCode, signalIds, diagnostics);
+      }
+    }
+
+    return diagnostics;
+  },
+  description:
+    'Ensure ctx.fire() calls match the declared fires array in trail definitions.',
+  name: 'fires-declarations',
+  severity: 'error',
+};