@ontrails/warden 0.2.0

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 } from './source/signals.js';
+import {
+  deriveConstString,
+  findConfigProperty,
+  findTrailDefinitions,
+  getStringValue,
+  identifierName,
+  isStringLiteral,
+  offsetToLine,
+  parse,
+} from '@ontrails/source';
+import type { AstNode } from '@ontrails/source';
+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,149 @@
+import { collectOnTargetSignalIds } from './source/signals.js';
+import {
+  collectCrudTableIds,
+  findStoreTableDefinitions,
+} from './source/stores.js';
+import { offsetToLine, parse } from '@ontrails/source';
+import type { AstNode } from '@ontrails/source';
+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(', ')}. Consume them with trail on: declarations — prefer the table's typed signal handles (table.signals.created / .updated / .removed), which carry the store-bound identity; a string id must be fully scoped when the store is bound to a resource — or remove the unused reactive pattern if nothing should react to this table's changes.`,
+  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-render-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 '@ontrails/source';
+import type { AstNode } from '@ontrails/source';
+import type { WardenDiagnostic, WardenRule } from './types.js';
+
+const RULE_NAME = 'owner-render-parity';
+
+const HTTP_METHOD_DERIVATION_PATH = resolve(
+  fileURLToPath(new URL('../../../http/src/method.ts', import.meta.url))
+);
+
+const isTargetFile = (filePath: string): boolean =>
+  resolve(filePath) === HTTP_METHOD_DERIVATION_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 IntentKeyMap {
+  readonly keys: ReadonlySet<string>;
+  readonly node: AstNode;
+}
+
+const findHttpMethodByIntentMap = (ast: AstNode): IntentKeyMap | null => {
+  let found: IntentKeyMap | 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 intentKeyMap keys: ${extra.join(', ')}` : '',
+  ].filter(Boolean);
+
+  return [
+    'owner-render-parity: httpMethodByIntent must cover the core intentValues owner vocabulary.',
+    ...details,
+  ].join(' ');
+};
+
+export const ownerRenderParity: WardenRule = {
+  check(sourceCode: string, filePath: string): readonly WardenDiagnostic[] {
+    if (!isTargetFile(filePath)) {
+      return [];
+    }
+
+    const ast = parse(filePath, sourceCode);
+    if (!ast) {
+      return [];
+    }
+
+    const intentKeyMap = findHttpMethodByIntentMap(ast);
+    const ownerKeys = new Set<string>(intentValues);
+    const derivedKeys = intentKeyMap?.keys ?? new Set<string>();
+    const missing = [...ownerKeys]
+      .filter((key) => !derivedKeys.has(key))
+      .toSorted();
+    const extra = [...derivedKeys]
+      .filter((key) => !ownerKeys.has(key))
+      .toSorted();
+
+    if (intentKeyMap && missing.length === 0 && extra.length === 0) {
+      return [];
+    }
+
+    const node = intentKeyMap?.node ?? ast;
+    return [
+      {
+        filePath,
+        line: offsetToLine(sourceCode, node.start),
+        message: intentKeyMap
+          ? buildMessage(missing, extra)
+          : 'owner-render-parity: expected httpMethodByIntent to render core intentValues.',
+        rule: RULE_NAME,
+        severity: 'error',
+      },
+    ];
+  },
+  description:
+    'Require owner-derived intentKeyMap 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,
+});
+
+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',
+};

package/src/rules/prefer-schema-inference.ts

