@ontrails/warden 1.0.0-beta.14 → 1.0.0-beta.16

package/src/trails/resolved-import-boundary.trail.ts

@@ -0,0 +1,109 @@
+import { resolvedImportBoundary } from '../rules/resolved-import-boundary.js';
+import { wrapRule } from './wrap-rule.js';
+
+export const resolvedImportBoundaryTrail = wrapRule({
+  examples: [
+    {
+      expected: {
+        diagnostics: [
+          {
+            filePath: 'packages/app/src/index.ts',
+            line: 1,
+            message:
+              'Import "@fixture/core/internal/secret" is not exported by @fixture/core. Import the package root or an exported subpath instead.',
+            rule: 'resolved-import-boundary',
+            severity: 'error',
+          },
+        ],
+      },
+      input: {
+        filePath: 'packages/app/src/index.ts',
+        importResolutionsByFile: {
+          'packages/app/src/index.ts': [
+            {
+              crossesPackageBoundary: true,
+              errorKind: 'package-path-not-exported',
+              importSource: '@fixture/core/internal/secret',
+              importerPath: 'packages/app/src/index.ts',
+              isInternalTarget: false,
+              line: 1,
+              packageName: '@fixture/core',
+              usesPublicExport: false,
+            },
+          ],
+        },
+        knownTrailIds: [],
+        sourceCode: "import { secret } from '@fixture/core/internal/secret';\n",
+      },
+      name: 'Cross-package imports must use exported package subpaths',
+    },
+    {
+      expected: {
+        diagnostics: [
+          {
+            filePath: 'packages/app/src/index.ts',
+            line: 1,
+            message:
+              'Local import "../../core/src/public" crosses into @fixture/core. Import the target package public surface instead.',
+            rule: 'resolved-import-boundary',
+            severity: 'error',
+          },
+        ],
+      },
+      input: {
+        filePath: 'packages/app/src/index.ts',
+        importResolutionsByFile: {
+          'packages/app/src/index.ts': [
+            {
+              crossesPackageBoundary: true,
+              importSource: '../../core/src/public',
+              importerPath: 'packages/app/src/index.ts',
+              isInternalTarget: false,
+              line: 1,
+              packageName: '@fixture/core',
+              usesPublicExport: false,
+            },
+          ],
+        },
+        knownTrailIds: [],
+        sourceCode: "import { pub } from '../../core/src/public';\n",
+      },
+      name: 'Relative imports must not cross package boundaries',
+    },
+    {
+      expected: {
+        diagnostics: [
+          {
+            filePath: 'packages/app/src/index.ts',
+            line: 1,
+            message:
+              'Import "../../core/src/internal/secret" targets internal/private files in @fixture/core. Import the target package public surface instead.',
+            rule: 'resolved-import-boundary',
+            severity: 'error',
+          },
+        ],
+      },
+      input: {
+        filePath: 'packages/app/src/index.ts',
+        importResolutionsByFile: {
+          'packages/app/src/index.ts': [
+            {
+              crossesPackageBoundary: true,
+              importSource: '../../core/src/internal/secret',
+              importerPath: 'packages/app/src/index.ts',
+              isInternalTarget: true,
+              line: 1,
+              packageName: '@fixture/core',
+              usesPublicExport: false,
+            },
+          ],
+        },
+        knownTrailIds: [],
+        sourceCode:
+          "import { secret } from '../../core/src/internal/secret';\n",
+      },
+      name: 'Cross-package imports must not target internals',
+    },
+  ],
+  rule: resolvedImportBoundary,
+});

package/src/trails/{provision-declarations.trail.ts → resource-declarations.trail.ts}

@@ -1,25 +1,25 @@
-import { provisionDeclarations } from '../rules/provision-declarations.js';
+import { resourceDeclarations } from '../rules/resource-declarations.js';
 import { wrapRule } from './wrap-rule.js';
 
