@ontrails/warden 1.0.0-beta.4 → 1.0.0-beta.42

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,220 @@
+import { getLateBoundSignalRef } from '@ontrails/core';
+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),
+    ])
+  );
+};
+
+/**
+ * Signal ids whose contracts are store-derived advertisements.
+ *
+ * @remarks
+ * Store resources advertise `created`/`updated`/`removed` signals for every
+ * table as available capability. Leaving them unconsumed is a legitimate
+ * steady state, so produced-without-consumer coaching would be pure noise for
+ * store-backed apps.
+ */
+const collectStoreDerivedSignalIds = (topo: Topo): ReadonlySet<string> =>
+  new Set(
+    topo
+      .listSignals()
+      .filter(
+        (signal) => getLateBoundSignalRef(signal)?.kind === 'store-derived'
+      )
+      .map((signal) => signal.id)
+  );
+
+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>,
+  storeDerivedSignalIds: ReadonlySet<string>
+): 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) &&
+      !storeDerivedSignalIds.has(signalId)
+    ) {
+      diagnostics.push(
+        buildProducedWithoutConsumerDiagnostic(signalId, relations)
+      );
+    }
+  }
+
+  return diagnostics;
+};
+
+export const signalGraphCoaching: TopoAwareWardenRule = {
+  checkTopo: (topo) =>
+    buildDiagnostics(
+      collectRelations(topo),
+      collectStoreDerivedSignalIds(topo)
+    ),
+  description:
+    'Warn when typed signal contracts are declared or produced without reactive consumers.',
+  name: RULE_NAME,
+  severity: 'warn',
+};

package/src/rules/source/composition.ts

@@ -0,0 +1,165 @@
+/** Warden-private composition helpers. */
+
+import { intentValues } from '@ontrails/core';
+import type { Intent } from '@ontrails/core';
+
+import {
+  buildFrameworkNamespaceContext,
+  deriveConstString,
+  extractBindingName,
+  extractTrailDefinition,
+  findConfigProperty,
+  findTrailDefinitions,
+  getStringValue,
+  identifierName,
+  isStringLiteral,
+  walk,
+} from '@ontrails/source';
+import type { AstNode } from '@ontrails/source';
+
+/** Collect `const foo = trail('id', ...)` bindings from a parsed file. */
+export const collectNamedTrailIds = (
+  ast: AstNode
+): ReadonlyMap<string, string> => {
+  const ids = new Map<string, string>();
+  const context = buildFrameworkNamespaceContext(ast);
+
+  walk(ast, (node) => {
+    if (node.type !== 'VariableDeclarator') {
+      return;
+    }
+
+    const { id, init } = node as unknown as {
+      readonly id?: AstNode;
+      readonly init?: AstNode;
+    };
+    if (!init) {
+      return;
+    }
+
+    const def = extractTrailDefinition(init, context);
+    const name = extractBindingName(id);
+    if (def?.kind === 'trail' && name) {
+      ids.set(name, def.id);
+    }
+  });
+
+  return ids;
+};
+
+/** Extract the raw `composes: [...]` array elements from a trail config. */
+export const getComposeElements = (config: AstNode): readonly AstNode[] => {
+  const composesProp = findConfigProperty(config, 'composes');
+  if (!composesProp) {
+    return [];
+  }
+
+  const arrayNode = composesProp.value;
+  if (!arrayNode || (arrayNode as AstNode).type !== 'ArrayExpression') {
+    return [];
+  }
+
+  const elements = (arrayNode as AstNode)['elements'] as
+    | readonly AstNode[]
+    | undefined;
+  return elements ?? [];
+};
+
+/**
+ * Resolve a single `composes: [...]` element to its target trail ID.
+ *
+ * Handles string literals, identifier references (via `namedTrailIds` map or
+ * `const NAME = '...'` resolution), and inline `trail(...)` call expressions.
+ */
+export const deriveComposeElementId = (
+  element: AstNode,
+  sourceCode: string,
+  namedTrailIds: ReadonlyMap<string, string>
+): string | null => {
+  if (isStringLiteral(element)) {
+    return getStringValue(element);
+  }
+
+  if (element.type === 'Identifier') {
+    const name = identifierName(element);
+    return name
+      ? (namedTrailIds.get(name) ?? deriveConstString(name, sourceCode))
+      : null;
+  }
+
+  const inlineDef = extractTrailDefinition(element);
+  return inlineDef?.kind === 'trail' ? inlineDef.id : null;
+};
+
+/**
+ * Collect all trail IDs referenced by a single trail definition's
+ * `composes: [...]` array, deduplicated.
+ */
+export const extractDefinitionComposeTargetIds = (
+  config: AstNode,
+  sourceCode: string,
+  namedTrailIds: ReadonlyMap<string, string>
+): readonly string[] => [
+  ...new Set(
+    getComposeElements(config).flatMap((element) => {
+      const id = deriveComposeElementId(element, sourceCode, namedTrailIds);
+      return id ? [id] : [];
+    })
+  ),
+];
+
+/** Collect all trail IDs referenced by declared `composes: [...]` arrays. */
+export const collectComposeTargetTrailIds = (
+  ast: AstNode,
+  sourceCode: string
+): ReadonlySet<string> => {
+  const ids = new Set<string>();
+  const namedTrailIds = collectNamedTrailIds(ast);
+
+  for (const def of findTrailDefinitions(ast)) {
+    if (def.kind !== 'trail') {
+      continue;
+    }
+
+    for (const id of extractDefinitionComposeTargetIds(
+      def.config,
+      sourceCode,
+      namedTrailIds
+    )) {
+      ids.add(id);
+    }
+  }
+
+  return ids;
+};
+
+const INTENT_VALUE_SET = new Set<string>(intentValues);
+const DEFAULT_INTENT: Intent = 'write';
+
+const normalizeTrailIntent = (value: string): Intent =>
+  INTENT_VALUE_SET.has(value) ? (value as Intent) : DEFAULT_INTENT;
+
+const extractTrailIntent = (config: AstNode): Intent => {
+  const intentProp = findConfigProperty(config, 'intent');
+  if (!intentProp || !isStringLiteral(intentProp.value as AstNode)) {
+    return DEFAULT_INTENT;
+  }
+
+  const value = getStringValue(intentProp.value as AstNode);
+  return value ? normalizeTrailIntent(value) : DEFAULT_INTENT;
+};
+
+/** Collect the normalized intent for every trail definition in a parsed file. */
+export const collectTrailIntentsById = (
+  ast: AstNode
+): ReadonlyMap<string, Intent> => {
+  const intents = new Map<string, Intent>();
+
+  for (const def of findTrailDefinitions(ast)) {
+    if (def.kind === 'trail') {
+      intents.set(def.id, extractTrailIntent(def.config));
+    }
+  }
+
+  return intents;
+};

