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

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,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

@@ -0,0 +1,213 @@
+/**
+ * Factory that wraps a WardenRule as a trail.
+ *
+ * Keeps each rule trail file minimal — just the import + examples.
+ */
+
+import { InternalError, trail, Result } from '@ontrails/core';
+import type { Trail } from '@ontrails/core';
+
+import type {
+  ProjectAwareWardenRule,
+  ProjectContext,
+  TopoAwareWardenRule,
+  WardenRule,
+} from '../rules/types.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. */
+  readonly rule: WardenRule;
+  /** Trail examples for testing and documentation. */
+  readonly examples: Trail<RuleInput, RuleOutput>['examples'];
+}
+
+interface WrapProjectAwareRuleOptions {
+  /** The existing project-aware warden rule to wrap. */
+  readonly rule: ProjectAwareWardenRule;
+  /** Trail examples for testing and documentation. */
+  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.composeTargetTrailIds
+    ? { composeTargetTrailIds: new Set(input.composeTargetTrailIds) }
+    : {}),
+  ...(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.
+ *
+ * The trail ID follows the pattern `warden.rule.<rule-name>`.
+ */
+export function wrapRule(
+  options: WrapProjectAwareRuleOptions
+): Trail<ProjectAwareRuleInput, RuleOutput>;
+export function wrapRule(
+  options: WrapRuleOptions
+): Trail<RuleInput, RuleOutput>;
+export function wrapRule(
+  options: WrapRuleOptions | WrapProjectAwareRuleOptions
+): Trail<RuleInput, RuleOutput> | Trail<ProjectAwareRuleInput, RuleOutput> {
+  const { rule, examples } = options;
+  const isProjectAware = 'checkWithContext' in rule;
+
+  if (isProjectAware) {
+    const projectAwareRule = rule as ProjectAwareWardenRule;
+    return trail(`warden.rule.${rule.name}`, {
+      blaze: (input: ProjectAwareRuleInput) => {
+        const diagnostics = projectAwareRule.checkWithContext(
+          input.sourceCode,
+          input.filePath,
+          buildProjectContext(input)
+        );
+        return Result.ok({ diagnostics: [...diagnostics] });
+      },
+      description: rule.description,
+      examples: examples as Trail<
+        ProjectAwareRuleInput,
+        RuleOutput
+      >['examples'],
+      input: projectAwareRuleInput,
+      intent: 'read',
+      meta: buildRuleMeta(rule),
+      output: ruleOutput,
+    });
+  }
+
+  return trail(`warden.rule.${rule.name}`, {
+    blaze: (input: RuleInput) => {
+      const diagnostics = rule.check(input.sourceCode, input.filePath);
+      return Result.ok({ diagnostics: [...diagnostics] });
+    },
+    description: rule.description,
+    examples: examples as Trail<RuleInput, RuleOutput>['examples'],
+    input: ruleInput,
+    intent: 'read',
+    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, {
+          graph: input.graph,
+        });
+        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,
+  });
+};