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

package/src/rules/no-throw-in-detour-recover.ts

@@ -0,0 +1,225 @@
+import {
+  findConfigProperty,
+  findTrailDefinitions,
+  identifierName,
+  offsetToLine,
+  parse,
+  walk,
+  walkScope,
+} from './ast.js';
+import type { AstNode } from './ast.js';
+import { isTestFile } from './scan.js';
+import type { WardenDiagnostic, WardenRule } from './types.js';
+
+const TRANSPARENT_WRAPPER_TYPES = new Set([
+  'ParenthesizedExpression',
+  'TSAsExpression',
+  'TSSatisfiesExpression',
+  'TSNonNullExpression',
+  'TSTypeAssertion',
+]);
+
+const FUNCTION_TYPES = new Set([
+  'ArrowFunctionExpression',
+  'FunctionDeclaration',
+  'FunctionExpression',
+]);
+
+const unwrapExpression = (node: AstNode | undefined): AstNode | undefined => {
+  let current = node;
+  while (current && TRANSPARENT_WRAPPER_TYPES.has(current.type)) {
+    current = current['expression'] as AstNode | undefined;
+  }
+  return current;
+};
+
+const getDetourElements = (config: AstNode): readonly (AstNode | null)[] => {
+  const detoursProp = findConfigProperty(config, 'detours');
+  if (!detoursProp) {
+    return [];
+  }
+
+  const detoursValue = unwrapExpression(
+    detoursProp.value as AstNode | undefined
+  );
+  if (!detoursValue || detoursValue.type !== 'ArrayExpression') {
+    return [];
+  }
+
+  return (
+    ((detoursValue as AstNode)['elements'] as readonly (AstNode | null)[]) ?? []
+  );
+};
+
+const getFunctionBody = (node: AstNode | undefined): AstNode | undefined => {
+  if (!node || !FUNCTION_TYPES.has(node.type)) {
+    return undefined;
+  }
+
+  const { body } = node;
+  return Array.isArray(body) ? undefined : (body as AstNode | undefined);
+};
+
+interface RecoverBodyMatch {
+  readonly index: number;
+  readonly trailId: string;
+  readonly body: AstNode;
+}
+
+const collectFunctionRecoverBinding = (
+  bindings: Map<string, AstNode>,
+  node: AstNode
+): boolean => {
+  if (node.type !== 'FunctionDeclaration') {
+    return false;
+  }
+
+  const name = identifierName(node['id'] as AstNode | undefined);
+  if (name) {
+    bindings.set(name, node);
+  }
+  return true;
+};
+
+const collectVariableRecoverBinding = (
+  bindings: Map<string, AstNode>,
+  node: AstNode
+): void => {
+  if (node.type !== 'VariableDeclarator') {
+    return;
+  }
+
+  const name = identifierName(node['id'] as AstNode | undefined);
+  const init = unwrapExpression(node['init'] as AstNode | undefined);
+  if (!name || !init || !FUNCTION_TYPES.has(init.type)) {
+    return;
+  }
+
+  bindings.set(name, init);
+};
+
+const collectRecoverBinding = (
+  bindings: Map<string, AstNode>,
+  node: AstNode
+): void => {
+  if (collectFunctionRecoverBinding(bindings, node)) {
+    return;
+  }
+
+  collectVariableRecoverBinding(bindings, node);
+};
+
+const collectRecoverBindings = (ast: AstNode): ReadonlyMap<string, AstNode> => {
+  const bindings = new Map<string, AstNode>();
+
+  walk(ast, (node) => {
+    collectRecoverBinding(bindings, node);
+  });
+
+  return bindings;
+};
+
+const resolveRecoverBody = (
+  node: AstNode | undefined,
+  bindings: ReadonlyMap<string, AstNode>
+): AstNode | undefined => {
+  const unwrapped = unwrapExpression(node);
+  if (!unwrapped) {
+    return undefined;
+  }
+
+  const inlineBody = getFunctionBody(unwrapped);
+  if (inlineBody) {
+    return inlineBody;
+  }
+
+  const bindingName = identifierName(unwrapped);
+  if (!bindingName) {
+    return undefined;
+  }
+
+  return getFunctionBody(bindings.get(bindingName));
+};
+
+const resolveRecoverBodyFromElement = (
+  element: AstNode | null,
+  bindings: ReadonlyMap<string, AstNode>
+): AstNode | undefined => {
+  if (!element || element.type !== 'ObjectExpression') {
+    return undefined;
+  }
+
+  const recoverProp = findConfigProperty(element, 'recover');
+  return resolveRecoverBody(
+    recoverProp?.value as AstNode | undefined,
+    bindings
+  );
+};
+
+const appendRecoverBodies = (
+  bodies: RecoverBodyMatch[],
+  definition: { readonly config: AstNode; readonly id: string },
+  bindings: ReadonlyMap<string, AstNode>
+): void => {
+  const detourElements = getDetourElements(definition.config);
+  for (const [index, element] of detourElements.entries()) {
+    const body = resolveRecoverBodyFromElement(element, bindings);
+    if (!body) {
+      continue;
+    }
+
+    bodies.push({ body, index, trailId: definition.id });
+  }
+};
+
+const findRecoverBodies = (ast: AstNode): readonly RecoverBodyMatch[] => {
+  const bindings = collectRecoverBindings(ast);
+  const bodies: RecoverBodyMatch[] = [];
+
+  for (const definition of findTrailDefinitions(ast)) {
+    if (definition.kind !== 'trail') {
+      continue;
+    }
+
+    appendRecoverBodies(bodies, definition, bindings);
+  }
+
+  return bodies;
+};
+
+export const noThrowInDetourRecover: WardenRule = {
+  check(sourceCode: string, filePath: string): readonly WardenDiagnostic[] {
+    if (isTestFile(filePath)) {
+      return [];
+    }
+
+    const ast = parse(filePath, sourceCode);
+    if (!ast) {
+      return [];
+    }
+
+    const diagnostics: WardenDiagnostic[] = [];
+
+    for (const recover of findRecoverBodies(ast)) {
+      walkScope(recover.body, (node) => {
+        if (node.type !== 'ThrowStatement') {
+          return;
+        }
+
+        diagnostics.push({
+          filePath,
+          line: offsetToLine(sourceCode, node.start),
+          message: `Trail "${recover.trailId}" detour[${recover.index}] recover must not throw. Return Result.err() instead.`,
+          rule: 'no-throw-in-detour-recover',
+          severity: 'error',
+        });
+      });
+    }
+
+    return diagnostics;
+  },
+  description:
+    'Disallow throw statements inside detour recover functions. Use Result.err() instead.',
+  name: 'no-throw-in-detour-recover',
+  severity: 'error',
+};

