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

package/src/trails/marker-schema-unsupported.trail.ts

@@ -0,0 +1,23 @@
+import { markerSchemaUnsupported } from '../rules/trail-versioning-source.js';
+import { wrapRule } from './wrap-rule.js';
+
+export const markerSchemaUnsupportedTrail = wrapRule({
+  examples: [
+    {
+      expected: { diagnostics: [] },
+      input: {
+        filePath: 'src/trails/versioned.ts',
+        sourceCode: `
+trail('versioned.schema', {
+  version: 2,
+  input: z.object({ name: z.string() }),
+  output: z.object({ message: z.string() }),
+  implementation: async () => Result.ok({ message: 'ok' }),
+});
+`,
+      },
+      name: 'Stable marker-compatible schemas pass',
+    },
+  ],
+  rule: markerSchemaUnsupported,
+});

package/src/trails/missing-reconcile.trail.ts

@@ -0,0 +1,33 @@
+import { missingReconcile } from '../rules/missing-reconcile.js';
+import { wrapRule } from './wrap-rule.js';
+
+export const missingReconcileTrail = wrapRule({
+  examples: [
+    {
+      expected: { diagnostics: [] },
+      input: {
+        // Composite keys: `${storeBinding}:${tableName}` so two stores with
+        // the same table name don't collide.
+        crudTableIds: ['definition:notes'],
+        filePath: 'clean.ts',
+        knownTrailIds: ['notes.reconcile'],
+        reconcileTableIds: ['definition:notes'],
+        sourceCode: `import { store } from '@ontrails/store';
+import { z } from 'zod';
+
+const definition = store({
+  notes: {
+    identity: 'id',
+    schema: z.object({
+      id: z.string(),
+      title: z.string(),
+    }),
+    versioned: true,
+  },
+});`,
+      },
+      name: 'Versioned CRUD tables stay clean when reconcile exists',
+    },
+  ],
+  rule: missingReconcile,
+});

package/src/trails/missing-visibility.trail.ts

@@ -0,0 +1,22 @@
+import { missingVisibility } from '../rules/missing-visibility.js';
+import { wrapRule } from './wrap-rule.js';
+
+export const missingVisibilityTrail = wrapRule({
+  examples: [
+    {
+      expected: { diagnostics: [] },
+      input: {
+        composeTargetTrailIds: ['entity.resolve'],
+        filePath: 'clean.ts',
+        knownTrailIds: ['entity.resolve'],
+        sourceCode: `trail('entity.resolve', {
+  visibility: 'internal',
+  composeInput: z.object({ forkedFrom: z.string() }),
+  implementation: async () => Result.ok({}),
+});`,
+      },
+      name: 'Composition-only trails stay quiet when already internal',
+    },
+  ],
+  rule: missingVisibility,
+});

package/src/trails/no-destructured-compose.trail.ts

@@ -0,0 +1,44 @@
+import { noDestructuredCompose } from '../rules/no-destructured-compose.js';
+import { wrapRule } from './wrap-rule.js';
+
+export const noDestructuredComposeTrail = wrapRule({
+  examples: [
+    {
+      expected: { diagnostics: [] },
+      input: {
+        filePath: 'clean.ts',
+        sourceCode: `trail("entity.onboard", {
+  composes: ["entity.create"],
+  implementation: async (input, ctx) => ctx.compose("entity.create", input),
+});`,
+      },
+      name: 'Clean implementation using ctx.compose directly',
+    },
+    {
+      expected: {
+        diagnostics: [
+          {
+            filePath: 'destructured.ts',
+            line: 4,
+            message:
+              'Trail "entity.onboard" destructures compose from the implementation context. Use ctx.compose(...) directly so composition stays visible and Warden can recognize composed Result values.',
+            rule: 'no-destructured-compose',
+            severity: 'warn',
+          },
+        ],
+      },
+      input: {
+        filePath: 'destructured.ts',
+        sourceCode: `trail("entity.onboard", {
+  composes: ["entity.create"],
+  implementation: async (input, ctx) => {
+    const { compose } = ctx;
+    return compose("entity.create", input);
+  },
+});`,
+      },
+      name: 'Warns when compose is destructured from the implementation context',
+    },
+  ],
+  rule: noDestructuredCompose,
+});

