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

package/src/trails/schema.ts

@@ -0,0 +1,237 @@
+/**
+ * Shared Zod schemas for warden rule trails.
+ *
+ * Every rule trail shares the same input (source file) and output
+ * (array of diagnostics) shape.
+ */
+
+import { intentValues } from '@ontrails/core';
+import type { Topo } from '@ontrails/core';
+import type { TopoGraph } from '@ontrails/topography';
+import { z } from 'zod';
+import { wardenImportResolutionErrorKinds } from '../resolve.js';
+import { wardenFixClasses, wardenFixSafeties } from '../rules/metadata.js';
+
+export const guidanceLinkSchema = z.object({
+  label: z.string(),
+  path: z.string().optional(),
+  url: z.string().optional(),
+});
+
+export const guidanceSchema = z.object({
+  commands: z.array(z.string()).readonly().optional(),
+  docs: z.array(guidanceLinkSchema).readonly().optional(),
+  relatedRules: z.array(z.string()).readonly().optional(),
+  steps: z.array(z.string()).readonly().optional(),
+  summary: z.string(),
+});
+
+export const fixEditSchema = z.object({
+  end: z.number(),
+  replacement: z.string(),
+  start: z.number(),
+});
+
+export const fixSchema = z.object({
+  class: z.enum(wardenFixClasses),
+  edits: z.array(fixEditSchema).readonly().optional(),
+  fixture: z.string().optional(),
+  reason: z.string(),
+  safety: z.enum(wardenFixSafeties),
+});
+
+/** A single diagnostic emitted by a warden rule trail. */
+export const diagnosticSchema = z.object({
+  code: z.string().optional().describe('Optional rule-local diagnostic code'),
+  filePath: z.string().describe('File path that was analyzed'),
+  fix: fixSchema.optional().describe('Structured fix metadata'),
+  guidance: guidanceSchema
+    .optional()
+    .describe('Structured remediation guidance'),
+  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'),
+});
+
+export const importResolutionSchema = z.object({
+  builtinModule: z.string().optional(),
+  crossesPackageBoundary: z.boolean(),
+  errorKind: z.enum(wardenImportResolutionErrorKinds).optional(),
+  errorMessage: z.string().optional(),
+  importSource: z.string(),
+  importerPath: z.string(),
+  isInternalTarget: z.boolean(),
+  line: z.number(),
+  packageName: z.string().optional(),
+  packageRoot: z.string().optional(),
+  resolvedPath: z.string().optional(),
+  usesPublicExport: z.boolean(),
+});
+
+export const publicWorkspaceSchema = z.object({
+  bin: z.record(z.string(), z.string()).optional(),
+  exportTargets: z.record(z.string(), z.string()).optional(),
+  files: z.array(z.string()).optional(),
+  hasExports: z.boolean(),
+  name: z.string(),
+  packageJsonPath: z.string(),
+  rootDir: z.string(),
+});
+
+export const exportedSymbolDefinitionSchema = z.object({
+  filePath: z.string(),
+  kind: z.enum([
+    'class',
+    'const',
+    'enum',
+    'export',
+    'function',
+    'interface',
+    'type',
+  ]),
+  line: z.number(),
+  name: z.string(),
+  workspaceName: z.string(),
+  workspaceRoot: z.string(),
+});
+
+/**
+ * Extended input for project-aware warden rule trails.
+ *
+ * Adds `knownTrailIds` so the caller can supply compose-file context and avoid
+ * false positives for `@see` references or compose-file entity relationships.
+ */
+export const authoredMcpSurfaceBindingSetSchema = z.object({
+  appName: z.string().describe('App/topo label the bindings were authored for'),
+  bindings: z
+    .record(z.string(), z.union([z.string(), z.array(z.string()).readonly()]))
+    .describe('Surfaces overlay mcp bindings: binding name to selector(s)'),
+  trailIds: z
+    .array(z.string())
+    .readonly()
+    .describe('Trail ids registered in the owning app topo'),
+});
+
+export const projectAwareRuleInput = ruleInput.extend({
+  authoredMcpSurfaceBindingSets: z
+    .array(authoredMcpSurfaceBindingSetSchema)
+    .readonly()
+    .optional()
+    .describe(
+      'Per-app authored surfaces overlay mcp bindings with owning-app trail ids'
+    ),
+  composeTargetTrailIds: z
+    .array(z.string())
+    .optional()
+    .describe('Trail IDs referenced by composes arrays across the project'),
+  crudCoverageByEntity: z
+    .record(z.string(), z.array(z.string()))
+    .optional()
+    .describe(
+      'CRUD operation coverage per entity aggregated across the project'
+    ),
+  crudTableIds: z
+    .array(z.string())
+    .optional()
+    .describe('Store table IDs used with CRUD factories across the project'),
+  documentedImportResolutionsByFile: z
+    .record(z.string(), z.array(importResolutionSchema))
+    .optional()
+    .describe('Resolved docs/specifier facts keyed by documentation file path'),
+  entityReferencesByName: z
+    .record(z.string(), z.array(z.string()))
+    .optional()
+    .describe('Declared entity references keyed by source entity name'),
+  exportedSymbolDefinitionsByName: z
+    .record(z.string(), z.array(exportedSymbolDefinitionSchema))
+    .optional()
+    .describe('Public exported symbol definitions grouped by exported name'),
+  importResolutionsByFile: z
+    .record(z.string(), z.array(importResolutionSchema))
+    .optional()
+    .describe('Resolved import facts keyed by importer file path'),
+  knownEntityIds: z
+    .array(z.string())
+    .optional()
+    .describe('Entity names known across the project'),
+  knownResourceIds: z
+    .array(z.string())
+    .optional()
+    .describe('Resource IDs known across the project'),
+  knownSignalIds: z
+    .array(z.string())
+    .optional()
+    .describe('Signal IDs known across the project'),
+  knownTrailIds: z
+    .array(z.string())
+    .optional()
+    .describe('Trail IDs known across the project'),
+  onTargetSignalIds: z
+    .array(z.string())
+    .optional()
+    .describe('Signal IDs referenced by trail on arrays across the project'),
+  publicWorkspaces: z
+    .record(z.string(), publicWorkspaceSchema)
+    .optional()
+    .describe('Non-private published @ontrails workspaces by package name'),
+  reconcileTableIds: z
+    .array(z.string())
+    .optional()
+    .describe('Store table IDs used with reconcile trails across the project'),
+  topoTrailIds: z
+    .array(z.string())
+    .optional()
+    .describe('Trail IDs registered in configured app topo targets'),
+  trailIntentsById: z
+    .record(z.string(), z.enum(intentValues))
+    .optional()
+    .describe('Normalized trail intents keyed by trail ID'),
+});
+
+/**
+ * Input for topo-aware warden rule trails.
+ *
+ * The `Topo` graph is not a serializable value, so the schema accepts it
+ * as an opaque `z.custom`. Topo-aware rules are invoked from the warden
+ * runtime with a live, resolved topo reference — they are not expected
+ * to be called across a network boundary.
+ */
+export const topoAwareRuleInput = z.object({
+  graph: z
+    .custom<TopoGraph>(
+      (value) =>
+        typeof value === 'object' && value !== null && 'entries' in value,
+      { message: 'Expected a serialized TopoGraph object' }
+    )
+    .optional()
+    .describe('Optional derived TopoGraph with graph-only audit annotations'),
+  topo: z
+    .custom<Topo>(
+      (value) =>
+        typeof value === 'object' &&
+        value !== null &&
+        'trails' in value &&
+        'resources' in value &&
+        'entities' in value &&
+        'signals' in value,
+      { message: 'Expected a resolved Topo instance' }
+    )
+    .describe('Resolved topo graph under inspection'),
+});
+
+/** 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 TopoAwareRuleInput = z.infer<typeof topoAwareRuleInput>;
+export type RuleOutput = z.infer<typeof ruleOutput>;

package/src/trails/signal-graph-coaching.trail.ts

@@ -0,0 +1,77 @@
+import { Result, resource, signal, topo, trail } from '@ontrails/core';
+import { z } from 'zod';
+
+import { signalGraphCoaching } from '../rules/signal-graph-coaching.js';
+import { wrapTopoRule } from './wrap-rule.js';
+
+const unusedSignal = signal('invoice.unused', {
+  payload: z.object({ invoiceId: z.string() }),
+});
+
+const producedSignal = signal('invoice.created', {
+  payload: z.object({ invoiceId: z.string() }),
+});
+
+const producerTrail = trail('invoice.create', {
+  fires: [producedSignal],
+  implementation: async (_input, ctx) => {
+    await ctx.fire?.(producedSignal, { invoiceId: 'inv_1' });
+    return Result.ok({ invoiceId: 'inv_1' });
+  },
+  input: z.object({}),
+  output: z.object({ invoiceId: z.string() }),
+});
+
+const resourceSignal = signal('store:invoice.created', {
+  payload: z.object({ invoiceId: z.string() }),
+});
+
+const invoiceStore = resource('store', {
+  create: () => Result.ok({ ok: true }),
+  signals: [resourceSignal],
+});
+
+export const signalGraphCoachingTrail = wrapTopoRule({
+  examples: [
+    {
+      expected: {
+        diagnostics: [
+          {
+            filePath: '<topo>',
+            line: 1,
+            message:
+              'Signal "invoice.created" is produced by producer trail "invoice.create" but has no consumer trails. Add an on: consumer if the signal is meant to drive reactive work, or remove the unused fires:/producer declaration.',
+            rule: 'signal-graph-coaching',
+            severity: 'warn',
+          },
+          {
+            filePath: '<topo>',
+            line: 1,
+            message:
+              'Signal "invoice.unused" is declared in the topo but has no producer trails, producer resources, or consumer trails. Add fires:/on: edges, attach producer metadata, or remove the unused signal contract.',
+            rule: 'signal-graph-coaching',
+            severity: 'warn',
+          },
+          {
+            filePath: '<topo>',
+            line: 1,
+            message:
+              'Signal "store:invoice.created" is produced by producer resource "store" but has no consumer trails. Add an on: consumer if the signal is meant to drive reactive work, or remove the unused fires:/producer declaration.',
+            rule: 'signal-graph-coaching',
+            severity: 'warn',
+          },
+        ],
+      },
+      input: {
+        topo: topo('trl-447-signal-graph-coaching', {
+          invoiceStore,
+          producedSignal,
+          producerTrail,
+          unusedSignal,
+        }),
+      },
+      name: 'Declared and produced signals without consumers get coaching',
+    },
+  ],
+  rule: signalGraphCoaching,
+});

package/src/trails/static-resource-accessor-preference.trail.ts

@@ -0,0 +1,25 @@
+import { staticResourceAccessorPreference } from '../rules/static-resource-accessor-preference.js';
+import { wrapRule } from './wrap-rule.js';
+
+export const staticResourceAccessorPreferenceTrail = wrapRule({
+  examples: [
+    {
+      expected: { diagnostics: [] },
+      input: {
+        filePath: 'clean.ts',
+        sourceCode: `const db = resource("db.main", {
+  create: () => Result.ok({ source: "factory" }),
+});
+
+trail("entity.show", {
+  resources: [db],
+  implementation: async (_input, ctx) => {
+    return Result.ok(db.from(ctx));
+  }
+})`,
+      },
+      name: 'Static resource helper access',
+    },
+  ],
+  rule: staticResourceAccessorPreference,
+});

package/src/trails/surface-overlay-coherence.trail.ts

@@ -0,0 +1,24 @@
+import { Result, topo, trail } from '@ontrails/core';
+import { z } from 'zod';
+
+import { surfaceOverlayCoherence } from '../rules/surface-overlay-coherence.js';
+import { wrapTopoRule } from './wrap-rule.js';
+
+const listTrail = trail('gear.list', {
+  implementation: () => Result.ok([]),
+  input: z.object({}),
+  output: z.array(z.string()),
+});
+
+export const surfaceOverlayCoherenceTrail = wrapTopoRule({
+  examples: [
+    {
+      expected: { diagnostics: [] },
+      input: {
+        topo: topo('surface-overlay-coherence', { listTrail }),
+      },
+      name: 'Topo without a serialized surfaces overlay stays quiet',
+    },
+  ],
+  rule: surfaceOverlayCoherence,
+});

package/src/trails/surface-trailhead-coherence.trail.ts

@@ -0,0 +1,25 @@
+import { surfaceTrailheadCoherence } from '../rules/surface-trailhead-coherence.js';
+import { wrapRule } from './wrap-rule.js';
+
+export const surfaceTrailheadCoherenceTrail = wrapRule({
+  examples: [
+    {
+      expected: { diagnostics: [] },
+      input: {
+        filePath: 'mcp-options.ts',
+        sourceCode: `export const trailheads = {
+  inspect: {
+    description: "Inspect topo state.",
+    trails: ["survey", "survey.brief"],
+  },
+  governance: {
+    description: "Run diagnostics.",
+    trails: ["warden", "doctor"],
+  },
+};`,
+      },
+      name: 'Reviewable trailhead map',
+    },
+  ],
+  rule: surfaceTrailheadCoherence,
+});

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/trail-fork-coaching.trail.ts

@@ -0,0 +1,42 @@
+import { trailForkCoaching } from '../rules/trail-fork-coaching.js';
+import { wrapRule } from './wrap-rule.js';
+
+export const trailForkCoachingTrail = wrapRule({
+  examples: [
+    {
+      expected: {
+        diagnostics: [
+          {
+            filePath: 'users.ts',
+            line: 9,
+            message:
+              'Trail "users.manage" branches on input.action ("create", "delete"). This may be a trail fork hidden as a surface accommodation. If branches change semantics (intent, permits, errors, outputs, lifecycle, or side effects) or structure (selected trail identity), split them into distinct trails, a composing trail, or a trailhead that preserves member identity.',
+            rule: 'trail-fork-coaching',
+            severity: 'warn',
+          },
+        ],
+      },
+      input: {
+        filePath: 'users.ts',
+        sourceCode: `import { Result, trail } from "@ontrails/core";
+import { z } from "zod";
+
+export const usersManage = trail("users.manage", {
+  input: z.object({
+    action: z.enum(["create", "delete"]),
+  }),
+  implementation: async (input) => {
+    switch (input.action) {
+      case "create":
+        return Result.ok({ created: true });
+      case "delete":
+        return Result.ok({ deleted: true });
+    }
+  },
+});`,
+      },
+      name: 'Possible trail fork hidden behind action',
+    },
+  ],
+  rule: trailForkCoaching,
+});

package/src/trails/trailhead-override-divergence.trail.ts

@@ -0,0 +1,47 @@
+import { trailheadOverrideDivergence } from '../rules/trailhead-override-divergence.js';
+import { wrapRule } from './wrap-rule.js';
+
+export const trailheadOverrideDivergenceTrail = wrapRule({
+  examples: [
+    {
+      expected: { diagnostics: [] },
+      input: {
+        authoredMcpSurfaceBindingSets: [
+          {
+            appName: 'demo',
+            bindings: { inspect: ['survey', 'survey.brief'] },
+            trailIds: ['survey', 'survey.brief'],
+          },
+        ],
+        filePath: 'mcp-options.ts',
+        sourceCode: `export const trailheads = {
+  inspect: {
+    description: "Inspect topo state.",
+    trails: ["survey", "survey.brief"],
+  },
+};`,
+      },
+      name: 'Aligned call-site override',
+    },
+    {
+      input: {
+        authoredMcpSurfaceBindingSets: [
+          {
+            appName: 'demo',
+            bindings: { inspect: ['survey', 'survey.brief'] },
+            trailIds: ['survey', 'survey.brief'],
+          },
+        ],
+        filePath: 'mcp-options.ts',
+        sourceCode: `export const trailheads = {
+  inspect: {
+    description: "Inspect topo state.",
+    trails: ["survey"],
+  },
+};`,
+      },
+      name: 'Diverging member selectors are flagged',
+    },
+  ],
+  rule: trailheadOverrideDivergence,
+});

package/src/trails/unmaterialized-activation-source.trail.ts

@@ -0,0 +1,72 @@
+import { Result, schedule, signal, topo, trail, webhook } from '@ontrails/core';
+import { z } from 'zod';
+
+import { unmaterializedActivationSource } from '../rules/unmaterialized-activation-source.js';
+import { wrapTopoRule } from './wrap-rule.js';
+
+const invoicePaidWebhook = webhook('webhook.invoice.paid', {
+  parse: z.object({ invoiceId: z.string() }),
+  path: '/webhooks/invoice/paid',
+});
+
+const webhookConsumer = trail('invoice.audit-webhook', {
+  implementation: () => Result.ok({ ok: true }),
+  input: z.object({ invoiceId: z.string() }),
+  on: [invoicePaidWebhook],
+  output: z.object({ ok: z.boolean() }),
+});
+
+const invoiceCreated = signal('invoice.created', {
+  from: ['invoice.create'],
+  payload: z.object({ invoiceId: z.string() }),
+});
+
+const signalProducer = trail('invoice.create', {
+  fires: [invoiceCreated],
+  implementation: async (_input, ctx) => {
+    await ctx.fire?.(invoiceCreated, { invoiceId: 'inv_1' });
+    return Result.ok({ invoiceId: 'inv_1' });
+  },
+  input: z.object({}),
+  output: z.object({ invoiceId: z.string() }),
+});
+
+const signalConsumer = trail('invoice.index', {
+  implementation: () => Result.ok({ ok: true }),
+  input: z.object({ invoiceId: z.string() }),
+  on: [invoiceCreated],
+  output: z.object({ ok: z.boolean() }),
+});
+
+const scheduleConsumer = trail('invoice.reconcile', {
+  implementation: () => Result.ok({ ok: true }),
+  input: z.object({}),
+  on: [schedule('schedule.invoice.reconcile', { cron: '0 * * * *' })],
+  output: z.object({ ok: z.boolean() }),
+});
+
+export const unmaterializedActivationSourceTrail = wrapTopoRule({
+  examples: [
+    {
+      expected: { diagnostics: [] },
+      input: {
+        topo: topo('trl-461-webhook-materialized', { webhookConsumer }),
+      },
+      name: 'Webhook activation sources are materialized by HTTP',
+    },
+    {
+      expected: { diagnostics: [] },
+      input: {
+        topo: topo('trl-496-materialized-sources', {
+          invoiceCreated,
+          scheduleConsumer,
+          signalConsumer,
+          signalProducer,
+          webhookConsumer,
+        }),
+      },
+      name: 'Signal, schedule, and webhook activation sources are materialized',
+    },
+  ],
+  rule: unmaterializedActivationSource,
+});

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