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

package/src/rules/webhook-route-collision.ts

@@ -0,0 +1,243 @@
+import { shouldIncludeTrailForSurface } from '@ontrails/core';
+import type { Topo, Trail } from '@ontrails/core';
+
+import type { TopoAwareWardenRule, WardenDiagnostic } from './types.js';
+
+const RULE_NAME = 'webhook-route-collision';
+const TOPO_FILE = '<topo>';
+
+type RouteMethod = 'DELETE' | 'GET' | 'PATCH' | 'POST' | 'PUT';
+
+interface RouteClaim {
+  readonly method: RouteMethod;
+  readonly parse?: unknown;
+  readonly path: string;
+  readonly sourceId?: string | undefined;
+  readonly trailId: string;
+  readonly type: 'derived-trail' | 'webhook';
+  readonly verify?: unknown;
+}
+
+const methodByIntent = {
+  destroy: 'DELETE',
+  read: 'GET',
+  write: 'POST',
+} as const satisfies Record<string, RouteMethod>;
+
+const derivedTrailPath = (trailId: string): string =>
+  `/${trailId.replaceAll('.', '/')}`;
+
+const derivedTrailMethod = (
+  trail: Trail<unknown, unknown, unknown>
+): RouteMethod =>
+  (methodByIntent as Partial<Record<string, RouteMethod>>)[trail.intent] ??
+  'POST';
+
+const routeKey = ({ method, path }: Pick<RouteClaim, 'method' | 'path'>) =>
+  `${method} ${path}`;
+
+const sortedClaims = (claims: readonly RouteClaim[]): readonly RouteClaim[] =>
+  [...claims].toSorted((a, b) => {
+    const byType = a.type.localeCompare(b.type);
+    if (byType !== 0) {
+      return byType;
+    }
+    const byTrail = a.trailId.localeCompare(b.trailId);
+    if (byTrail !== 0) {
+      return byTrail;
+    }
+    return (a.sourceId ?? '').localeCompare(b.sourceId ?? '');
+  });
+
+/**
+ * Mirror the HTTP builder's default materialization policy. A derived trail
+ * route is only emitted when {@link shouldIncludeTrailForSurface} accepts the
+ * trail under empty options — internal trails are excluded unless callers
+ * explicitly include them by id, which the warden cannot anticipate. Without
+ * this filter the rule reports collisions against routes that HTTP would never
+ * materialize. See `packages/http/src/build.ts` (`eligibleTrails`).
+ */
+const collectDerivedTrailClaims = (topo: Topo): readonly RouteClaim[] =>
+  topo
+    .list()
+    .filter((trail) => shouldIncludeTrailForSurface(trail))
+    .map((trail) => ({
+      method: derivedTrailMethod(trail),
+      path: derivedTrailPath(trail.id),
+      trailId: trail.id,
+      type: 'derived-trail' as const,
+    }));
+
+const webhookMethod = (method: string | undefined): RouteMethod =>
+  (method?.trim().toUpperCase() as RouteMethod | undefined) ?? 'POST';
+
+/**
+ * Mirror the HTTP builder's default materialization policy for webhook
+ * consumers. HTTP's `eligibleWebhookTrails` skips internal trails unless
+ * callers explicitly include them by id, which the warden cannot anticipate.
+ * Without this filter the rule reports collisions against webhook routes that
+ * HTTP would never materialize. See `packages/http/src/build.ts`
+ * (`eligibleWebhookTrails`, `isInternalTrail`).
+ *
+ * `shouldIncludeTrailForSurface` cannot be reused here because it short-
+ * circuits on any trail with `activationSources.length > 0` — those are exactly
+ * the webhook consumer trails we need to inspect. Replicate the visibility
+ * shape inline: `visibility: 'internal'` and the legacy `meta.internal === true`
+ * convention both opt out of default materialization.
+ */
+const isInternalConsumer = (trail: Trail<unknown, unknown, unknown>): boolean =>
+  trail.visibility === 'internal' || trail.meta?.['internal'] === true;
+
+const collectWebhookClaims = (topo: Topo): readonly RouteClaim[] => {
+  const claims: RouteClaim[] = [];
+
+  for (const trail of topo.list()) {
+    if (isInternalConsumer(trail)) {
+      continue;
+    }
+    for (const activation of trail.activationSources) {
+      if (
+        activation.source.kind !== 'webhook' ||
+        typeof activation.source.path !== 'string'
+      ) {
+        continue;
+      }
+      claims.push({
+        method: webhookMethod(activation.source.method),
+        parse: activation.source.parse,
+        path: activation.source.path.trim(),
+        sourceId: activation.source.id,
+        trailId: trail.id,
+        type: 'webhook',
+        verify: activation.source.verify,
+      });
+    }
+  }
+
+  return claims;
+};
+
+const claimLabel = (claim: RouteClaim): string =>
+  claim.type === 'webhook'
+    ? `webhook source "${claim.sourceId}" on trail "${claim.trailId}"`
+    : `derived trail route "${claim.trailId}"`;
+
+const buildDiagnostic = (
+  key: string,
+  claims: readonly RouteClaim[]
+): WardenDiagnostic => ({
+  filePath: TOPO_FILE,
+  line: 1,
+  message: `HTTP webhook route collision on ${key}: ${sortedClaims(claims)
+    .map(claimLabel)
+    .join(
+      ', '
+    )}. Give each webhook source a distinct method/path pair or move the direct trail route before materializing the HTTP surface.`,
+  rule: RULE_NAME,
+  severity: 'error',
+});
+
+const buildPolicyMismatchDiagnostic = (
+  key: string,
+  sourceId: string | undefined,
+  field: 'parse' | 'verifier',
+  claims: readonly RouteClaim[]
+): WardenDiagnostic => {
+  const labels = sortedClaims(claims).map(claimLabel).join(', ');
+  const remediation =
+    field === 'verifier'
+      ? 'Reuse the same WebhookSource object so both consumers run under one verifier.'
+      : 'Reuse the same WebhookSource object so both consumers parse payloads under one contract.';
+  return {
+    filePath: TOPO_FILE,
+    line: 1,
+    message: `HTTP webhook route collision on ${key}: trails sharing webhook source "${sourceId ?? '<unknown>'}" declare a mismatched ${field} policy (${labels}). ${remediation}`,
+    rule: RULE_NAME,
+    severity: 'error',
+  };
+};
+
+/**
+ * Within a group of webhook claims that share the same `sourceId`, surface a
+ * diagnostic when the underlying source declarations diverge on `verify` or
+ * `parse`. The HTTP builder rejects the same combination at runtime in
+ * {@link mergeWebhookRoutes}; flagging it here surfaces the failure at lint
+ * time instead of waiting for surface construction. Reference equality matches
+ * the runtime check (a shared `WebhookSource` always passes; two separately
+ * declared schemas or callbacks are treated as distinct policies).
+ */
+const collectPolicyMismatchDiagnostics = (
+  key: string,
+  webhookClaims: readonly RouteClaim[]
+): WardenDiagnostic[] => {
+  const claimsBySourceId = new Map<string, RouteClaim[]>();
+  for (const claim of webhookClaims) {
+    const id = claim.sourceId ?? '';
+    const current = claimsBySourceId.get(id) ?? [];
+    current.push(claim);
+    claimsBySourceId.set(id, current);
+  }
+
+  const diagnostics: WardenDiagnostic[] = [];
+  for (const [id, grouped] of claimsBySourceId) {
+    if (grouped.length < 2) {
+      continue;
+    }
+    const verifyRefs = new Set(grouped.map((claim) => claim.verify));
+    if (verifyRefs.size > 1) {
+      diagnostics.push(
+        buildPolicyMismatchDiagnostic(key, id, 'verifier', grouped)
+      );
+      continue;
+    }
+    const parseRefs = new Set(grouped.map((claim) => claim.parse));
+    if (parseRefs.size > 1) {
+      diagnostics.push(
+        buildPolicyMismatchDiagnostic(key, id, 'parse', grouped)
+      );
+    }
+  }
+  return diagnostics;
+};
+
+const buildDiagnostics = (claims: readonly RouteClaim[]) => {
+  const claimsByRoute = new Map<string, RouteClaim[]>();
+  for (const claim of claims) {
+    const key = routeKey(claim);
+    const current = claimsByRoute.get(key) ?? [];
+    current.push(claim);
+    claimsByRoute.set(key, current);
+  }
+
+  const diagnostics: WardenDiagnostic[] = [];
+  for (const [key, grouped] of claimsByRoute) {
+    const webhookClaims = grouped.filter((claim) => claim.type === 'webhook');
+    if (webhookClaims.length === 0) {
+      continue;
+    }
+    const webhookSourceIds = new Set(
+      webhookClaims.map((claim) => claim.sourceId)
+    );
+    if (
+      webhookSourceIds.size > 1 ||
+      grouped.some((claim) => claim.type === 'derived-trail')
+    ) {
+      diagnostics.push(buildDiagnostic(key, grouped));
+      continue;
+    }
+    diagnostics.push(...collectPolicyMismatchDiagnostics(key, webhookClaims));
+  }
+  return diagnostics;
+};
+
+export const webhookRouteCollision: TopoAwareWardenRule = {
+  checkTopo: (topo) =>
+    buildDiagnostics([
+      ...collectDerivedTrailClaims(topo),
+      ...collectWebhookClaims(topo),
+    ]),
+  description:
+    'Reject webhook source method/path pairs that collide with each other or derived HTTP trail routes.',
+  name: RULE_NAME,
+  severity: 'error',
+};

