@ontrails/warden 1.0.0-beta.8 → 1.0.0-beta.9

package/dist/trails/schema.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Shared Zod schemas for warden rule trails.
+ *
+ * Every rule trail shares the same input (source file) and output
+ * (array of diagnostics) shape.
+ */
+import { z } from 'zod';
+/** A single diagnostic emitted by a warden rule trail. */
+export declare const diagnosticSchema: z.ZodObject<{
+    filePath: z.ZodString;
+    line: z.ZodNumber;
+    message: z.ZodString;
+    rule: z.ZodString;
+    severity: z.ZodEnum<{
+        error: "error";
+        warn: "warn";
+    }>;
+}, z.core.$strip>;
+/** Input accepted by every warden rule trail. */
+export declare const ruleInput: z.ZodObject<{
+    filePath: z.ZodString;
+    sourceCode: z.ZodString;
+}, z.core.$strip>;
+/**
+ * Extended input for project-aware warden rule trails.
+ *
+ * Adds `knownTrailIds` so the caller can supply cross-file context and avoid
+ * false positives for detour targets or `@see` references defined in other
+ * files.
+ */
+export declare const projectAwareRuleInput: z.ZodObject<{
+    filePath: z.ZodString;
+    sourceCode: z.ZodString;
+    knownTrailIds: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+/** Output returned by every warden rule trail. */
+export declare const ruleOutput: z.ZodObject<{
+    diagnostics: z.ZodArray<z.ZodObject<{
+        filePath: z.ZodString;
+        line: z.ZodNumber;
+        message: z.ZodString;
+        rule: z.ZodString;
+        severity: z.ZodEnum<{
+            error: "error";
+            warn: "warn";
+        }>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type RuleInput = z.infer<typeof ruleInput>;
+export type ProjectAwareRuleInput = z.infer<typeof projectAwareRuleInput>;
+export type RuleOutput = z.infer<typeof ruleOutput>;
+//# sourceMappingURL=schema.d.ts.map

package/dist/trails/schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../src/trails/schema.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,0DAA0D;AAC1D,eAAO,MAAM,gBAAgB;;;;;;;;;iBAM3B,CAAC;AAEH,iDAAiD;AACjD,eAAO,MAAM,SAAS;;;iBAGpB,CAAC;AAEH;;;;;;GAMG;AACH,eAAO,MAAM,qBAAqB;;;;iBAKhC,CAAC;AAEH,kDAAkD;AAClD,eAAO,MAAM,UAAU;;;;;;;;;;;iBAErB,CAAC;AAEH,MAAM,MAAM,SAAS,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,SAAS,CAAC,CAAC;AAClD,MAAM,MAAM,qBAAqB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAC1E,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,UAAU,CAAC,CAAC"}

package/dist/trails/schema.js

@@ -0,0 +1,38 @@
+/**
+ * Shared Zod schemas for warden rule trails.
+ *
+ * Every rule trail shares the same input (source file) and output
+ * (array of diagnostics) shape.
+ */
+import { z } from 'zod';
+/** A single diagnostic emitted by a warden rule trail. */
+export const diagnosticSchema = z.object({
+    filePath: z.string().describe('File path that was analyzed'),
+    line: z.number().describe('1-based line number'),
+    message: z.string().describe('Human-readable diagnostic message'),
+    rule: z.string().describe('Rule name'),
+    severity: z.enum(['error', 'warn']).describe('Diagnostic severity'),
+});
+/** Input accepted by every warden rule trail. */
+export const ruleInput = z.object({
+    filePath: z.string().describe('Path to the source file'),
+    sourceCode: z.string().describe('Source code content'),
+});
+/**
+ * Extended input for project-aware warden rule trails.
+ *
+ * Adds `knownTrailIds` so the caller can supply cross-file context and avoid
+ * false positives for detour targets or `@see` references defined in other
+ * files.
+ */
+export const projectAwareRuleInput = ruleInput.extend({
+    knownTrailIds: z
+        .array(z.string())
+        .optional()
+        .describe('Trail IDs known across the project'),
+});
+/** Output returned by every warden rule trail. */
+export const ruleOutput = z.object({
+    diagnostics: z.array(diagnosticSchema).describe('Diagnostics found'),
+});
+//# sourceMappingURL=schema.js.map

package/dist/trails/schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.js","sourceRoot":"","sources":["../../src/trails/schema.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,0DAA0D;AAC1D,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,CAAC,MAAM,CAAC;IACvC,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,6BAA6B,CAAC;IAC5D,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,qBAAqB,CAAC;IAChD,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,mCAAmC,CAAC;IACjE,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,WAAW,CAAC;IACtC,QAAQ,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC,CAAC,QAAQ,CAAC,qBAAqB,CAAC;CACpE,CAAC,CAAC;AAEH,iDAAiD;AACjD,MAAM,CAAC,MAAM,SAAS,GAAG,CAAC,CAAC,MAAM,CAAC;IAChC,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,yBAAyB,CAAC;IACxD,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,qBAAqB,CAAC;CACvD,CAAC,CAAC;AAEH;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,SAAS,CAAC,MAAM,CAAC;IACpD,aAAa,EAAE,CAAC;SACb,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC;SACjB,QAAQ,EAAE;SACV,QAAQ,CAAC,oCAAoC,CAAC;CAClD,CAAC,CAAC;AAEH,kDAAkD;AAClD,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,CAAC,MAAM,CAAC;IACjC,WAAW,EAAE,CAAC,CAAC,KAAK,CAAC,gBAAgB,CAAC,CAAC,QAAQ,CAAC,mBAAmB,CAAC;CACrE,CAAC,CAAC"}

package/dist/trails/topo.d.ts

@@ -0,0 +1,3 @@
+/** Topo collecting all warden rule trails. */
+export declare const wardenTopo: import("@ontrails/core").Topo;
+//# sourceMappingURL=topo.d.ts.map

package/dist/trails/topo.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"topo.d.ts","sourceRoot":"","sources":["../../src/trails/topo.ts"],"names":[],"mappings":"AAIA,8CAA8C;AAC9C,eAAO,MAAM,UAAU,+BAAwB,CAAC"}

package/dist/trails/topo.js

@@ -0,0 +1,5 @@
+import { topo } from '@ontrails/core';
+import * as rules from './index.js';
+/** Topo collecting all warden rule trails. */
+export const wardenTopo = topo('warden', rules);
+//# sourceMappingURL=topo.js.map

package/dist/trails/topo.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"topo.js","sourceRoot":"","sources":["../../src/trails/topo.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,gBAAgB,CAAC;AAEtC,OAAO,KAAK,KAAK,MAAM,YAAY,CAAC;AAEpC,8CAA8C;AAC9C,MAAM,CAAC,MAAM,UAAU,GAAG,IAAI,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC"}

package/dist/trails/valid-describe-refs.trail.d.ts

@@ -0,0 +1,14 @@
+export declare const validDescribeRefsTrail: import("@ontrails/core").Trail<{
+    filePath: string;
+    sourceCode: string;
+    knownTrailIds?: string[] | undefined;
+}, {
+    diagnostics: {
+        filePath: string;
+        line: number;
+        message: string;
+        rule: string;
+        severity: "error" | "warn";
+    }[];
+}>;
+//# sourceMappingURL=valid-describe-refs.trail.d.ts.map

package/dist/trails/valid-describe-refs.trail.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"valid-describe-refs.trail.d.ts","sourceRoot":"","sources":["../../src/trails/valid-describe-refs.trail.ts"],"names":[],"mappings":"AAGA,eAAO,MAAM,sBAAsB;;;;;;;;;;;;EAcjC,CAAC"}

package/dist/trails/valid-describe-refs.trail.js

@@ -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,
+});
+//# sourceMappingURL=valid-describe-refs.trail.js.map

