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

package/.turbo/turbo-lint.log

@@ -1,3 +1,3 @@
 $ oxlint ./src
 Found 0 warnings and 0 errors.
-Finished in 17ms on 30 files with 93 rules using 24 threads.
+Finished in 19ms on 32 files with 93 rules using 24 threads.

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # @ontrails/warden
 
+## 1.0.0-beta.5
+
+### Minor Changes
+
+- Type utilities and follow-declarations warden rule.
+
+  **core**: Add `TrailInput<T>`, `TrailOutput<T>` utility types and `inputOf()`, `outputOf()` runtime schema accessors.
+
+  **warden**: Add `follow-declarations` rule — statically analyzes `ctx.follow()` calls against declared `follow: [...]` arrays. Errors on undeclared calls, warns on unused declarations.
+
+### Patch Changes
+
+- Updated dependencies
+  - @ontrails/core@1.0.0-beta.5
+  - @ontrails/schema@1.0.0-beta.5
+
 ## 1.0.0-beta.4
 
 ### Major Changes

package/README.md

@@ -37,6 +37,7 @@ console.log(formatWardenReport(report));
 | `no-direct-implementation-call` | warn | Direct `.run()` calls bypassing `ctx.follow()` |
 | `no-direct-impl-in-route` | warn | Direct `.run()` calls inside trail bodies with `follow` |
 | `prefer-schema-inference` | warn | Redundant field overrides already derivable from the schema |
+| `follow-declarations` | error/warn | `ctx.follow()` calls that drift from declared `follow: [...]` |
 | `valid-describe-refs` | warn | `@see` refs in `.describe()` that do not resolve |
 
 ## Drift detection

package/dist/rules/follow-declarations.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Validates that `ctx.follow()` calls match the declared `follow` array.
+ *
+ * Statically analyzes trail run functions to find `ctx.follow('trailId', ...)`
+ * calls and compares them against the `follow: [...]` declaration in the trail
+ * config. Reports errors for undeclared follows and warnings for unused ones.
+ */
+import type { WardenRule } from './types.js';
+/**
+ * Validates that `ctx.follow()` calls align with declared `follow` arrays.
+ */
+export declare const followDeclarations: WardenRule;
+//# sourceMappingURL=follow-declarations.d.ts.map

package/dist/rules/follow-declarations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"follow-declarations.d.ts","sourceRoot":"","sources":["../../src/rules/follow-declarations.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAYH,OAAO,KAAK,EAAoB,UAAU,EAAE,MAAM,YAAY,CAAC;AA8O/D;;GAEG;AACH,eAAO,MAAM,kBAAkB,EAAE,UAuBhC,CAAC"}

package/dist/rules/follow-declarations.js