package/src/trails/activation-orphan.trail.ts

@@ -0,0 +1,84 @@
+import { Result, schedule, signal, topo, trail } from '@ontrails/core';
+import { z } from 'zod';
+
+import { activationOrphan } from '../rules/activation-orphan.js';
+import { wrapTopoRule } from './wrap-rule.js';
+
+const orphanSignal = signal('invoice.paid', {
+  payload: z.object({ invoiceId: z.string() }),
+});
+
+const orphanConsumer = trail('invoice.audit', {
+  blaze: () => Result.ok({ ok: true }),
+  input: z.object({ invoiceId: z.string() }),
+  on: [orphanSignal],
+  output: z.object({ ok: z.boolean() }),
+});
+
+const producedSignal = signal('invoice.created', {
+  from: ['invoice.create'],
+  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 producedConsumer = trail('invoice.index', {
+  blaze: () => Result.ok({ ok: true }),
+  input: z.object({ invoiceId: z.string() }),
+  on: [producedSignal],
+  output: z.object({ ok: z.boolean() }),
+});
+
+const scheduledConsumer = 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 activationOrphanTrail = wrapTopoRule({
+  examples: [
+    {
+      expected: {
+        diagnostics: [
+          {
+            filePath: '<topo>',
+            line: 1,
+            message:
+              'Signal activation source "invoice.paid" activates trail "invoice.audit" but has no producer declaration in the topo. Add a trail fires: declaration, add signal from: producer metadata, or remove the unused activation source.',
+            rule: 'activation-orphan',
+            severity: 'warn',
+          },
+        ],
+      },
+      input: {
+        topo: topo('trl-452-activation-orphan', {
+          orphanConsumer,
+          orphanSignal,
+        }),
+      },
+      name: 'Signal activation consumers need producer declarations',
+    },
+    {
+      expected: { diagnostics: [] },
+      input: {
+        topo: topo('trl-452-activation-clean', {
+          producedConsumer,
+          producedSignal,
+          producerTrail,
+          scheduledConsumer,
+        }),
+      },
+      name: 'Produced signals and schedules are not activation orphans',
+    },
+  ],
+  rule: activationOrphan,
+});

package/src/trails/circular-refs.trail.ts

@@ -0,0 +1,29 @@
+import { circularRefs } from '../rules/circular-refs.js';
+import { wrapRule } from './wrap-rule.js';
+
+export const circularRefsTrail = wrapRule({
+  examples: [
+    {
+      expected: { diagnostics: [] },
+      input: {
+        contourReferencesByName: {
+          gist: ['user'],
+          user: [],
+        },
+        filePath: 'contours.ts',
+        knownContourIds: ['gist', 'user'],
+        knownTrailIds: [],
+        sourceCode: `const user = contour("user", {
+  id: z.string().uuid(),
+}, { identity: "id" });
+
+const gist = contour("gist", {
+  id: z.string().uuid(),
+  ownerId: user.id(),
+}, { identity: "id" });`,
+      },
+      name: 'Acyclic contour references stay clean',
+    },
+  ],
+  rule: circularRefs,
+});

package/src/trails/composes-declarations.trail.ts

@@ -0,0 +1,22 @@
+import { composesDeclarations } from '../rules/composes-declarations.js';
+import { wrapRule } from './wrap-rule.js';
+
+export const composesDeclarationsTrail = wrapRule({
+  examples: [
+    {
+      expected: { diagnostics: [] },
+      input: {
+        filePath: 'clean.ts',
+        sourceCode: `trail("entity.onboard", {
+  composes: ["entity.create"],
+  blaze: async (input, ctx) => {
+    const result = await ctx.compose("entity.create", input);
+    return Result.ok(result);
+  }
+})`,
+      },
+      name: 'Matched composing declarations and calls',
+    },
+  ],
+  rule: composesDeclarations,
+});

package/src/trails/context-no-surface-types.trail.ts

@@ -0,0 +1,21 @@
+import { contextNoSurfaceTypes } from '../rules/context-no-surface-types.js';
+import { wrapRule } from './wrap-rule.js';
+
+export const contextNoSurfaceTypesTrail = wrapRule({
+  examples: [
+    {
+      expected: { diagnostics: [] },
+      input: {
+        filePath: 'clean.ts',
+        sourceCode: `import { trail, Result } from "@ontrails/core";
+trail("entity.show", {
+  blaze: async (input, ctx) => {
+    return Result.ok({ name: "test" });
+  }
+})`,
+      },
+      name: 'Clean trail without surface imports',
+    },
+  ],
+  rule: contextNoSurfaceTypes,
+});

package/src/trails/contour-exists.trail.ts

@@ -0,0 +1,21 @@
+import { contourExists } from '../rules/contour-exists.js';
+import { wrapRule } from './wrap-rule.js';
+
+export const contourExistsTrail = wrapRule({
+  examples: [
+    {
+      expected: { diagnostics: [] },
+      input: {
+        filePath: 'entity.ts',
+        knownContourIds: ['user'],
+        knownTrailIds: ['user.create'],
+        sourceCode: `trail("user.create", {
+  contours: [user],
+  blaze: async (input, ctx) => Result.ok({ ok: true }),
+})`,
+      },
+      name: 'Declared contours resolve to known project contours',
+    },
+  ],
+  rule: contourExists,
+});

package/src/trails/dead-internal-trail.trail.ts

@@ -0,0 +1,26 @@
+import { deadInternalTrail } from '../rules/dead-internal-trail.js';
+import { wrapRule } from './wrap-rule.js';
+
+export const deadInternalTrailTrail = wrapRule({
+  examples: [
+    {
+      expected: { diagnostics: [] },
+      input: {
+        composeTargetTrailIds: ['entity.sync'],
+        filePath: 'clean.ts',
+        knownTrailIds: ['entity.public', 'entity.sync'],
+        sourceCode: `trail('entity.public', {
+  composes: ['entity.sync'],
+  blaze: async (_input, ctx) => ctx.compose('entity.sync', {}),
+});
+
+trail('entity.sync', {
+  visibility: 'internal',
+  blaze: async () => Result.ok({}),
+});`,
+      },
+      name: 'Internal trails stay clean when another trail composes them',
+    },
+  ],
+  rule: deadInternalTrail,
+});

package/src/trails/deprecation-without-guidance.trail.ts

@@ -0,0 +1,21 @@
+import { topo } from '@ontrails/core';
+import { deriveTopoGraph } from '@ontrails/topographer';
+
+import { deprecationWithoutGuidance } from '../rules/trail-versioning-topo.js';
+import { wrapTopoRule } from './wrap-rule.js';
+
+const emptyTopo = topo('deprecation-without-guidance-clean', {});
+
+export const deprecationWithoutGuidanceTrail = wrapTopoRule({
+  examples: [
+    {
+      expected: { diagnostics: [] },
+      input: {
+        graph: deriveTopoGraph(emptyTopo),
+        topo: emptyTopo,
+      },
+      name: 'No deprecated version entries passes',
+    },
+  ],
+  rule: deprecationWithoutGuidance,
+});

package/src/trails/draft-file-marking.trail.ts

@@ -0,0 +1,16 @@
+import { draftFileMarking } from '../rules/draft-file-marking.js';
+import { wrapRule } from './wrap-rule.js';
+
+export const draftFileMarkingTrail = wrapRule({
+  examples: [
+    {
+      expected: { diagnostics: [] },
+      input: {
+        filePath: 'clean.ts',
+        sourceCode: `export const id = "notes.list";`,
+      },
+      name: 'File without draft ids passes',
+    },
+  ],
+  rule: draftFileMarking,
+});

package/src/trails/draft-visible-debt.trail.ts

@@ -0,0 +1,16 @@
+import { draftVisibleDebt } from '../rules/draft-visible-debt.js';
+import { wrapRule } from './wrap-rule.js';
+
+export const draftVisibleDebtTrail = wrapRule({
+  examples: [
+    {
+      expected: { diagnostics: [] },
+      input: {
+        filePath: 'clean.ts',
+        sourceCode: `export const id = "notes.list";`,
+      },
+      name: 'File without draft ids emits no visible-debt diagnostics',
+    },
+  ],
+  rule: draftVisibleDebt,
+});

package/src/trails/error-mapping-completeness.trail.ts

@@ -0,0 +1,29 @@
+import { errorMappingCompleteness } from '../rules/error-mapping-completeness.js';
+import { wrapRule } from './wrap-rule.js';
+
+export const errorMappingCompletenessTrail = wrapRule({
+  examples: [
+    {
+      expected: { diagnostics: [] },
+      input: {
+        filePath: 'surface-error-map.ts',
+        sourceCode: `import { createSurfaceErrorMapper } from "@ontrails/core";
+
+const cliMapper = createSurfaceErrorMapper({
+  auth: 9,
+  cancelled: 130,
+  conflict: 3,
+  internal: 8,
+  network: 7,
+  not_found: 2,
+  permission: 4,
+  rate_limit: 6,
+  timeout: 5,
+  validation: 1,
+});`,
+      },
+      name: 'Complete surface error mapper',
+    },
+  ],
+  rule: errorMappingCompleteness,
+});

package/src/trails/example-valid.trail.ts

@@ -0,0 +1,25 @@
+import { exampleValid } from '../rules/example-valid.js';
+import { wrapRule } from './wrap-rule.js';
+
+export const exampleValidTrail = wrapRule({
+  examples: [
+    {
+      expected: { diagnostics: [] },
+      input: {
+        filePath: 'contours.ts',
+        sourceCode: `const user = contour("user", {
+  id: z.string().uuid(),
+  name: z.string(),
+}, {
+  examples: [{
+    id: "550e8400-e29b-41d4-a716-446655440000",
+    name: "Ada",
+  }],
+  identity: "id",
+});`,
+      },
+      name: 'Contour examples validate against their schema',
+    },
+  ],
+  rule: exampleValid,
+});

package/src/trails/fires-declarations.trail.ts

@@ -0,0 +1,23 @@
+import { firesDeclarations } from '../rules/fires-declarations.js';
+import { wrapRule } from './wrap-rule.js';
+
+export const firesDeclarationsTrail = wrapRule({
+  examples: [
+    {
+      expected: { diagnostics: [] },
+      input: {
+        filePath: 'clean.ts',
+        sourceCode: `const entityCreated = signal("entity.created", { payload: z.object({}) });
+trail("entity.onboard", {
+  fires: [entityCreated],
+  blaze: async (input, ctx) => {
+    await ctx.fire(entityCreated, { id: input.id });
+    return Result.ok({});
+  }
+})`,
+      },
+      name: 'Matched fires declarations and calls',
+    },
+  ],
+  rule: firesDeclarations,
+});

package/src/trails/fork-without-preserved-blaze.trail.ts

@@ -0,0 +1,31 @@
+import { forkWithoutPreservedBlaze } from '../rules/trail-versioning-source.js';
+import { wrapRule } from './wrap-rule.js';
+
+export const forkWithoutPreservedBlazeTrail = wrapRule({
+  examples: [
+    {
+      expected: { diagnostics: [] },
+      input: {
+        filePath: 'src/trails/versioned.ts',
+        sourceCode: `
+trail('versioned.clean', {
+  version: 2,
+  versions: {
+    1: {
+      input: z.object({ name: z.string() }),
+      output: z.object({ message: z.string() }),
+      transpose: {
+        input: ({ input }) => input,
+        output: ({ output }) => output,
+      },
+    },
+  },
+  blaze: async () => Result.ok({ message: 'ok' }),
+});
+`,
+      },
+      name: 'Revision entries use transpose',
+    },
+  ],
+  rule: forkWithoutPreservedBlaze,
+});

package/src/trails/implementation-returns-result.trail.ts

@@ -0,0 +1,20 @@
+import { implementationReturnsResult } from '../rules/implementation-returns-result.js';
+import { wrapRule } from './wrap-rule.js';
+
+export const implementationReturnsResultTrail = wrapRule({
+  examples: [
+    {
+      expected: { diagnostics: [] },
+      input: {
+        filePath: 'clean.ts',
+        sourceCode: `trail("entity.show", {
+  blaze: async (input, ctx) => {
+    return Result.ok({ name: "test" });
+  }
+})`,
+      },
+      name: 'Implementation returning Result.ok()',
+    },
+  ],
+  rule: implementationReturnsResult,
+});