@ontrails/warden 1.0.0-beta.2 → 1.0.0-beta.21

package/src/trails/no-top-level-surface.trail.ts

@@ -0,0 +1,43 @@
+import { noTopLevelSurface } from '../rules/no-top-level-surface.js';
+import { wrapRule } from './wrap-rule.js';
+
+export const noTopLevelSurfaceTrail = wrapRule({
+  examples: [
+    {
+      expected: { diagnostics: [] },
+      input: {
+        filePath: 'src/mcp.ts',
+        sourceCode: `import { surface } from "@ontrails/mcp";
+import graph from "./app";
+
+await surface(graph);`,
+      },
+      name: 'Allows dedicated surface entry modules',
+    },
+    {
+      expected: {
+        diagnostics: [
+          {
+            filePath: 'src/app.ts',
+            line: 6,
+            message:
+              'This module exports a topo and opens a surface at module top level. Trails introspection commands (`survey`, `guide`, `compile`) import topo entry modules, so opening a surface here can trigger sockets or transports during introspection. Move surface-opening to a separate entry/bin and keep the topo-export module side-effect-free.',
+            rule: 'no-top-level-surface',
+            severity: 'warn',
+          },
+        ],
+      },
+      input: {
+        filePath: 'src/app.ts',
+        sourceCode: `import { topo } from "@ontrails/core";
+import { surface } from "@ontrails/mcp";
+import * as trails from "./trails";
+
+export const graph = topo("app", trails);
+await surface(graph);`,
+      },
+      name: 'Warns when a topo export module opens a surface',
+    },
+  ],
+  rule: noTopLevelSurface,
+});

package/src/trails/on-references-exist.trail.ts

@@ -0,0 +1,21 @@
+import { onReferencesExist } from '../rules/on-references-exist.js';
+import { wrapRule } from './wrap-rule.js';
+
+export const onReferencesExistTrail = wrapRule({
+  examples: [
+    {
+      expected: { diagnostics: [] },
+      input: {
+        filePath: 'consumer.ts',
+        knownSignalIds: ['entity.created'],
+        knownTrailIds: ['notify'],
+        sourceCode: `trail("notify", {
+  on: ["entity.created"],
+  blaze: async (input, ctx) => Result.ok({}),
+})`,
+      },
+      name: 'Resolved on: reference',
+    },
+  ],
+  rule: onReferencesExist,
+});

package/src/trails/orphaned-signal.trail.ts

@@ -0,0 +1,36 @@
+import { orphanedSignal } from '../rules/orphaned-signal.js';
+import { wrapRule } from './wrap-rule.js';
+
+export const orphanedSignalTrail = wrapRule({
+  examples: [
+    {
+      expected: { diagnostics: [] },
+      input: {
+        // Composite keys: `${storeBinding}:${tableName}` so two stores with
+        // the same table name don't collide.
+        crudTableIds: ['definition:notes'],
+        filePath: 'clean.ts',
+        knownTrailIds: ['notes.notify'],
+        onTargetSignalIds: [
+          'definition:notes.created',
+          'definition:notes.updated',
+          'definition:notes.removed',
+        ],
+        sourceCode: `import { store } from '@ontrails/store';
+import { z } from 'zod';
+
+const definition = store({
+  notes: {
+    identity: 'id',
+    schema: z.object({
+      id: z.string(),
+      title: z.string(),
+    }),
+  },
+});`,
+      },
+      name: 'Derived store signals stay quiet when trail on consumers exist',
+    },
+  ],
+  rule: orphanedSignal,
+});

package/src/trails/owner-projection-parity.trail.ts

@@ -0,0 +1,26 @@
+import { fileURLToPath } from 'node:url';
+
+import { ownerProjectionParity } from '../rules/owner-projection-parity.js';
+import { wrapRule } from './wrap-rule.js';
+
+export const ownerProjectionParityTrail = wrapRule({
+  examples: [
+    {
+      expected: { diagnostics: [] },
+      input: {
+        filePath: fileURLToPath(
+          new URL('../../../http/src/method.ts', import.meta.url)
+        ),
+        sourceCode: `import type { Intent } from '@ontrails/core';
+
+export const httpMethodByIntent = {
+  destroy: 'DELETE',
+  read: 'GET',
+  write: 'POST',
+} as const satisfies Record<Intent, 'GET' | 'POST' | 'DELETE'>;`,
+      },
+      name: 'HTTP method projection covers core intent values',
+    },
+  ],
+  rule: ownerProjectionParity,
+});