package/dist/trails/valid-describe-refs.trail.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"valid-describe-refs.trail.js","sourceRoot":"","sources":["../../src/trails/valid-describe-refs.trail.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,iCAAiC,CAAC;AACpE,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAE1C,MAAM,CAAC,MAAM,sBAAsB,GAAG,QAAQ,CAAC;IAC7C,QAAQ,EAAE;QACR;YACE,QAAQ,EAAE,EAAE,WAAW,EAAE,EAAE,EAAE;YAC7B,KAAK,EAAE;gBACL,QAAQ,EAAE,UAAU;gBACpB,UAAU,EAAE;;IAEhB;aACG;YACD,IAAI,EAAE,4BAA4B;SACnC;KACF;IACD,IAAI,EAAE,iBAAiB;CACxB,CAAC,CAAC"}

package/dist/trails/valid-detour-refs.trail.d.ts

@@ -0,0 +1,14 @@
+export declare const validDetourRefsTrail: import("@ontrails/core").Trail<{
+    filePath: string;
+    sourceCode: string;
+    knownTrailIds?: string[] | undefined;
+}, {
+    diagnostics: {
+        filePath: string;
+        line: number;
+        message: string;
+        rule: string;
+        severity: "error" | "warn";
+    }[];
+}>;
+//# sourceMappingURL=valid-detour-refs.trail.d.ts.map