package/src/trails/no-dev-permit-in-source.trail.ts

@@ -0,0 +1,16 @@
+import { noDevPermitInSource } from '../rules/no-dev-permit-in-source.js';
+import { wrapRule } from './wrap-rule.js';
+
+export const noDevPermitInSourceTrail = wrapRule({
+  examples: [
+    {
+      expected: { diagnostics: [] },
+      input: {
+        filePath: 'apps/example/src/cli.ts',
+        sourceCode: `import { tokenPreset } from '@ontrails/cli';\n`,
+      },
+      name: 'Source files without --dev-permit are clean',
+    },
+  ],
+  rule: noDevPermitInSource,
+});

package/src/trails/no-direct-implementation-call.trail.ts

@@ -0,0 +1,16 @@
+import { noDirectImplementationCall } from '../rules/no-direct-implementation-call.js';
+import { wrapRule } from './wrap-rule.js';
+
+export const noDirectImplementationCallTrail = wrapRule({
+  examples: [
+    {
+      expected: { diagnostics: [] },
+      input: {
+        filePath: 'clean.ts',
+        sourceCode: `const data = await ctx.compose("entity.show", { id: "1" });`,
+      },
+      name: 'Clean code using ctx.compose instead of .implementation()',
+    },
+  ],
+  rule: noDirectImplementationCall,
+});

package/src/trails/no-legacy-cli-alias-export.trail.ts

@@ -0,0 +1,41 @@
+import { noLegacyCliAliasExport } from '../rules/no-legacy-cli-alias-export.js';
+import { wrapRule } from './wrap-rule.js';
+
+export const noLegacyCliAliasExportTrail = wrapRule({
+  examples: [
+    {
+      expected: { diagnostics: [] },
+      input: {
+        filePath: 'apps/example/src/app.ts',
+        sourceCode: `import { surfaceOverlay } from '@ontrails/core';\n\nexport const trailsOverlays = [surfaceOverlay({ cli: { ls: 'gear.list' } })];\n`,
+      },
+      name: 'App modules binding CLI through trailsOverlays are clean',
+    },
+    {
+      expected: {
+        diagnostics: [
+          {
+            filePath: 'apps/example/src/app.ts',
+            fix: {
+              class: 'export-restructure',
+              reason:
+                "Legacy CLI alias export 'trailsCliAliases' must be rewritten into a surfaceOverlay({ cli: { ... } }) entry inside the module's trailsOverlays array export; run the Regrade class export-restructure:cli-aliases (TRL-1210) to automate this restructure.",
+              safety: 'review',
+            },
+            line: 1,
+            message:
+              "Legacy CLI alias export 'trailsCliAliases' was removed in the TRL-1207 surfaces-overlay cutover. Wrap the alias map into surfaceOverlay({ cli: { ... } }) from @ontrails/core inside the module's trailsOverlays array export.",
+            rule: 'no-legacy-cli-alias-export',
+            severity: 'error',
+          },
+        ],
+      },
+      input: {
+        filePath: 'apps/example/src/app.ts',
+        sourceCode: `export const trailsCliAliases = { 'gear.ls': [['gear', 'ls']] };\n`,
+      },
+      name: 'Legacy CLI alias exports produce migration diagnostics',
+    },
+  ],
+  rule: noLegacyCliAliasExport,
+});

package/src/trails/no-legacy-layer-imports.trail.ts