package/src/trails/pending-force.trail.ts

@@ -0,0 +1,21 @@
+import { topo } from '@ontrails/core';
+import { deriveTopoGraph } from '@ontrails/topographer';
+
+import { pendingForce } from '../rules/trail-versioning-topo.js';
+import { wrapTopoRule } from './wrap-rule.js';
+
+const emptyTopo = topo('pending-force-clean', {});
+
+export const pendingForceTrail = wrapTopoRule({
+  examples: [
+    {
+      expected: { diagnostics: [] },
+      input: {
+        graph: deriveTopoGraph(emptyTopo),
+        topo: emptyTopo,
+      },
+      name: 'No pending force audit events passes',
+    },
+  ],
+  rule: pendingForce,
+});

package/src/trails/permit-governance.trail.ts

@@ -0,0 +1,51 @@
+import { Result, topo, trail } from '@ontrails/core';
+import { z } from 'zod';
+
+import { permitGovernance } from '../rules/permit-governance.js';
+import { wrapTopoRule } from './wrap-rule.js';
+
+const destroyWithoutPermit = trail('entity.delete', {
+  blaze: () => Result.ok({ ok: true }),
+  input: z.object({}),
+  intent: 'destroy',
+  output: z.object({ ok: z.boolean() }),
+});
+
+const scopedDestroy = trail('entity.delete', {
+  blaze: () => Result.ok({ ok: true }),
+  input: z.object({}),
+  intent: 'destroy',
+  output: z.object({ ok: z.boolean() }),
+  permit: { scopes: ['entity:delete'] },
+});
+
+export const permitGovernanceTrail = wrapTopoRule({
+  examples: [
+    {
+      expected: {
+        diagnostics: [
+          {
+            filePath: '<topo>',
+            line: 1,
+            message:
+              'Trail "entity.delete" has intent \'destroy\' but no permit declaration',
+            rule: 'permit.destroyWithoutPermit',
+            severity: 'error',
+          },
+        ],
+      },
+      input: {
+        topo: topo('trl-377-missing-permit', { destroyWithoutPermit }),
+      },
+      name: 'Destroy trails without permits emit an error',
+    },
+    {
+      expected: { diagnostics: [] },
+      input: {
+        topo: topo('trl-377-scoped-destroy', { scopedDestroy }),
+      },
+      name: 'Scoped destroy permits keep permit governance clean',
+    },
+  ],
+  rule: permitGovernance,
+});

package/src/trails/prefer-schema-inference.trail.ts

@@ -0,0 +1,21 @@
+import { preferSchemaInference } from '../rules/prefer-schema-inference.js';
+import { wrapRule } from './wrap-rule.js';
+
+export const preferSchemaInferenceTrail = wrapRule({
+  examples: [
+    {
+      expected: { diagnostics: [] },
+      input: {
+        filePath: 'clean.ts',
+        sourceCode: `trail("entity.show", {
+  input: z.object({ name: z.string() }),
+  blaze: async (input, ctx) => {
+    return Result.ok({ name: input.name });
+  }
+})`,
+      },
+      name: 'Trail without redundant field overrides',
+    },
+  ],
+  rule: preferSchemaInference,
+});

package/src/trails/public-export-example-coverage.trail.ts

@@ -0,0 +1,16 @@
+import { publicExportExampleCoverage } from '../rules/public-export-example-coverage.js';
+import { wrapRule } from './wrap-rule.js';
+
+export const publicExportExampleCoverageTrail = wrapRule({
+  examples: [
+    {
+      expected: { diagnostics: [] },
+      input: {
+        filePath: 'packages/other-pkg/src/index.ts',
+        sourceCode: `export { somethingElse } from './other.js';\n`,
+      },
+      name: 'Ignores barrels outside the public API example policy',
+    },
+  ],
+  rule: publicExportExampleCoverage,
+});