package/src/rules/source/drafts.ts

@@ -0,0 +1,164 @@
+/** Warden-private draft policy helpers. */
+
+import { existsSync, readFileSync } from 'node:fs';
+import { basename, dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { DRAFT_ID_PREFIX } from '@ontrails/core';
+
+import {
+  getStringValue,
+  identifierName,
+  isStringLiteral,
+  walk,
+} from '@ontrails/source';
+import type { AstNode } from '@ontrails/source';
+
+/**
+ * Names of framework constants whose value is a draft-marker prefix literal.
+ *
+ * String literals that initialize a `const` declaration with one of these
+ * names are treated as the framework's own draft-marker declarations, not as
+ * draft-id usage. This list is intentionally small and explicit — adding a
+ * new framework draft-prefix constant requires updating this set.
+ */
+export const FRAMEWORK_DRAFT_PREFIX_CONSTANT_NAMES: ReadonlySet<string> =
+  new Set(['DRAFT_ID_PREFIX', 'DRAFT_FILE_PREFIX']);
+
+/**
+ * Exact string literal value allowed for framework draft-prefix constant
+ * declarations. Tightens the exemption so a future framework file cannot
+ * redeclare `DRAFT_ID_PREFIX = '_draft.something-else'` and accidentally
+ * suppress its own draft-id diagnostic.
+ */
+const FRAMEWORK_DRAFT_PREFIX_LITERAL = DRAFT_ID_PREFIX;
+
+interface PackageJsonWithName {
+  readonly name: string;
+}
+
+const FRAMEWORK_DRAFT_PREFIX_PACKAGES: ReadonlySet<string> = new Set([
+  '@ontrails/core',
+  '@ontrails/warden',
+]);
+
+const isPackageJsonWithName = (value: unknown): value is PackageJsonWithName =>
+  typeof value === 'object' &&
+  value !== null &&
+  typeof (value as { name?: unknown }).name === 'string';
+
+const readPackageJsonName = (packageJsonPath: string): string | null => {
+  try {
+    const parsed = JSON.parse(readFileSync(packageJsonPath, 'utf8'));
+    return isPackageJsonWithName(parsed) ? parsed.name : null;
+  } catch {
+    return null;
+  }
+};
+
+const frameworkDraftPackageRoot = (filePath: string): string | null => {
+  const resolvedPath = resolve(filePath);
+  if (basename(resolvedPath) !== 'draft.ts') {
+    return null;
+  }
+
+  const sourceDir = dirname(resolvedPath);
+  if (basename(sourceDir) !== 'src') {
+    return null;
+  }
+
+  const packageRoot = dirname(sourceDir);
+  if (!existsSync(join(packageRoot, 'package.json'))) {
+    return null;
+  }
+
+  return packageRoot;
+};
+
+/** Fallback exemption when framework files are consumed from a different install path. */
+const isFrameworkDraftPrefixSourceFile = (filePath: string): boolean => {
+  const root = frameworkDraftPackageRoot(filePath);
+  if (!root) {
+    return false;
+  }
+  const packageName = readPackageJsonName(join(root, 'package.json'));
+  return (
+    packageName !== null && FRAMEWORK_DRAFT_PREFIX_PACKAGES.has(packageName)
+  );
+};
+
+/**
+ * Absolute paths of the two framework files allowed to declare the
+ * draft-prefix constants. Anchored against the rule module's own URL so the
+ * exemption is scoped to this package's real on-disk location — a consumer
+ * repository that happens to declare `const DRAFT_ID_PREFIX = '_draft.leak'`
+ * anywhere else cannot hide a genuine leak by matching the identifier name.
+ *
+ * The two framework files are:
+ *  - `packages/core/src/draft.ts`   (defines `DRAFT_ID_PREFIX`)
+ *  - `packages/warden/src/draft.ts` (defines `DRAFT_FILE_PREFIX`)
+ */
+const FRAMEWORK_DRAFT_CONSTANT_FILES: ReadonlySet<string> = new Set([
+  resolve(
+    fileURLToPath(new URL('../../../../core/src/draft.ts', import.meta.url))
+  ),
+  resolve(fileURLToPath(new URL('../../draft.ts', import.meta.url))),
+]);
+
+/**
+ * Collect the source offsets of string literals that initialize a framework
+ * draft-prefix constant declaration (e.g. `export const DRAFT_ID_PREFIX =
+ * '_draft.'`). Used by draft-awareness rules to skip their own marker
+ * constants.
+ *
+ * Exemption is gated on all three of:
+ *   1. The file is one of the two known framework draft files, or its package
+ *      root `package.json` name is `@ontrails/core` or `@ontrails/warden`.
+ *   2. The declaration name is `DRAFT_ID_PREFIX` or `DRAFT_FILE_PREFIX`.
+ *   3. The string literal value is exactly `'_draft.'`.
+ *
+ * A consumer file that reuses one of these identifier names cannot hide a
+ * `_draft.*` leak — the path gate rejects it outright.
+ */
+export const collectFrameworkDraftPrefixConstantOffsets = (
+  ast: AstNode,
+  filePath: string
+): ReadonlySet<number> => {
+  const offsets = new Set<number>();
+
+  const resolvedPath = resolve(filePath);
+  if (
+    !FRAMEWORK_DRAFT_CONSTANT_FILES.has(resolvedPath) &&
+    !isFrameworkDraftPrefixSourceFile(resolvedPath)
+  ) {
+    return offsets;
+  }
+
+  walk(ast, (node) => {
+    if (node.type !== 'VariableDeclarator') {
+      return;
+    }
+
+    const { id, init } = node as unknown as {
+      readonly id?: AstNode;
+      readonly init?: AstNode;
+    };
+    const name = identifierName(id);
+    if (
+      !name ||
+      !FRAMEWORK_DRAFT_PREFIX_CONSTANT_NAMES.has(name) ||
+      !init ||
+      !isStringLiteral(init)
+    ) {
+      return;
+    }
+
+    if (getStringValue(init) !== FRAMEWORK_DRAFT_PREFIX_LITERAL) {
+      return;
+    }
+
+    offsets.add(init.start);
+  });
+
+  return offsets;
+};