@@ -0,0 +1,195 @@
+/**
+ * Validates that `ctx.follow()` calls match the declared `follow` array.
+ *
+ * Statically analyzes trail run functions to find `ctx.follow('trailId', ...)`
+ * calls and compares them against the `follow: [...]` declaration in the trail
+ * config. Reports errors for undeclared follows and warnings for unused ones.
+ */
+import { findConfigProperty, findRunBodies, findTrailDefinitions, offsetToLine, parse, walk, } from './ast.js';
+import { isTestFile } from './scan.js';
+// ---------------------------------------------------------------------------
+// String literal helpers
+// ---------------------------------------------------------------------------
+/** Check if a node is a string literal (covers `StringLiteral` and `Literal` with string value). */
+const isStringLiteral = (node) => {
+    if (node.type === 'StringLiteral') {
+        return true;
+    }
+    if (node.type === 'Literal') {
+        return typeof node.value === 'string';
+    }
+    return false;
+};
+/** Extract the string value from a string literal node. */
+const getStringValue = (node) => {
+    const val = node.value;
+    return typeof val === 'string' ? val : null;
+};
+// ---------------------------------------------------------------------------
+// Declared follow extraction
+// ---------------------------------------------------------------------------
+/** Extract the ArrayExpression elements from a config's `follow` property. */
+const getFollowElements = (config) => {
+    const followProp = findConfigProperty(config, 'follow');
+    if (!followProp) {
+        return null;
+    }
+    const arrayNode = followProp.value;
+    if (!arrayNode || arrayNode.type !== 'ArrayExpression') {
+        return null;
+    }
+    const elements = arrayNode['elements'];
+    return elements ?? null;
+};
+/** Collect string IDs from array elements. */
+const collectStringIds = (elements) => {
+    const ids = new Set();
+    for (const el of elements) {
+        if (isStringLiteral(el)) {
+            const val = getStringValue(el);
+            if (val) {
+                ids.add(val);
+            }
+        }
+    }
+    return ids;
+};
+/** Extract string literal elements from a `follow: [...]` array property. */
+const extractDeclaredFollows = (config) => {
+    const elements = getFollowElements(config);
+    return elements ? collectStringIds(elements) : new Set();
+};
+// ---------------------------------------------------------------------------
+// Called follow extraction — member expression helpers
+// ---------------------------------------------------------------------------
+const MEMBER_TYPES = new Set(['StaticMemberExpression', 'MemberExpression']);
+/** Get the name of an Identifier node, or null. */
+const identifierName = (node) => {
+    if (node?.type !== 'Identifier') {
+        return null;
+    }
+    return node.name ?? null;
+};
+/** Extract object and property Identifier names from a MemberExpression. */
+const extractMemberPair = (callee) => {
+    if (!MEMBER_TYPES.has(callee.type)) {
+        return null;
+    }
+    const objName = identifierName(callee.object);
+    const propName = identifierName(callee.property);
+    return objName && propName ? { objName, propName } : null;
+};
+/** Extract the first argument string from a CallExpression's arguments list. */
+const extractFirstStringArg = (node) => {
+    const args = node['arguments'];
+    if (!args || args.length === 0) {
+        return null;
+    }
+    const [firstArg] = args;
+    if (!firstArg || !isStringLiteral(firstArg)) {
+        // Dynamic ID — cannot resolve statically
+        return null;
+    }
+    return getStringValue(firstArg);
+};
+/** Check if a node is a `ctx.follow(...)` call and return the string trail ID. */
+const extractFollowCallId = (node) => {
+    if (node.type !== 'CallExpression') {
+        return null;
+    }
+    const callee = node['callee'];
+    if (!callee) {
+        return null;
+    }
+    const pair = extractMemberPair(callee);
+    if (!pair || pair.objName !== 'ctx' || pair.propName !== 'follow') {
+        return null;
+    }
+    return extractFirstStringArg(node);
+};
+/** Walk run bodies and collect all statically resolvable ctx.follow() trail IDs. */
+const extractCalledFollows = (config) => {
+    const ids = new Set();
+    for (const body of findRunBodies(config)) {
+        walk(body, (node) => {
+            const id = extractFollowCallId(node);
+            if (id) {
+                ids.add(id);
+            }
+        });
+    }
+    return ids;
+};
+// ---------------------------------------------------------------------------
+// Diagnostic builders
+// ---------------------------------------------------------------------------
+const buildUndeclaredDiagnostic = (trailId, followId, filePath, line) => ({
+    filePath,
+    line,
+    message: `Trail "${trailId}": ctx.follow('${followId}') called but '${followId}' is not declared in follow`,
+    rule: 'follow-declarations',
+    severity: 'error',
+});
+const buildUnusedDiagnostic = (trailId, followId, filePath, line) => ({
+    filePath,
+    line,
+    message: `Trail "${trailId}": '${followId}' declared in follow but ctx.follow('${followId}') never called`,
+    rule: 'follow-declarations',
+    severity: 'warn',
+});
+// ---------------------------------------------------------------------------
+// Comparison
+// ---------------------------------------------------------------------------
+/** Emit error for each called ID not present in declared set. */
+const reportUndeclared = (called, declared, ctx, diagnostics) => {
+    for (const id of called) {
+        if (!declared.has(id)) {
+            diagnostics.push(buildUndeclaredDiagnostic(ctx.trailId, id, ctx.filePath, ctx.line));
+        }
+    }
+};
+/** Emit warning for each declared ID not present in called set. */
+const reportUnused = (declared, called, ctx, diagnostics) => {
+    for (const id of declared) {
+        if (!called.has(id)) {
+            diagnostics.push(buildUnusedDiagnostic(ctx.trailId, id, ctx.filePath, ctx.line));
+        }
+    }
+};
+const checkTrailDefinition = (def, filePath, sourceCode, diagnostics) => {
+    const declared = extractDeclaredFollows(def.config);
+    const called = extractCalledFollows(def.config);
+    if (declared.size === 0 && called.size === 0) {
+        return;
+    }
+    const line = offsetToLine(sourceCode, def.start);
+    const ctx = { filePath, line, trailId: def.id };
+    reportUndeclared(called, declared, ctx, diagnostics);
+    reportUnused(declared, called, ctx, diagnostics);
+};
+// ---------------------------------------------------------------------------
+// Rule
+// ---------------------------------------------------------------------------
+/**
+ * Validates that `ctx.follow()` calls align with declared `follow` arrays.
+ */
+export const followDeclarations = {
+    check(sourceCode, filePath) {
+        if (isTestFile(filePath)) {
+            return [];
+        }
+        const ast = parse(filePath, sourceCode);
+        if (!ast) {
+            return [];
+        }
+        const diagnostics = [];
+        for (const def of findTrailDefinitions(ast)) {
+            checkTrailDefinition(def, filePath, sourceCode, diagnostics);
+        }
+        return diagnostics;
+    },
+    description: 'Ensure ctx.follow() calls match the declared follow array in trail definitions.',
+    name: 'follow-declarations',
+    severity: 'error',
+};
+//# sourceMappingURL=follow-declarations.js.map