@@ -0,0 +1,41 @@
+import { noLegacyLayerImports } from '../rules/no-legacy-layer-imports.js';
+import { wrapRule } from './wrap-rule.js';
+
+export const noLegacyLayerImportsTrail = wrapRule({
+  examples: [
+    {
+      expected: { diagnostics: [] },
+      input: {
+        filePath: 'apps/example/src/cli.ts',
+        sourceCode: `import { tokenPreset } from '@ontrails/cli';\n`,
+      },
+      name: 'Source files without legacy layer references are clean',
+    },
+    {
+      expected: {
+        diagnostics: [
+          {
+            filePath: 'apps/example/src/cli.ts',
+            fix: {
+              class: 'term-rewrite',
+              reason:
+                "Legacy layer 'authLayer' was removed in TRL-475; Permit enforcement is intrinsic to executeTrail. Removal has no mechanical replacement, so it needs human migration.",
+              safety: 'review',
+            },
+            line: 1,
+            message:
+              "Legacy layer 'authLayer' was removed in TRL-475. Permit enforcement is intrinsic to executeTrail. See docs/adr/0043-layer-evolution.md.",
+            rule: 'no-legacy-layer-imports',
+            severity: 'error',
+          },
+        ],
+      },
+      input: {
+        filePath: 'apps/example/src/cli.ts',
+        sourceCode: `import { authLayer } from '@ontrails/permits';\n`,
+      },
+      name: 'Legacy layer imports produce migration diagnostics',
+    },
+  ],
+  rule: noLegacyLayerImports,
+});

package/src/trails/no-native-error-result.trail.ts

@@ -0,0 +1,18 @@
+import { noNativeErrorResult } from '../rules/no-native-error-result.js';
+import { wrapRule } from './wrap-rule.js';
+
+export const noNativeErrorResultTrail = wrapRule({
+  examples: [
+    {
+      expected: { diagnostics: [] },
+      input: {
+        filePath: 'entity.ts',
+        sourceCode: `import { InternalError, Result } from "@ontrails/core";
+
+export const load = () => Result.err(new InternalError("failed"));`,
+      },
+      name: 'Specific TrailsError subclasses stay clean',
+    },
+  ],
+  rule: noNativeErrorResult,
+});

package/src/trails/no-redundant-result-error-wrap.trail.ts

@@ -0,0 +1,55 @@
+import { noRedundantResultErrorWrap } from '../rules/no-redundant-result-error-wrap.js';
+import { wrapRule } from './wrap-rule.js';
+
+export const noRedundantResultErrorWrapTrail = wrapRule({
+  examples: [
+    {
+      expected: { diagnostics: [] },
+      input: {
+        filePath: 'entity.ts',
+        sourceCode: `import { Result, trail } from "@ontrails/core";
+
+trail("entity.load", {
+  implementation: async (input, ctx) => {
+    const loaded = await ctx.compose("entity.fetch", input);
+    if (loaded.isErr()) {
+      return loaded;
+    }
+    return Result.ok(loaded.value);
+  },
+});`,
+      },
+      name: 'Existing Result values pass through directly',
+    },
+    {
+      expected: {
+        diagnostics: [
+          {
+            filePath: 'entity.ts',
+            line: 7,
+            message:
+              'Trail "entity.load": Result.err(loaded.error) re-wraps a Result that already carries that error. Return loaded directly to preserve the original Result boundary.',
+            rule: 'no-redundant-result-error-wrap',
+            severity: 'warn',
+          },
+        ],
+      },
+      input: {
+        filePath: 'entity.ts',
+        sourceCode: `import { Result, trail } from "@ontrails/core";
+
+trail("entity.load", {
+  implementation: async (input, ctx) => {
+    const loaded = await ctx.compose("entity.fetch", input);
+    if (loaded.isErr()) {
+      return Result.err(loaded.error);
+    }
+    return Result.ok(loaded.value);
+  },
+});`,
+      },
+      name: 'Warns when an existing Result error is re-wrapped',
+    },
+  ],
+  rule: noRedundantResultErrorWrap,
+});

package/src/trails/no-retired-cross-vocabulary.trail.ts

