@ontrails/warden 1.0.0-beta.4 → 1.0.0-beta.42

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

@@ -0,0 +1,306 @@
+import {
+  shouldIncludeTrailForSurface,
+  webhookPathPatternsOverlap,
+} 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 hasDynamicSegment = (path: string): boolean => path.includes('/:');
+
+/**
+ * Flag distinct route keys whose path patterns can both match one concrete
+ * request. Exact-key collisions are handled by the grouping pass; this pass
+ * extends detection to dynamic-segment patterns (`/hooks/:endpoint` vs
+ * `/hooks/github`), where at least one webhook claim participates.
+ */
+const collectPatternOverlapDiagnostics = (
+  claimsByRoute: ReadonlyMap<string, readonly RouteClaim[]>
+): WardenDiagnostic[] => {
+  const diagnostics: WardenDiagnostic[] = [];
+  const keys = [...claimsByRoute.keys()].toSorted();
+
+  for (const [index, leftKey] of keys.entries()) {
+    for (const rightKey of keys.slice(index + 1)) {
+      const leftClaims = claimsByRoute.get(leftKey) ?? [];
+      const rightClaims = claimsByRoute.get(rightKey) ?? [];
+      const [leftFirst] = leftClaims;
+      const [rightFirst] = rightClaims;
+      if (leftFirst === undefined || rightFirst === undefined) {
+        continue;
+      }
+      if (leftFirst.method !== rightFirst.method) {
+        continue;
+      }
+      if (
+        !(
+          hasDynamicSegment(leftFirst.path) ||
+          hasDynamicSegment(rightFirst.path)
+        )
+      ) {
+        continue;
+      }
+      const participants = [...leftClaims, ...rightClaims];
+      if (!participants.some((claim) => claim.type === 'webhook')) {
+        continue;
+      }
+      if (!webhookPathPatternsOverlap(leftFirst.path, rightFirst.path)) {
+        continue;
+      }
+      diagnostics.push({
+        filePath: TOPO_FILE,
+        line: 1,
+        message: `HTTP webhook route pattern overlap between ${leftKey} and ${rightKey}: ${sortedClaims(
+          participants
+        )
+          .map(claimLabel)
+          .join(
+            ', '
+          )}. Both patterns can match one request path; make the patterns disjoint or merge the sources.`,
+        rule: RULE_NAME,
+        severity: 'error',
+      });
+    }
+  }
+  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));
+  }
+  diagnostics.push(...collectPatternOverlapDiagnostics(claimsByRoute));
+  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', {
+  implementation: () => 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', {
+  fires: [producedSignal],
+  implementation: async (_input, ctx) => {
+    await ctx.fire?.(producedSignal, { invoiceId: 'inv_1' });
+    return Result.ok({ invoiceId: 'inv_1' });
+  },
+  input: z.object({}),
+  output: z.object({ invoiceId: z.string() }),
+});
+
+const producedConsumer = trail('invoice.index', {
+  implementation: () => Result.ok({ ok: true }),
+  input: z.object({ invoiceId: z.string() }),
+  on: [producedSignal],
+  output: z.object({ ok: z.boolean() }),
+});
+
+const scheduledConsumer = 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 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/captured-kernel.trail.ts

@@ -0,0 +1,108 @@
+import { capturedKernel } from '../rules/captured-kernel.js';
+import { wrapRule } from './wrap-rule.js';
+
+export const capturedKernelTrail = wrapRule({
+  examples: [
+    {
+      expected: {
+        diagnostics: [
+          {
+            filePath: 'packages/core/src/kernel.ts',
+            guidance: {
+              steps: [
+                'Review whether the public subpath should become an owned package surface, move back behind the package root, or be split into a better-owned package.',
+                'If the imported capability is reusable source-code machinery, serves at least two independently owned toolchain capabilities, exposes one genuinely shared contract, and owns no verdict, migration plan, graph query, or surface rendering, consider relocating it to @ontrails/source.',
+                'Otherwise, preserve the current owner or choose another doctrinal owner.',
+              ],
+              summary:
+                'Review ownership before an internal re-exported kernel hardens into a public package seam.',
+            },
+            line: 1,
+            message:
+              '@ontrails/core export target "@ontrails/core/kernel" re-exports internal target "./internal/kernel.js" and is consumed by external production packages @ontrails/cli, @ontrails/store. Review ownership of the exported subpath and its captured kernel before it becomes a durable public seam.',
+            rule: 'captured-kernel',
+            severity: 'warn',
+          },
+        ],
+      },
+      input: {
+        filePath: 'packages/core/src/kernel.ts',
+        importResolutionsByFile: {
+          'packages/cli/src/index.ts': [
+            {
+              crossesPackageBoundary: true,
+              importSource: '@ontrails/core/kernel',
+              importerPath: 'packages/cli/src/index.ts',
+              isInternalTarget: false,
+              line: 1,
+              packageName: '@ontrails/core',
+              packageRoot: 'packages/core',
+              resolvedPath: 'packages/core/src/kernel.ts',
+              usesPublicExport: true,
+            },
+          ],
+          'packages/core/src/kernel.ts': [
+            {
+              crossesPackageBoundary: false,
+              importSource: './internal/kernel.js',
+              importerPath: 'packages/core/src/kernel.ts',
+              isInternalTarget: true,
+              line: 1,
+              packageName: '@ontrails/core',
+              packageRoot: 'packages/core',
+              resolvedPath: 'packages/core/src/internal/kernel.ts',
+              usesPublicExport: false,
+            },
+          ],
+          'packages/store/src/index.ts': [
+            {
+              crossesPackageBoundary: true,
+              importSource: '@ontrails/core/kernel',
+              importerPath: 'packages/store/src/index.ts',
+              isInternalTarget: false,
+              line: 1,
+              packageName: '@ontrails/core',
+              packageRoot: 'packages/core',
+              resolvedPath: 'packages/core/src/kernel.ts',
+              usesPublicExport: true,
+            },
+          ],
+        },
+        knownTrailIds: [],
+        publicWorkspaces: {
+          '@ontrails/cli': {
+            exportTargets: {
+              '@ontrails/cli': 'packages/cli/src/index.ts',
+            },
+            hasExports: true,
+            name: '@ontrails/cli',
+            packageJsonPath: 'packages/cli/package.json',
+            rootDir: 'packages/cli',
+          },
+          '@ontrails/core': {
+            exportTargets: {
+              '@ontrails/core': 'packages/core/src/index.ts',
+              '@ontrails/core/kernel': 'packages/core/src/kernel.ts',
+            },
+            hasExports: true,
+            name: '@ontrails/core',
+            packageJsonPath: 'packages/core/package.json',
+            rootDir: 'packages/core',
+          },
+          '@ontrails/store': {
+            exportTargets: {
+              '@ontrails/store': 'packages/store/src/index.ts',
+            },
+            hasExports: true,
+            name: '@ontrails/store',
+            packageJsonPath: 'packages/store/package.json',
+            rootDir: 'packages/store',
+          },
+        },
+        sourceCode: "export { kernel } from './internal/kernel.js';\n",
+      },
+      name: 'Flags captured kernels consumed by multiple production packages',
+    },
+  ],
+  rule: capturedKernel,
+});

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: {
+        entityReferencesByName: {
+          gist: ['user'],
+          user: [],
+        },
+        filePath: 'entities.ts',
+        knownEntityIds: ['gist', 'user'],
+        knownTrailIds: [],
+        sourceCode: `const user = entity("user", {
+  id: z.string().uuid(),
+}, { identity: "id" });
+
+const gist = entity("gist", {
+  id: z.string().uuid(),
+  ownerId: user.id(),
+}, { identity: "id" });`,
+      },
+      name: 'Acyclic entity references stay clean',
+    },
+  ],
+  rule: circularRefs,
+});

