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

package/src/rules/trail-versioning-topo.ts

@@ -0,0 +1,172 @@
+import { deriveTopoGraph } from '@ontrails/topographer';
+import type {
+  TopoGraph,
+  TopoGraphEntry,
+  TopoGraphForceEntry,
+  TopoGraphVersionEntry,
+} from '@ontrails/topographer';
+import type { Topo } from '@ontrails/core';
+
+import type { TopoAwareWardenRule, WardenDiagnostic } from './types.js';
+
+const TOPO_FILE = '<topo>';
+
+const isArchived = (entry: TopoGraphVersionEntry): boolean =>
+  entry.status?.state === 'archived';
+
+const isDeprecatedWithoutGuidance = (entry: TopoGraphVersionEntry): boolean =>
+  entry.status?.state === 'deprecated' &&
+  entry.status.successor === undefined &&
+  entry.status.note === undefined &&
+  (entry.status.migration === undefined || entry.status.migration.length === 0);
+
+const versionNumbersFor = (entry: TopoGraphEntry): readonly number[] => [
+  ...(entry.version === undefined ? [] : [entry.version]),
+  ...Object.keys(entry.versions ?? {}).map(Number),
+];
+
+const versionEntryName = (trailId: string, version: string): string =>
+  `${trailId}@${version}`;
+
+const topoDiagnostic = (
+  rule: string,
+  severity: WardenDiagnostic['severity'],
+  message: string
+): WardenDiagnostic => ({
+  filePath: TOPO_FILE,
+  line: 1,
+  message,
+  rule,
+  severity,
+});
+
+const trailEntries = (graph: TopoGraph): readonly TopoGraphEntry[] =>
+  graph.entries.filter((entry) => entry.kind === 'trail');
+
+const graphFor = (
+  topo: Topo,
+  context: Parameters<TopoAwareWardenRule['checkTopo']>[1]
+): TopoGraph => context?.graph ?? deriveTopoGraph(topo);
+
+const forceKey = (force: TopoGraphForceEntry): string =>
+  JSON.stringify([
+    force.kind,
+    force.id,
+    force.change,
+    force.detail,
+    force.reason,
+    force.severity,
+    force.source,
+  ]);
+
+const pendingForceDiagnostic = (force: TopoGraphForceEntry): WardenDiagnostic =>
+  topoDiagnostic(
+    'pending-force',
+    'warn',
+    `Trail "${force.id}" has a pending forced topo break (${force.change}: ${force.detail}). Resolve or document the force event before release.`
+  );
+
+export const deprecationWithoutGuidance: TopoAwareWardenRule = {
+  checkTopo(topo, context) {
+    return trailEntries(graphFor(topo, context)).flatMap((entry) =>
+      Object.entries(entry.versions ?? {}).flatMap(([version, historical]) =>
+        isDeprecatedWithoutGuidance(historical)
+          ? [
+              topoDiagnostic(
+                'deprecation-without-guidance',
+                'error',
+                `Trail "${versionEntryName(entry.id, version)}" is deprecated without successor, migration, or note guidance. Add at least one guidance field to the version status.`
+              ),
+            ]
+          : []
+      )
+    );
+  },
+  description:
+    'Require deprecated trail version entries to carry successor, migration, or note guidance.',
+  name: 'deprecation-without-guidance',
+  severity: 'error',
+};
+
+export const versionGap: TopoAwareWardenRule = {
+  checkTopo(topo, context) {
+    const diagnostics: WardenDiagnostic[] = [];
+    for (const entry of trailEntries(graphFor(topo, context))) {
+      if (entry.version === undefined) {
+        continue;
+      }
+      const historicalVersions = new Set(
+        Object.keys(entry.versions ?? {}).map(Number)
+      );
+      if (historicalVersions.has(entry.version)) {
+        diagnostics.push(
+          topoDiagnostic(
+            'version-gap',
+            'error',
+            `Trail "${entry.id}" declares current version ${entry.version} both as current and as a historical entry. Remove the duplicate historical entry.`
+          )
+        );
+      }
+
+      const versions = new Set(versionNumbersFor(entry));
+      for (let version = 1; version <= entry.version; version += 1) {
+        if (!versions.has(version)) {
+          diagnostics.push(
+            topoDiagnostic(
+              'version-gap',
+              'error',
+              `Trail "${entry.id}" has a gap before current version ${entry.version}: missing version ${version}. Historical version coverage must be contiguous, including archived entries.`
+            )
+          );
+        }
+      }
+    }
+    return diagnostics;
+  },
+  description:
+    'Require trail version coverage to stay contiguous from v1 through the current version.',
+  name: 'version-gap',
+  severity: 'error',
+};
+
+export const versionWithoutExamples: TopoAwareWardenRule = {
+  checkTopo(topo, context) {
+    return trailEntries(graphFor(topo, context)).flatMap((entry) =>
+      Object.entries(entry.versions ?? {}).flatMap(([version, historical]) =>
+        !isArchived(historical) && (historical.exampleCount ?? 0) === 0
+          ? [
+              topoDiagnostic(
+                'version-without-examples',
+                'warn',
+                `Trail "${versionEntryName(entry.id, version)}" is a live historical version without examples. Add version-entry examples or archive the entry if it no longer participates in runtime negotiation.`
+              ),
+            ]
+          : []
+      )
+    );
+  },
+  description:
+    'Warn when live historical trail version entries do not include examples.',
+  name: 'version-without-examples',
+  severity: 'warn',
+};
+
+export const pendingForce: TopoAwareWardenRule = {
+  checkTopo(topo, context) {
+    const graph = graphFor(topo, context);
+    const diagnostics = new Map<string, WardenDiagnostic>();
+    for (const entry of trailEntries(graph)) {
+      for (const force of entry.forces ?? []) {
+        diagnostics.set(forceKey(force), pendingForceDiagnostic(force));
+      }
+    }
+    for (const force of graph.forces ?? []) {
+      diagnostics.set(forceKey(force), pendingForceDiagnostic(force));
+    }
+    return [...diagnostics.values()];
+  },
+  description:
+    'Warn when graph-only force audit events remain attached to trail entries or the topo graph.',
+  name: 'pending-force',
+  severity: 'warn',
+};