@@ -0,0 +1,141 @@
+import type { WardenDiagnostic, WardenRule } from './types.js';
+import { isTestFile } from './scan.js';
+import {
+  findTrailLikeSpecs,
+  parseArrayEntries,
+  parseObjectProperties,
+  parseStringLiteral,
+  parseZodObjectShape,
+} from './specs.js';
+
+const REDUNDANT_OVERRIDE_KEYS = new Set(['label', 'options']);
+
+const hasOnlyRedundantKeys = (
+  properties: ReadonlyMap<string, { value: string }>
+): boolean =>
+  [...properties.keys()].every((key) => REDUNDANT_OVERRIDE_KEYS.has(key));
+
+const redundantLabelPart = (
+  derivedLabel: string,
+  properties: ReadonlyMap<string, { value: string }>
+): string[] => {
+  const label = parseStringLiteral(properties.get('label')?.value ?? '');
+  return label !== null && label === derivedLabel ? ['label'] : [];
+};
+
+const optionsAreDerivedDefaults = (
+  optionsText: string,
+  schemaOptions: readonly string[]
+): boolean => {
+  const entries = parseArrayEntries(optionsText, 0, optionsText);
+  if (entries.length !== schemaOptions.length) {
+    return false;
+  }
+
+  return entries.every((entry, index) => {
+    if (!entry.text.startsWith('{')) {
+      return false;
+    }
+
+    const properties = parseObjectProperties(entry.text, 0, entry.text);
+    if (properties.size !== 1) {
+      return false;
+    }
+
+    const value = parseStringLiteral(properties.get('value')?.value ?? '');
+    return value !== null && value === schemaOptions[index];
+  });
+};
+
+const redundantOptionsPart = (
+  options: { value: string } | undefined,
+  schemaOptions: readonly string[] | undefined
+): string[] =>
+  options !== undefined &&
+  schemaOptions !== undefined &&
+  optionsAreDerivedDefaults(options.value, schemaOptions)
+    ? ['options']
+    : [];
+
+const findRedundantParts = (
+  fieldKey: string,
+  fieldOverride: string,
+  schemaText: string
+): string[] => {
+  const fieldInfo = parseZodObjectShape(schemaText).get(fieldKey);
+  if (!fieldInfo) {
+    return [];
+  }
+
+  const properties = parseObjectProperties(fieldOverride, 0, fieldOverride);
+  if (properties.size === 0) {
+    return ['field metadata'];
+  }
+
+  if (!hasOnlyRedundantKeys(properties)) {
+    return [];
+  }
+
+  const redundant = [
+    ...redundantLabelPart(fieldInfo.derivedLabel, properties),
+    ...redundantOptionsPart(properties.get('options'), fieldInfo.options),
+  ];
+
+  return redundant.length === properties.size ? redundant : [];
+};
+
+const diagnosticsForSpec = (
+  sourceCode: string,
+  filePath: string,
+  spec: ReturnType<typeof findTrailLikeSpecs>[number]
+): readonly WardenDiagnostic[] => {
+  const input = spec.properties.get('input');
+  const fields = spec.properties.get('fields');
+  if (!input || !fields) {
+    return [];
+  }
+
+  const fieldEntries = parseObjectProperties(
+    fields.value,
+    fields.start,
+    sourceCode
+  );
+  return [...fieldEntries.entries()]
+    .map(([fieldKey, fieldEntry]) => ({
+      fieldEntry,
+      fieldKey,
+      redundantParts: findRedundantParts(
+        fieldKey,
+        fieldEntry.value,
+        input.value
+      ),
+    }))
+    .filter(({ redundantParts }) => redundantParts.length > 0)
+    .map(({ fieldEntry, fieldKey, redundantParts }) => ({
+      filePath,
+      line: fieldEntry.line,
+      message: `Trail "${spec.id}" field "${fieldKey}" only repeats schema-derived ${redundantParts.join(' and ')}. Remove the override and let deriveFields() infer it.`,
+      rule: 'prefer-schema-inference',
+      severity: 'warn' as const,
+    }));
+};
+
+/**
+ * Warns when a fields override only repeats metadata deriveFields() already gets from
+ * the schema.
+ */
+export const preferSchemaInference: WardenRule = {
+  check(sourceCode: string, filePath: string): readonly WardenDiagnostic[] {
+    if (isTestFile(filePath)) {
+      return [];
+    }
+
+    return findTrailLikeSpecs(sourceCode).flatMap((spec) =>
+      diagnosticsForSpec(sourceCode, filePath, spec)
+    );
+  },
+  description:
+    'Warn when fields overrides only restate labels or enum options deriveFields() already infers from the Zod schema.',
+  name: 'prefer-schema-inference',
+  severity: 'warn',
+};