package/src/trails/public-internal-deep-imports.trail.ts

@@ -0,0 +1,94 @@
+import { publicInternalDeepImports } from '../rules/public-internal-deep-imports.js';
+import { wrapRule } from './wrap-rule.js';
+
+export const publicInternalDeepImportsTrail = wrapRule({
+  examples: [
+    {
+      expected: { diagnostics: [] },
+      input: {
+        filePath: 'packages/store/src/trails/example.ts',
+        importResolutionsByFile: {
+          'packages/store/src/trails/example.ts': [
+            {
+              crossesPackageBoundary: true,
+              importSource: '@ontrails/core/trails',
+              importerPath: 'packages/store/src/trails/example.ts',
+              isInternalTarget: false,
+              line: 1,
+              packageName: '@ontrails/core',
+              packageRoot: 'packages/core',
+              resolvedPath: 'packages/core/src/trails/index.ts',
+              usesPublicExport: true,
+            },
+          ],
+        },
+        knownTrailIds: [],
+        publicWorkspaces: {
+          '@ontrails/core': {
+            hasExports: true,
+            name: '@ontrails/core',
+            packageJsonPath: 'packages/core/package.json',
+            rootDir: 'packages/core',
+          },
+          '@ontrails/store': {
+            hasExports: true,
+            name: '@ontrails/store',
+            packageJsonPath: 'packages/store/package.json',
+            rootDir: 'packages/store',
+          },
+        },
+        sourceCode: `import { deriveTrail } from '@ontrails/core/trails';\n`,
+      },
+      name: 'Allows exported package subpaths',
+    },
+    {
+      expected: {
+        diagnostics: [
+          {
+            filePath: 'packages/store/src/trails/example.ts',
+            line: 1,
+            message:
+              '@ontrails specifier "@ontrails/core/src/internal/hidden" is not exported by @ontrails/core. Use the package root or an exported subpath; if the API is missing, add an owner export follow-up instead of importing internals.',
+            rule: 'public-internal-deep-imports',
+            severity: 'error',
+          },
+        ],
+      },
+      input: {
+        filePath: 'packages/store/src/trails/example.ts',
+        importResolutionsByFile: {
+          'packages/store/src/trails/example.ts': [
+            {
+              crossesPackageBoundary: true,
+              errorKind: 'package-path-not-exported',
+              importSource: '@ontrails/core/src/internal/hidden',
+              importerPath: 'packages/store/src/trails/example.ts',
+              isInternalTarget: false,
+              line: 1,
+              packageName: '@ontrails/core',
+              usesPublicExport: false,
+            },
+          ],
+        },
+        knownTrailIds: [],
+        publicWorkspaces: {
+          '@ontrails/core': {
+            hasExports: true,
+            name: '@ontrails/core',
+            packageJsonPath: 'packages/core/package.json',
+            rootDir: 'packages/core',
+          },
+          '@ontrails/store': {
+            hasExports: true,
+            name: '@ontrails/store',
+            packageJsonPath: 'packages/store/package.json',
+            rootDir: 'packages/store',
+          },
+        },
+        sourceCode: `import { hidden } from '@ontrails/core/src/internal/hidden';\n`,
+      },
+      name: 'Flags compose-package imports into owner internals',
+    },
+  ],
+  rule: publicInternalDeepImports,
+});

package/src/trails/public-output-schema.trail.ts