package/dist/trails/valid-detour-refs.trail.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"valid-detour-refs.trail.d.ts","sourceRoot":"","sources":["../../src/trails/valid-detour-refs.trail.ts"],"names":[],"mappings":"AAGA,eAAO,MAAM,oBAAoB;;;;;;;;;;;;EAoB/B,CAAC"}

package/dist/trails/valid-detour-refs.trail.js

@@ -0,0 +1,24 @@
+import { validDetourRefs } from '../rules/valid-detour-refs.js';
+import { wrapRule } from './wrap-rule.js';
+export const validDetourRefsTrail = wrapRule({
+    examples: [
+        {
+            expected: { diagnostics: [] },
+            input: {
+                filePath: 'clean.ts',
+                knownTrailIds: ['entity.fallback', 'entity.show'],
+                sourceCode: `trail("entity.fallback", {
+  run: async (input, ctx) => Result.ok(data)
+})
+
+trail("entity.show", {
+  detours: [{ target: "entity.fallback" }],
+  run: async (input, ctx) => Result.ok(data)
+})`,
+            },
+            name: 'Valid detour target reference',
+        },
+    ],
+    rule: validDetourRefs,
+});
+//# sourceMappingURL=valid-detour-refs.trail.js.map

package/dist/trails/valid-detour-refs.trail.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"valid-detour-refs.trail.js","sourceRoot":"","sources":["../../src/trails/valid-detour-refs.trail.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,+BAA+B,CAAC;AAChE,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAE1C,MAAM,CAAC,MAAM,oBAAoB,GAAG,QAAQ,CAAC;IAC3C,QAAQ,EAAE;QACR;YACE,QAAQ,EAAE,EAAE,WAAW,EAAE,EAAE,EAAE;YAC7B,KAAK,EAAE;gBACL,QAAQ,EAAE,UAAU;gBACpB,aAAa,EAAE,CAAC,iBAAiB,EAAE,aAAa,CAAC;gBACjD,UAAU,EAAE;;;;;;;GAOjB;aACI;YACD,IAAI,EAAE,+BAA+B;SACtC;KACF;IACD,IAAI,EAAE,eAAe;CACtB,CAAC,CAAC"}

package/dist/trails/wrap-rule.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Factory that wraps a WardenRule as a trail.
+ *
+ * Keeps each rule trail file minimal — just the import + examples.
+ */
+import type { Trail } from '@ontrails/core';
+import type { ProjectAwareWardenRule, WardenRule } from '../rules/types.js';
+import type { ProjectAwareRuleInput, RuleInput, RuleOutput } 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'];
+}
+/**
+ * Wrap an existing `WardenRule` as a trail with typed input/output.
+ *
+ * The trail ID follows the pattern `warden.rule.<rule-name>`.
+ */
+export declare function wrapRule(options: WrapProjectAwareRuleOptions): Trail<ProjectAwareRuleInput, RuleOutput>;
+export declare function wrapRule(options: WrapRuleOptions): Trail<RuleInput, RuleOutput>;
+export {};
+//# sourceMappingURL=wrap-rule.d.ts.map

package/dist/trails/wrap-rule.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wrap-rule.d.ts","sourceRoot":"","sources":["../../src/trails/wrap-rule.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,gBAAgB,CAAC;AAE5C,OAAO,KAAK,EAAE,sBAAsB,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAE5E,OAAO,KAAK,EAAE,qBAAqB,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEhF,UAAU,eAAe;IACvB,wCAAwC;IACxC,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAC1B,oDAAoD;IACpD,QAAQ,CAAC,QAAQ,EAAE,KAAK,CAAC,SAAS,EAAE,UAAU,CAAC,CAAC,UAAU,CAAC,CAAC;CAC7D;AAED,UAAU,2BAA2B;IACnC,sDAAsD;IACtD,QAAQ,CAAC,IAAI,EAAE,sBAAsB,CAAC;IACtC,oDAAoD;IACpD,QAAQ,CAAC,QAAQ,EAAE,KAAK,CAAC,qBAAqB,EAAE,UAAU,CAAC,CAAC,UAAU,CAAC,CAAC;CACzE;AAED;;;;GAIG;AACH,wBAAgB,QAAQ,CACtB,OAAO,EAAE,2BAA2B,GACnC,KAAK,CAAC,qBAAqB,EAAE,UAAU,CAAC,CAAC;AAC5C,wBAAgB,QAAQ,CACtB,OAAO,EAAE,eAAe,GACvB,KAAK,CAAC,SAAS,EAAE,UAAU,CAAC,CAAC"}