package/src/rules/types.ts

@@ -1,14 +1,201 @@
+import type { Intent, Topo } from '@ontrails/core';
+import type { TopoGraph } from '@ontrails/topographer';
+
+import type { WardenDepth } from '../config.js';
+import type { WardenImportResolution } from '../resolve.js';
+import type { WardenPublicWorkspace } from '../workspaces.js';
+
 /**
  * Severity level for warden diagnostics.
  */
 export type WardenSeverity = 'error' | 'warn';
 
+/**
+ * Execution tier for a Warden rule.
+ *
+ * Tier names describe the narrowest runtime shape that can answer the rule's
+ * question. They do not change ownership: source-static rules can still be
+ * durable public Warden doctrine.
+ */
+export type WardenRuleTier =
+  | 'advisory'
+  | 'drift'
+  | 'project-static'
+  | 'source-static'
+  | 'topo-aware';
+
+/**
+ * Context where a Warden rule applies.
+ */
+export type WardenRuleScope =
+  | 'advisory'
+  | 'extension'
+  | 'external'
+  | 'internal'
+  | 'repo-local'
+  | 'temporary';
+
+/**
+ * Lifecycle state for a Warden rule.
+ */
+export type WardenRuleLifecycleState = 'deprecated' | 'durable' | 'temporary';
+
+/**
+ * Queryable concern dimension for Warden rule metadata.
+ */
+export type WardenRuleConcern =
+  | 'composition'
+  | 'general'
+  | 'lifecycle'
+  | 'meta'
+  | 'permits'
+  | 'resources'
+  | 'results'
+  | 'signals';
+
+/**
+ * Lifecycle metadata for a Warden rule.
+ */
+export interface WardenRuleLifecycle {
+  /** Current lifecycle state. */
+  readonly state: WardenRuleLifecycleState;
+  /** Required for temporary or deprecated rules. */
+  readonly retireWhen?: string | undefined;
+}
+
+/**
+ * Documentation or reference target for Warden remediation guidance.
+ */
+export interface WardenGuidanceLink {
+  /** Human-readable link label. */
+  readonly label: string;
+  /** Repository-relative documentation path, when the target is in-tree. */
+  readonly path?: string | undefined;
+  /** External documentation URL, when the target is outside the repo. */
+  readonly url?: string | undefined;
+}
+
+/**
+ * Structured remediation guidance that can be rendered for humans or projected
+ * into agent-facing manifests without scraping diagnostic prose.
+ */
+export interface WardenGuidance {
+  /** Concise next step for the finding or rule. */
+  readonly summary: string;
+  /** Ordered remediation steps, when the rule benefits from more detail. */
+  readonly steps?: readonly string[] | undefined;
+  /** Reference docs that explain the invariant. */
+  readonly docs?: readonly WardenGuidanceLink[] | undefined;
+  /** Example commands. These are guidance examples, not autofix contracts. */
+  readonly commands?: readonly string[] | undefined;
+  /** Related rule identifiers that help agents navigate nearby doctrine. */
+  readonly relatedRules?: readonly string[] | undefined;
+}
+
+/**
+ * Transform class a fix belongs to.
+ *
+ * Names the kind of mechanical change so agents, the guide, and downstream
+ * regrades can route by class. `term-rewrite` is the durable name for retired
+ * vocabulary renames (`vocab-cutover` is historical wording only).
+ */
+export type WardenFixClass = 'term-rewrite';
+
+/**
+ * How safe a fix is to apply without human review.
+ *
+ * - `safe`: a deterministic, scope-correct source edit `warden --fix` may apply
+ *   automatically.
+ * - `review`: the change is understood but needs human judgement (ambiguous
+ *   span, removal with no mechanical replacement, semantic follow-up). The
+ *   finding stays reported; `warden --fix` never applies it.
+ */
+export type WardenFixSafety = 'review' | 'safe';
+
+/**
+ * A concrete, half-open source edit `[start, end)` replaced by `replacement`.
+ *
+ * Offsets are JavaScript string indices into the exact analyzed source text,
+ * matching `String.prototype.slice()` and the `offsetToLine` helper the rules
+ * already use. Carrying an explicit span (not just a line) lets `warden --fix`
+ * apply edits deterministically and
+ * last-to-first without re-parsing.
+ */
+export interface WardenFixEdit {
+  /** Inclusive start offset into the source. */
+  readonly start: number;
+  /** Exclusive end offset into the source. */
+  readonly end: number;
+  /** Text that replaces the `[start, end)` span. */
+  readonly replacement: string;
+}
+
+/**
+ * Per-finding fix metadata attached to a diagnostic.
+ *
+ * Authored on the diagnostic at construction because only the rule that matched
+ * knows the concrete span. `warden --fix` applies `edits` only when
+ * `safety` is `safe`; `review` fixes stay reported with their guidance so a
+ * human (or a downstream regrade) can resolve them.
+ */
+export interface WardenFix {
+  /** Transform class this fix belongs to. */
+  readonly class: WardenFixClass;
+  /** Whether `warden --fix` may apply this automatically. */
+  readonly safety: WardenFixSafety;
+  /** Source edits to apply, when `safety` is `safe`. Empty for review-only. */
+  readonly edits?: readonly WardenFixEdit[] | undefined;
+  /** Why the fix is needed and what it changes, for humans and migration notes. */
+  readonly reason: string;
+  /** Optional pointer to a fixture or example demonstrating the fix. */
+  readonly fixture?: string | undefined;
+}
+
+/**
+ * Per-rule fix capability, projected into the guide/manifest.
+ *
+ * Declares that a rule can emit {@link WardenFix} metadata and the default
+ * safety for its fixes, so `warden --help`, the guide, and agent surfaces can
+ * advertise fix availability without a finding in hand. Concrete edits still
+ * live on each diagnostic's {@link WardenFix}.
+ */
+export interface WardenFixCapability {
+  /** Transform class the rule's fixes belong to. */
+  readonly class: WardenFixClass;
+  /** Default safety for fixes this rule emits. */
+  readonly safety: WardenFixSafety;
+}
+
+/**
+ * Stable metadata used to classify Warden rules before dispatch filtering.
+ */
+export interface WardenRuleMetadata {
+  /** Cumulative Warden depth where this rule first becomes relevant. */
+  readonly depth: WardenDepth;
+  /** Queryable rule concern for agent-facing surfaces. */
+  readonly concern: WardenRuleConcern;
+  /** One-line invariant the rule protects. */
+  readonly invariant: string;
+  /** Rule lifecycle. */
+  readonly lifecycle: WardenRuleLifecycle;
+  /** Where the rule applies. */
+  readonly scope: WardenRuleScope;
+  /** Narrowest Warden tier that can answer the rule. */
+  readonly tier: WardenRuleTier;
+  /** Structured remediation guidance for diagnostics emitted by this rule. */
+  readonly guidance?: WardenGuidance | undefined;
+  /** Declares that this rule can emit fix metadata, for guide projection. */
+  readonly fix?: WardenFixCapability | undefined;
+}
+
 /**
  * A single diagnostic reported by a warden rule.
  */
 export interface WardenDiagnostic {
   /** Rule identifier, e.g. "no-throw-in-implementation" */
   readonly rule: string;
+  /** Optional rule-local diagnostic code for checks with multiple stable findings. */
+  readonly code?: string | undefined;
   /** Severity level */
   readonly severity: WardenSeverity;
   /** Human-readable message describing the violation */
@@ -17,13 +204,20 @@ export interface WardenDiagnostic {
   readonly line: number;
   /** File path that was analyzed */
   readonly filePath: string;
+  /** Topo/app identity for diagnostics emitted during multi-topo runs. */
+  readonly topoName?: string | undefined;
+  /** Optional finding-level guidance. Defaults from rule metadata when absent. */
+  readonly guidance?: WardenGuidance | undefined;
+  /** Optional structured fix for this finding. `warden --fix` applies safe edits. */
+  readonly fix?: WardenFix | undefined;
 }
 
 /**
- * A warden rule is a function that analyzes source code and returns diagnostics.
+ * A warden rule analyzes one source file and returns diagnostics.
  *
- * Rules use string/regex analysis (not full AST parsing) to detect patterns
- * that violate Trails conventions.
+ * Rules should prefer structured AST helpers when they inspect TypeScript
+ * syntax. Simple string checks remain acceptable when the authored rule is
+ * explicitly about text that is not parseable syntax, such as generated output.
  */
 export interface WardenRule {
   /** Unique rule identifier */
@@ -32,6 +226,8 @@ export interface WardenRule {
   readonly severity: WardenSeverity;
   /** Human-readable description of what the rule enforces */
   readonly description: string;
+  /** Optional inline classification. Built-ins are classified by registry. */
+  readonly metadata?: WardenRuleMetadata | undefined;
   /** Run the rule against source code and return any diagnostics */
   readonly check: (
     sourceCode: string,
@@ -40,13 +236,54 @@ export interface WardenRule {
 }
 
 /**
- * Options for cross-file rules that need knowledge of all trail IDs in a project.
+ * Options for compose-file rules that need knowledge of all trail IDs in a project.
  */
 export interface ProjectContext {
+  /** All known contour names in the project. */
+  readonly knownContourIds?: ReadonlySet<string>;
+  /** Store table IDs used with the CRUD factory across the project. */
+  readonly crudTableIds?: ReadonlySet<string>;
   /** All known trail IDs in the project */
   readonly knownTrailIds: ReadonlySet<string>;
-  /** All trail IDs referenced as detour targets across the project */
-  readonly detourTargetTrailIds?: ReadonlySet<string>;
+  /** Declared contour references keyed by source contour name. */
+  readonly contourReferencesByName?: ReadonlyMap<string, readonly string[]>;
+  /** All known resource IDs in the project */
+  readonly knownResourceIds?: ReadonlySet<string>;
+  /** All known signal IDs in the project */
+  readonly knownSignalIds?: ReadonlySet<string>;
+  /** All trail IDs referenced by declared composes arrays across the project. */
+  readonly composeTargetTrailIds?: ReadonlySet<string>;
+  /** Signal IDs referenced by trail `on` arrays across the project. */
+  readonly onTargetSignalIds?: ReadonlySet<string>;
+  /** Store table IDs used with reconcile trails across the project. */
+  readonly reconcileTableIds?: ReadonlySet<string>;
+  /** Resolved import facts keyed by importer file path across the project. */
+  readonly importResolutionsByFile?: ReadonlyMap<
+    string,
+    readonly WardenImportResolution[]
+  >;
+  /** Resolved docs/specifier facts keyed by documentation file path. */
+  readonly documentedImportResolutionsByFile?: ReadonlyMap<
+    string,
+    readonly WardenImportResolution[]
+  >;
+  /** Non-private published @ontrails workspaces discovered from the root manifest. */
+  readonly publicWorkspaces?: ReadonlyMap<string, WardenPublicWorkspace>;
+  /** Normalized trail intents by trail ID across the project. */
+  readonly trailIntentsById?: ReadonlyMap<string, Intent>;
+  /**
+   * CRUD operation coverage per entity aggregated across the project.
+   *
+   * Keys are stable entity IDs (authored contour names, `imported:<local>`
+   * sentinels for contours imported from another module, or store-table IDs
+   * produced by `deriveStoreTableId`). Values are the set of CRUD operations
+   * (`create`, `read`, `update`, `delete`, `list`) observed for that entity.
+   *
+   * Enables compose-file completeness evaluation so one-file-per-operation
+   * layouts (e.g. separate `create.ts`, `read.ts`) do not trip file-scoped
+   * coverage warnings.
+   */
+  readonly crudCoverageByEntity?: ReadonlyMap<string, ReadonlySet<string>>;
 }
 
 /**
@@ -60,3 +297,30 @@ export interface ProjectAwareWardenRule extends WardenRule {
     context: ProjectContext
   ) => readonly WardenDiagnostic[];
 }
+
+/**
+ * A topo-aware warden rule inspects the compiled runtime trail graph —
+ * actual `Trail` objects with resolved types, accessor shapes, detour
+ * declarations, `pattern` field values, and other runtime-only data that
+ * is unavailable to AST-based rules.
+ *
+ * Unlike `WardenRule` and `ProjectAwareWardenRule`, which analyze source
+ * code on a per-file basis, a `TopoAwareWardenRule` runs once per topo
+ * and returns diagnostics spanning the whole graph. A rule file must
+ * implement exactly one of the three rule kinds.
+ */
+export interface TopoAwareWardenRule {
+  /** Unique rule identifier */
+  readonly name: string;
+  /** Default severity */
+  readonly severity: WardenSeverity;
+  /** Human-readable description of what the rule enforces */
+  readonly description: string;
+  /** Optional inline classification. Built-ins are classified by registry. */
+  readonly metadata?: WardenRuleMetadata | undefined;
+  /** Run the rule against the resolved topo and return any diagnostics */
+  readonly checkTopo: (
+    topo: Topo,
+    context?: { readonly graph?: TopoGraph | undefined } | undefined
+  ) => readonly WardenDiagnostic[] | Promise<readonly WardenDiagnostic[]>;
+}

package/src/rules/unmaterialized-activation-source.ts

@@ -0,0 +1,84 @@
+import type { ActivationSourceKind, Topo } from '@ontrails/core';
+
+import type { TopoAwareWardenRule, WardenDiagnostic } from './types.js';
+
+const RULE_NAME = 'unmaterialized-activation-source';
+const TOPO_FILE = '<topo>';
+
+const MATERIALIZED_SOURCE_KINDS = new Set<ActivationSourceKind>([
+  'schedule',
+  'signal',
+  'webhook',
+]);
+
+const PENDING_SOURCE_KINDS = new Set<ActivationSourceKind>();
+
+interface SourceConsumers {
+  readonly id: string;
+  readonly kind: ActivationSourceKind;
+  readonly key: string;
+  readonly trailIds: readonly string[];
+}
+
+const sourceKey = (kind: ActivationSourceKind, id: string): string =>
+  `${kind}:${id}`;
+
+const sortedUnique = (values: Iterable<string>): readonly string[] =>
+  [...new Set(values)].toSorted();
+
+const collectSourceConsumers = (topo: Topo): readonly SourceConsumers[] => {
+  const consumersBySource = new Map<
+    string,
+    {
+      readonly id: string;
+      readonly kind: ActivationSourceKind;
+      readonly trailIds: Set<string>;
+    }
+  >();
+
+  for (const trail of topo.list()) {
+    for (const activation of trail.activationSources) {
+      const key = sourceKey(activation.source.kind, activation.source.id);
+      const current =
+        consumersBySource.get(key) ??
+        ({
+          id: activation.source.id,
+          kind: activation.source.kind,
+          trailIds: new Set<string>(),
+        } as const);
+      current.trailIds.add(trail.id);
+      consumersBySource.set(key, current);
+    }
+  }
+
+  return [...consumersBySource.entries()]
+    .map(([key, source]) => ({
+      id: source.id,
+      key,
+      kind: source.kind,
+      trailIds: sortedUnique(source.trailIds),
+    }))
+    .toSorted((a, b) => a.key.localeCompare(b.key));
+};
+
+const isUnmaterialized = (kind: ActivationSourceKind): boolean =>
+  PENDING_SOURCE_KINDS.has(kind) && !MATERIALIZED_SOURCE_KINDS.has(kind);
+
+const buildDiagnostic = (source: SourceConsumers): WardenDiagnostic => ({
+  filePath: TOPO_FILE,
+  line: 1,
+  message: `Activation source "${source.id}" of kind "${source.kind}" activates trail${source.trailIds.length === 1 ? '' : 's'} ${source.trailIds.map((id) => `"${id}"`).join(', ')} but no built-in materializer is available in this stack. Add the materializer before relying on runtime delivery, or defer the source declaration until the materializer lands.`,
+  rule: RULE_NAME,
+  severity: 'warn',
+});
+
+export const unmaterializedActivationSource: TopoAwareWardenRule = {
+  checkTopo: (topo) =>
+    collectSourceConsumers(topo)
+      .filter((source) => isUnmaterialized(source.kind))
+      .map((source) => buildDiagnostic(source)),
+  description:
+    'Warn when declared activation sources do not have an available runtime materializer.',
+  name: RULE_NAME,
+  severity: 'warn',
+};