@ontrails/warden 1.0.0-beta.14 → 1.0.0-beta.16

package/src/trails/static-resource-accessor-preference.trail.ts

@@ -0,0 +1,25 @@
+import { staticResourceAccessorPreference } from '../rules/static-resource-accessor-preference.js';
+import { wrapRule } from './wrap-rule.js';
+
+export const staticResourceAccessorPreferenceTrail = wrapRule({
+  examples: [
+    {
+      expected: { diagnostics: [] },
+      input: {
+        filePath: 'clean.ts',
+        sourceCode: `const db = resource("db.main", {
+  create: () => Result.ok({ source: "factory" }),
+});
+
+trail("entity.show", {
+  resources: [db],
+  blaze: async (_input, ctx) => {
+    return Result.ok(db.from(ctx));
+  }
+})`,
+      },
+      name: 'Static resource helper access',
+    },
+  ],
+  rule: staticResourceAccessorPreference,
+});

package/src/trails/unmaterialized-activation-source.trail.ts

@@ -0,0 +1,69 @@
+import { Result, schedule, signal, topo, trail, webhook } from '@ontrails/core';
+import { z } from 'zod';
+
+import { unmaterializedActivationSource } from '../rules/unmaterialized-activation-source.js';
+import { wrapTopoRule } from './wrap-rule.js';
+
+const invoicePaidWebhook = webhook('webhook.invoice.paid', {
+  parse: z.object({ invoiceId: z.string() }),
+  path: '/webhooks/invoice/paid',
+});
+
+const webhookConsumer = trail('invoice.audit-webhook', {
+  blaze: () => Result.ok({ ok: true }),
+  input: z.object({ invoiceId: z.string() }),
+  on: [invoicePaidWebhook],
+  output: z.object({ ok: z.boolean() }),
+});
+
+const invoiceCreated = signal('invoice.created', {
+  from: ['invoice.create'],
+  payload: z.object({ invoiceId: z.string() }),
+});
+
+const signalProducer = trail('invoice.create', {
+  blaze: () => Result.ok({ invoiceId: 'inv_1' }),
+  fires: [invoiceCreated],
+  input: z.object({}),
+  output: z.object({ invoiceId: z.string() }),
+});
+
+const signalConsumer = trail('invoice.index', {
+  blaze: () => Result.ok({ ok: true }),
+  input: z.object({ invoiceId: z.string() }),
+  on: [invoiceCreated],
+  output: z.object({ ok: z.boolean() }),
+});
+
+const scheduleConsumer = trail('invoice.reconcile', {
+  blaze: () => Result.ok({ ok: true }),
+  input: z.object({}),
+  on: [schedule('schedule.invoice.reconcile', { cron: '0 * * * *' })],
+  output: z.object({ ok: z.boolean() }),
+});
+
+export const unmaterializedActivationSourceTrail = wrapTopoRule({
+  examples: [
+    {
+      expected: { diagnostics: [] },
+      input: {
+        topo: topo('trl-461-webhook-materialized', { webhookConsumer }),
+      },
+      name: 'Webhook activation sources are materialized by HTTP',
+    },
+    {
+      expected: { diagnostics: [] },
+      input: {
+        topo: topo('trl-496-materialized-sources', {
+          invoiceCreated,
+          scheduleConsumer,
+          signalConsumer,
+          signalProducer,
+          webhookConsumer,
+        }),
+      },
+      name: 'Signal, schedule, and webhook activation sources are materialized',
+    },
+  ],
+  rule: unmaterializedActivationSource,
+});

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/webhook-route-collision.trail.ts

@@ -0,0 +1,50 @@
+import { Result, topo, trail, webhook } from '@ontrails/core';
+import { z } from 'zod';
+
+import { webhookRouteCollision } from '../rules/webhook-route-collision.js';
+import { wrapTopoRule } from './wrap-rule.js';
+
+const paymentWebhook = webhook('webhook.payment.received', {
+  parse: z.object({ paymentId: z.string() }),
+  path: '/webhooks/payment',
+});
+
+const paymentReceiver = trail('payment.receive', {
+  blaze: () => Result.ok({ ok: true }),
+  input: z.object({ paymentId: z.string() }),
+  on: [paymentWebhook],
+  output: z.object({ ok: z.boolean() }),
+});
+
+const directRoute = trail('webhooks.payment', {
+  blaze: () => Result.ok({ ok: true }),
+  input: z.object({}),
+  output: z.object({ ok: z.boolean() }),
+});
+
+export const webhookRouteCollisionTrail = wrapTopoRule({
+  examples: [
+    {
+      expected: {
+        diagnostics: [
+          {
+            filePath: '<topo>',
+            line: 1,
+            message:
+              'HTTP webhook route collision on POST /webhooks/payment: derived trail route "webhooks.payment", webhook source "webhook.payment.received" on trail "payment.receive". Give each webhook source a distinct method/path pair or move the direct trail route before materializing the HTTP surface.',
+            rule: 'webhook-route-collision',
+            severity: 'error',
+          },
+        ],
+      },
+      input: {
+        topo: topo('trl-461-webhook-route-collision', {
+          directRoute,
+          paymentReceiver,
+        }),
+      },
+      name: 'Webhook route colliding with a derived direct HTTP route',
+    },
+  ],
+  rule: webhookRouteCollision,
+});

package/src/trails/wrap-rule.ts

@@ -4,16 +4,28 @@
  * 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 { getWardenRuleMetadata } from '../rules/metadata.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 +41,79 @@ interface WrapProjectAwareRuleOptions {
   readonly examples: Trail<ProjectAwareRuleInput, RuleOutput>['examples'];
 }
 
+const buildRuleMeta = (rule: WardenRule | TopoAwareWardenRule) => {
+  const metadata = getWardenRuleMetadata(rule);
+  return {
+    category: 'governance',
+    ...(metadata ? { warden: metadata } : {}),
+    severity: rule.severity,
+  };
+};
+
+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) }
+    : {}),
+  ...(input.importResolutionsByFile
+    ? {
+        importResolutionsByFile: new Map(
+          Object.entries(input.importResolutionsByFile)
+        ),
+      }
+    : {}),
+  ...(input.documentedImportResolutionsByFile
+    ? {
+        documentedImportResolutionsByFile: new Map(
+          Object.entries(input.documentedImportResolutionsByFile)
+        ),
+      }
+    : {}),
+  ...(input.publicWorkspaces
+    ? { publicWorkspaces: new Map(Object.entries(input.publicWorkspaces)) }
+    : {}),
+  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 +135,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] });
       },
@@ -72,7 +149,7 @@ export function wrapRule(
       >['examples'],
       input: projectAwareRuleInput,
       intent: 'read',
-      meta: { category: 'governance', severity: rule.severity },
+      meta: buildRuleMeta(rule),
       output: ruleOutput,
     });
   }
@@ -86,7 +163,49 @@ export function wrapRule(
     examples: examples as Trail<RuleInput, RuleOutput>['examples'],
     input: ruleInput,
     intent: 'read',
-    meta: { category: 'governance', severity: rule.severity },
+    meta: buildRuleMeta(rule),
     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: buildRuleMeta(rule),
+    output: ruleOutput,
+  });
+};