@@ -0,0 +1,42 @@
+import { noRetiredCrossVocabulary } from '../rules/no-retired-cross-vocabulary.js';
+import { wrapRule } from './wrap-rule.js';
+
+export const noRetiredCrossVocabularyTrail = wrapRule({
+  examples: [
+    {
+      expected: { diagnostics: [] },
+      input: {
+        filePath: 'apps/example/src/trails/play.ts',
+        sourceCode: 'export const play = trail("play", { composes: [] });\n',
+      },
+      name: 'Source files using compose vocabulary are clean',
+    },
+    {
+      expected: {
+        diagnostics: [
+          {
+            filePath: 'apps/example/src/trails/play.ts',
+            fix: {
+              class: 'term-rewrite',
+              edits: [{ end: 43, replacement: 'composes', start: 36 }],
+              reason:
+                "Retired composition vocabulary 'crosses' has a mechanical beta.19 replacement 'composes'.",
+              safety: 'safe',
+            },
+            line: 1,
+            message:
+              "Retired composition vocabulary 'crosses' should be 'composes' after the beta.19 compose cutover.",
+            rule: 'no-retired-cross-vocabulary',
+            severity: 'error',
+          },
+        ],
+      },
+      input: {
+        filePath: 'apps/example/src/trails/play.ts',
+        sourceCode: 'export const play = trail("play", { crosses: [] });\n',
+      },
+      name: 'Retired crosses declarations produce safe migration diagnostics',
+    },
+  ],
+  rule: noRetiredCrossVocabulary,
+});

package/src/trails/no-sync-result-assumption.trail.ts

@@ -0,0 +1,19 @@
+import { noSyncResultAssumption } from '../rules/no-sync-result-assumption.js';
+import { wrapRule } from './wrap-rule.js';
+
+export const noSyncResultAssumptionTrail = wrapRule({
+  examples: [
+    {
+      expected: { diagnostics: [] },
+      input: {
+        filePath: 'clean.ts',
+        sourceCode: `const result = await myTrail.implementation(input, ctx);
+if (result.isOk()) {
+  console.log(result.value);
+}`,
+      },
+      name: 'Properly awaited .implementation() call',
+    },
+  ],
+  rule: noSyncResultAssumption,
+});

package/src/trails/no-throw-in-detour-recover.trail.ts

@@ -0,0 +1,24 @@
+import { noThrowInDetourRecover } from '../rules/no-throw-in-detour-recover.js';
+import { wrapRule } from './wrap-rule.js';
+
+export const noThrowInDetourRecoverTrail = wrapRule({
+  examples: [
+    {
+      expected: { diagnostics: [] },
+      input: {
+        filePath: 'clean.ts',
+        sourceCode: `trail("entity.save", {
+  detours: [
+    {
+      on: ConflictError,
+      recover: async () => Result.ok({ recovered: true }),
+    },
+  ],
+  implementation: () => Result.err(new ConflictError("conflict")),
+})`,
+      },
+      name: 'Detour recover without throw',
+    },
+  ],
+  rule: noThrowInDetourRecover,
+});

package/src/trails/no-throw-in-implementation.trail.ts

@@ -0,0 +1,20 @@
+import { noThrowInImplementation } from '../rules/no-throw-in-implementation.js';
+import { wrapRule } from './wrap-rule.js';
+
+export const noThrowInImplementationTrail = wrapRule({
+  examples: [
+    {
+      expected: { diagnostics: [] },
+      input: {
+        filePath: 'clean.ts',
+        sourceCode: `trail("entity.show", {
+  implementation: async (input, ctx) => {
+    return Result.ok({ name: "test" });
+  }
+})`,
+      },
+      name: 'Clean implementation without throw',
+    },
+  ],
+  rule: noThrowInImplementation,
+});

package/src/trails/no-top-level-surface.trail.ts

