@ontrails/warden 1.0.0-beta.0 → 1.0.0-beta.10

package/src/rules/no-throw-in-detour-target.ts

@@ -6,7 +6,7 @@
  */
 
 import {
-  findImplementationBodies,
+  findRunBodies,
   findTrailDefinitions,
   offsetToLine,
   parse,
@@ -66,7 +66,7 @@ const findThrowsInTargetedTrails = (
       continue;
     }
 
-    for (const body of findImplementationBodies(def.config as AstNode)) {
+    for (const body of findRunBodies(def.config as AstNode)) {
       walk(body, (node) => {
         if (node.type === 'ThrowStatement') {
           diagnostics.push({

package/src/rules/no-throw-in-implementation.ts

@@ -1,11 +1,11 @@
 /**
- * Finds `throw` statements inside `implementation:` function bodies.
+ * Finds `throw` statements inside `run:` function bodies.
  *
  * Uses AST parsing for accurate detection — no false positives from
  * throw in comments, strings, or nested non-implementation functions.
  */
 
-import { findImplementationBodies, offsetToLine, parse, walk } from './ast.js';
+import { findRunBodies, offsetToLine, parse, walk } from './ast.js';
 import type { WardenDiagnostic, WardenRule } from './types.js';
 
 export const noThrowInImplementation: WardenRule = {
@@ -17,7 +17,7 @@ export const noThrowInImplementation: WardenRule = {
 
     const diagnostics: WardenDiagnostic[] = [];
 
-    for (const body of findImplementationBodies(ast)) {
+    for (const body of findRunBodies(ast)) {
       walk(body, (node) => {
         if (node.type === 'ThrowStatement') {
           diagnostics.push({

package/src/rules/specs.ts

@@ -18,7 +18,7 @@ export interface ObjectProperty extends ParsedEntry {
 
 export interface TrailLikeSpec {
   readonly id: string;
-  readonly kind: 'hike' | 'trail';
+  readonly kind: 'event' | 'trail';
   readonly line: number;
   readonly properties: ReadonlyMap<string, ObjectProperty>;
   readonly specText: string;
@@ -31,7 +31,7 @@ export interface SchemaFieldInfo {
   readonly required: boolean;
 }
 
-const TRAIL_LIKE_PATTERN = /\b(trail|hike)\s*\(/g;
+const TRAIL_LIKE_PATTERN = /\b(trail|event)\s*\(/g;
 
 const PROPERTY_PATTERN =
   /^(?:readonly\s+)?(?:(["'`])([^"'`]+)\1|([A-Za-z_$][\w$]*))\s*:\s*([\s\S]+)$/;
@@ -214,7 +214,7 @@ const resolveSpecId = (
 
 const buildTrailLikeSpec = (
   sourceCode: string,
-  kind: 'hike' | 'trail',
+  kind: 'event' | 'trail',
   specArg: SplitEntry,
   specStart: number,
   id: string,
@@ -276,7 +276,7 @@ const resolveTrailLikeSpec = (
 
 const parseTrailLikeMatch = (
   sourceCode: string,
-  kind: 'hike' | 'trail',
+  kind: 'event' | 'trail',
   callStart: number
 ): TrailLikeSpec | null => {
   const resolved = resolveTrailLikeSpec(sourceCode, callStart);
@@ -352,7 +352,7 @@ export const findTrailLikeSpecs = (
       continue;
     }
 
-    const kind = match[1] === 'hike' ? 'hike' : 'trail';
+    const kind = match[1] === 'event' ? 'event' : 'trail';
     const spec = parseTrailLikeMatch(sourceCode, kind, callStart);
     if (spec !== null) {
       specs.push(spec);

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;
+};

package/src/trails/schema.ts

@@ -0,0 +1,46 @@
+/**
+ * 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'),
+});
+
+export type RuleInput = z.infer<typeof ruleInput>;
+export type ProjectAwareRuleInput = z.infer<typeof projectAwareRuleInput>;
+export type RuleOutput = z.infer<typeof ruleOutput>;

package/src/trails/topo.ts

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

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-refs.trail.ts

@@ -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,
+});

package/src/trails/wrap-rule.ts

@@ -0,0 +1,84 @@
+/**
+ * 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 type { Trail } from '@ontrails/core';
+
+import type { ProjectAwareWardenRule, WardenRule } from '../rules/types.js';
+import { projectAwareRuleInput, ruleInput, ruleOutput } from './schema.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 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}`, {
+      description: rule.description,
+      examples: examples as Trail<
+        ProjectAwareRuleInput,
+        RuleOutput
+      >['examples'],
+      input: projectAwareRuleInput,
+      intent: 'read',
+      metadata: { category: 'governance', severity: rule.severity },
+      output: ruleOutput,
+      run: (input: ProjectAwareRuleInput) => {
+        const diagnostics = projectAwareRule.checkWithContext(
+          input.sourceCode,
+          input.filePath,
+          {
+            knownTrailIds: input.knownTrailIds
+              ? new Set(input.knownTrailIds)
+              : new Set<string>(),
+          }
+        );
+        return Result.ok({ diagnostics: [...diagnostics] });
+      },
+    });
+  }
+
+  return trail(`warden.rule.${rule.name}`, {
+    description: rule.description,
+    examples: examples as Trail<RuleInput, RuleOutput>['examples'],
+    input: ruleInput,
+    intent: 'read',
+    metadata: { category: 'governance', severity: rule.severity },
+    output: ruleOutput,
+    run: (input: RuleInput) => {
+      const diagnostics = rule.check(input.sourceCode, input.filePath);
+      return Result.ok({ diagnostics: [...diagnostics] });
+    },
+  });
+}

package/tsconfig.tsbuildinfo

@@ -1 +1 @@
-{"root":["./src/cli.ts","./src/drift.ts","./src/formatters.ts","./src/index.ts","./src/rules/ast.ts","./src/rules/context-no-surface-types.ts","./src/rules/implementation-returns-result.ts","./src/rules/index.ts","./src/rules/no-direct-impl-in-route.ts","./src/rules/no-direct-implementation-call.ts","./src/rules/no-sync-result-assumption.ts","./src/rules/no-throw-in-detour-target.ts","./src/rules/no-throw-in-implementation.ts","./src/rules/prefer-schema-inference.ts","./src/rules/scan.ts","./src/rules/specs.ts","./src/rules/structure.ts","./src/rules/types.ts","./src/rules/valid-describe-refs.ts","./src/rules/valid-detour-refs.ts"],"version":"5.9.3"}
+{"root":["./src/cli.ts","./src/drift.ts","./src/formatters.ts","./src/index.ts","./src/rules/ast.ts","./src/rules/context-no-surface-types.ts","./src/rules/follow-declarations.ts","./src/rules/implementation-returns-result.ts","./src/rules/index.ts","./src/rules/no-direct-impl-in-route.ts","./src/rules/no-direct-implementation-call.ts","./src/rules/no-sync-result-assumption.ts","./src/rules/no-throw-in-detour-target.ts","./src/rules/no-throw-in-implementation.ts","./src/rules/prefer-schema-inference.ts","./src/rules/scan.ts","./src/rules/specs.ts","./src/rules/structure.ts","./src/rules/types.ts","./src/rules/valid-describe-refs.ts","./src/rules/valid-detour-refs.ts","./src/trails/context-no-surface-types.trail.ts","./src/trails/follow-declarations.trail.ts","./src/trails/implementation-returns-result.trail.ts","./src/trails/index.ts","./src/trails/no-direct-impl-in-route.trail.ts","./src/trails/no-direct-implementation-call.trail.ts","./src/trails/no-sync-result-assumption.trail.ts","./src/trails/no-throw-in-detour-target.trail.ts","./src/trails/no-throw-in-implementation.trail.ts","./src/trails/prefer-schema-inference.trail.ts","./src/trails/run.ts","./src/trails/schema.ts","./src/trails/topo.ts","./src/trails/valid-describe-refs.trail.ts","./src/trails/valid-detour-refs.trail.ts","./src/trails/wrap-rule.ts"],"version":"5.9.3"}