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

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/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"],"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"}