@ontrails/warden 1.0.0-beta.2 → 1.0.0-beta.21

package/src/rules/resource-exists.ts

@@ -0,0 +1,179 @@
+import { isDraftId } from '@ontrails/core';
+
+import {
+  collectNamedResourceIds,
+  collectResourceDefinitionIds,
+  extractFirstStringArg,
+  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';
+
+const isResourceCall = (node: AstNode): boolean =>
+  node.type === 'CallExpression' &&
+  identifierName((node as unknown as { callee?: AstNode }).callee) ===
+    'resource';
+
+const getResourceElements = (config: AstNode): readonly AstNode[] => {
+  const resourcesProp = findConfigProperty(config, 'resources');
+  if (!resourcesProp) {
+    return [];
+  }
+
+  const arrayNode = resourcesProp.value;
+  if (!arrayNode || (arrayNode as AstNode).type !== 'ArrayExpression') {
+    return [];
+  }
+
+  const elements = (arrayNode as AstNode)['elements'] as
+    | readonly AstNode[]
+    | undefined;
+  return elements ?? [];
+};
+
+const extractDeclaredResourceId = (
+  element: AstNode,
+  resourceIdsByName: ReadonlyMap<string, string>
+): string | null => {
+  if (element.type === 'Identifier') {
+    const name = identifierName(element);
+    return name ? (resourceIdsByName.get(name) ?? null) : null;
+  }
+
+  if (isStringLiteral(element)) {
+    return getStringValue(element);
+  }
+
+  return isResourceCall(element) ? extractFirstStringArg(element) : null;
+};
+
+const extractDeclaredResourceIds = (
+  config: AstNode,
+  resourceIdsByName: ReadonlyMap<string, string>
+): readonly string[] => [
+  ...new Set(
+    getResourceElements(config).flatMap((element) => {
+      const id = extractDeclaredResourceId(element, resourceIdsByName);
+      return id ? [id] : [];
+    })
+  ),
+];
+
+const buildMissingResourceDiagnostic = (
+  trailId: string,
+  resourceId: string,
+  filePath: string,
+  line: number
+): WardenDiagnostic => ({
+  filePath,
+  line,
+  message: `Trail "${trailId}" declares resource "${resourceId}" which is not defined in the project. Define it with resource('${resourceId}', ...) and ensure that definition is included in the topo.`,
+  rule: 'resource-exists',
+  severity: 'error',
+});
+
+const reportMissingResources = (
+  def: { id: string; config: AstNode; start: number },
+  sourceCode: string,
+  resourceIdsByName: ReadonlyMap<string, string>,
+  filePath: string,
+  knownResourceIds: ReadonlySet<string>,
+  diagnostics: WardenDiagnostic[]
+): void => {
+  const line = offsetToLine(sourceCode, def.start);
+  for (const resourceId of extractDeclaredResourceIds(
+    def.config,
+    resourceIdsByName
+  )) {
+    if (!knownResourceIds.has(resourceId) && !isDraftId(resourceId)) {
+      diagnostics.push(
+        buildMissingResourceDiagnostic(def.id, resourceId, filePath, line)
+      );
+    }
+  }
+};
+
+const buildResourceDiagnostics = (
+  ast: AstNode,
+  sourceCode: string,
+  filePath: string,
+  knownResourceIds: ReadonlySet<string>
+): readonly WardenDiagnostic[] => {
+  const diagnostics: WardenDiagnostic[] = [];
+  const resourceIdsByName = collectNamedResourceIds(ast);
+  for (const def of findTrailDefinitions(ast)) {
+    reportMissingResources(
+      def,
+      sourceCode,
+      resourceIdsByName,
+      filePath,
+      knownResourceIds,
+      diagnostics
+    );
+  }
+  return diagnostics;
+};
+
+const checkResourcesExist = (
+  sourceCode: string,
+  filePath: string,
+  knownResourceIds: ReadonlySet<string>
+): readonly WardenDiagnostic[] => {
+  if (isTestFile(filePath)) {
+    return [];
+  }
+
+  const ast = parse(filePath, sourceCode);
+  if (!ast) {
+    return [];
+  }
+
+  return buildResourceDiagnostics(ast, sourceCode, filePath, knownResourceIds);
+};
+
+/**
+ * Checks that all declared resources resolve to known resource definitions.
+ */
+export const resourceExists: ProjectAwareWardenRule = {
+  check(sourceCode: string, filePath: string): readonly WardenDiagnostic[] {
+    const ast = parse(filePath, sourceCode);
+    if (!ast) {
+      return [];
+    }
+    return checkResourcesExist(
+      sourceCode,
+      filePath,
+      collectResourceDefinitionIds(ast)
+    );
+  },
+  checkWithContext(
+    sourceCode: string,
+    filePath: string,
+    context: ProjectContext
+  ): readonly WardenDiagnostic[] {
+    const ast = parse(filePath, sourceCode);
+    const localResourceIds = ast
+      ? collectResourceDefinitionIds(ast)
+      : new Set<string>();
+    return checkResourcesExist(
+      sourceCode,
+      filePath,
+      context.knownResourceIds ?? localResourceIds
+    );
+  },
+  description:
+    'Ensure every resource declared on a trail resolves to a known resource definition.',
+  name: 'resource-exists',
+  severity: 'error',
+};

package/src/rules/resource-id-grammar.ts

@@ -0,0 +1,65 @@
+import {
+  extractFirstStringArg,
+  identifierName,
+  offsetToLine,
+  parse,
+  walk,
+} from './ast.js';
+import type { AstNode } from './ast.js';
+import { isTestFile } from './scan.js';
+import type { WardenDiagnostic, WardenRule } from './types.js';
+
+const isResourceCall = (node: AstNode): boolean =>
+  node.type === 'CallExpression' &&
+  identifierName((node as unknown as { callee?: AstNode }).callee) ===
+    'resource';
+
+const buildDiagnostic = (
+  resourceId: string,
+  filePath: string,
+  line: number
+): WardenDiagnostic => ({
+  filePath,
+  line,
+  message: `Resource "${resourceId}" is invalid because resource ids may not contain ":".`,
+  rule: 'resource-id-grammar',
+  severity: 'error',
+});
+
+export const resourceIdGrammar: WardenRule = {
+  check(sourceCode: string, filePath: string): readonly WardenDiagnostic[] {
+    if (isTestFile(filePath)) {
+      return [];
+    }
+
+    const ast = parse(filePath, sourceCode);
+    if (!ast) {
+      return [];
+    }
+
+    const diagnostics: WardenDiagnostic[] = [];
+    walk(ast, (node) => {
+      if (!isResourceCall(node)) {
+        return;
+      }
+
+      const resourceId = extractFirstStringArg(node);
+      if (!resourceId || !resourceId.includes(':')) {
+        return;
+      }
+
+      diagnostics.push(
+        buildDiagnostic(
+          resourceId,
+          filePath,
+          offsetToLine(sourceCode, node.start)
+        )
+      );
+    });
+
+    return diagnostics;
+  },
+  description: 'Ensure resource ids do not contain the ":" scope separator.',
+  name: 'resource-id-grammar',
+  severity: 'error',
+};

package/src/rules/resource-mock-coverage.ts

@@ -0,0 +1,115 @@
+/**
+ * Warns when a `resource('id', { ... })` definition declares neither a `mock`
+ * factory nor an explicit `unmockable` reason.
+ *
+ * Every resource should declare its test posture: a `mock` factory so
+ * `testAll(app)` runs without production-like configuration (common pitfall
+ * #10), or an explicit `unmockable: { reason }` escape hatch when it genuinely
+ * cannot be mocked. The `mock?`/`unmockable?` fields are both optional in
+ * `ResourceSpec`, so the compiler does not enforce the choice — this rule does.
+ *
+ * Conservative by design (zero false positives over completeness): only flags
+ * a `resource()` call whose second argument is an inline object literal with no
+ * spread. A referenced spec variable, a spread spec, or a non-object second
+ * argument cannot be verified statically, so they are skipped.
+ */
+
+import {
+  extractFirstStringArg,
+  findConfigProperty,
+  identifierName,
+  offsetToLine,
+  parse,
+  walk,
+} from './ast.js';
+import type { AstNode } from './ast.js';
+import { isFrameworkInternalFile, isTestFile } from './scan.js';
+import type { WardenDiagnostic, WardenRule } from './types.js';
+
+const isResourceCall = (node: AstNode): boolean =>
+  node.type === 'CallExpression' &&
+  identifierName((node as unknown as { callee?: AstNode }).callee) ===
+    'resource';
+
+/**
+ * `.test-d.ts` type-fixture files are not matched by `isTestFile` (its pattern
+ * keys on `.test.`/`.spec.`), yet they hold type-inference probe resources that
+ * intentionally omit `mock`. Treat them as test fixtures here.
+ */
+const isTypeFixtureFile = (filePath: string): boolean =>
+  filePath.endsWith('.test-d.ts') || filePath.endsWith('.test-d.tsx');
+
+/**
+ * Framework-internal packages (`@ontrails/warden`, `@ontrails/testing`) define
+ * throwaway fixture resources to build example topos for other rules' tests
+ * (e.g. signal-graph-coaching's `invoiceStore`). Those scaffolding resources
+ * are not governed application resources, so skip them — consistent with how
+ * the rest of the framework treats `isFrameworkInternalFile` source.
+ */
+const isExcludedFile = (filePath: string): boolean =>
+  isTestFile(filePath) ||
+  isTypeFixtureFile(filePath) ||
+  isFrameworkInternalFile(filePath);
+
+/** A spec object literal we can analyze: an ObjectExpression with no spread. */
+const isStaticallyAnalyzableSpec = (spec: AstNode | undefined): boolean => {
+  if (!spec || spec.type !== 'ObjectExpression') {
+    return false;
+  }
+  const properties = spec['properties'] as readonly AstNode[] | undefined;
+  if (!properties) {
+    return false;
+  }
+  // A spread (`...base`) could contribute `mock`/`unmockable` from elsewhere;
+  // we cannot prove its absence, so do not flag.
+  return properties.every((prop) => prop.type === 'Property');
+};
+
+const declaresTestPosture = (spec: AstNode): boolean =>
+  findConfigProperty(spec, 'mock') !== null ||
+  findConfigProperty(spec, 'unmockable') !== null;
+
+export const resourceMockCoverage: WardenRule = {
+  check(sourceCode: string, filePath: string): readonly WardenDiagnostic[] {
+    if (isExcludedFile(filePath)) {
+      return [];
+    }
+
+    const ast = parse(filePath, sourceCode);
+    if (!ast) {
+      return [];
+    }
+
+    const diagnostics: WardenDiagnostic[] = [];
+    walk(ast, (node) => {
+      if (!isResourceCall(node)) {
+        return;
+      }
+
+      const args = node['arguments'] as readonly AstNode[] | undefined;
+      const spec = args?.[1];
+      if (!isStaticallyAnalyzableSpec(spec) || !spec) {
+        return;
+      }
+      if (declaresTestPosture(spec)) {
+        return;
+      }
+
+      const resourceId = extractFirstStringArg(node);
+      const subject = resourceId ? `Resource "${resourceId}"` : 'Resource';
+      diagnostics.push({
+        filePath,
+        line: offsetToLine(sourceCode, node.start),
+        message: `${subject} declares no mock factory. Add a mock() so testAll(app) runs without configuration, or declare unmockable: { reason } if it intentionally cannot be mocked.`,
+        rule: 'resource-mock-coverage',
+        severity: 'warn',
+      });
+    });
+
+    return diagnostics;
+  },
+  description:
+    'Resource definitions declare a mock factory or an explicit unmockable reason.',
+  name: 'resource-mock-coverage',
+  severity: 'warn',
+};

package/src/rules/scan.ts

@@ -1,6 +1,13 @@
 const TEST_FILE_PATTERN =
   /(?:^|\/)__tests__(?:\/|$)|(?:\.test|\.spec)\.[cm]?[jt]sx?$/;
 
+// The CLI scan-target contract also recognizes a singular `__test__` directory.
+// That compatibility stays scoped to the root-relative scan helpers: it must not
+// reach the absolute-path `isTestFile` rule predicate, where an ancestor
+// directory named `__test__` would otherwise misclassify every source file.
+const SCAN_TARGET_TEST_FILE_PATTERN =
+  /(?:^|\/)__tests?__(?:\/|$)|(?:\.test|\.spec)\.[cm]?[jt]sx?$/;
+
 const FRAMEWORK_INTERNAL_SEGMENTS = [
   '/packages/testing/',
   '/packages/warden/',
@@ -9,38 +16,44 @@ const FRAMEWORK_INTERNAL_SEGMENTS = [
 const normalizeFilePath = (filePath: string): string =>
   filePath.replaceAll('\\', '/');
 
-const maskText = (text: string): string => text.replaceAll(/[^\n]/g, ' ');
-
-const stripPattern = (sourceCode: string, pattern: RegExp): string =>
-  sourceCode.replaceAll(pattern, (match) => maskText(match));
+const toRootRelativeScanPath = (filePath: string): string =>
+  normalizeFilePath(filePath).replace(/^\.\//, '');
 
 export const isTestFile = (filePath: string): boolean =>
   TEST_FILE_PATTERN.test(normalizeFilePath(filePath));
 
-export const isFrameworkInternalFile = (filePath: string): boolean => {
-  const normalized = normalizeFilePath(filePath);
-  return FRAMEWORK_INTERNAL_SEGMENTS.some((segment) =>
-    normalized.includes(segment)
+export const isWardenTestScanTarget = (filePath: string): boolean =>
+  SCAN_TARGET_TEST_FILE_PATTERN.test(toRootRelativeScanPath(filePath));
+
+export const isWardenInfrastructureScanTarget = (filePath: string): boolean => {
+  const match = toRootRelativeScanPath(filePath);
+  return (
+    match.endsWith('.d.ts') ||
+    match.startsWith('node_modules/') ||
+    match.startsWith('dist/') ||
+    match.startsWith('.git/')
   );
 };
 
 /**
- * Replace quoted content and comments with whitespace while preserving line
- * breaks so simple line-based scanners do not match examples or messages.
+ * Whether a root-relative path should receive Warden committed-source checks.
+ *
+ * Warden's CLI glob runner passes root-relative matches here. Consumers that
+ * already have a root-relative source path should use the same helper before
+ * invoking Warden-owned rules directly so diagnostics do not drift from the
+ * CLI runner's scan target contract.
  */
-export const stripQuotedContent = (sourceCode: string): string => {
-  let sanitized = sourceCode;
-  const patterns = [
-    /\/\/[^\n]*/g,
-    /\/\*[\s\S]*?\*\//g,
-    /'[^'\\\n]*(?:\\.[^'\\\n]*)*'/g,
-    /"[^"\\\n]*(?:\\.[^"\\\n]*)*"/g,
-    /`[\s\S]*?`/g,
-  ];
-
-  for (const pattern of patterns) {
-    sanitized = stripPattern(sanitized, pattern);
-  }
-
-  return sanitized;
+export const isWardenSourceScanTarget = (filePath: string): boolean =>
+  !isWardenInfrastructureScanTarget(filePath) &&
+  !isWardenTestScanTarget(filePath);
+
+export const isWardenDevPermitTestScanTarget = (filePath: string): boolean =>
+  !isWardenInfrastructureScanTarget(filePath) &&
+  isWardenTestScanTarget(filePath);
+
+export const isFrameworkInternalFile = (filePath: string): boolean => {
+  const normalized = normalizeFilePath(filePath);
+  return FRAMEWORK_INTERNAL_SEGMENTS.some((segment) =>
+    normalized.includes(segment)
+  );
 };

package/src/rules/scheduled-destroy-intent.ts

@@ -0,0 +1,44 @@
+import type { AnyTrail } from '@ontrails/core';
+
+import type { TopoAwareWardenRule, WardenDiagnostic } from './types.js';
+
+const RULE_NAME = 'scheduled-destroy-intent';
+const TOPO_FILE = '<topo>';
+
+const isScheduleActivated = (trail: AnyTrail): boolean =>
+  trail.activationSources.some(
+    (activation) => activation.source.kind === 'schedule'
+  );
+
+const scheduleSourceIds = (trail: AnyTrail): readonly string[] => [
+  ...new Set(
+    trail.activationSources.flatMap((activation) =>
+      activation.source.kind === 'schedule' ? [activation.source.id] : []
+    )
+  ),
+];
+
+const buildDiagnostic = (
+  trail: AnyTrail,
+  sourceIds: readonly string[]
+): WardenDiagnostic => ({
+  filePath: TOPO_FILE,
+  line: 1,
+  message: `Trail "${trail.id}" declares intent: 'destroy' and is activated by schedule source${sourceIds.length === 1 ? '' : 's'} ${sourceIds.map((id) => `"${id}"`).join(', ')}. Scheduled destroy work should make cadence, permit scope, idempotency, and recovery explicit before it runs unattended.`,
+  rule: RULE_NAME,
+  severity: 'warn',
+});
+
+export const scheduledDestroyIntent: TopoAwareWardenRule = {
+  checkTopo: (topo) =>
+    topo
+      .list()
+      .filter(
+        (trail) => trail.intent === 'destroy' && isScheduleActivated(trail)
+      )
+      .map((trail) => buildDiagnostic(trail, scheduleSourceIds(trail))),
+  description:
+    'Warn when destroy-intent trails are activated by schedule sources.',
+  name: RULE_NAME,
+  severity: 'warn',
+};

package/src/rules/signal-graph-coaching.ts

@@ -0,0 +1,191 @@
+import type { Topo } from '@ontrails/core';
+
+import type { TopoAwareWardenRule, WardenDiagnostic } from './types.js';
+
+const RULE_NAME = 'signal-graph-coaching';
+const TOPO_FILE = '<topo>';
+
+interface SignalRelations {
+  readonly consumers: readonly string[];
+  readonly producerResources: readonly string[];
+  readonly producerTrails: readonly string[];
+}
+
+const sortedUnique = (values: Iterable<string>): readonly string[] =>
+  [...new Set(values)].toSorted();
+
+const collectSignalIds = (topo: Topo): readonly string[] =>
+  sortedUnique(topo.listSignals().map((signal) => signal.id));
+
+const collectProducerTrails = (
+  topo: Topo
+): ReadonlyMap<string, readonly string[]> => {
+  const producersBySignal = new Map<string, Set<string>>();
+
+  for (const signal of topo.listSignals()) {
+    if ((signal.from?.length ?? 0) === 0) {
+      continue;
+    }
+    const producers = producersBySignal.get(signal.id) ?? new Set<string>();
+    for (const producerTrailId of signal.from ?? []) {
+      producers.add(producerTrailId);
+    }
+    producersBySignal.set(signal.id, producers);
+  }
+
+  for (const trail of topo.list()) {
+    for (const signalId of trail.fires) {
+      const producers = producersBySignal.get(signalId) ?? new Set<string>();
+      producers.add(trail.id);
+      producersBySignal.set(signalId, producers);
+    }
+  }
+
+  return new Map(
+    [...producersBySignal.entries()].map(([signalId, producers]) => [
+      signalId,
+      sortedUnique(producers),
+    ])
+  );
+};
+
+const collectProducerResources = (
+  topo: Topo
+): ReadonlyMap<string, readonly string[]> => {
+  const resourcesBySignal = new Map<string, Set<string>>();
+
+  for (const resource of topo.listResources()) {
+    for (const signal of resource.signals ?? []) {
+      const resources = resourcesBySignal.get(signal.id) ?? new Set<string>();
+      resources.add(resource.id);
+      resourcesBySignal.set(signal.id, resources);
+    }
+  }
+
+  return new Map(
+    [...resourcesBySignal.entries()].map(([signalId, resources]) => [
+      signalId,
+      sortedUnique(resources),
+    ])
+  );
+};
+
+const collectConsumers = (
+  topo: Topo
+): ReadonlyMap<string, readonly string[]> => {
+  const consumersBySignal = new Map<string, Set<string>>();
+
+  for (const trail of topo.list()) {
+    for (const activation of trail.activationSources) {
+      if (activation.source.kind !== 'signal') {
+        continue;
+      }
+      const consumers =
+        consumersBySignal.get(activation.source.id) ?? new Set<string>();
+      consumers.add(trail.id);
+      consumersBySignal.set(activation.source.id, consumers);
+    }
+  }
+
+  return new Map(
+    [...consumersBySignal.entries()].map(([signalId, consumers]) => [
+      signalId,
+      sortedUnique(consumers),
+    ])
+  );
+};
+
+const collectRelations = (topo: Topo): ReadonlyMap<string, SignalRelations> => {
+  const producerTrails = collectProducerTrails(topo);
+  const producerResources = collectProducerResources(topo);
+  const consumers = collectConsumers(topo);
+
+  return new Map(
+    collectSignalIds(topo).map((signalId) => [
+      signalId,
+      {
+        consumers: consumers.get(signalId) ?? [],
+        producerResources: producerResources.get(signalId) ?? [],
+        producerTrails: producerTrails.get(signalId) ?? [],
+      },
+    ])
+  );
+};
+
+const quoteList = (values: readonly string[]): string =>
+  values.map((value) => `"${value}"`).join(', ');
+
+const formatProducerClause = ({
+  producerResources,
+  producerTrails,
+}: SignalRelations): string => {
+  const clauses: string[] = [];
+  if (producerTrails.length > 0) {
+    clauses.push(
+      `producer trail${producerTrails.length === 1 ? '' : 's'} ${quoteList(producerTrails)}`
+    );
+  }
+  if (producerResources.length > 0) {
+    clauses.push(
+      `producer resource${producerResources.length === 1 ? '' : 's'} ${quoteList(producerResources)}`
+    );
+  }
+  return clauses.join(' and ');
+};
+
+const buildDeadSignalDiagnostic = (signalId: string): WardenDiagnostic => ({
+  filePath: TOPO_FILE,
+  line: 1,
+  message: `Signal "${signalId}" is declared in the topo but has no producer trails, producer resources, or consumer trails. Add fires:/on: edges, attach producer metadata, or remove the unused signal contract.`,
+  rule: RULE_NAME,
+  severity: 'warn',
+});
+
+const buildProducedWithoutConsumerDiagnostic = (
+  signalId: string,
+  relations: SignalRelations
+): WardenDiagnostic => ({
+  filePath: TOPO_FILE,
+  line: 1,
+  message: `Signal "${signalId}" is produced by ${formatProducerClause(relations)} but has no consumer trails. Add an on: consumer if the signal is meant to drive reactive work, or remove the unused fires:/producer declaration.`,
+  rule: RULE_NAME,
+  severity: 'warn',
+});
+
+const hasProducer = ({
+  producerResources,
+  producerTrails,
+}: SignalRelations): boolean =>
+  producerResources.length > 0 || producerTrails.length > 0;
+
+const hasConsumer = ({ consumers }: SignalRelations): boolean =>
+  consumers.length > 0;
+
+const buildDiagnostics = (
+  relationsBySignal: ReadonlyMap<string, SignalRelations>
+): readonly WardenDiagnostic[] => {
+  const diagnostics: WardenDiagnostic[] = [];
+
+  for (const [signalId, relations] of relationsBySignal) {
+    if (!hasProducer(relations) && !hasConsumer(relations)) {
+      diagnostics.push(buildDeadSignalDiagnostic(signalId));
+      continue;
+    }
+
+    if (hasProducer(relations) && !hasConsumer(relations)) {
+      diagnostics.push(
+        buildProducedWithoutConsumerDiagnostic(signalId, relations)
+      );
+    }
+  }
+
+  return diagnostics;
+};
+
+export const signalGraphCoaching: TopoAwareWardenRule = {
+  checkTopo: (topo) => buildDiagnostics(collectRelations(topo)),
+  description:
+    'Warn when typed signal contracts are declared or produced without reactive consumers.',
+  name: RULE_NAME,
+  severity: 'warn',
+};