@@ -0,0 +1,55 @@
+import { Result, topo, trail } from '@ontrails/core';
+import { z } from 'zod';
+
+import { publicOutputSchema } from '../rules/public-output-schema.js';
+import { wrapTopoRule } from './wrap-rule.js';
+
+const cleanTrail = trail('report.read', {
+  blaze: () => Result.ok({ ok: true }),
+  input: z.object({}),
+  output: z.object({ ok: z.boolean() }),
+});
+
+const cleanTopo = topo('public-output-schema-clean', {
+  cleanTrail,
+});
+
+const missingOutputTrail = trail('report.missing', {
+  blaze: () => Result.ok({ ok: true }),
+  input: z.object({}),
+});
+
+const missingOutputTopo = topo('public-output-schema-missing', {
+  missingOutputTrail,
+});
+
+export const publicOutputSchemaTrail = wrapTopoRule({
+  examples: [
+    {
+      expected: { diagnostics: [] },
+      input: {
+        topo: cleanTopo,
+      },
+      name: 'Public surface trails declare output schemas',
+    },
+    {
+      expected: {
+        diagnostics: [
+          {
+            filePath: '<topo>',
+            line: 1,
+            message:
+              'Trail "report.missing" is visible to public MCP/HTTP surface projection but does not declare an output schema. Add an explicit output schema, or mark the trail visibility as internal if it is composition-only.',
+            rule: 'public-output-schema',
+            severity: 'error',
+          },
+        ],
+      },
+      input: {
+        topo: missingOutputTopo,
+      },
+      name: 'Public surface trails without output schemas are flagged',
+    },
+  ],
+  rule: publicOutputSchema,
+});

package/src/trails/public-union-output-discriminants.trail.ts

@@ -0,0 +1,33 @@
+import { Result, topo, trail } from '@ontrails/core';
+import { z } from 'zod';
+
+import { publicUnionOutputDiscriminants } from '../rules/public-union-output-discriminants.js';
+import { wrapTopoRule } from './wrap-rule.js';
+
+const cleanOutput = z.discriminatedUnion('kind', [
+  z.object({ kind: z.literal('message'), message: z.string() }),
+  z.object({ count: z.number(), kind: z.literal('count') }),
+]);
+
+const cleanTrail = trail('report.read', {
+  blaze: () => Result.ok({ kind: 'message' as const, message: 'ok' }),
+  input: z.object({}),
+  output: cleanOutput,
+});
+
+const cleanTopo = topo('public-union-output-discriminants-clean', {
+  cleanTrail,
+});
+
+export const publicUnionOutputDiscriminantsTrail = wrapTopoRule({
+  examples: [
+    {
+      expected: { diagnostics: [] },
+      input: {
+        topo: cleanTopo,
+      },
+      name: 'Public output object unions expose a literal discriminator',
+    },
+  ],
+  rule: publicUnionOutputDiscriminants,
+});

package/src/trails/read-intent-fires.trail.ts

@@ -0,0 +1,20 @@
+import { readIntentFires } from '../rules/read-intent-fires.js';
+import { wrapRule } from './wrap-rule.js';
+
+export const readIntentFiresTrail = wrapRule({
+  examples: [
+    {
+      expected: { diagnostics: [] },
+      input: {
+        filePath: 'clean.ts',
+        sourceCode: `const entityLoaded = signal('entity.loaded', { payload: z.object({}) });
+trail('entity.read', {
+  intent: 'read',
+  blaze: async () => Result.ok({}),
+});`,
+      },
+      name: 'Read trails without fires stay quiet',
+    },
+  ],
+  rule: readIntentFires,
+});

package/src/trails/reference-exists.trail.ts

@@ -0,0 +1,25 @@
+import { referenceExists } from '../rules/reference-exists.js';
+import { wrapRule } from './wrap-rule.js';
+
+export const referenceExistsTrail = wrapRule({
+  examples: [
+    {
+      expected: { diagnostics: [] },
+      input: {
+        filePath: 'contours.ts',
+        knownContourIds: ['gist', 'user'],
+        knownTrailIds: [],
+        sourceCode: `const user = contour("user", {
+  id: z.string().uuid(),
+}, { identity: "id" });
+
+const gist = contour("gist", {
+  id: z.string().uuid(),
+  ownerId: user.id(),
+}, { identity: "id" });`,
+      },
+      name: 'Contour references resolve to known project contours',
+    },
+  ],
+  rule: referenceExists,
+});

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: 'Compose-package imports must use exported package subpaths',
+    },
+    {
+      expected: {
+        diagnostics: [
+          {
+            filePath: 'packages/app/src/index.ts',
+            line: 1,
+            message:
+              'Local import "../../core/src/public" composes 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 compose 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: 'Compose-package imports must not target internals',
+    },
+  ],
+  rule: resolvedImportBoundary,
+});

package/src/trails/resource-declarations.trail.ts

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

package/src/trails/resource-exists.trail.ts

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