package/src/trails/cli-command-route-coherence.trail.ts

@@ -0,0 +1,47 @@
+import { Result, topo, trail } from '@ontrails/core';
+import { z } from 'zod';
+
+import { cliCommandRouteCoherence } from '../rules/cli-command-route-coherence.js';
+import { wrapTopoRule } from './wrap-rule.js';
+
+const searchTrail = trail('wayfind.search', {
+  cli: {
+    aliases: ['find'],
+  },
+  implementation: () => Result.ok([]),
+  input: z.object({ query: z.string() }),
+  output: z.array(z.string()),
+});
+
+const collidingTrail = trail('wayfind.find', {
+  implementation: () => Result.ok([]),
+  input: z.object({ query: z.string() }),
+  output: z.array(z.string()),
+});
+
+export const cliCommandRouteCoherenceTrail = wrapTopoRule({
+  examples: [
+    {
+      expected: {
+        diagnostics: [
+          {
+            filePath: '<topo>',
+            line: 1,
+            message:
+              'CLI command route collision on "wayfind find": canonical route for trail "wayfind.find" (derived), alias route for trail "wayfind.search" (trail). Rename or remove one CLI alias so every accepted command path normalizes into exactly one trail contract.',
+            rule: 'cli-command-route-coherence',
+            severity: 'error',
+          },
+        ],
+      },
+      input: {
+        topo: topo('cli-command-route-coherence', {
+          collidingTrail,
+          searchTrail,
+        }),
+      },
+      name: 'CLI alias colliding with another command route',
+    },
+  ],
+  rule: cliCommandRouteCoherence,
+});

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"],
+  implementation: 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", {
+  implementation: async (input, ctx) => {
+    return Result.ok({ name: "test" });
+  }
+})`,
+      },
+      name: 'Clean trail without surface imports',
+    },
+  ],
+  rule: contextNoSurfaceTypes,
+});

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'],
+  implementation: async (_input, ctx) => ctx.compose('entity.sync', {}),
+});
+
+trail('entity.sync', {
+  visibility: 'internal',
+  implementation: async () => Result.ok({}),
+});`,
+      },
+      name: 'Internal trails stay clean when another trail composes them',
+    },
+  ],
+  rule: deadInternalTrail,
+});

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

@@ -0,0 +1,31 @@
+import { deadPublicTrail } from '../rules/dead-public-trail.js';
+import { wrapRule } from './wrap-rule.js';
+
+export const deadPublicTrailTrail = wrapRule({
+  examples: [
+    {
+      expected: {
+        diagnostics: [
+          {
+            filePath: 'packages/regrade/src/downstream/report.ts',
+            line: 1,
+            message:
+              'Exported public trail "regrade.downstream.report" is not registered in a configured app topo, composed by another trail, or activated by on:. Anchor the contract in a topo, compose it, mark it internal, or remove the public export.',
+            rule: 'dead-public-trail',
+            severity: 'warn',
+          },
+        ],
+      },
+      input: {
+        filePath: 'packages/regrade/src/downstream/report.ts',
+        knownTrailIds: ['regrade.downstream.report', 'regrade'],
+        sourceCode: `export const regradeReportTrail = trail('regrade.downstream.report', {
+  implementation: async () => Result.ok({}),
+});`,
+        topoTrailIds: ['regrade'],
+      },
+      name: 'Exported package trail missing from registered app topos',
+    },
+  ],
+  rule: deadPublicTrail,
+});