@ontrails/warden 0.2.0

package/src/trails/surface-trailhead-coherence.trail.ts

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

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"]),
+  }),
+  implementation: 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/trailhead-override-divergence.trail.ts

@@ -0,0 +1,47 @@
+import { trailheadOverrideDivergence } from '../rules/trailhead-override-divergence.js';
+import { wrapRule } from './wrap-rule.js';
+
+export const trailheadOverrideDivergenceTrail = wrapRule({
+  examples: [
+    {
+      expected: { diagnostics: [] },
+      input: {
+        authoredMcpSurfaceBindingSets: [
+          {
+            appName: 'demo',
+            bindings: { inspect: ['survey', 'survey.brief'] },
+            trailIds: ['survey', 'survey.brief'],
+          },
+        ],
+        filePath: 'mcp-options.ts',
+        sourceCode: `export const trailheads = {
+  inspect: {
+    description: "Inspect topo state.",
+    trails: ["survey", "survey.brief"],
+  },
+};`,
+      },
+      name: 'Aligned call-site override',
+    },
+    {
+      input: {
+        authoredMcpSurfaceBindingSets: [
+          {
+            appName: 'demo',
+            bindings: { inspect: ['survey', 'survey.brief'] },
+            trailIds: ['survey', 'survey.brief'],
+          },
+        ],
+        filePath: 'mcp-options.ts',
+        sourceCode: `export const trailheads = {
+  inspect: {
+    description: "Inspect topo state.",
+    trails: ["survey"],
+  },
+};`,
+      },
+      name: 'Diverging member selectors are flagged',
+    },
+  ],
+  rule: trailheadOverrideDivergence,
+});

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', {
+  implementation: () => 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', {
+  fires: [invoiceCreated],
+  implementation: async (_input, ctx) => {
+    await ctx.fire?.(invoiceCreated, { invoiceId: 'inv_1' });
+    return Result.ok({ invoiceId: 'inv_1' });
+  },
+  input: z.object({}),
+  output: z.object({ invoiceId: z.string() }),
+});
+
+const signalConsumer = trail('invoice.index', {
+  implementation: () => Result.ok({ ok: true }),
+  input: z.object({ invoiceId: z.string() }),
+  on: [invoiceCreated],
+  output: z.object({ ok: z.boolean() }),
+});
+
+const scheduleConsumer = trail('invoice.reconcile', {
+  implementation: () => 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. Move the "ConflictError" detour before "TrailsError" so the more specific recovery runs, or remove it if the broader detour should own this case.',
+            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', {
+  detours: [
+    {
+      on: ConflictError,
+      recover: async () => {
+        const result = await Promise.resolve(Result.ok({ ok: true }));
+        return result;
+      },
+    },
+  ],
+  implementation: () => Result.ok({ ok: true }),
+  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. Pass the error class itself, such as on: TimeoutError — not an error instance, a string name, or an error category.',
+            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', {
+  implementation: () => 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', {
+  implementation: 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', {
+  implementation: () => 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 source code via @ontrails/source 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 the shared source helpers (callee -> getNodeCallee). Raw node-field casts drift from the shared source helper 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', {
+  implementation: () => Result.ok({ ok: true }),
+  input: z.object({ paymentId: z.string() }),
+  on: [paymentWebhook],
+  output: z.object({ ok: z.boolean() }),
+});
+
+const directRoute = trail('webhooks.payment', {
+  implementation: () => 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; if a derived trail route is part of the collision, change the webhook path or rename the trail so its derived route differs.',
+            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/workspace-lock-ownership.trail.ts

@@ -0,0 +1,16 @@
+import { workspaceLockOwnership } from '../rules/workspace-lock-ownership.js';
+import { wrapRule } from './wrap-rule.js';
+
+export const workspaceLockOwnershipTrail = wrapRule({
+  examples: [
+    {
+      expected: { diagnostics: [] },
+      input: {
+        filePath: 'src/app.ts',
+        sourceCode: '',
+      },
+      name: 'File-scoped wrapper defers project ownership checks',
+    },
+  ],
+  rule: workspaceLockOwnership,
+});