@ontrails/warden 1.0.0-beta.13 → 1.0.0-beta.15

package/src/trails/{provision-exists.trail.ts → resource-exists.trail.ts}

@@ -1,27 +1,27 @@
-import { provisionExists } from '../rules/provision-exists.js';
+import { resourceExists } from '../rules/resource-exists.js';
 import { wrapRule } from './wrap-rule.js';
 
-export const provisionExistsTrail = wrapRule({
+export const resourceExistsTrail = wrapRule({
   examples: [
     {
       expected: { diagnostics: [] },
       input: {
         filePath: 'clean.ts',
-        knownProvisionIds: ['db.main'],
+        knownResourceIds: ['db.main'],
         knownTrailIds: ['entity.show'],
-        sourceCode: `const db = provision("db.main", {
+        sourceCode: `const db = resource("db.main", {
   create: () => Result.ok({ source: "factory" }),
 });
 
 trail("entity.show", {
-  provisions: [db],
+  resources: [db],
   blaze: async (_input, ctx) => {
     return Result.ok(db.from(ctx));
   }
 })`,
       },
-      name: 'Declared provisions resolve to known project provisions',
+      name: 'Declared resources resolve to known project resources',
     },
   ],
-  rule: provisionExists,
+  rule: resourceExists,
 });

package/src/trails/resource-id-grammar.trail.ts

@@ -0,0 +1,39 @@
+import { resourceIdGrammar } from '../rules/resource-id-grammar.js';
+import { wrapRule } from './wrap-rule.js';
+
+export const resourceIdGrammarTrail = wrapRule({
+  examples: [
+    {
+      expected: { diagnostics: [] },
+      input: {
+        filePath: 'clean.ts',
+        sourceCode: `const db = resource("db.main", {
+  create: () => Result.ok({}),
+});`,
+      },
+      name: 'Resource ids stay free of the scope separator',
+    },
+    {
+      expected: {
+        diagnostics: [
+          {
+            filePath: 'invalid.ts',
+            line: 1,
+            message:
+              'Resource "billing:primary" is invalid because resource ids may not contain ":".',
+            rule: 'resource-id-grammar',
+            severity: 'error',
+          },
+        ],
+      },
+      input: {
+        filePath: 'invalid.ts',
+        sourceCode: `const db = resource("billing:primary", {
+  create: () => Result.ok({}),
+});`,
+      },
+      name: 'Colon-separated resource ids are rejected',
+    },
+  ],
+  rule: resourceIdGrammar,
+});

package/src/trails/run.ts

@@ -1,51 +1,148 @@
 /**
- * Run all warden rule trails against a single source file.
+ * Run file-scoped warden rule trails against a single source file.
  *
- * Returns a flat array of diagnostics from every rule.
+ * Returns a flat array of diagnostics from every source-aware rule. Built-in
+ * topo-aware rules are dispatched separately via `runTopoAwareWardenTrails()`
+ * so callers that loop files do not duplicate graph-level findings.
  */
 
+import type { Topo } from '@ontrails/core';
 import { run } from '@ontrails/core';
 
+import { wardenTopoRules } from '../rules/index.js';
 import type { WardenDiagnostic } from '../rules/types.js';
 import type { RuleOutput } from './schema.js';
 import { wardenTopo } from './topo.js';
 
 /**
- * Run all warden rule trails for a given file and collect diagnostics.
+ * Run all file-scoped warden rule trails for a given file and collect diagnostics.
  *
  * Each rule trail runs independently. Errors from individual trails are
  * silently skipped so that one broken rule does not block the rest.
  */
-export const runWardenTrails = async (
+const appendDiagnostics = (
+  target: WardenDiagnostic[],
+  diagnostics: readonly WardenDiagnostic[]
+): void => {
+  for (const diagnostic of diagnostics) {
+    target.push(diagnostic);
+  }
+};
+
+type TrailIntentMap = Readonly<Record<string, 'destroy' | 'read' | 'write'>>;
+
+interface ProjectRuleOptions {
+  readonly contourReferencesByName?: Readonly<
+    Record<string, readonly string[]>
+  >;
+  readonly crossTargetTrailIds?: readonly string[];
+  readonly crudTableIds?: readonly string[];
+  readonly crudCoverageByEntity?: Readonly<Record<string, readonly string[]>>;
+  readonly knownContourIds?: readonly string[];
+  readonly knownResourceIds?: readonly string[];
+  readonly knownSignalIds?: readonly string[];
+  readonly knownTrailIds?: readonly string[];
+  readonly onTargetSignalIds?: readonly string[];
+  readonly reconcileTableIds?: readonly string[];
+  readonly trailIntentsById?: TrailIntentMap;
+}
+
+const PROJECT_OPTION_KEYS = [
+  'contourReferencesByName',
+  'crossTargetTrailIds',
+  'crudTableIds',
+  'crudCoverageByEntity',
+  'knownContourIds',
+  'knownResourceIds',
+  'knownSignalIds',
+  'knownTrailIds',
+  'onTargetSignalIds',
+  'reconcileTableIds',
+  'trailIntentsById',
+] as const satisfies readonly (keyof ProjectRuleOptions)[];
+
+const hasProjectOptions = (options?: ProjectRuleOptions): boolean =>
+  Boolean(
+    options && PROJECT_OPTION_KEYS.some((key) => options[key] !== undefined)
+  );
+
+const collectProjectOptions = (
+  options?: ProjectRuleOptions
+): ProjectRuleOptions => {
+  if (!options) {
+    return {};
+  }
+
+  return Object.fromEntries(
+    PROJECT_OPTION_KEYS.flatMap((key) => {
+      const value = options[key];
+      return value === undefined ? [] : [[key, value] as const];
+    })
+  ) as ProjectRuleOptions;
+};
+
+const buildRuleInput = (
   filePath: string,
   sourceCode: string,
-  options?: {
-    readonly knownProvisionIds?: readonly string[];
-    readonly knownTrailIds?: readonly string[];
+  options?: ProjectRuleOptions
+): {
+  readonly filePath: string;
+  readonly sourceCode: string;
+} & ProjectRuleOptions => {
+  const base = { filePath, sourceCode };
+  if (!hasProjectOptions(options)) {
+    return base;
   }
+
+  return { ...base, ...collectProjectOptions(options) };
+};
+
+const topoAwareTrailIds = new Set(
+  [...wardenTopoRules.keys()].map((ruleName) => `warden.rule.${ruleName}`)
+);
+
+export const runWardenTrails = async (
+  filePath: string,
+  sourceCode: string,
+  options?: ProjectRuleOptions
 ): Promise<readonly WardenDiagnostic[]> => {
   const allDiagnostics: WardenDiagnostic[] = [];
+  const input = buildRuleInput(filePath, sourceCode, options);
 
   for (const id of wardenTopo.ids()) {
-    const input =
-      options?.knownTrailIds || options?.knownProvisionIds
-        ? {
-            filePath,
-            ...(options?.knownProvisionIds
-              ? { knownProvisionIds: options.knownProvisionIds }
-              : {}),
-            ...(options?.knownTrailIds
-              ? { knownTrailIds: options.knownTrailIds }
-              : {}),
-            sourceCode,
-          }
-        : { filePath, sourceCode };
+    if (topoAwareTrailIds.has(id)) {
+      continue;
+    }
     const result = await run(wardenTopo, id, input);
     if (result.isOk()) {
-      const { diagnostics } = result.value as RuleOutput;
-      for (const d of diagnostics) {
-        allDiagnostics.push(d);
-      }
+      appendDiagnostics(
+        allDiagnostics,
+        (result.value as RuleOutput).diagnostics
+      );
+    }
+  }
+
+  return allDiagnostics;
+};
+
+/**
+ * Run the built-in topo-aware warden rule trails once against a resolved topo.
+ *
+ * Unlike `runWardenTrails()`, which is file-scoped, topo-aware rules inspect
+ * the compiled graph and should only be dispatched once per topo.
+ */
+export const runTopoAwareWardenTrails = async (
+  topo: Topo
+): Promise<readonly WardenDiagnostic[]> => {
+  const allDiagnostics: WardenDiagnostic[] = [];
+
+  for (const id of topoAwareTrailIds) {
+    const result = await run(wardenTopo, id, { topo });
+    if (result.isOk()) {
+      appendDiagnostics(
+        allDiagnostics,
+        (result.value as RuleOutput).diagnostics
+      );
     }
   }
 

package/src/trails/schema.ts

@@ -5,6 +5,7 @@
  * (array of diagnostics) shape.
  */
 
+import type { Topo } from '@ontrails/core';
 import { z } from 'zod';
 
 /** A single diagnostic emitted by a warden rule trail. */
@@ -26,18 +27,78 @@ export const ruleInput = z.object({
  * Extended input for project-aware warden rule trails.
  *
  * Adds `knownTrailIds` so the caller can supply cross-file context and avoid
- * false positives for detour targets or `@see` references defined in other
- * files.
+ * false positives for `@see` references or cross-file contour relationships.
  */
 export const projectAwareRuleInput = ruleInput.extend({
-  knownProvisionIds: z
+  contourReferencesByName: z
+    .record(z.string(), z.array(z.string()))
+    .optional()
+    .describe('Declared contour references keyed by source contour name'),
+  crossTargetTrailIds: z
+    .array(z.string())
+    .optional()
+    .describe('Trail IDs referenced by crosses arrays across the project'),
+  crudCoverageByEntity: z
+    .record(z.string(), z.array(z.string()))
+    .optional()
+    .describe(
+      'CRUD operation coverage per entity aggregated across the project'
+    ),
+  crudTableIds: z
+    .array(z.string())
+    .optional()
+    .describe('Store table IDs used with CRUD factories across the project'),
+  knownContourIds: z
+    .array(z.string())
+    .optional()
+    .describe('Contour names known across the project'),
+  knownResourceIds: z
+    .array(z.string())
+    .optional()
+    .describe('Resource IDs known across the project'),
+  knownSignalIds: z
     .array(z.string())
     .optional()
-    .describe('Provision IDs known across the project'),
+    .describe('Signal IDs known across the project'),
   knownTrailIds: z
     .array(z.string())
     .optional()
     .describe('Trail IDs known across the project'),
+  onTargetSignalIds: z
+    .array(z.string())
+    .optional()
+    .describe('Signal IDs referenced by trail on arrays across the project'),
+  reconcileTableIds: z
+    .array(z.string())
+    .optional()
+    .describe('Store table IDs used with reconcile trails across the project'),
+  trailIntentsById: z
+    .record(z.string(), z.enum(['read', 'write', 'destroy']))
+    .optional()
+    .describe('Normalized trail intents keyed by trail ID'),
+});
+
+/**
+ * Input for topo-aware warden rule trails.
+ *
+ * The `Topo` graph is not a serializable value, so the schema accepts it
+ * as an opaque `z.custom`. Topo-aware rules are invoked from the warden
+ * runtime with a live, resolved topo reference — they are not expected
+ * to be called across a network boundary.
+ */
+export const topoAwareRuleInput = z.object({
+  topo: z
+    .custom<Topo>(
+      (value) =>
+        typeof value === 'object' &&
+        value !== null &&
+        'trails' in value &&
+        'resources' in value &&
+        'contours' in value &&
+        'signals' in value,
+      { message: 'Expected a resolved Topo instance' }
+    )
+    .describe('Resolved topo graph under inspection'),
 });
 
 /** Output returned by every warden rule trail. */
@@ -47,4 +108,5 @@ export const ruleOutput = z.object({
 
 export type RuleInput = z.infer<typeof ruleInput>;
 export type ProjectAwareRuleInput = z.infer<typeof projectAwareRuleInput>;
+export type TopoAwareRuleInput = z.infer<typeof topoAwareRuleInput>;
 export type RuleOutput = z.infer<typeof ruleOutput>;

package/src/trails/unreachable-detour-shadowing.trail.ts

@@ -0,0 +1,45 @@
+import { unreachableDetourShadowing } from '../rules/unreachable-detour-shadowing.js';
+import { wrapRule } from './wrap-rule.js';
+
+export const unreachableDetourShadowingTrail = wrapRule({
+  examples: [
+    {
+      expected: { diagnostics: [] },
+      input: {
+        filePath: 'clean.ts',
+        sourceCode: `trail("entity.save", {
+  detours: [
+    { on: ConflictError, recover: async () => Result.ok({ winner: "specific" }) },
+    { on: TrailsError, recover: async () => Result.ok({ winner: "broad" }) },
+  ],
+});`,
+      },
+      name: 'Specific detours can precede broader ones',
+    },
+    {
+      expected: {
+        diagnostics: [
+          {
+            filePath: 'shadowed.ts',
+            line: 4,
+            message:
+              'Trail "entity.save" declares detour on "ConflictError" after earlier detour on "TrailsError". Because "TrailsError" matches "ConflictError" first, the later detour is unreachable.',
+            rule: 'unreachable-detour-shadowing',
+            severity: 'error',
+          },
+        ],
+      },
+      input: {
+        filePath: 'shadowed.ts',
+        sourceCode: `trail("entity.save", {
+  detours: [
+    { on: TrailsError, recover: async () => Result.ok({ winner: "broad" }) },
+    { on: ConflictError, recover: async () => Result.ok({ winner: "specific" }) },
+  ],
+});`,
+      },
+      name: 'Broader detours declared first shadow later specific ones',
+    },
+  ],
+  rule: unreachableDetourShadowing,
+});

package/src/trails/valid-detour-contract.trail.ts

@@ -0,0 +1,71 @@
+import { ConflictError, Result, topo, trail } from '@ontrails/core';
+import { z } from 'zod';
+
+import { validDetourContract } from '../rules/valid-detour-contract.js';
+import { wrapTopoRule } from './wrap-rule.js';
+
+const validTrail = trail('entity.save', {
+  blaze: () => Result.ok({ ok: true }),
+  detours: [
+    {
+      on: ConflictError,
+      recover: async () => {
+        const result = await Promise.resolve(Result.ok({ ok: true }));
+        return result;
+      },
+    },
+  ],
+  input: z.object({}),
+  output: z.object({ ok: z.boolean() }),
+});
+
+const invalidContractTrail = {
+  ...validTrail,
+  detours: [
+    {
+      on: 'ConflictError',
+      recover: 'not a function',
+    },
+  ],
+} as unknown as typeof validTrail;
+
+export const validDetourContractTrail = wrapTopoRule({
+  examples: [
+    {
+      expected: { diagnostics: [] },
+      input: {
+        topo: topo('trl-380-valid-detour-contract', { validTrail }),
+      },
+      name: 'Detours with an error constructor and recover function stay clean',
+    },
+    {
+      expected: {
+        diagnostics: [
+          {
+            filePath: '<topo>',
+            line: 1,
+            message:
+              'Trail "entity.save" detour[0] must declare an error constructor in on:. Received ConflictError.',
+            rule: 'valid-detour-contract',
+            severity: 'error',
+          },
+          {
+            filePath: '<topo>',
+            line: 1,
+            message:
+              'Trail "entity.save" detour[0] must declare a callable recover function.',
+            rule: 'valid-detour-contract',
+            severity: 'error',
+          },
+        ],
+      },
+      input: {
+        topo: topo('trl-380-invalid-detour-contract', {
+          invalidContractTrail,
+        } as Record<string, unknown>),
+      },
+      name: 'Malformed detour contracts emit diagnostics',
+    },
+  ],
+  rule: validDetourContract,
+});

package/src/trails/warden-export-symmetry.trail.ts

@@ -0,0 +1,16 @@
+import { wardenExportSymmetry } from '../rules/warden-export-symmetry.js';
+import { wrapRule } from './wrap-rule.js';
+
+export const wardenExportSymmetryTrail = wrapRule({
+  examples: [
+    {
+      expected: { diagnostics: [] },
+      input: {
+        filePath: 'packages/other-pkg/src/index.ts',
+        sourceCode: `export { somethingElse } from './other.js';\n`,
+      },
+      name: 'Ignores files outside the warden barrel',
+    },
+  ],
+  rule: wardenExportSymmetry,
+});

package/src/trails/warden-rules-use-ast.trail.ts

@@ -0,0 +1,45 @@
+import { fileURLToPath } from 'node:url';
+import { wardenRulesUseAst } from '../rules/warden-rules-use-ast.js';
+import { wrapRule } from './wrap-rule.js';
+
+/**
+ * Resolve a filePath inside this package's `src/rules/` directory so the
+ * positive example fires the path-anchored scope check. Anchoring via
+ * `import.meta.url` keeps the example robust to the cwd under which tests run.
+ */
+const fakeRulePath = fileURLToPath(
+  new URL('../rules/fake-rule.ts', import.meta.url)
+);
+
+export const wardenRulesUseAstTrail = wrapRule({
+  examples: [
+    {
+      expected: { diagnostics: [] },
+      input: {
+        filePath: 'packages/other-pkg/src/index.ts',
+        sourceCode: `const lines = sourceCode.split('\\n');\n`,
+      },
+      name: 'Ignores files outside the warden rules directory',
+    },
+    {
+      expected: {
+        diagnostics: [
+          {
+            filePath: fakeRulePath,
+            line: 1,
+            message:
+              'warden-rules-use-ast: sourceCode.split(...) treats source text as a string. Warden rules must inspect the AST via packages/warden/src/rules/ast.ts helpers, not regex-scan raw source text. Use findStringLiterals, findTrailDefinitions, findConfigProperty, or a similar AST walker. Raw-text scanning produces false positives on string literals, template payloads, and docstrings — see TRL-335, ADR-0036.',
+            rule: 'warden-rules-use-ast',
+            severity: 'error',
+          },
+        ],
+      },
+      input: {
+        filePath: fakeRulePath,
+        sourceCode: `export const r = { check(sourceCode: string) { return sourceCode.split('\\n'); } };\n`,
+      },
+      name: 'Flags sourceCode.split(...) in a rule file',
+    },
+  ],
+  rule: wardenRulesUseAst,
+});

package/src/trails/wrap-rule.ts

@@ -4,16 +4,27 @@
  * Keeps each rule trail file minimal — just the import + examples.
  */
 
-import { trail, Result } from '@ontrails/core';
+import { InternalError, trail, Result } from '@ontrails/core';
 import type { Trail } from '@ontrails/core';
 
 import type {
   ProjectAwareWardenRule,
   ProjectContext,
+  TopoAwareWardenRule,
   WardenRule,
 } from '../rules/types.js';
-import { projectAwareRuleInput, ruleInput, ruleOutput } from './schema.js';
-import type { ProjectAwareRuleInput, RuleInput, RuleOutput } from './schema.js';
+import {
+  projectAwareRuleInput,
+  ruleInput,
+  ruleOutput,
+  topoAwareRuleInput,
+} from './schema.js';
+import type {
+  ProjectAwareRuleInput,
+  RuleInput,
+  RuleOutput,
+  TopoAwareRuleInput,
+} from './schema.js';
 
 interface WrapRuleOptions {
   /** The existing warden rule to wrap. */
@@ -29,6 +40,53 @@ interface WrapProjectAwareRuleOptions {
   readonly examples: Trail<ProjectAwareRuleInput, RuleOutput>['examples'];
 }
 
+const buildProjectContext = (input: ProjectAwareRuleInput): ProjectContext => ({
+  ...(input.contourReferencesByName
+    ? {
+        contourReferencesByName: new Map(
+          Object.entries(input.contourReferencesByName)
+        ),
+      }
+    : {}),
+  ...(input.crudTableIds ? { crudTableIds: new Set(input.crudTableIds) } : {}),
+  ...(input.crudCoverageByEntity
+    ? {
+        crudCoverageByEntity: new Map(
+          Object.entries(input.crudCoverageByEntity).map(
+            ([entityId, operations]) => [
+              entityId,
+              new Set(operations) as ReadonlySet<string>,
+            ]
+          )
+        ),
+      }
+    : {}),
+  ...(input.knownContourIds
+    ? { knownContourIds: new Set(input.knownContourIds) }
+    : {}),
+  knownTrailIds: input.knownTrailIds
+    ? new Set(input.knownTrailIds)
+    : new Set<string>(),
+  ...(input.crossTargetTrailIds
+    ? { crossTargetTrailIds: new Set(input.crossTargetTrailIds) }
+    : {}),
+  ...(input.knownResourceIds
+    ? { knownResourceIds: new Set(input.knownResourceIds) }
+    : {}),
+  ...(input.knownSignalIds
+    ? { knownSignalIds: new Set(input.knownSignalIds) }
+    : {}),
+  ...(input.onTargetSignalIds
+    ? { onTargetSignalIds: new Set(input.onTargetSignalIds) }
+    : {}),
+  ...(input.reconcileTableIds
+    ? { reconcileTableIds: new Set(input.reconcileTableIds) }
+    : {}),
+  ...(input.trailIntentsById
+    ? { trailIntentsById: new Map(Object.entries(input.trailIntentsById)) }
+    : {}),
+});
+
 /**
  * Wrap an existing `WardenRule` as a trail with typed input/output.
  *
@@ -50,18 +108,10 @@ export function wrapRule(
     const projectAwareRule = rule as ProjectAwareWardenRule;
     return trail(`warden.rule.${rule.name}`, {
       blaze: (input: ProjectAwareRuleInput) => {
-        const context = {
-          knownProvisionIds: input.knownProvisionIds
-            ? new Set(input.knownProvisionIds)
-            : undefined,
-          knownTrailIds: input.knownTrailIds
-            ? new Set(input.knownTrailIds)
-            : new Set<string>(),
-        } as ProjectContext;
         const diagnostics = projectAwareRule.checkWithContext(
           input.sourceCode,
           input.filePath,
-          context
+          buildProjectContext(input)
         );
         return Result.ok({ diagnostics: [...diagnostics] });
       },
@@ -90,3 +140,45 @@ export function wrapRule(
     output: ruleOutput,
   });
 }
+
+interface WrapTopoRuleOptions {
+  /** The existing topo-aware warden rule to wrap. */
+  readonly rule: TopoAwareWardenRule;
+  /** Trail examples for testing and documentation. */
+  readonly examples: Trail<TopoAwareRuleInput, RuleOutput>['examples'];
+}
+
+/**
+ * Wrap an existing `TopoAwareWardenRule` as a trail.
+ *
+ * Mirrors `wrapRule` for the per-topo dispatch path. Topo-aware rules run
+ * once per topo against the compiled runtime graph rather than per file,
+ * so the trail accepts the live `Topo` as input.
+ */
+export const wrapTopoRule = (
+  options: WrapTopoRuleOptions
+): Trail<TopoAwareRuleInput, RuleOutput> => {
+  const { rule, examples } = options;
+  return trail(`warden.rule.${rule.name}`, {
+    blaze: async (input: TopoAwareRuleInput) => {
+      try {
+        const diagnostics = await rule.checkTopo(input.topo);
+        return Result.ok({ diagnostics: [...diagnostics] });
+      } catch (error) {
+        const cause = error instanceof Error ? error : new Error(String(error));
+        return Result.err(
+          new InternalError(
+            `Topo-aware rule "${rule.name}" threw while inspecting topo: ${cause.message}`,
+            { cause }
+          )
+        );
+      }
+    },
+    description: rule.description,
+    examples,
+    input: topoAwareRuleInput,
+    intent: 'read',
+    meta: { category: 'governance', severity: rule.severity },
+    output: ruleOutput,
+  });
+};

package/tsconfig.tests.json

@@ -0,0 +1,10 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "noEmit": true,
+    "rootDir": "./src",
+    "types": ["bun"]
+  },
+  "include": ["src/**/*.test.ts", "src/__tests__/**/*.ts"],
+  "exclude": []
+}