package/src/rules/no-throw-in-implementation.ts

@@ -1,11 +1,13 @@
 /**
  * Finds `throw` statements inside `blaze:` function bodies.
  *
- * Uses AST parsing for accurate detection — no false positives from
- * throw in comments, strings, or nested non-implementation functions.
+ * Uses scope-aware AST walking so throws inside nested callbacks
+ * (e.g. `.map()`, `.filter()`, inner helpers) are not attributed to
+ * the blaze body itself. ADR-0007 requires this class of false positive
+ * to be avoided — only throws in the blaze body scope should be flagged.
  */
 
-import { findBlazeBodies, offsetToLine, parse, walk } from './ast.js';
+import { findBlazeBodies, offsetToLine, parse, walkScope } from './ast.js';
 import type { WardenDiagnostic, WardenRule } from './types.js';
 
 export const noThrowInImplementation: WardenRule = {
@@ -18,7 +20,7 @@ export const noThrowInImplementation: WardenRule = {
     const diagnostics: WardenDiagnostic[] = [];
 
     for (const body of findBlazeBodies(ast)) {
-      walk(body, (node) => {
+      walkScope(body, (node) => {
         if (node.type === 'ThrowStatement') {
           diagnostics.push({
             filePath,

package/src/rules/on-references-exist.ts

@@ -0,0 +1,194 @@
+/**
+ * Validates that every signal id declared in a trail's `on:` array resolves
+ * to a known signal definition somewhere in the project.
+ *
+ * Mirrors `resource-exists` structurally — collects local signal definitions
+ * for the standalone `check()` path and accepts a project-wide
+ * `knownSignalIds` set via `checkWithContext()`.
+ */
+
+import { isDraftId } from '@ontrails/core';
+
+import {
+  collectSignalDefinitionIds,
+  findConfigProperty,
+  findTrailDefinitions,
+  getStringValue,
+  identifierName,
+  isStringLiteral,
+  offsetToLine,
+  parse,
+  deriveConstString,
+} from './ast.js';
+import type { AstNode } from './ast.js';
+import { isTestFile } from './scan.js';
+import type {
+  ProjectAwareWardenRule,
+  ProjectContext,
+  WardenDiagnostic,
+} from './types.js';
+
+// ---------------------------------------------------------------------------
+// Declared `on:` extraction
+// ---------------------------------------------------------------------------
+
+const getOnElements = (config: AstNode): readonly AstNode[] => {
+  const onProp = findConfigProperty(config, 'on');
+  if (!onProp) {
+    return [];
+  }
+
+  const arrayNode = onProp.value;
+  if (!arrayNode || (arrayNode as AstNode).type !== 'ArrayExpression') {
+    return [];
+  }
+
+  const elements = (arrayNode as AstNode)['elements'] as
+    | readonly AstNode[]
+    | undefined;
+  return elements ?? [];
+};
+
+/**
+ * Resolve an `on:` array element to a signal id when possible.
+ *
+ * Handles string literals and `const NAME = 'id'` identifier references.
+ * Object-form entries (e.g. `on: [someSignal]` where `someSignal` is a
+ * `Signal` value) cannot be statically resolved here and are skipped — the
+ * runtime normalizes them inside `trail()`, so skipping is safe. The tradeoff
+ * is that typo'd Signal imports won't be caught at lint time; the TypeScript
+ * compiler catches those instead.
+ */
+const extractOnElementId = (
+  element: AstNode,
+  sourceCode: string
+): string | null => {
+  if (element.type === 'Identifier') {
+    const name = identifierName(element);
+    return name ? deriveConstString(name, sourceCode) : null;
+  }
+
+  if (isStringLiteral(element)) {
+    return getStringValue(element);
+  }
+
+  return null;
+};
+
+const extractDeclaredOnIds = (
+  config: AstNode,
+  sourceCode: string
+): readonly string[] => [
+  ...new Set(
+    getOnElements(config).flatMap((element) => {
+      const id = extractOnElementId(element, sourceCode);
+      return id ? [id] : [];
+    })
+  ),
+];
+
+// ---------------------------------------------------------------------------
+// Diagnostics
+// ---------------------------------------------------------------------------
+
+const buildMissingSignalDiagnostic = (
+  trailId: string,
+  signalId: string,
+  filePath: string,
+  line: number
+): WardenDiagnostic => ({
+  filePath,
+  line,
+  message: `Trail "${trailId}" declares on: "${signalId}" which is not a known signal in the project.`,
+  rule: 'on-references-exist',
+  severity: 'error',
+});
+
+const reportMissingSignals = (
+  def: { id: string; config: AstNode; start: number },
+  sourceCode: string,
+  filePath: string,
+  knownSignalIds: ReadonlySet<string>,
+  diagnostics: WardenDiagnostic[]
+): void => {
+  const line = offsetToLine(sourceCode, def.start);
+  for (const signalId of extractDeclaredOnIds(def.config, sourceCode)) {
+    if (!knownSignalIds.has(signalId) && !isDraftId(signalId)) {
+      diagnostics.push(
+        buildMissingSignalDiagnostic(def.id, signalId, filePath, line)
+      );
+    }
+  }
+};
+
+const buildSignalDiagnostics = (
+  ast: AstNode,
+  sourceCode: string,
+  filePath: string,
+  knownSignalIds: ReadonlySet<string>
+): readonly WardenDiagnostic[] => {
+  const diagnostics: WardenDiagnostic[] = [];
+  for (const def of findTrailDefinitions(ast)) {
+    if (def.kind !== 'trail') {
+      continue;
+    }
+    reportMissingSignals(
+      def,
+      sourceCode,
+      filePath,
+      knownSignalIds,
+      diagnostics
+    );
+  }
+  return diagnostics;
+};
+
+const checkOnReferences = (
+  ast: AstNode | null,
+  sourceCode: string,
+  filePath: string,
+  knownSignalIds: ReadonlySet<string>
+): readonly WardenDiagnostic[] => {
+  if (isTestFile(filePath) || !ast) {
+    return [];
+  }
+  return buildSignalDiagnostics(ast, sourceCode, filePath, knownSignalIds);
+};
+
+/**
+ * Checks that every `on:` reference resolves to a known signal definition.
+ */
+export const onReferencesExist: ProjectAwareWardenRule = {
+  check(sourceCode: string, filePath: string): readonly WardenDiagnostic[] {
+    const ast = parse(filePath, sourceCode);
+    if (!ast) {
+      return [];
+    }
+    return checkOnReferences(
+      ast,
+      sourceCode,
+      filePath,
+      collectSignalDefinitionIds(ast)
+    );
+  },
+  checkWithContext(
+    sourceCode: string,
+    filePath: string,
+    context: ProjectContext
+  ): readonly WardenDiagnostic[] {
+    const ast = parse(filePath, sourceCode);
+    const localSignalIds = ast
+      ? collectSignalDefinitionIds(ast)
+      : new Set<string>();
+    return checkOnReferences(
+      ast,
+      sourceCode,
+      filePath,
+      context.knownSignalIds ?? localSignalIds
+    );
+  },
+  description:
+    'Ensure every signal id declared in a trail on: array resolves to a known signal definition.',
+  name: 'on-references-exist',
+  severity: 'error',
+};

package/src/rules/orphaned-signal.ts

@@ -0,0 +1,150 @@
+import {
+  collectCrudTableIds,
+  collectOnTargetSignalIds,
+  findStoreTableDefinitions,
+  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 CHANGE_SIGNAL_OPERATIONS = ['created', 'updated', 'removed'] as const;
+
+const buildOrphanedSignalDiagnostic = (
+  tableId: string,
+  missingSignalIds: readonly string[],
+  filePath: string,
+  line: number
+): WardenDiagnostic => ({
+  filePath,
+  line,
+  message: `Store table "${tableId}" derives change signals with no trail listeners: ${missingSignalIds.join(', ')}. Add trail on: consumers or remove the unused reactive pattern.`,
+  rule: 'orphaned-signal',
+  severity: 'warn',
+});
+
+const getMissingSignalIds = (
+  tableId: string,
+  onTargetSignalIds: ReadonlySet<string>
+): readonly string[] =>
+  CHANGE_SIGNAL_OPERATIONS.map((operation) => `${tableId}.${operation}`).filter(
+    (signalId) =>
+      !onTargetSignalIds.has(signalId) &&
+      // Bare-name fallback: string-literal `on:` consumers store the signal
+      // without the composite `${storeBinding}:` prefix.
+      !onTargetSignalIds.has(signalId.replace(/^[^:]+:/, ''))
+  );
+
+/**
+ * Strip the `${storeBinding}:` prefix from a composite signal id for display.
+ * Keeps diagnostic messages readable while keeping keys composite internally.
+ */
+const stripStoreBinding = (
+  signalId: string,
+  storeBinding: string | null
+): string => {
+  if (!storeBinding) {
+    return signalId;
+  }
+  const prefix = `${storeBinding}:`;
+  return signalId.startsWith(prefix) ? signalId.slice(prefix.length) : signalId;
+};
+
+const buildDefinitionDiagnostic = (
+  definition: ReturnType<typeof findStoreTableDefinitions>[number],
+  sourceCode: string,
+  filePath: string,
+  crudTableIds: ReadonlySet<string>,
+  onTargetSignalIds: ReadonlySet<string>
+): WardenDiagnostic | null => {
+  if (!crudTableIds.has(definition.key)) {
+    return null;
+  }
+
+  const missingSignalIds = getMissingSignalIds(
+    definition.key,
+    onTargetSignalIds
+  );
+  return missingSignalIds.length === 0
+    ? null
+    : buildOrphanedSignalDiagnostic(
+        definition.name,
+        missingSignalIds.map((id) =>
+          stripStoreBinding(id, definition.storeBinding)
+        ),
+        filePath,
+        offsetToLine(sourceCode, definition.start)
+      );
+};
+
+const checkOrphanedSignals = (
+  ast: AstNode | null,
+  sourceCode: string,
+  filePath: string,
+  crudTableIds: ReadonlySet<string>,
+  onTargetSignalIds: ReadonlySet<string>
+): readonly WardenDiagnostic[] => {
+  if (isTestFile(filePath) || !ast) {
+    return [];
+  }
+
+  const diagnostics: WardenDiagnostic[] = [];
+
+  for (const definition of findStoreTableDefinitions(ast)) {
+    const diagnostic = buildDefinitionDiagnostic(
+      definition,
+      sourceCode,
+      filePath,
+      crudTableIds,
+      onTargetSignalIds
+    );
+    if (diagnostic) {
+      diagnostics.push(diagnostic);
+    }
+  }
+
+  return diagnostics;
+};
+
+export const orphanedSignal: ProjectAwareWardenRule = {
+  check(sourceCode: string, filePath: string): readonly WardenDiagnostic[] {
+    const ast = parse(filePath, sourceCode);
+    return checkOrphanedSignals(
+      ast,
+      sourceCode,
+      filePath,
+      ast ? collectCrudTableIds(ast) : new Set<string>(),
+      ast ? collectOnTargetSignalIds(ast, sourceCode) : new Set<string>()
+    );
+  },
+  checkWithContext(
+    sourceCode: string,
+    filePath: string,
+    context: ProjectContext
+  ): readonly WardenDiagnostic[] {
+    const ast = parse(filePath, sourceCode);
+    const localCrudTableIds = ast
+      ? collectCrudTableIds(ast)
+      : new Set<string>();
+    const localOnTargetSignalIds = ast
+      ? collectOnTargetSignalIds(ast, sourceCode)
+      : new Set<string>();
+
+    return checkOrphanedSignals(
+      ast,
+      sourceCode,
+      filePath,
+      context.crudTableIds ?? localCrudTableIds,
+      context.onTargetSignalIds ?? localOnTargetSignalIds
+    );
+  },
+  description:
+    'Warn when CRUD-backed store change signals are never consumed by trail on: declarations.',
+  name: 'orphaned-signal',
+  severity: 'warn',
+};

package/src/rules/permit-governance.ts

@@ -0,0 +1,25 @@
+import type { Trail } from '@ontrails/core';
+import { validatePermits } from '@ontrails/permits';
+
+import type { TopoAwareWardenRule, WardenDiagnostic } from './types.js';
+
+const toWardenDiagnostic = (
+  diagnostic: ReturnType<typeof validatePermits>[number]
+): WardenDiagnostic => ({
+  filePath: '<topo>',
+  line: 1,
+  message: diagnostic.message,
+  rule: `permit.${diagnostic.rule}`,
+  severity: diagnostic.severity === 'error' ? 'error' : 'warn',
+});
+
+export const permitGovernance: TopoAwareWardenRule = {
+  checkTopo: (topo) =>
+    validatePermits(
+      topo.list() as readonly Trail<unknown, unknown, unknown>[]
+    ).map(toWardenDiagnostic),
+  description:
+    'Enforces permit declarations and scope hygiene across the compiled topo',
+  name: 'permit-governance',
+  severity: 'warn',
+};