package/dist/rules/follow-declarations.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"follow-declarations.js","sourceRoot":"","sources":["../../src/rules/follow-declarations.ts"],"names":[],"mappings":"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"}

package/dist/rules/index.d.ts

@@ -2,6 +2,7 @@ import type { WardenRule } from './types.js';
 export type { ProjectAwareWardenRule, ProjectContext, WardenDiagnostic, WardenRule, WardenSeverity, } from './types.js';
 export { noThrowInImplementation } from './no-throw-in-implementation.js';
 export { contextNoSurfaceTypes } from './context-no-surface-types.js';
+export { followDeclarations } from './follow-declarations.js';
 export { validDetourRefs } from './valid-detour-refs.js';
 export { noDirectImplInRoute } from './no-direct-impl-in-route.js';
 export { noDirectImplementationCall } from './no-direct-implementation-call.js';

package/dist/rules/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/rules/index.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAI7C,YAAY,EACV,sBAAsB,EACtB,cAAc,EACd,gBAAgB,EAChB,UAAU,EACV,cAAc,GACf,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,uBAAuB,EAAE,MAAM,iCAAiC,CAAC;AAC1E,OAAO,EAAE,qBAAqB,EAAE,MAAM,+BAA+B,CAAC;AACtE,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AACzD,OAAO,EAAE,mBAAmB,EAAE,MAAM,8BAA8B,CAAC;AACnE,OAAO,EAAE,0BAA0B,EAAE,MAAM,oCAAoC,CAAC;AAChF,OAAO,EAAE,sBAAsB,EAAE,MAAM,gCAAgC,CAAC;AACxE,OAAO,EAAE,2BAA2B,EAAE,MAAM,oCAAoC,CAAC;AACjF,OAAO,EAAE,qBAAqB,EAAE,MAAM,gCAAgC,CAAC;AACvE,OAAO,EAAE,qBAAqB,EAAE,MAAM,8BAA8B,CAAC;AACrE,OAAO,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAE7D,qDAAqD;AACrD,eAAO,MAAM,WAAW,EAAE,WAAW,CAAC,MAAM,EAAE,UAAU,CActD,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/rules/index.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAI7C,YAAY,EACV,sBAAsB,EACtB,cAAc,EACd,gBAAgB,EAChB,UAAU,EACV,cAAc,GACf,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,uBAAuB,EAAE,MAAM,iCAAiC,CAAC;AAC1E,OAAO,EAAE,qBAAqB,EAAE,MAAM,+BAA+B,CAAC;AACtE,OAAO,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAC9D,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AACzD,OAAO,EAAE,mBAAmB,EAAE,MAAM,8BAA8B,CAAC;AACnE,OAAO,EAAE,0BAA0B,EAAE,MAAM,oCAAoC,CAAC;AAChF,OAAO,EAAE,sBAAsB,EAAE,MAAM,gCAAgC,CAAC;AACxE,OAAO,EAAE,2BAA2B,EAAE,MAAM,oCAAoC,CAAC;AACjF,OAAO,EAAE,qBAAqB,EAAE,MAAM,gCAAgC,CAAC;AACvE,OAAO,EAAE,qBAAqB,EAAE,MAAM,8BAA8B,CAAC;AACrE,OAAO,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAE7D,qDAAqD;AACrD,eAAO,MAAM,WAAW,EAAE,WAAW,CAAC,MAAM,EAAE,UAAU,CAetD,CAAC"}

package/dist/rules/index.js

@@ -1,4 +1,5 @@
 import { contextNoSurfaceTypes } from './context-no-surface-types.js';
+import { followDeclarations } from './follow-declarations.js';
 import { implementationReturnsResult } from './implementation-returns-result.js';
 import { noDirectImplInRoute } from './no-direct-impl-in-route.js';
 import { noDirectImplementationCall } from './no-direct-implementation-call.js';
