@ontrails/warden 1.0.0-beta.3 → 1.0.0-beta.32

package/src/trails/signal-graph-coaching.trail.ts

@@ -0,0 +1,77 @@
+import { Result, resource, signal, topo, trail } from '@ontrails/core';
+import { z } from 'zod';
+
+import { signalGraphCoaching } from '../rules/signal-graph-coaching.js';
+import { wrapTopoRule } from './wrap-rule.js';
+
+const unusedSignal = signal('invoice.unused', {
+  payload: z.object({ invoiceId: z.string() }),
+});
+
+const producedSignal = signal('invoice.created', {
+  payload: z.object({ invoiceId: z.string() }),
+});
+
+const producerTrail = trail('invoice.create', {
+  blaze: async (_input, ctx) => {
+    await ctx.fire?.(producedSignal, { invoiceId: 'inv_1' });
+    return Result.ok({ invoiceId: 'inv_1' });
+  },
+  fires: [producedSignal],
+  input: z.object({}),
+  output: z.object({ invoiceId: z.string() }),
+});
+
+const resourceSignal = signal('store:invoice.created', {
+  payload: z.object({ invoiceId: z.string() }),
+});
+
+const invoiceStore = resource('store', {
+  create: () => Result.ok({ ok: true }),
+  signals: [resourceSignal],
+});
+
+export const signalGraphCoachingTrail = wrapTopoRule({
+  examples: [
+    {
+      expected: {
+        diagnostics: [
+          {
+            filePath: '<topo>',
+            line: 1,
+            message:
+              'Signal "invoice.created" is produced by producer trail "invoice.create" 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: 'signal-graph-coaching',
+            severity: 'warn',
+          },
+          {
+            filePath: '<topo>',
+            line: 1,
+            message:
+              'Signal "invoice.unused" 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: 'signal-graph-coaching',
+            severity: 'warn',
+          },
+          {
+            filePath: '<topo>',
+            line: 1,
+            message:
+              'Signal "store:invoice.created" is produced by producer resource "store" 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: 'signal-graph-coaching',
+            severity: 'warn',
+          },
+        ],
+      },
+      input: {
+        topo: topo('trl-447-signal-graph-coaching', {
+          invoiceStore,
+          producedSignal,
+          producerTrail,
+          unusedSignal,
+        }),
+      },
+      name: 'Declared and produced signals without consumers get coaching',
+    },
+  ],
+  rule: signalGraphCoaching,
+});

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/surface-facet-coherence.trail.ts

@@ -0,0 +1,25 @@
+import { surfaceFacetCoherence } from '../rules/surface-facet-coherence.js';
+import { wrapRule } from './wrap-rule.js';
+
+export const surfaceFacetCoherenceTrail = wrapRule({
+  examples: [
+    {
+      expected: { diagnostics: [] },
+      input: {
+        filePath: 'mcp-options.ts',
+        sourceCode: `export const facets = {
+  inspect: {
+    description: "Inspect topo state.",
+    trails: ["survey", "survey.brief"],
+  },
+  governance: {
+    description: "Run diagnostics.",
+    trails: ["warden", "doctor"],
+  },
+};`,
+      },
+      name: 'Reviewable trailhead map',
+    },
+  ],
+  rule: surfaceFacetCoherence,
+});

package/src/trails/topo.ts

@@ -0,0 +1,6 @@
+import { topo } from '@ontrails/core';
+
+import * as rules from './index.js';
+
+/** Topo collecting all warden rule trails. */
+export const wardenTopo = topo('warden', rules);

package/src/trails/trail-fork-coaching.trail.ts

@@ -0,0 +1,42 @@
+import { trailForkCoaching } from '../rules/trail-fork-coaching.js';
+import { wrapRule } from './wrap-rule.js';
+
+export const trailForkCoachingTrail = wrapRule({
+  examples: [
+    {
+      expected: {
+        diagnostics: [
+          {
+            filePath: 'users.ts',
+            line: 9,
+            message:
+              'Trail "users.manage" branches on input.action ("create", "delete"). This may be a trail fork hidden as a surface accommodation. If branches change semantics (intent, permits, errors, outputs, lifecycle, or side effects) or structure (selected trail identity), split them into distinct trails, a composing trail, or a trailhead that preserves member identity.',
+            rule: 'trail-fork-coaching',
+            severity: 'warn',
+          },
+        ],
+      },
+      input: {
+        filePath: 'users.ts',
+        sourceCode: `import { Result, trail } from "@ontrails/core";
+import { z } from "zod";
+
+export const usersManage = trail("users.manage", {
+  input: z.object({
+    action: z.enum(["create", "delete"]),
+  }),
+  blaze: async (input) => {
+    switch (input.action) {
+      case "create":
+        return Result.ok({ created: true });
+      case "delete":
+        return Result.ok({ deleted: true });
+    }
+  },
+});`,
+      },
+      name: 'Possible trail fork hidden behind action',
+    },
+  ],
+  rule: trailForkCoaching,
+});

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

