@ontrails/core 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 19ms on 58 files with 93 rules using 24 threads.
+Finished in 21ms on 60 files with 93 rules using 24 threads.

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # @ontrails/core
 
+## 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.
+
 ## 1.0.0-beta.4
 
 ### Major Changes

package/README.md

@@ -46,6 +46,15 @@ const onboard = trail('entity.onboard', {
 | `topo(name, ...modules)` | Collect trail modules into a queryable topology |
 | `validateTopo(topo)` | Structural validation: follow targets exist, no cycles, examples parse, output schemas present |
 
+### Type utilities
+
+| Export | What it does |
+| --- | --- |
+| `TrailInput<T>` | Extract the input type from a `Trail` |
+| `TrailOutput<T>` | Extract the output type from a `Trail` |
+| `inputOf(trail)` | Get the input Zod schema from a trail instance |
+| `outputOf(trail)` | Get the output Zod schema (or `undefined`) from a trail instance |
+
 ### Result
 
 ```typescript

package/dist/index.d.ts

@@ -5,6 +5,8 @@ export type { Implementation, TrailContext, FollowFn, ProgressCallback, Progress
 export { createTrailContext } from './context.js';
 export { trail } from './trail.js';
 export type { AnyTrail, Intent, Trail, TrailSpec, TrailExample, } from './trail.js';
+export type { TrailInput, TrailOutput } from './type-utils.js';
+export { inputOf, outputOf } from './type-utils.js';
 export { event } from './event.js';
 export type { AnyEvent, Event, EventSpec } from './event.js';
 export { topo } from './topo.js';

package/dist/index.d.ts.map

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

package/dist/index.js

@@ -6,6 +6,7 @@ export { TrailsError, ValidationError, AmbiguousError, AssertionError, NotFoundE
 export { createTrailContext } from './context.js';
 // Trail
 export { trail } from './trail.js';
+export { inputOf, outputOf } from './type-utils.js';
 // Event
 export { event } from './event.js';
 // Topo

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,SAAS;AACT,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAErC,SAAS;AACT,OAAO,EACL,WAAW,EACX,eAAe,EACf,cAAc,EACd,cAAc,EACd,aAAa,EACb,kBAAkB,EAClB,aAAa,EACb,eAAe,EACf,YAAY,EACZ,cAAc,EACd,YAAY,EACZ,aAAa,EACb,SAAS,EACT,cAAc,EACd,WAAW,EACX,aAAa,EACb,cAAc,EACd,YAAY,EACZ,WAAW,EACX,aAAa,GACd,MAAM,aAAa,CAAC;AAcrB,kBAAkB;AAClB,OAAO,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAElD,QAAQ;AACR,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AASnC,QAAQ;AACR,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAGnC,OAAO;AACP,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAGjC,kBAAkB;AAClB,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAGlD,QAAQ;AACR,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAgB3C,SAAS;AACT,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAG3C,aAAa;AACb,OAAO,EACL,aAAa,EACb,cAAc,EACd,eAAe,EACf,eAAe,GAChB,MAAM,iBAAiB,CAAC;AAEzB,gBAAgB;AAChB,OAAO,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAGtE,aAAa;AACb,OAAO,EACL,KAAK,EACL,WAAW,EACX,WAAW,EACX,eAAe,GAChB,MAAM,iBAAiB,CAAC;AAGzB,uDAAuD;AAEvD,gBAAgB;AAChB,OAAO,EACL,KAAK,EACL,OAAO,EACP,IAAI,EACJ,KAAK,EACL,cAAc,EACd,WAAW,EACX,OAAO,EACP,MAAM,GACP,MAAM,cAAc,CAAC;AAStB,gBAAgB;AAChB,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAE7E,YAAY;AACZ,OAAO,EACL,iBAAiB,EACjB,iBAAiB,EACjB,eAAe,GAChB,MAAM,gBAAgB,CAAC;AAExB,OAAO;AACP,OAAO,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAGzD,SAAS;AACT,OAAO,EACL,SAAS,EACT,gBAAgB,EAChB,aAAa,EACb,WAAW,EACX,WAAW,GACZ,MAAM,aAAa,CAAC;AAErB,cAAc;AACd,OAAO,EACL,KAAK,EACL,MAAM,EACN,OAAO,EACP,MAAM,EACN,eAAe,GAChB,MAAM,kBAAkB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,SAAS;AACT,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAErC,SAAS;AACT,OAAO,EACL,WAAW,EACX,eAAe,EACf,cAAc,EACd,cAAc,EACd,aAAa,EACb,kBAAkB,EAClB,aAAa,EACb,eAAe,EACf,YAAY,EACZ,cAAc,EACd,YAAY,EACZ,aAAa,EACb,SAAS,EACT,cAAc,EACd,WAAW,EACX,aAAa,EACb,cAAc,EACd,YAAY,EACZ,WAAW,EACX,aAAa,GACd,MAAM,aAAa,CAAC;AAcrB,kBAAkB;AAClB,OAAO,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAElD,QAAQ;AACR,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAWnC,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAEpD,QAAQ;AACR,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAGnC,OAAO;AACP,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAGjC,kBAAkB;AAClB,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAGlD,QAAQ;AACR,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAgB3C,SAAS;AACT,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAG3C,aAAa;AACb,OAAO,EACL,aAAa,EACb,cAAc,EACd,eAAe,EACf,eAAe,GAChB,MAAM,iBAAiB,CAAC;AAEzB,gBAAgB;AAChB,OAAO,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAGtE,aAAa;AACb,OAAO,EACL,KAAK,EACL,WAAW,EACX,WAAW,EACX,eAAe,GAChB,MAAM,iBAAiB,CAAC;AAGzB,uDAAuD;AAEvD,gBAAgB;AAChB,OAAO,EACL,KAAK,EACL,OAAO,EACP,IAAI,EACJ,KAAK,EACL,cAAc,EACd,WAAW,EACX,OAAO,EACP,MAAM,GACP,MAAM,cAAc,CAAC;AAStB,gBAAgB;AAChB,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAE7E,YAAY;AACZ,OAAO,EACL,iBAAiB,EACjB,iBAAiB,EACjB,eAAe,GAChB,MAAM,gBAAgB,CAAC;AAExB,OAAO;AACP,OAAO,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAGzD,SAAS;AACT,OAAO,EACL,SAAS,EACT,gBAAgB,EAChB,aAAa,EACb,WAAW,EACX,WAAW,GACZ,MAAM,aAAa,CAAC;AAErB,cAAc;AACd,OAAO,EACL,KAAK,EACL,MAAM,EACN,OAAO,EACP,MAAM,EACN,eAAe,GAChB,MAAM,kBAAkB,CAAC"}

package/dist/type-utils.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Type utilities for extracting input/output types from trails.
+ */
+import type { z } from 'zod';
+import type { AnyTrail, Trail } from './trail.js';
+/** Extract the input type from a Trail. */
+export type TrailInput<T extends AnyTrail> = T extends Trail<infer I, any> ? I : never;
+/** Extract the output type from a Trail. */
+export type TrailOutput<T extends AnyTrail> = T extends Trail<any, infer O> ? O : never;
+/** Get the input Zod schema from a trail. */
+export declare const inputOf: <I, O>(trail: Trail<I, O>) => z.ZodType<I>;
+/** Get the output Zod schema from a trail, if defined. */
+export declare const outputOf: <I, O>(trail: Trail<I, O>) => z.ZodType<O> | undefined;
+//# sourceMappingURL=type-utils.d.ts.map

package/dist/type-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"type-utils.d.ts","sourceRoot":"","sources":["../src/type-utils.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAE7B,OAAO,KAAK,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAQlD,2CAA2C;AAC3C,MAAM,MAAM,UAAU,CAAC,CAAC,SAAS,QAAQ,IACvC,CAAC,SAAS,KAAK,CAAC,MAAM,CAAC,EAAE,GAAG,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;AAE5C,4CAA4C;AAC5C,MAAM,MAAM,WAAW,CAAC,CAAC,SAAS,QAAQ,IACxC,CAAC,SAAS,KAAK,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;AAQ5C,6CAA6C;AAC7C,eAAO,MAAM,OAAO,GAAI,CAAC,EAAE,CAAC,EAAE,OAAO,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,KAAG,CAAC,CAAC,OAAO,CAAC,CAAC,CAAgB,CAAC;AAE/E,0DAA0D;AAC1D,eAAO,MAAM,QAAQ,GAAI,CAAC,EAAE,CAAC,EAAE,OAAO,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,KAAG,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,SACrD,CAAC"}

package/dist/type-utils.js

@@ -0,0 +1,12 @@
+/**
+ * Type utilities for extracting input/output types from trails.
+ */
+/* oxlint-enable no-explicit-any */
+// ---------------------------------------------------------------------------
+// Runtime schema accessors
+// ---------------------------------------------------------------------------
+/** Get the input Zod schema from a trail. */
+export const inputOf = (trail) => trail.input;
+/** Get the output Zod schema from a trail, if defined. */
+export const outputOf = (trail) => trail.output;
+//# sourceMappingURL=type-utils.js.map

package/dist/type-utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"type-utils.js","sourceRoot":"","sources":["../src/type-utils.ts"],"names":[],"mappings":"AAAA;;GAEG;AAoBH,mCAAmC;AAEnC,8EAA8E;AAC9E,2BAA2B;AAC3B,8EAA8E;AAE9E,6CAA6C;AAC7C,MAAM,CAAC,MAAM,OAAO,GAAG,CAAO,KAAkB,EAAgB,EAAE,CAAC,KAAK,CAAC,KAAK,CAAC;AAE/E,0DAA0D;AAC1D,MAAM,CAAC,MAAM,QAAQ,GAAG,CAAO,KAAkB,EAA4B,EAAE,CAC7E,KAAK,CAAC,MAAM,CAAC"}

package/package.json

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

package/src/__tests__/type-utils.test.ts

@@ -0,0 +1,63 @@
+import { describe, expect, test } from 'bun:test';
+
+import { z } from 'zod';
+
+import { Result } from '../result';
+import { trail } from '../trail';
+import type { TrailInput, TrailOutput } from '../type-utils';
+import { inputOf, outputOf } from '../type-utils';
+
+const greetTrail = trail('greet', {
+  input: z.object({ name: z.string() }),
+  output: z.object({ message: z.string() }),
+  run: (input) => Result.ok({ message: `Hello, ${input.name}!` }),
+});
+
+const noOutputTrail = trail('ping', {
+  input: z.object({}),
+  run: () => Result.ok(),
+});
+
+describe('type-utils', () => {
+  describe('inputOf', () => {
+    test('returns the Zod input schema and can parse valid input', () => {
+      const schema = inputOf(greetTrail);
+      const result = schema.safeParse({ name: 'Alice' });
+      expect(result.success).toBe(true);
+      expect(
+        (result as { success: true; data: { name: string } }).data
+      ).toEqual({
+        name: 'Alice',
+      });
+    });
+  });
+
+  describe('outputOf', () => {
+    test('returns the Zod output schema when defined', () => {
+      const schema = outputOf(greetTrail);
+      expect(schema).toBeDefined();
+      // oxlint-disable-next-line no-non-null-assertion -- guarded by toBeDefined() above
+      const result = schema!.safeParse({ message: 'hello' });
+      expect(result.success).toBe(true);
+    });
+
+    test('returns undefined when no output schema', () => {
+      const schema = outputOf(noOutputTrail);
+      expect(schema).toBeUndefined();
+    });
+  });
+
+  describe('type-level checks', () => {
+    test('TrailInput matches expected shape', () => {
+      // If this compiles, the type is correct
+      const _input: TrailInput<typeof greetTrail> = { name: 'test' };
+      expect(_input.name).toBe('test');
+    });
+
+    test('TrailOutput matches expected shape', () => {
+      // If this compiles, the type is correct
+      const _output: TrailOutput<typeof greetTrail> = { message: 'hello' };
+      expect(_output.message).toBe('hello');
+    });
+  });
+});

package/src/index.ts

@@ -50,6 +50,10 @@ export type {
   TrailExample,
 } from './trail.js';
 
+// Type utilities
+export type { TrailInput, TrailOutput } from './type-utils.js';
+export { inputOf, outputOf } from './type-utils.js';
+
 // Event
 export { event } from './event.js';
 export type { AnyEvent, Event, EventSpec } from './event.js';

package/src/type-utils.ts

@@ -0,0 +1,34 @@
+/**
+ * Type utilities for extracting input/output types from trails.
+ */
+
+import type { z } from 'zod';
+
+import type { AnyTrail, Trail } from './trail.js';
+
+// ---------------------------------------------------------------------------
+// Utility types
+// ---------------------------------------------------------------------------
+
+/* oxlint-disable no-explicit-any -- `any` required for conditional type inference; `unknown` breaks inference */
+
+/** Extract the input type from a Trail. */
+export type TrailInput<T extends AnyTrail> =
+  T extends Trail<infer I, any> ? I : never;
+
+/** Extract the output type from a Trail. */
+export type TrailOutput<T extends AnyTrail> =
+  T extends Trail<any, infer O> ? O : never;
+
+/* oxlint-enable no-explicit-any */
+
+// ---------------------------------------------------------------------------
+// Runtime schema accessors
+// ---------------------------------------------------------------------------
+
+/** Get the input Zod schema from a trail. */
+export const inputOf = <I, O>(trail: Trail<I, O>): z.ZodType<I> => trail.input;
+
+/** Get the output Zod schema from a trail, if defined. */
+export const outputOf = <I, O>(trail: Trail<I, O>): z.ZodType<O> | undefined =>
+  trail.output;

package/tsconfig.tsbuildinfo

@@ -1 +1 @@
-{"root":["./src/adapters.ts","./src/blob-ref.ts","./src/branded.ts","./src/collections.ts","./src/context.ts","./src/derive.ts","./src/errors.ts","./src/event.ts","./src/fetch.ts","./src/guards.ts","./src/health.ts","./src/index.ts","./src/job.ts","./src/layer.ts","./src/path-security.ts","./src/resilience.ts","./src/result.ts","./src/serialization.ts","./src/topo.ts","./src/trail.ts","./src/types.ts","./src/validate-topo.ts","./src/validation.ts","./src/workspace.ts","./src/patterns/bulk.ts","./src/patterns/change.ts","./src/patterns/date-range.ts","./src/patterns/index.ts","./src/patterns/pagination.ts","./src/patterns/progress.ts","./src/patterns/sorting.ts","./src/patterns/status.ts","./src/patterns/timestamps.ts","./src/redaction/index.ts","./src/redaction/patterns.ts","./src/redaction/redactor.ts"],"version":"5.9.3"}
+{"root":["./src/adapters.ts","./src/blob-ref.ts","./src/branded.ts","./src/collections.ts","./src/context.ts","./src/derive.ts","./src/errors.ts","./src/event.ts","./src/fetch.ts","./src/guards.ts","./src/health.ts","./src/index.ts","./src/job.ts","./src/layer.ts","./src/path-security.ts","./src/resilience.ts","./src/result.ts","./src/serialization.ts","./src/topo.ts","./src/trail.ts","./src/type-utils.ts","./src/types.ts","./src/validate-topo.ts","./src/validation.ts","./src/workspace.ts","./src/patterns/bulk.ts","./src/patterns/change.ts","./src/patterns/date-range.ts","./src/patterns/index.ts","./src/patterns/pagination.ts","./src/patterns/progress.ts","./src/patterns/sorting.ts","./src/patterns/status.ts","./src/patterns/timestamps.ts","./src/redaction/index.ts","./src/redaction/patterns.ts","./src/redaction/redactor.ts"],"version":"5.9.3"}