@@ -0,0 +1,43 @@
+import { noTopLevelSurface } from '../rules/no-top-level-surface.js';
+import { wrapRule } from './wrap-rule.js';
+
+export const noTopLevelSurfaceTrail = wrapRule({
+  examples: [
+    {
+      expected: { diagnostics: [] },
+      input: {
+        filePath: 'src/mcp.ts',
+        sourceCode: `import { surface } from "@ontrails/mcp";
+import graph from "./app";
+
+await surface(graph);`,
+      },
+      name: 'Allows dedicated surface entry modules',
+    },
+    {
+      expected: {
+        diagnostics: [
+          {
+            filePath: 'src/app.ts',
+            line: 6,
+            message:
+              'This module exports a topo and opens a surface at module top level. Trails introspection commands (`survey`, `guide`, `compile`) import topo entry modules, so opening a surface here can trigger sockets or transports during introspection. Move surface-opening to a separate entry/bin and keep the topo-export module side-effect-free.',
+            rule: 'no-top-level-surface',
+            severity: 'warn',
+          },
+        ],
+      },
+      input: {
+        filePath: 'src/app.ts',
+        sourceCode: `import { topo } from "@ontrails/core";
+import { surface } from "@ontrails/mcp";
+import * as trails from "./trails";
+
+export const graph = topo("app", trails);
+await surface(graph);`,
+      },
+      name: 'Warns when a topo export module opens a surface',
+    },
+  ],
+  rule: noTopLevelSurface,
+});

package/src/trails/on-references-exist.trail.ts

@@ -0,0 +1,21 @@
+import { onReferencesExist } from '../rules/on-references-exist.js';
+import { wrapRule } from './wrap-rule.js';
+
+export const onReferencesExistTrail = wrapRule({
+  examples: [
+    {
+      expected: { diagnostics: [] },
+      input: {
+        filePath: 'consumer.ts',
+        knownSignalIds: ['entity.created'],
+        knownTrailIds: ['notify'],
+        sourceCode: `trail("notify", {
+  on: ["entity.created"],
+  implementation: async (input, ctx) => Result.ok({}),
+})`,
+      },
+      name: 'Resolved on: reference',
+    },
+  ],
+  rule: onReferencesExist,
+});

package/src/trails/orphaned-signal.trail.ts

@@ -0,0 +1,36 @@
+import { orphanedSignal } from '../rules/orphaned-signal.js';
+import { wrapRule } from './wrap-rule.js';
+
+export const orphanedSignalTrail = wrapRule({
+  examples: [
+    {
+      expected: { diagnostics: [] },
+      input: {
+        // Composite keys: `${storeBinding}:${tableName}` so two stores with
+        // the same table name don't collide.
+        crudTableIds: ['definition:notes'],
+        filePath: 'clean.ts',
+        knownTrailIds: ['notes.notify'],
+        onTargetSignalIds: [
+          'definition:notes.created',
+          'definition:notes.updated',
+          'definition:notes.removed',
+        ],
+        sourceCode: `import { store } from '@ontrails/store';
+import { z } from 'zod';
+
+const definition = store({
+  notes: {
+    identity: 'id',
+    schema: z.object({
+      id: z.string(),
+      title: z.string(),
+    }),
+  },
+});`,
+      },
+      name: 'Derived store signals stay quiet when trail on consumers exist',
+    },
+  ],
+  rule: orphanedSignal,
+});

package/src/trails/owner-projection-parity.trail.ts

@@ -0,0 +1,26 @@
+import { fileURLToPath } from 'node:url';
+
+import { ownerProjectionParity } from '../rules/owner-projection-parity.js';
+import { wrapRule } from './wrap-rule.js';
+
+export const ownerProjectionParityTrail = wrapRule({
+  examples: [
+    {
+      expected: { diagnostics: [] },
+      input: {
+        filePath: fileURLToPath(
+          new URL('../../../http/src/method.ts', import.meta.url)
+        ),
+        sourceCode: `import type { Intent } from '@ontrails/core';
+
+export const httpMethodByIntent = {
+  destroy: 'DELETE',
+  read: 'GET',
+  write: 'POST',
+} as const satisfies Record<Intent, 'GET' | 'POST' | 'DELETE'>;`,
+      },
+      name: 'HTTP method projection covers core intent values',
+    },
+  ],
+  rule: ownerProjectionParity,
+});