@@ -10,6 +11,7 @@ import { validDescribeRefs } from './valid-describe-refs.js';
 import { validDetourRefs } from './valid-detour-refs.js';
 export { noThrowInImplementation } from './no-throw-in-implementation.js';
 export { contextNoSurfaceTypes } from './context-no-surface-types.js';
+export { followDeclarations } from './follow-declarations.js';
 export { validDetourRefs } from './valid-detour-refs.js';
 export { noDirectImplInRoute } from './no-direct-impl-in-route.js';
 export { noDirectImplementationCall } from './no-direct-implementation-call.js';
@@ -22,6 +24,7 @@ export { validDescribeRefs } from './valid-describe-refs.js';
 export const wardenRules = new Map([
     [noThrowInImplementation.name, noThrowInImplementation],
     [contextNoSurfaceTypes.name, contextNoSurfaceTypes],
+    [followDeclarations.name, followDeclarations],
     [preferSchemaInference.name, preferSchemaInference],
     [validDescribeRefs.name, validDescribeRefs],
     [validDetourRefs.name, validDetourRefs],

package/dist/rules/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/rules/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,qBAAqB,EAAE,MAAM,+BAA+B,CAAC;AACtE,OAAO,EAAE,2BAA2B,EAAE,MAAM,oCAAoC,CAAC;AACjF,OAAO,EAAE,mBAAmB,EAAE,MAAM,8BAA8B,CAAC;AACnE,OAAO,EAAE,0BAA0B,EAAE,MAAM,oCAAoC,CAAC;AAChF,OAAO,EAAE,sBAAsB,EAAE,MAAM,gCAAgC,CAAC;AACxE,OAAO,EAAE,qBAAqB,EAAE,MAAM,gCAAgC,CAAC;AACvE,OAAO,EAAE,uBAAuB,EAAE,MAAM,iCAAiC,CAAC;AAC1E,OAAO,EAAE,qBAAqB,EAAE,MAAM,8BAA8B,CAAC;AAErE,OAAO,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAC7D,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAUzD,OAAO,EAAE,uBAAuB,EAAE,MAAM,iCAAiC,CAAC;AAC1E,OAAO,EAAE,qBAAqB,EAAE,MAAM,+BAA+B,CAAC;AACtE,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AACzD,OAAO,EAAE,mBAAmB,EAAE,MAAM,8BAA8B,CAAC;AACnE,OAAO,EAAE,0BAA0B,EAAE,MAAM,oCAAoC,CAAC;AAChF,OAAO,EAAE,sBAAsB,EAAE,MAAM,gCAAgC,CAAC;AACxE,OAAO,EAAE,2BAA2B,EAAE,MAAM,oCAAoC,CAAC;AACjF,OAAO,EAAE,qBAAqB,EAAE,MAAM,gCAAgC,CAAC;AACvE,OAAO,EAAE,qBAAqB,EAAE,MAAM,8BAA8B,CAAC;AACrE,OAAO,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAE7D,qDAAqD;AACrD,MAAM,CAAC,MAAM,WAAW,GAAoC,IAAI,GAAG,CAGjE;IACA,CAAC,uBAAuB,CAAC,IAAI,EAAE,uBAAuB,CAAC;IACvD,CAAC,qBAAqB,CAAC,IAAI,EAAE,qBAAqB,CAAC;IACnD,CAAC,qBAAqB,CAAC,IAAI,EAAE,qBAAqB,CAAC;IACnD,CAAC,iBAAiB,CAAC,IAAI,EAAE,iBAAiB,CAAC;IAC3C,CAAC,eAAe,CAAC,IAAI,EAAE,eAAe,CAAC;IACvC,CAAC,0BAA0B,CAAC,IAAI,EAAE,0BAA0B,CAAC;IAC7D,CAAC,sBAAsB,CAAC,IAAI,EAAE,sBAAsB,CAAC;IACrD,CAAC,2BAA2B,CAAC,IAAI,EAAE,2BAA2B,CAAC;IAC/D,CAAC,qBAAqB,CAAC,IAAI,EAAE,qBAAqB,CAAC;IACnD,CAAC,mBAAmB,CAAC,IAAI,EAAE,mBAAmB,CAAC;CAChD,CAAC,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/rules/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,qBAAqB,EAAE,MAAM,+BAA+B,CAAC;AACtE,OAAO,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAC9D,OAAO,EAAE,2BAA2B,EAAE,MAAM,oCAAoC,CAAC;AACjF,OAAO,EAAE,mBAAmB,EAAE,MAAM,8BAA8B,CAAC;AACnE,OAAO,EAAE,0BAA0B,EAAE,MAAM,oCAAoC,CAAC;AAChF,OAAO,EAAE,sBAAsB,EAAE,MAAM,gCAAgC,CAAC;AACxE,OAAO,EAAE,qBAAqB,EAAE,MAAM,gCAAgC,CAAC;AACvE,OAAO,EAAE,uBAAuB,EAAE,MAAM,iCAAiC,CAAC;AAC1E,OAAO,EAAE,qBAAqB,EAAE,MAAM,8BAA8B,CAAC;AAErE,OAAO,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAC7D,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAUzD,OAAO,EAAE,uBAAuB,EAAE,MAAM,iCAAiC,CAAC;AAC1E,OAAO,EAAE,qBAAqB,EAAE,MAAM,+BAA+B,CAAC;AACtE,OAAO,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAC9D,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AACzD,OAAO,EAAE,mBAAmB,EAAE,MAAM,8BAA8B,CAAC;AACnE,OAAO,EAAE,0BAA0B,EAAE,MAAM,oCAAoC,CAAC;AAChF,OAAO,EAAE,sBAAsB,EAAE,MAAM,gCAAgC,CAAC;AACxE,OAAO,EAAE,2BAA2B,EAAE,MAAM,oCAAoC,CAAC;AACjF,OAAO,EAAE,qBAAqB,EAAE,MAAM,gCAAgC,CAAC;AACvE,OAAO,EAAE,qBAAqB,EAAE,MAAM,8BAA8B,CAAC;AACrE,OAAO,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAE7D,qDAAqD;AACrD,MAAM,CAAC,MAAM,WAAW,GAAoC,IAAI,GAAG,CAGjE;IACA,CAAC,uBAAuB,CAAC,IAAI,EAAE,uBAAuB,CAAC;IACvD,CAAC,qBAAqB,CAAC,IAAI,EAAE,qBAAqB,CAAC;IACnD,CAAC,kBAAkB,CAAC,IAAI,EAAE,kBAAkB,CAAC;IAC7C,CAAC,qBAAqB,CAAC,IAAI,EAAE,qBAAqB,CAAC;IACnD,CAAC,iBAAiB,CAAC,IAAI,EAAE,iBAAiB,CAAC;IAC3C,CAAC,eAAe,CAAC,IAAI,EAAE,eAAe,CAAC;IACvC,CAAC,0BAA0B,CAAC,IAAI,EAAE,0BAA0B,CAAC;IAC7D,CAAC,sBAAsB,CAAC,IAAI,EAAE,sBAAsB,CAAC;IACrD,CAAC,2BAA2B,CAAC,IAAI,EAAE,2BAA2B,CAAC;IAC/D,CAAC,qBAAqB,CAAC,IAAI,EAAE,qBAAqB,CAAC;IACnD,CAAC,mBAAmB,CAAC,IAAI,EAAE,mBAAmB,CAAC;CAChD,CAAC,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ontrails/warden",
-  "version": "1.0.0-beta.4",
+  "version": "1.0.0-beta.5",
   "type": "module",
   "exports": {
     ".": "./src/index.ts",

package/src/__tests__/follow-declarations.test.ts

@@ -0,0 +1,151 @@
+import { describe, expect, test } from 'bun:test';
+
+import { followDeclarations } from '../rules/follow-declarations.js';
+
+const TEST_FILE = 'test.ts';
+
+describe('follow-declarations', () => {
+  describe('clean cases', () => {
+    test('declared and called match exactly', () => {
+      const code = `
+import { trail, Result } from '@ontrails/core';
+const t = trail('onboard', {
+  follow: ['entity.add', 'search'],
+  input: z.object({ name: z.string() }),
+  run: async (input, ctx) => {
+    await ctx.follow('entity.add', { name: input.name });
+    await ctx.follow('search', { query: input.name });
+    return Result.ok({});
+  },
+});
+`;
+
+      const diagnostics = followDeclarations.check(code, TEST_FILE);
+
+      expect(diagnostics.length).toBe(0);
+    });
+
+    test('no follow declaration and no ctx.follow() calls', () => {
+      const code = `
+trail('simple', {
+  input: z.object({ name: z.string() }),
+  run: async (input, ctx) => {
+    return Result.ok({ greeting: 'hello ' + input.name });
+  },
+});
+`;
+
+      const diagnostics = followDeclarations.check(code, TEST_FILE);
+
+      expect(diagnostics.length).toBe(0);
+    });
+  });
+
+  describe('error cases', () => {
+    test('called but not declared produces error', () => {
+      const code = `
+trail('onboard', {
+  input: z.object({ name: z.string() }),
+  run: async (input, ctx) => {
+    await ctx.follow('entity.add', { name: input.name });
+    return Result.ok({});
+  },
+});
+`;
+
+      const diagnostics = followDeclarations.check(code, TEST_FILE);
+
+      expect(diagnostics.length).toBe(1);
+      expect(diagnostics[0]?.severity).toBe('error');
+      expect(diagnostics[0]?.rule).toBe('follow-declarations');
+      expect(diagnostics[0]?.message).toContain("ctx.follow('entity.add')");
+      expect(diagnostics[0]?.message).toContain('not declared in follow');
+    });
+  });
+
+  describe('warn cases', () => {
+    test('declared but not called produces warning', () => {
+      const code = `
+trail('onboard', {
+  follow: ['entity.add', 'search'],
+  run: async (input, ctx) => {
+    await ctx.follow('entity.add', { name: input.name });
+    return Result.ok({});
+  },
+});
+`;
+
+      const diagnostics = followDeclarations.check(code, TEST_FILE);
+
+      expect(diagnostics.length).toBe(1);
+      expect(diagnostics[0]?.severity).toBe('warn');
+      expect(diagnostics[0]?.rule).toBe('follow-declarations');
+      expect(diagnostics[0]?.message).toContain("'search' declared in follow");
+      expect(diagnostics[0]?.message).toContain('never called');
+    });
+  });
+
+  describe('edge cases', () => {
+    test('dynamic follow IDs are skipped', () => {
+      const code = `
+trail('dispatch', {
+  follow: ['entity.add'],
+  run: async (input, ctx) => {
+    const trailId = input.target;
+    await ctx.follow(trailId, input);
+    await ctx.follow('entity.add', input);
+    return Result.ok({});
+  },
+});
+`;
+
+      const diagnostics = followDeclarations.check(code, TEST_FILE);
+
+      expect(diagnostics.length).toBe(0);
+    });
+
+    test('multiple trails in one file are validated independently', () => {
+      const code = `
+trail('alpha', {
+  follow: ['shared'],
+  run: async (input, ctx) => {
+    await ctx.follow('shared', input);
+    return Result.ok({});
+  },
+});
+
+trail('beta', {
+  run: async (input, ctx) => {
+    await ctx.follow('undeclared', input);
+    return Result.ok({});
+  },
+});
+`;
+
+      const diagnostics = followDeclarations.check(code, TEST_FILE);
+
+      expect(diagnostics.length).toBe(1);
+      expect(diagnostics[0]?.message).toContain('Trail "beta"');
+      expect(diagnostics[0]?.message).toContain("'undeclared'");
+      expect(diagnostics[0]?.severity).toBe('error');
+    });
+
+    test('skips test files', () => {
+      const code = `
+trail('onboard', {
+  run: async (input, ctx) => {
+    await ctx.follow('entity.add', input);
+    return Result.ok({});
+  },
+});
+`;
+
+      const diagnostics = followDeclarations.check(
+        code,
+        'src/__tests__/trails.test.ts'
+      );
+
+      expect(diagnostics.length).toBe(0);
+    });
+  });
+});

package/src/rules/follow-declarations.ts

@@ -0,0 +1,283 @@
+/**
+ * Validates that `ctx.follow()` calls match the declared `follow` array.
+ *
+ * Statically analyzes trail run functions to find `ctx.follow('trailId', ...)`
+ * calls and compares them against the `follow: [...]` declaration in the trail
+ * config. Reports errors for undeclared follows and warnings for unused ones.
+ */
+
+import {
+  findConfigProperty,
+  findRunBodies,
+  findTrailDefinitions,
+  offsetToLine,
+  parse,
+  walk,
+} from './ast.js';
+import type { AstNode } from './ast.js';
+import { isTestFile } from './scan.js';
+import type { WardenDiagnostic, WardenRule } from './types.js';
+
+// ---------------------------------------------------------------------------
+// String literal helpers
+// ---------------------------------------------------------------------------
+
+/** Check if a node is a string literal (covers `StringLiteral` and `Literal` with string value). */
+const isStringLiteral = (node: AstNode): boolean => {
+  if (node.type === 'StringLiteral') {
+    return true;
+  }
+  if (node.type === 'Literal') {
+    return typeof (node as unknown as { value?: unknown }).value === 'string';
+  }
+  return false;
+};
+
+/** Extract the string value from a string literal node. */
+const getStringValue = (node: AstNode): string | null => {
+  const val = (node as unknown as { value?: unknown }).value;
+  return typeof val === 'string' ? val : null;
+};
+
+// ---------------------------------------------------------------------------
+// Declared follow extraction
+// ---------------------------------------------------------------------------
+
+/** Extract the ArrayExpression elements from a config's `follow` property. */
+const getFollowElements = (config: AstNode): readonly AstNode[] | null => {
+  const followProp = findConfigProperty(config, 'follow');
+  if (!followProp) {
+    return null;
+  }
+
+  const arrayNode = followProp.value;
+  if (!arrayNode || (arrayNode as AstNode).type !== 'ArrayExpression') {
+    return null;
+  }
+
+  const elements = (arrayNode as AstNode)['elements'] as
+    | readonly AstNode[]
+    | undefined;
+  return elements ?? null;
+};
+
+/** Collect string IDs from array elements. */
+const collectStringIds = (elements: readonly AstNode[]): Set<string> => {
+  const ids = new Set<string>();
+  for (const el of elements) {
+    if (isStringLiteral(el)) {
+      const val = getStringValue(el);
+      if (val) {
+        ids.add(val);
+      }
+    }
+  }
+  return ids;
+};
+
+/** Extract string literal elements from a `follow: [...]` array property. */
+const extractDeclaredFollows = (config: AstNode): ReadonlySet<string> => {
+  const elements = getFollowElements(config);
+  return elements ? collectStringIds(elements) : new Set();
+};
+
+// ---------------------------------------------------------------------------
+// Called follow extraction — member expression helpers
+// ---------------------------------------------------------------------------
+
+const MEMBER_TYPES = new Set(['StaticMemberExpression', 'MemberExpression']);
+
+/** Get the name of an Identifier node, or null. */
+const identifierName = (node: AstNode | undefined): string | null => {
+  if (node?.type !== 'Identifier') {
+    return null;
+  }
+  return (node as unknown as { name?: string }).name ?? null;
+};
+
+/** Extract object and property Identifier names from a MemberExpression. */
+const extractMemberPair = (
+  callee: AstNode
+): { objName: string; propName: string } | null => {
+  if (!MEMBER_TYPES.has(callee.type)) {
+    return null;
+  }
+
+  const objName = identifierName(
+    (callee as unknown as { object?: AstNode }).object
+  );
+  const propName = identifierName(
+    (callee as unknown as { property?: AstNode }).property
+  );
+
+  return objName && propName ? { objName, propName } : null;
+};
+
+/** Extract the first argument string from a CallExpression's arguments list. */
+const extractFirstStringArg = (node: AstNode): string | null => {
+  const args = node['arguments'] as readonly AstNode[] | undefined;
+  if (!args || args.length === 0) {
+    return null;
+  }
+
+  const [firstArg] = args;
+  if (!firstArg || !isStringLiteral(firstArg)) {
+    // Dynamic ID — cannot resolve statically
+    return null;
+  }
+
+  return getStringValue(firstArg);
+};
+
+/** Check if a node is a `ctx.follow(...)` call and return the string trail ID. */
+const extractFollowCallId = (node: AstNode): string | null => {
+  if (node.type !== 'CallExpression') {
+    return null;
+  }
+
+  const callee = node['callee'] as AstNode | undefined;
+  if (!callee) {
+    return null;
+  }
+
+  const pair = extractMemberPair(callee);
+  if (!pair || pair.objName !== 'ctx' || pair.propName !== 'follow') {
+    return null;
+  }
+
+  return extractFirstStringArg(node);
+};
+
+/** Walk run bodies and collect all statically resolvable ctx.follow() trail IDs. */
+const extractCalledFollows = (config: AstNode): ReadonlySet<string> => {
+  const ids = new Set<string>();
+
+  for (const body of findRunBodies(config)) {
+    walk(body, (node) => {
+      const id = extractFollowCallId(node);
+      if (id) {
+        ids.add(id);
+      }
+    });
+  }
+
+  return ids;
+};
+
+// ---------------------------------------------------------------------------
+// Diagnostic builders
+// ---------------------------------------------------------------------------
+
+const buildUndeclaredDiagnostic = (
+  trailId: string,
+  followId: string,
+  filePath: string,
+  line: number
+): WardenDiagnostic => ({
+  filePath,
+  line,
+  message: `Trail "${trailId}": ctx.follow('${followId}') called but '${followId}' is not declared in follow`,
+  rule: 'follow-declarations',
+  severity: 'error',
+});
+
+const buildUnusedDiagnostic = (
+  trailId: string,
+  followId: string,
+  filePath: string,
+  line: number
+): WardenDiagnostic => ({
+  filePath,
+  line,
+  message: `Trail "${trailId}": '${followId}' declared in follow but ctx.follow('${followId}') never called`,
+  rule: 'follow-declarations',
+  severity: 'warn',
+});
+
+// ---------------------------------------------------------------------------
+// Comparison
+// ---------------------------------------------------------------------------
+
+/** Emit error for each called ID not present in declared set. */
+const reportUndeclared = (
+  called: ReadonlySet<string>,
+  declared: ReadonlySet<string>,
+  ctx: { trailId: string; filePath: string; line: number },
+  diagnostics: WardenDiagnostic[]
+): void => {
+  for (const id of called) {
+    if (!declared.has(id)) {
+      diagnostics.push(
+        buildUndeclaredDiagnostic(ctx.trailId, id, ctx.filePath, ctx.line)
+      );
+    }
+  }
+};
+
+/** Emit warning for each declared ID not present in called set. */
+const reportUnused = (
+  declared: ReadonlySet<string>,
+  called: ReadonlySet<string>,
+  ctx: { trailId: string; filePath: string; line: number },
+  diagnostics: WardenDiagnostic[]
+): void => {
+  for (const id of declared) {
+    if (!called.has(id)) {
+      diagnostics.push(
+        buildUnusedDiagnostic(ctx.trailId, id, ctx.filePath, ctx.line)
+      );
+    }
+  }
+};
+
+const checkTrailDefinition = (
+  def: { id: string; config: AstNode; start: number },
+  filePath: string,
+  sourceCode: string,
+  diagnostics: WardenDiagnostic[]
+): void => {
+  const declared = extractDeclaredFollows(def.config);
+  const called = extractCalledFollows(def.config);
+
+  if (declared.size === 0 && called.size === 0) {
+    return;
+  }
+
+  const line = offsetToLine(sourceCode, def.start);
+  const ctx = { filePath, line, trailId: def.id };
+
+  reportUndeclared(called, declared, ctx, diagnostics);
+  reportUnused(declared, called, ctx, diagnostics);
+};
+
+// ---------------------------------------------------------------------------
+// Rule
+// ---------------------------------------------------------------------------
+
+/**
+ * Validates that `ctx.follow()` calls align with declared `follow` arrays.
+ */
+export const followDeclarations: WardenRule = {
+  check(sourceCode: string, filePath: string): readonly WardenDiagnostic[] {
+    if (isTestFile(filePath)) {
+      return [];
+    }
+
+    const ast = parse(filePath, sourceCode);
+    if (!ast) {
+      return [];
+    }
+
+    const diagnostics: WardenDiagnostic[] = [];
+
+    for (const def of findTrailDefinitions(ast)) {
+      checkTrailDefinition(def, filePath, sourceCode, diagnostics);
+    }
+
+    return diagnostics;
+  },
+  description:
+    'Ensure ctx.follow() calls match the declared follow array in trail definitions.',
+  name: 'follow-declarations',
+  severity: 'error',
+};

package/src/rules/index.ts

@@ -1,4 +1,5 @@
 import { contextNoSurfaceTypes } from './context-no-surface-types.js';
+import { followDeclarations } from './follow-declarations.js';
 import { implementationReturnsResult } from './implementation-returns-result.js';
 import { noDirectImplInRoute } from './no-direct-impl-in-route.js';
 import { noDirectImplementationCall } from './no-direct-implementation-call.js';
@@ -20,6 +21,7 @@ export type {
 
 export { noThrowInImplementation } from './no-throw-in-implementation.js';
 export { contextNoSurfaceTypes } from './context-no-surface-types.js';
+export { followDeclarations } from './follow-declarations.js';
 export { validDetourRefs } from './valid-detour-refs.js';
 export { noDirectImplInRoute } from './no-direct-impl-in-route.js';
 export { noDirectImplementationCall } from './no-direct-implementation-call.js';
@@ -36,6 +38,7 @@ export const wardenRules: ReadonlyMap<string, WardenRule> = new Map<
 >([
   [noThrowInImplementation.name, noThrowInImplementation],
   [contextNoSurfaceTypes.name, contextNoSurfaceTypes],
+  [followDeclarations.name, followDeclarations],
   [preferSchemaInference.name, preferSchemaInference],
   [validDescribeRefs.name, validDescribeRefs],
   [validDetourRefs.name, validDetourRefs],

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"],"version":"5.9.3"}