package/dist/trails/wrap-rule.js

@@ -0,0 +1,43 @@
+/**
+ * Factory that wraps a WardenRule as a trail.
+ *
+ * Keeps each rule trail file minimal — just the import + examples.
+ */
+import { trail, Result } from '@ontrails/core';
+import { projectAwareRuleInput, ruleInput, ruleOutput } from './schema.js';
+export function wrapRule(options) {
+    const { rule, examples } = options;
+    const isProjectAware = 'checkWithContext' in rule;
+    if (isProjectAware) {
+        const projectAwareRule = rule;
+        return trail(`warden.rule.${rule.name}`, {
+            description: rule.description,
+            examples: examples,
+            input: projectAwareRuleInput,
+            intent: 'read',
+            metadata: { category: 'governance', severity: rule.severity },
+            output: ruleOutput,
+            run: (input) => {
+                const diagnostics = projectAwareRule.checkWithContext(input.sourceCode, input.filePath, {
+                    knownTrailIds: input.knownTrailIds
+                        ? new Set(input.knownTrailIds)
+                        : new Set(),
+                });
+                return Result.ok({ diagnostics: [...diagnostics] });
+            },
+        });
+    }
+    return trail(`warden.rule.${rule.name}`, {
+        description: rule.description,
+        examples: examples,
+        input: ruleInput,
+        intent: 'read',
+        metadata: { category: 'governance', severity: rule.severity },
+        output: ruleOutput,
+        run: (input) => {
+            const diagnostics = rule.check(input.sourceCode, input.filePath);
+            return Result.ok({ diagnostics: [...diagnostics] });
+        },
+    });
+}
+//# sourceMappingURL=wrap-rule.js.map