package/src/trails/pending-force.trail.ts

@@ -0,0 +1,21 @@
+import { topo } from '@ontrails/core';
+import { deriveTopoGraph } from '@ontrails/topography';
+
+import { pendingForce } from '../rules/trail-versioning-topo.js';
+import { wrapTopoRule } from './wrap-rule.js';
+
+const emptyTopo = topo('pending-force-clean', {});
+
+export const pendingForceTrail = wrapTopoRule({
+  examples: [
+    {
+      expected: { diagnostics: [] },
+      input: {
+        graph: deriveTopoGraph(emptyTopo),
+        topo: emptyTopo,
+      },
+      name: 'No pending force audit events passes',
+    },
+  ],
+  rule: pendingForce,
+});

package/src/trails/permit-governance.trail.ts

@@ -0,0 +1,51 @@
+import { Result, topo, trail } from '@ontrails/core';
+import { z } from 'zod';
+
+import { permitGovernance } from '../rules/permit-governance.js';
+import { wrapTopoRule } from './wrap-rule.js';
+
+const destroyWithoutPermit = trail('entity.delete', {
+  implementation: () => Result.ok({ ok: true }),
+  input: z.object({}),
+  intent: 'destroy',
+  output: z.object({ ok: z.boolean() }),
+});
+
+const scopedDestroy = trail('entity.delete', {
+  implementation: () => Result.ok({ ok: true }),
+  input: z.object({}),
+  intent: 'destroy',
+  output: z.object({ ok: z.boolean() }),
+  permit: { scopes: ['entity:delete'] },
+});
+
+export const permitGovernanceTrail = wrapTopoRule({
+  examples: [
+    {
+      expected: {
+        diagnostics: [
+          {
+            filePath: '<topo>',
+            line: 1,
+            message:
+              'Trail "entity.delete" has intent \'destroy\' but no permit declaration',
+            rule: 'permit.destroyWithoutPermit',
+            severity: 'error',
+          },
+        ],
+      },
+      input: {
+        topo: topo('trl-377-missing-permit', { destroyWithoutPermit }),
+      },
+      name: 'Destroy trails without permits emit an error',
+    },
+    {
+      expected: { diagnostics: [] },
+      input: {
+        topo: topo('trl-377-scoped-destroy', { scopedDestroy }),
+      },
+      name: 'Scoped destroy permits keep permit governance clean',
+    },
+  ],
+  rule: permitGovernance,
+});

package/src/trails/prefer-schema-inference.trail.ts

@@ -0,0 +1,21 @@
+import { preferSchemaInference } from '../rules/prefer-schema-inference.js';
+import { wrapRule } from './wrap-rule.js';
+
+export const preferSchemaInferenceTrail = wrapRule({
+  examples: [
+    {
+      expected: { diagnostics: [] },
+      input: {
+        filePath: 'clean.ts',
+        sourceCode: `trail("entity.show", {
+  input: z.object({ name: z.string() }),
+  implementation: async (input, ctx) => {
+    return Result.ok({ name: input.name });
+  }
+})`,
+      },
+      name: 'Trail without redundant field overrides',
+    },
+  ],
+  rule: preferSchemaInference,
+});

package/src/trails/public-export-example-coverage.trail.ts

@@ -0,0 +1,16 @@
+import { publicExportExampleCoverage } from '../rules/public-export-example-coverage.js';
+import { wrapRule } from './wrap-rule.js';
+
+export const publicExportExampleCoverageTrail = wrapRule({
+  examples: [
+    {
+      expected: { diagnostics: [] },
+      input: {
+        filePath: 'packages/other-pkg/src/index.ts',
+        sourceCode: `export { somethingElse } from './other.js';\n`,
+      },
+      name: 'Ignores barrels outside the public API example policy',
+    },
+  ],
+  rule: publicExportExampleCoverage,
+});