@@ -0,0 +1,72 @@
+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: async (_input, ctx) => {
+    await ctx.fire?.(invoiceCreated, { invoiceId: 'inv_1' });
+    return 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-describe-refs.trail.ts

@@ -0,0 +1,18 @@
+import { validDescribeRefs } from '../rules/valid-describe-refs.js';
+import { wrapRule } from './wrap-rule.js';
+
+export const validDescribeRefsTrail = wrapRule({
+  examples: [
+    {
+      expected: { diagnostics: [] },
+      input: {
+        filePath: 'clean.ts',
+        sourceCode: `const schema = z.object({
+  name: z.string().describe("User display name"),
+});`,
+      },
+      name: 'Describe without @see refs',
+    },
+  ],
+  rule: validDescribeRefs,
+});

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. Expected recover: (attempt, ctx) => Promise<Result<...>>; inspect attempt.error for the matched error and return Result.err(...) for unrecoverable cases.',
+            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/version-gap.trail.ts

@@ -0,0 +1,35 @@
+import { Result, topo, trail } from '@ontrails/core';
+import { z } from 'zod';
+
+import { versionGap } from '../rules/trail-versioning-topo.js';
+import { wrapTopoRule } from './wrap-rule.js';
+
+const versionedTrail = trail('version.gap.clean', {
+  blaze: () => Result.ok({ ok: true }),
+  input: z.object({}),
+  output: z.object({ ok: z.boolean() }),
+  version: 2,
+  versions: {
+    1: {
+      input: z.object({}),
+      output: z.object({ ok: z.boolean() }),
+      transpose: {
+        input: () => ({}),
+        output: ({ output }) => output,
+      },
+    },
+  },
+});
+
+export const versionGapTrail = wrapTopoRule({
+  examples: [
+    {
+      expected: { diagnostics: [] },
+      input: {
+        topo: topo('version-gap-clean', { versionedTrail }),
+      },
+      name: 'Contiguous versions pass',
+    },
+  ],
+  rule: versionGap,
+});

package/src/trails/version-pinned-compose.trail.ts

@@ -0,0 +1,23 @@
+import { versionPinnedCompose } from '../rules/trail-versioning-source.js';
+import { wrapRule } from './wrap-rule.js';
+
+export const versionPinnedComposeTrail = wrapRule({
+  examples: [
+    {
+      expected: { diagnostics: [] },
+      input: {
+        filePath: 'src/trails/current.ts',
+        sourceCode: `
+trail('current.parent', {
+  blaze: async (_input, ctx) => {
+    await ctx.compose('current.child', {});
+    return Result.ok({});
+  },
+});
+`,
+      },
+      name: 'Current composition has no version-pin warning',
+    },
+  ],
+  rule: versionPinnedCompose,
+});

package/src/trails/version-without-examples.trail.ts

@@ -0,0 +1,38 @@
+import { Result, topo, trail } from '@ontrails/core';
+import { z } from 'zod';
+
+import { versionWithoutExamples } from '../rules/trail-versioning-topo.js';
+import { wrapTopoRule } from './wrap-rule.js';
+
+const archivedWithoutExamples = trail('version.examples.archived', {
+  blaze: () => Result.ok({ ok: true }),
+  input: z.object({}),
+  output: z.object({ ok: z.boolean() }),
+  version: 2,
+  versions: {
+    1: {
+      input: z.object({}),
+      output: z.object({ ok: z.boolean() }),
+      status: { state: 'archived' },
+      transpose: {
+        input: () => ({}),
+        output: ({ output }) => output,
+      },
+    },
+  },
+});
+
+export const versionWithoutExamplesTrail = wrapTopoRule({
+  examples: [
+    {
+      expected: { diagnostics: [] },
+      input: {
+        topo: topo('version-without-examples-clean', {
+          archivedWithoutExamples,
+        }),
+      },
+      name: 'Archived entries are exempt from example warnings',
+    },
+  ],
+  rule: versionWithoutExamples,
+});

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,64 @@
+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',
+    },
+    {
+      expected: {
+        diagnostics: [
+          {
+            filePath: fakeRulePath,
+            line: 1,
+            message:
+              'warden-rules-use-ast: raw AST node-field cast should use typed helpers from ./ast.js (callee -> getNodeCallee). Raw node-field casts drift from the curated @ontrails/warden/ast guard surface.',
+            rule: 'warden-rules-use-ast',
+            severity: 'warn',
+          },
+        ],
+      },
+      input: {
+        filePath: fakeRulePath,
+        sourceCode: `export const r = { check() { const callee = (node as unknown as { callee?: AstNode }).callee; return callee ? [] : []; } };\n`,
+      },
+      name: 'Warns on hand-cast AST node fields',
+    },
+  ],
+  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,
+});