package/dist/trails/wrap-rule.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"wrap-rule.js","sourceRoot":"","sources":["../../src/trails/wrap-rule.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,gBAAgB,CAAC;AAI/C,OAAO,EAAE,qBAAqB,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AA4B3E,MAAM,UAAU,QAAQ,CACtB,OAAsD;IAEtD,MAAM,EAAE,IAAI,EAAE,QAAQ,EAAE,GAAG,OAAO,CAAC;IACnC,MAAM,cAAc,GAAG,kBAAkB,IAAI,IAAI,CAAC;IAElD,IAAI,cAAc,EAAE,CAAC;QACnB,MAAM,gBAAgB,GAAG,IAA8B,CAAC;QACxD,OAAO,KAAK,CAAC,eAAe,IAAI,CAAC,IAAI,EAAE,EAAE;YACvC,WAAW,EAAE,IAAI,CAAC,WAAW;YAC7B,QAAQ,EAAE,QAGG;YACb,KAAK,EAAE,qBAAqB;YAC5B,MAAM,EAAE,MAAM;YACd,QAAQ,EAAE,EAAE,QAAQ,EAAE,YAAY,EAAE,QAAQ,EAAE,IAAI,CAAC,QAAQ,EAAE;YAC7D,MAAM,EAAE,UAAU;YAClB,GAAG,EAAE,CAAC,KAA4B,EAAE,EAAE;gBACpC,MAAM,WAAW,GAAG,gBAAgB,CAAC,gBAAgB,CACnD,KAAK,CAAC,UAAU,EAChB,KAAK,CAAC,QAAQ,EACd;oBACE,aAAa,EAAE,KAAK,CAAC,aAAa;wBAChC,CAAC,CAAC,IAAI,GAAG,CAAC,KAAK,CAAC,aAAa,CAAC;wBAC9B,CAAC,CAAC,IAAI,GAAG,EAAU;iBACtB,CACF,CAAC;gBACF,OAAO,MAAM,CAAC,EAAE,CAAC,EAAE,WAAW,EAAE,CAAC,GAAG,WAAW,CAAC,EAAE,CAAC,CAAC;YACtD,CAAC;SACF,CAAC,CAAC;IACL,CAAC;IAED,OAAO,KAAK,CAAC,eAAe,IAAI,CAAC,IAAI,EAAE,EAAE;QACvC,WAAW,EAAE,IAAI,CAAC,WAAW;QAC7B,QAAQ,EAAE,QAAoD;QAC9D,KAAK,EAAE,SAAS;QAChB,MAAM,EAAE,MAAM;QACd,QAAQ,EAAE,EAAE,QAAQ,EAAE,YAAY,EAAE,QAAQ,EAAE,IAAI,CAAC,QAAQ,EAAE;QAC7D,MAAM,EAAE,UAAU;QAClB,GAAG,EAAE,CAAC,KAAgB,EAAE,EAAE;YACxB,MAAM,WAAW,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,UAAU,EAAE,KAAK,CAAC,QAAQ,CAAC,CAAC;YACjE,OAAO,MAAM,CAAC,EAAE,CAAC,EAAE,WAAW,EAAE,CAAC,GAAG,WAAW,CAAC,EAAE,CAAC,CAAC;QACtD,CAAC;KACF,CAAC,CAAC;AACL,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ontrails/warden",
-  "version": "1.0.0-beta.8",
+  "version": "1.0.0-beta.9",
   "type": "module",
   "exports": {
     ".": "./src/index.ts",
@@ -14,12 +14,13 @@
     "clean": "rm -rf dist *.tsbuildinfo"
   },
   "devDependencies": {
+    "@ontrails/testing": "^1.0.0-beta.8",
     "@oxc-project/types": "^0.122.0",
     "oxc-parser": "^0.121.0",
     "zod": "^4.3.5"
   },
   "peerDependencies": {
-    "@ontrails/core": "^1.0.0-beta.6",
-    "@ontrails/schema": "^1.0.0-beta.6"
+    "@ontrails/core": "^1.0.0-beta.8",
+    "@ontrails/schema": "^1.0.0-beta.8"
   }
 }

package/src/__tests__/trails.test.ts

@@ -0,0 +1,19 @@
+import { describe, expect, test } from 'bun:test';
+import { testAll } from '@ontrails/testing';
+
+import { wardenTopo } from '../trails/topo.js';
+
+// oxlint-disable-next-line jest/require-hook -- testAll generates describe/test blocks, not setup code
+testAll(wardenTopo);
+
+describe('wardenTopo', () => {
+  test('contains all 11 rule trails', () => {
+    expect(wardenTopo.count).toBe(11);
+  });
+
+  test('all trail IDs follow warden.rule.* naming', () => {
+    for (const id of wardenTopo.ids()) {
+      expect(id).toMatch(/^warden\.rule\./);
+    }
+  });
+});

package/src/index.ts

