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

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,
+  deriveConstString,
+  findConfigProperty,
+  findTrailDefinitions,
+  getStringValue,
+  identifierName,
+  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';
+
+// ---------------------------------------------------------------------------
+// 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. Define it with signal('${signalId}', ...), include it in the topo, or fix the on: id if this is a typo.`,
+  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 on: consumers: ${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/owner-projection-parity.ts

@@ -0,0 +1,143 @@
+import { resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { intentValues } from '@ontrails/core';
+
+import {
+  getNodeExpression,
+  getNodeId,
+  getNodeInit,
+  getNodeKey,
+  getNodeProperties,
+  getPropertyName,
+  identifierName,
+  offsetToLine,
+  parse,
+  walk,
+} from './ast.js';
+import type { AstNode } from './ast.js';
+import type { WardenDiagnostic, WardenRule } from './types.js';
+
+const RULE_NAME = 'owner-projection-parity';
+
+const HTTP_METHOD_PROJECTION_PATH = resolve(
+  fileURLToPath(new URL('../../../http/src/method.ts', import.meta.url))
+);
+
+const isTargetFile = (filePath: string): boolean =>
+  resolve(filePath) === HTTP_METHOD_PROJECTION_PATH;
+
+const unwrapExpression = (node: AstNode | undefined): AstNode | undefined => {
+  let current = node;
+  while (
+    current &&
+    [
+      'ParenthesizedExpression',
+      'TSAsExpression',
+      'TSNonNullExpression',
+      'TSSatisfiesExpression',
+      'TSTypeAssertion',
+    ].includes(current.type)
+  ) {
+    current = getNodeExpression(current);
+  }
+  return current;
+};
+
+interface ProjectionMap {
+  readonly keys: ReadonlySet<string>;
+  readonly node: AstNode;
+}
+
+const findHttpMethodByIntentMap = (ast: AstNode): ProjectionMap | null => {
+  let found: ProjectionMap | null = null;
+
+  walk(ast, (node) => {
+    if (found || node.type !== 'VariableDeclarator') {
+      return;
+    }
+
+    const id = getNodeId(node);
+    const init = getNodeInit(node);
+    if (identifierName(id) !== 'httpMethodByIntent') {
+      return;
+    }
+
+    const objectExpression = unwrapExpression(init);
+    if (objectExpression?.type !== 'ObjectExpression') {
+      found = { keys: new Set(), node };
+      return;
+    }
+
+    const keys = new Set<string>();
+    for (const property of getNodeProperties(objectExpression) ?? []) {
+      if (property.type !== 'Property') {
+        continue;
+      }
+      const key = getPropertyName(getNodeKey(property));
+      if (key) {
+        keys.add(key);
+      }
+    }
+
+    found = { keys, node: objectExpression };
+  });
+
+  return found;
+};
+
+const buildMessage = (missing: string[], extra: string[]): string => {
+  const details = [
+    missing.length > 0 ? `missing owner intents: ${missing.join(', ')}` : '',
+    extra.length > 0 ? `unknown projection keys: ${extra.join(', ')}` : '',
+  ].filter(Boolean);
+
+  return [
+    'owner-projection-parity: httpMethodByIntent must cover the core intentValues owner vocabulary.',
+    ...details,
+  ].join(' ');
+};
+
+export const ownerProjectionParity: WardenRule = {
+  check(sourceCode: string, filePath: string): readonly WardenDiagnostic[] {
+    if (!isTargetFile(filePath)) {
+      return [];
+    }
+
+    const ast = parse(filePath, sourceCode);
+    if (!ast) {
+      return [];
+    }
+
+    const projection = findHttpMethodByIntentMap(ast);
+    const ownerKeys = new Set<string>(intentValues);
+    const projectionKeys = projection?.keys ?? new Set<string>();
+    const missing = [...ownerKeys]
+      .filter((key) => !projectionKeys.has(key))
+      .toSorted();
+    const extra = [...projectionKeys]
+      .filter((key) => !ownerKeys.has(key))
+      .toSorted();
+
+    if (projection && missing.length === 0 && extra.length === 0) {
+      return [];
+    }
+
+    const node = projection?.node ?? ast;
+    return [
+      {
+        filePath,
+        line: offsetToLine(sourceCode, node.start),
+        message: projection
+          ? buildMessage(missing, extra)
+          : 'owner-projection-parity: expected httpMethodByIntent to project core intentValues.',
+        rule: RULE_NAME,
+        severity: 'error',
+      },
+    ];
+  },
+  description:
+    'Require owner-derived projection maps to cover their authoritative owner vocabulary.',
+  name: RULE_NAME,
+  severity: 'error',
+};

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',
+};