-export const provisionDeclarationsTrail = wrapRule({
+export const resourceDeclarationsTrail = wrapRule({
   examples: [
     {
       expected: { diagnostics: [] },
       input: {
         filePath: 'clean.ts',
-        sourceCode: `const db = provision("db.main", {
+        sourceCode: `const db = resource("db.main", {
   create: () => Result.ok({ source: "factory" }),
 });
 
 trail("entity.show", {
-  provisions: [db],
+  resources: [db],
   blaze: async (_input, ctx) => {
     return Result.ok(db.from(ctx));
   }
 })`,
       },
-      name: 'Matched provision declarations and usage',
+      name: 'Matched resource declarations and usage',
     },
   ],
-  rule: provisionDeclarations,
+  rule: resourceDeclarations,
 });

package/src/trails/{provision-exists.trail.ts → resource-exists.trail.ts}

@@ -1,27 +1,27 @@
-import { provisionExists } from '../rules/provision-exists.js';
+import { resourceExists } from '../rules/resource-exists.js';
 import { wrapRule } from './wrap-rule.js';
 
-export const provisionExistsTrail = wrapRule({
+export const resourceExistsTrail = wrapRule({
   examples: [
     {
       expected: { diagnostics: [] },
       input: {
         filePath: 'clean.ts',
-        knownProvisionIds: ['db.main'],
+        knownResourceIds: ['db.main'],
         knownTrailIds: ['entity.show'],
-        sourceCode: `const db = provision("db.main", {
+        sourceCode: `const db = resource("db.main", {
   create: () => Result.ok({ source: "factory" }),
 });
 
 trail("entity.show", {
-  provisions: [db],
+  resources: [db],
   blaze: async (_input, ctx) => {
     return Result.ok(db.from(ctx));
   }
 })`,
       },
-      name: 'Declared provisions resolve to known project provisions',
+      name: 'Declared resources resolve to known project resources',
     },
   ],
-  rule: provisionExists,
+  rule: resourceExists,
 });

package/src/trails/resource-id-grammar.trail.ts

@@ -0,0 +1,39 @@
+import { resourceIdGrammar } from '../rules/resource-id-grammar.js';
+import { wrapRule } from './wrap-rule.js';
+
+export const resourceIdGrammarTrail = wrapRule({
+  examples: [
+    {
+      expected: { diagnostics: [] },
+      input: {
+        filePath: 'clean.ts',
+        sourceCode: `const db = resource("db.main", {
+  create: () => Result.ok({}),
+});`,
+      },
+      name: 'Resource ids stay free of the scope separator',
+    },
+    {
+      expected: {
+        diagnostics: [
+          {
+            filePath: 'invalid.ts',
+            line: 1,
+            message:
+              'Resource "billing:primary" is invalid because resource ids may not contain ":".',
+            rule: 'resource-id-grammar',
+            severity: 'error',
+          },
+        ],
+      },
+      input: {
+        filePath: 'invalid.ts',
+        sourceCode: `const db = resource("billing:primary", {
+  create: () => Result.ok({}),
+});`,
+      },
+      name: 'Colon-separated resource ids are rejected',
+    },
+  ],
+  rule: resourceIdGrammar,
+});

package/src/trails/run.ts

@@ -1,51 +1,160 @@
 /**
- * Run all warden rule trails against a single source file.
+ * Run file-scoped warden rule trails against a single source file.
  *
- * Returns a flat array of diagnostics from every rule.
+ * Returns a flat array of diagnostics from every source-aware rule. Built-in
+ * topo-aware rules are dispatched separately via `runTopoAwareWardenTrails()`
+ * so callers that loop files do not duplicate graph-level findings.
  */
 
+import type { Intent, Topo } from '@ontrails/core';
 import { run } from '@ontrails/core';
 
+import { wardenTopoRules } from '../rules/index.js';
 import type { WardenDiagnostic } from '../rules/types.js';
+import type { WardenImportResolution } from '../resolve.js';
+import type { WardenPublicWorkspace } from '../workspaces.js';
 import type { RuleOutput } from './schema.js';
 import { wardenTopo } from './topo.js';
 
 /**
- * Run all warden rule trails for a given file and collect diagnostics.
+ * Run all file-scoped 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 (
+const appendDiagnostics = (
+  target: WardenDiagnostic[],
+  diagnostics: readonly WardenDiagnostic[]
+): void => {
+  for (const diagnostic of diagnostics) {
+    target.push(diagnostic);
+  }
+};
+
+type TrailIntentMap = Readonly<Record<string, Intent>>;
+
+interface ProjectRuleOptions {
+  readonly contourReferencesByName?: Readonly<
+    Record<string, readonly string[]>
+  >;
+  readonly crossTargetTrailIds?: readonly string[];
+  readonly crudTableIds?: readonly string[];
+  readonly crudCoverageByEntity?: Readonly<Record<string, readonly string[]>>;
+  readonly knownContourIds?: readonly string[];
+  readonly importResolutionsByFile?: Readonly<
+    Record<string, readonly WardenImportResolution[]>
+  >;
+  readonly documentedImportResolutionsByFile?: Readonly<
+    Record<string, readonly WardenImportResolution[]>
+  >;
+  readonly knownResourceIds?: readonly string[];
+  readonly knownSignalIds?: readonly string[];
+  readonly knownTrailIds?: readonly string[];
+  readonly onTargetSignalIds?: readonly string[];
+  readonly publicWorkspaces?: Readonly<Record<string, WardenPublicWorkspace>>;
+  readonly reconcileTableIds?: readonly string[];
+  readonly trailIntentsById?: TrailIntentMap;
+}
+
+const PROJECT_OPTION_KEYS = [
+  'contourReferencesByName',
+  'crossTargetTrailIds',
+  'crudTableIds',
+  'crudCoverageByEntity',
+  'knownContourIds',
+  'importResolutionsByFile',
+  'documentedImportResolutionsByFile',
+  'knownResourceIds',
+  'knownSignalIds',
+  'knownTrailIds',
+  'onTargetSignalIds',
+  'publicWorkspaces',
+  'reconcileTableIds',
+  'trailIntentsById',
+] as const satisfies readonly (keyof ProjectRuleOptions)[];
+
+const hasProjectOptions = (options?: ProjectRuleOptions): boolean =>
+  Boolean(
+    options && PROJECT_OPTION_KEYS.some((key) => options[key] !== undefined)
+  );
+
+const collectProjectOptions = (
+  options?: ProjectRuleOptions
+): ProjectRuleOptions => {
+  if (!options) {
+    return {};
+  }
+
+  return Object.fromEntries(
+    PROJECT_OPTION_KEYS.flatMap((key) => {
+      const value = options[key];
+      return value === undefined ? [] : [[key, value] as const];
+    })
+  ) as ProjectRuleOptions;
+};
+
+const buildRuleInput = (
   filePath: string,
   sourceCode: string,
-  options?: {
-    readonly knownProvisionIds?: readonly string[];
-    readonly knownTrailIds?: readonly string[];
+  options?: ProjectRuleOptions
+): {
+  readonly filePath: string;
+  readonly sourceCode: string;
+} & ProjectRuleOptions => {
+  const base = { filePath, sourceCode };
+  if (!hasProjectOptions(options)) {
+    return base;
   }
+
+  return { ...base, ...collectProjectOptions(options) };
+};
+
+const topoAwareTrailIds = new Set(
+  [...wardenTopoRules.keys()].map((ruleName) => `warden.rule.${ruleName}`)
+);
+
+export const runWardenTrails = async (
+  filePath: string,
+  sourceCode: string,
+  options?: ProjectRuleOptions
 ): Promise<readonly WardenDiagnostic[]> => {
   const allDiagnostics: WardenDiagnostic[] = [];
+  const input = buildRuleInput(filePath, sourceCode, options);
 
   for (const id of wardenTopo.ids()) {
-    const input =
-      options?.knownTrailIds || options?.knownProvisionIds
-        ? {
-            filePath,
-            ...(options?.knownProvisionIds
-              ? { knownProvisionIds: options.knownProvisionIds }
-              : {}),
-            ...(options?.knownTrailIds
-              ? { knownTrailIds: options.knownTrailIds }
-              : {}),
-            sourceCode,
-          }
-        : { filePath, sourceCode };
+    if (topoAwareTrailIds.has(id)) {
+      continue;
+    }
     const result = await run(wardenTopo, id, input);
     if (result.isOk()) {
-      const { diagnostics } = result.value as RuleOutput;
-      for (const d of diagnostics) {
-        allDiagnostics.push(d);
-      }
+      appendDiagnostics(
+        allDiagnostics,
+        (result.value as RuleOutput).diagnostics
+      );
+    }
+  }
+
+  return allDiagnostics;
+};
+
+/**
+ * Run the built-in topo-aware warden rule trails once against a resolved topo.
+ *
+ * Unlike `runWardenTrails()`, which is file-scoped, topo-aware rules inspect
+ * the compiled graph and should only be dispatched once per topo.
+ */
+export const runTopoAwareWardenTrails = async (
+  topo: Topo
+): Promise<readonly WardenDiagnostic[]> => {
+  const allDiagnostics: WardenDiagnostic[] = [];
+
+  for (const id of topoAwareTrailIds) {
+    const result = await run(wardenTopo, id, { topo });
+    if (result.isOk()) {
+      appendDiagnostics(
+        allDiagnostics,
+        (result.value as RuleOutput).diagnostics
+      );
     }
   }
 

package/src/trails/scheduled-destroy-intent.trail.ts

@@ -0,0 +1,56 @@
+import { Result, schedule, topo, trail } from '@ontrails/core';
+import { z } from 'zod';
+
+import { scheduledDestroyIntent } from '../rules/scheduled-destroy-intent.js';
+import { wrapTopoRule } from './wrap-rule.js';
+
+export const scheduledDestroyTrail = trail('billing.purge-expired', {
+  blaze: () => Result.ok({ ok: true }),
+  input: z.object({}),
+  intent: 'destroy',
+  on: [
+    schedule('schedule.billing.purge-expired', {
+      cron: '0 2 * * *',
+    }),
+  ],
+  output: z.object({ ok: z.boolean() }),
+  permit: { scopes: ['billing:purge'] },
+});
+
+const scheduledWriteTrail = trail('billing.reconcile', {
+  blaze: () => Result.ok({ ok: true }),
+  input: z.object({}),
+  on: [schedule('schedule.billing.reconcile', { cron: '0 * * * *' })],
+  output: z.object({ ok: z.boolean() }),
+});
+
+export const scheduledDestroyIntentTrail = wrapTopoRule({
+  examples: [
+    {
+      expected: {
+        diagnostics: [
+          {
+            filePath: '<topo>',
+            line: 1,
+            message:
+              'Trail "billing.purge-expired" declares intent: \'destroy\' and is activated by schedule source "schedule.billing.purge-expired". Scheduled destroy work should make cadence, permit scope, idempotency, and recovery explicit before it runs unattended.',
+            rule: 'scheduled-destroy-intent',
+            severity: 'warn',
+          },
+        ],
+      },
+      input: {
+        topo: topo('trl-457-scheduled-destroy', { scheduledDestroyTrail }),
+      },
+      name: 'Scheduled destroy trails emit coaching',
+    },
+    {
+      expected: { diagnostics: [] },
+      input: {
+        topo: topo('trl-457-scheduled-write', { scheduledWriteTrail }),
+      },
+      name: 'Scheduled write trails do not emit destroy coaching',
+    },
+  ],
+  rule: scheduledDestroyIntent,
+});

package/src/trails/schema.ts

@@ -5,11 +5,31 @@
  * (array of diagnostics) shape.
  */
 
+import { intentValues } from '@ontrails/core';
+import type { Topo } from '@ontrails/core';
 import { z } from 'zod';
+import { wardenImportResolutionErrorKinds } from '../resolve.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(),
+});
 
 /** A single diagnostic emitted by a warden rule trail. */
 export const diagnosticSchema = z.object({
   filePath: z.string().describe('File path that was analyzed'),
+  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'),
@@ -22,22 +42,119 @@ export const ruleInput = z.object({
   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(),
+});
+
 /**
  * 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.
+ * false positives for `@see` references or cross-file contour relationships.
  */
 export const projectAwareRuleInput = ruleInput.extend({
-  knownProvisionIds: z
+  contourReferencesByName: z
+    .record(z.string(), z.array(z.string()))
+    .optional()
+    .describe('Declared contour references keyed by source contour name'),
+  crossTargetTrailIds: z
+    .array(z.string())
+    .optional()
+    .describe('Trail IDs referenced by crosses 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'),
+  importResolutionsByFile: z
+    .record(z.string(), z.array(importResolutionSchema))
+    .optional()
+    .describe('Resolved import facts keyed by importer file path'),
+  knownContourIds: z
+    .array(z.string())
+    .optional()
+    .describe('Contour 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('Provision IDs known across the project'),
+    .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'),
+  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({
+  topo: z
+    .custom<Topo>(
+      (value) =>
+        typeof value === 'object' &&
+        value !== null &&
+        'trails' in value &&
+        'resources' in value &&
+        'contours' in value &&
+        'signals' in value,
+      { message: 'Expected a resolved Topo instance' }
+    )
+    .describe('Resolved topo graph under inspection'),
 });
 
 /** Output returned by every warden rule trail. */
@@ -47,4 +164,5 @@ export const ruleOutput = z.object({
 
 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,74 @@
+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', {
+  blaze: () => Result.ok({ invoiceId: 'inv_1' }),
+  fires: [producedSignal],
+  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,
+});