@@ -45,3 +45,24 @@ export {
 // Drift detection
 export type { DriftResult } from './drift.js';
 export { checkDrift } from './drift.js';
+
+// Trail layer
+export { wardenTopo } from './trails/topo.js';
+export { runWardenTrails } from './trails/run.js';
+export {
+  contextNoSurfaceTypesTrail,
+  diagnosticSchema,
+  followDeclarationsTrail,
+  implementationReturnsResultTrail,
+  noDirectImplInRouteTrail,
+  noDirectImplementationCallTrail,
+  noSyncResultAssumptionTrail,
+  noThrowInDetourTargetTrail,
+  noThrowInImplementationTrail,
+  preferSchemaInferenceTrail,
+  ruleInput,
+  ruleOutput,
+  validDescribeRefsTrail,
+  validDetourRefsTrail,
+} from './trails/index.js';
+export type { RuleInput, RuleOutput } from './trails/index.js';

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

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

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

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", {
+  run: async (input, ctx) => {
+    return Result.ok({ name: "test" });
+  }
+})`,
+      },
+      name: 'Implementation returning Result.ok()',
+    },
+  ],
+  rule: implementationReturnsResult,
+});

package/src/trails/index.ts

@@ -0,0 +1,14 @@
+export { contextNoSurfaceTypesTrail } from './context-no-surface-types.trail.js';
+export { followDeclarationsTrail } from './follow-declarations.trail.js';
+export { implementationReturnsResultTrail } from './implementation-returns-result.trail.js';
+export { noDirectImplInRouteTrail } from './no-direct-impl-in-route.trail.js';
+export { noDirectImplementationCallTrail } from './no-direct-implementation-call.trail.js';
+export { noSyncResultAssumptionTrail } from './no-sync-result-assumption.trail.js';
+export { noThrowInDetourTargetTrail } from './no-throw-in-detour-target.trail.js';
+export { noThrowInImplementationTrail } from './no-throw-in-implementation.trail.js';
+export { preferSchemaInferenceTrail } from './prefer-schema-inference.trail.js';
+export { validDescribeRefsTrail } from './valid-describe-refs.trail.js';
+export { validDetourRefsTrail } from './valid-detour-refs.trail.js';
+
+export { ruleInput, ruleOutput, diagnosticSchema } from './schema.js';
+export type { RuleInput, RuleOutput } from './schema.js';

package/src/trails/no-direct-impl-in-route.trail.ts

@@ -0,0 +1,22 @@
+import { noDirectImplInRoute } from '../rules/no-direct-impl-in-route.js';
+import { wrapRule } from './wrap-rule.js';
+
+export const noDirectImplInRouteTrail = wrapRule({
+  examples: [
+    {
+      expected: { diagnostics: [] },
+      input: {
+        filePath: 'clean.ts',
+        sourceCode: `trail("entity.onboard", {
+  follow: ["entity.create"],
+  run: async (input, ctx) => {
+    const result = await ctx.follow("entity.create", input);
+    return Result.ok(result);
+  }
+})`,
+      },
+      name: 'Trail with follow using ctx.follow()',
+    },
+  ],
+  rule: noDirectImplInRoute,
+});

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.follow("entity.show", { id: "1" });`,
+      },
+      name: 'Clean code using ctx.follow instead of .run()',
+    },
+  ],
+  rule: noDirectImplementationCall,
+});

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.run(input, ctx);
+if (result.isOk()) {
+  console.log(result.value);
+}`,
+      },
+      name: 'Properly awaited .run() call',
+    },
+  ],
+  rule: noSyncResultAssumption,
+});

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

@@ -0,0 +1,20 @@
+import { noThrowInDetourTarget } from '../rules/no-throw-in-detour-target.js';
+import { wrapRule } from './wrap-rule.js';
+
+export const noThrowInDetourTargetTrail = wrapRule({
+  examples: [
+    {
+      expected: { diagnostics: [] },
+      input: {
+        filePath: 'clean.ts',
+        sourceCode: `trail("entity.fallback", {
+  run: async (input, ctx) => {
+    return Result.ok({ recovered: true });
+  }
+})`,
+      },
+      name: 'Detour target without throw',
+    },
+  ],
+  rule: noThrowInDetourTarget,
+});

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

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() }),
+  run: async (input, ctx) => {
+    return Result.ok({ name: input.name });
+  }
+})`,
+      },
+      name: 'Trail without redundant field overrides',
+    },
+  ],
+  rule: preferSchemaInference,
+});

package/src/trails/run.ts

@@ -0,0 +1,40 @@
+/**
+ * Run all warden rule trails against a single source file.
+ *
+ * Returns a flat array of diagnostics from every rule.
+ */
+
+import { dispatch } from '@ontrails/core';
+
+import type { WardenDiagnostic } from '../rules/types.js';
+import type { RuleOutput } from './schema.js';
+import { wardenTopo } from './topo.js';
+
+/**
+ * Dispatch all warden rule trails for a given file and collect diagnostics.
+ *
+ * Each rule trail runs independently. Errors from individual trails are
+ * silently skipped so that one broken rule does not block the rest.
+ */
+export const runWardenTrails = async (
+  filePath: string,
+  sourceCode: string,
+  options?: { readonly knownTrailIds?: readonly string[] }
+): Promise<readonly WardenDiagnostic[]> => {
+  const allDiagnostics: WardenDiagnostic[] = [];
+
+  for (const id of wardenTopo.ids()) {
+    const input = options?.knownTrailIds
+      ? { filePath, knownTrailIds: options.knownTrailIds, sourceCode }
+      : { filePath, sourceCode };
+    const result = await dispatch(wardenTopo, id, input);
+    if (result.isOk()) {
+      const { diagnostics } = result.value as RuleOutput;
+      for (const d of diagnostics) {
+        allDiagnostics.push(d);
+      }
+    }
+  }
+
+  return allDiagnostics;
+};