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

package/src/trails/incomplete-accessor-for-standard-op.trail.ts

@@ -0,0 +1,76 @@
+import { resource, Result, topo, trail } from '@ontrails/core';
+import { z } from 'zod';
+
+import { incompleteAccessorForStandardOp } from '../rules/incomplete-accessor-for-standard-op.js';
+import { wrapTopoRule } from './wrap-rule.js';
+
+type Accessor = Readonly<Record<string, (...args: unknown[]) => unknown>>;
+type Connection = Readonly<Record<string, Accessor>>;
+
+const noop = (): undefined => undefined;
+
+const buildResource = (id: string, contourName: string, accessor: Accessor) =>
+  resource<Connection>(id, {
+    create: () => Result.ok({ [contourName]: accessor }),
+    mock: () => ({ [contourName]: accessor }),
+  });
+
+const buildCrudTrail = (
+  trailId: string,
+  resourceValue: ReturnType<typeof buildResource>
+) =>
+  trail(trailId, {
+    blaze: () => Result.ok({ ok: true }),
+    input: z.object({}),
+    output: z.object({ ok: z.boolean() }),
+    pattern: 'crud',
+    resources: [resourceValue],
+  });
+
+const cleanResource = buildResource('store.note.clean', 'note', {
+  insert: noop,
+});
+const warningResource = buildResource('store.note.warn', 'note', {
+  upsert: noop,
+});
+
+const cleanTopo = topo('trl-269-clean', {
+  noteCreate: buildCrudTrail('note.create', cleanResource),
+  noteResource: cleanResource,
+});
+
+const warningTopo = topo('trl-269-warning', {
+  noteCreate: buildCrudTrail('note.create', warningResource),
+  noteResource: warningResource,
+});
+
+export const incompleteAccessorForStandardOpTrail = wrapTopoRule({
+  examples: [
+    {
+      expected: { diagnostics: [] },
+      input: {
+        topo: cleanTopo,
+      },
+      name: 'Preferred accessors keep CRUD trails quiet',
+    },
+    {
+      expected: {
+        diagnostics: [
+          {
+            filePath: '<topo>',
+            line: 1,
+            message:
+              'Trail "note.create" (crud.create): resource "store.note.warn" accessor "note" is missing preferred method "insert"; falls back to "upsert"',
+            rule: 'incomplete-accessor-for-standard-op',
+            severity: 'warn',
+          },
+        ],
+      },
+      input: {
+        topo: warningTopo,
+      },
+      name: 'Fallback-only create accessors emit a warning',
+    },
+  ],
+  rule: incompleteAccessorForStandardOp,
+});

package/src/trails/incomplete-crud.trail.ts

@@ -0,0 +1,39 @@
+import { incompleteCrud } from '../rules/incomplete-crud.js';
+import { wrapRule } from './wrap-rule.js';
+
+export const incompleteCrudTrail = wrapRule({
+  examples: [
+    {
+      expected: { diagnostics: [] },
+      input: {
+        filePath: 'clean.ts',
+        sourceCode: `import { Result, resource } from '@ontrails/core';
+import { store } from '@ontrails/store';
+import { crud } from '@ontrails/store/trails';
+import { z } from 'zod';
+
+const db = store({
+  notes: {
+    identity: 'id',
+    schema: z.object({
+      id: z.string(),
+      title: z.string(),
+    }),
+  },
+});
+
+const notesResource = resource('db.notes', {
+  create: () => Result.ok({}),
+  mock: () => ({}),
+});
+
+const [createNote, readNote, updateNote, deleteNote, listNote] = crud(
+  db.tables.notes,
+  notesResource
+);`,
+      },
+      name: 'Full CRUD coverage stays quiet',
+    },
+  ],
+  rule: incompleteCrud,
+});

package/src/trails/index.ts

@@ -0,0 +1,78 @@
+export { activationOrphanTrail } from './activation-orphan.trail.js';
+export { circularRefsTrail } from './circular-refs.trail.js';
+export { contourExistsTrail } from './contour-exists.trail.js';
+export { contextNoSurfaceTypesTrail } from './context-no-surface-types.trail.js';
+export { composesDeclarationsTrail } from './composes-declarations.trail.js';
+export { deadInternalTrailTrail } from './dead-internal-trail.trail.js';
+export { deprecationWithoutGuidanceTrail } from './deprecation-without-guidance.trail.js';
+export { draftFileMarkingTrail } from './draft-file-marking.trail.js';
+export { draftVisibleDebtTrail } from './draft-visible-debt.trail.js';
+export { errorMappingCompletenessTrail } from './error-mapping-completeness.trail.js';
+export { exampleValidTrail } from './example-valid.trail.js';
+export { firesDeclarationsTrail } from './fires-declarations.trail.js';
+export { forkWithoutPreservedBlazeTrail } from './fork-without-preserved-blaze.trail.js';
+export { implementationReturnsResultTrail } from './implementation-returns-result.trail.js';
+export { incompleteAccessorForStandardOpTrail } from './incomplete-accessor-for-standard-op.trail.js';
+export { incompleteCrudTrail } from './incomplete-crud.trail.js';
+export { intentPropagationTrail } from './intent-propagation.trail.js';
+export { layerFieldNameDriftTrail } from './layer-field-name-drift.trail.js';
+export { markerSchemaUnsupportedTrail } from './marker-schema-unsupported.trail.js';
+export { missingVisibilityTrail } from './missing-visibility.trail.js';
+export { missingReconcileTrail } from './missing-reconcile.trail.js';
+export { onReferencesExistTrail } from './on-references-exist.trail.js';
+export { noDevPermitInSourceTrail } from './no-dev-permit-in-source.trail.js';
+export { noDestructuredComposeTrail } from './no-destructured-compose.trail.js';
+export { noLegacyLayerImportsTrail } from './no-legacy-layer-imports.trail.js';
+export { noDirectImplementationCallTrail } from './no-direct-implementation-call.trail.js';
+export { noNativeErrorResultTrail } from './no-native-error-result.trail.js';
+export { noRedundantResultErrorWrapTrail } from './no-redundant-result-error-wrap.trail.js';
+export { noRetiredCrossVocabularyTrail } from './no-retired-cross-vocabulary.trail.js';
+export { noSyncResultAssumptionTrail } from './no-sync-result-assumption.trail.js';
+export { noThrowInDetourRecoverTrail } from './no-throw-in-detour-recover.trail.js';
+export { noThrowInImplementationTrail } from './no-throw-in-implementation.trail.js';
+export { noTopLevelSurfaceTrail } from './no-top-level-surface.trail.js';
+export { orphanedSignalTrail } from './orphaned-signal.trail.js';
+export { ownerProjectionParityTrail } from './owner-projection-parity.trail.js';
+export { pendingForceTrail } from './pending-force.trail.js';
+export { permitGovernanceTrail } from './permit-governance.trail.js';
+export { preferSchemaInferenceTrail } from './prefer-schema-inference.trail.js';
+export { publicExportExampleCoverageTrail } from './public-export-example-coverage.trail.js';
+export { publicInternalDeepImportsTrail } from './public-internal-deep-imports.trail.js';
+export { publicOutputSchemaTrail } from './public-output-schema.trail.js';
+export { publicUnionOutputDiscriminantsTrail } from './public-union-output-discriminants.trail.js';
+export { readIntentFiresTrail } from './read-intent-fires.trail.js';
+export { referenceExistsTrail } from './reference-exists.trail.js';
+export { resolvedImportBoundaryTrail } from './resolved-import-boundary.trail.js';
+export { resourceDeclarationsTrail } from './resource-declarations.trail.js';
+export { resourceIdGrammarTrail } from './resource-id-grammar.trail.js';
+export { resourceExistsTrail } from './resource-exists.trail.js';
+export { resourceMockCoverageTrail } from './resource-mock-coverage.trail.js';
+export { scheduledDestroyIntentTrail } from './scheduled-destroy-intent.trail.js';
+export { signalGraphCoachingTrail } from './signal-graph-coaching.trail.js';
+export { staticResourceAccessorPreferenceTrail } from './static-resource-accessor-preference.trail.js';
+export { surfaceFacetCoherenceTrail } from './surface-facet-coherence.trail.js';
+export { unmaterializedActivationSourceTrail } from './unmaterialized-activation-source.trail.js';
+export { unreachableDetourShadowingTrail } from './unreachable-detour-shadowing.trail.js';
+export { validDetourContractTrail } from './valid-detour-contract.trail.js';
+export { validDescribeRefsTrail } from './valid-describe-refs.trail.js';
+export { versionGapTrail } from './version-gap.trail.js';
+export { versionPinnedComposeTrail } from './version-pinned-compose.trail.js';
+export { versionWithoutExamplesTrail } from './version-without-examples.trail.js';
+export { wardenExportSymmetryTrail } from './warden-export-symmetry.trail.js';
+export { wardenRulesUseAstTrail } from './warden-rules-use-ast.trail.js';
+export { webhookRouteCollisionTrail } from './webhook-route-collision.trail.js';
+
+export {
+  diagnosticSchema,
+  projectAwareRuleInput,
+  ruleInput,
+  ruleOutput,
+  topoAwareRuleInput,
+} from './schema.js';
+export type {
+  ProjectAwareRuleInput,
+  RuleInput,
+  RuleOutput,
+  TopoAwareRuleInput,
+} from './schema.js';
+export { wrapRule, wrapTopoRule } from './wrap-rule.js';

package/src/trails/intent-propagation.trail.ts

@@ -0,0 +1,30 @@
+import { intentPropagation } from '../rules/intent-propagation.js';
+import { wrapRule } from './wrap-rule.js';
+
+export const intentPropagationTrail = wrapRule({
+  examples: [
+    {
+      expected: { diagnostics: [] },
+      input: {
+        filePath: 'clean.ts',
+        knownTrailIds: ['entity.read', 'entity.lookup'],
+        sourceCode: `trail('entity.read', {
+  intent: 'read',
+  composes: ['entity.lookup'],
+  blaze: async (_input, ctx) => ctx.compose('entity.lookup', {}),
+});
+
+trail('entity.lookup', {
+  intent: 'read',
+  blaze: async () => Result.ok({}),
+});`,
+        trailIntentsById: {
+          'entity.lookup': 'read',
+          'entity.read': 'read',
+        },
+      },
+      name: 'Read trails may compose other read trails',
+    },
+  ],
+  rule: intentPropagation,
+});

package/src/trails/layer-field-name-drift.trail.ts

@@ -0,0 +1,39 @@
+import { layerFieldNameDrift } from '../rules/layer-field-name-drift.js';
+import { wrapRule } from './wrap-rule.js';
+
+export const layerFieldNameDriftTrail = wrapRule({
+  examples: [
+    {
+      expected: { diagnostics: [] },
+      input: {
+        filePath: 'packages/cli/src/build.ts',
+        sourceCode: `import { LAYER_FIELD_RESERVED_NAMES } from '@ontrails/core';
+
+const collides = LAYER_FIELD_RESERVED_NAMES.has('all');
+`,
+      },
+      name: 'Allows shared core reserved-name set',
+    },
+    {
+      expected: {
+        diagnostics: [
+          {
+            filePath: 'packages/cli/src/build.ts',
+            line: 1,
+            message:
+              'layer-field-name-drift: surface-local reserved name set "META_FLAG_CANDIDATES" can make layer input fields project differently across surfaces. Import LAYER_FIELD_RESERVED_NAMES from @ontrails/core instead.',
+            rule: 'layer-field-name-drift',
+            severity: 'error',
+          },
+        ],
+      },
+      input: {
+        filePath: 'packages/cli/src/build.ts',
+        sourceCode: `const META_FLAG_CANDIDATES = new Set(['all']);
+`,
+      },
+      name: 'Flags surface-local reserved-name sets',
+    },
+  ],
+  rule: layerFieldNameDrift,
+});

package/src/trails/marker-schema-unsupported.trail.ts

@@ -0,0 +1,23 @@
+import { markerSchemaUnsupported } from '../rules/trail-versioning-source.js';
+import { wrapRule } from './wrap-rule.js';
+
+export const markerSchemaUnsupportedTrail = wrapRule({
+  examples: [
+    {
+      expected: { diagnostics: [] },
+      input: {
+        filePath: 'src/trails/versioned.ts',
+        sourceCode: `
+trail('versioned.schema', {
+  version: 2,
+  input: z.object({ name: z.string() }),
+  output: z.object({ message: z.string() }),
+  blaze: async () => Result.ok({ message: 'ok' }),
+});
+`,
+      },
+      name: 'Stable marker-compatible schemas pass',
+    },
+  ],
+  rule: markerSchemaUnsupported,
+});

package/src/trails/missing-reconcile.trail.ts

@@ -0,0 +1,33 @@
+import { missingReconcile } from '../rules/missing-reconcile.js';
+import { wrapRule } from './wrap-rule.js';
+
+export const missingReconcileTrail = 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.reconcile'],
+        reconcileTableIds: ['definition:notes'],
+        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(),
+    }),
+    versioned: true,
+  },
+});`,
+      },
+      name: 'Versioned CRUD tables stay clean when reconcile exists',
+    },
+  ],
+  rule: missingReconcile,
+});

package/src/trails/missing-visibility.trail.ts

@@ -0,0 +1,22 @@
+import { missingVisibility } from '../rules/missing-visibility.js';
+import { wrapRule } from './wrap-rule.js';
+
+export const missingVisibilityTrail = wrapRule({
+  examples: [
+    {
+      expected: { diagnostics: [] },
+      input: {
+        composeTargetTrailIds: ['entity.resolve'],
+        filePath: 'clean.ts',
+        knownTrailIds: ['entity.resolve'],
+        sourceCode: `trail('entity.resolve', {
+  visibility: 'internal',
+  composeInput: z.object({ forkedFrom: z.string() }),
+  blaze: async () => Result.ok({}),
+});`,
+      },
+      name: 'Composition-only trails stay quiet when already internal',
+    },
+  ],
+  rule: missingVisibility,
+});

package/src/trails/no-destructured-compose.trail.ts

@@ -0,0 +1,44 @@
+import { noDestructuredCompose } from '../rules/no-destructured-compose.js';
+import { wrapRule } from './wrap-rule.js';
+
+export const noDestructuredComposeTrail = wrapRule({
+  examples: [
+    {
+      expected: { diagnostics: [] },
+      input: {
+        filePath: 'clean.ts',
+        sourceCode: `trail("entity.onboard", {
+  composes: ["entity.create"],
+  blaze: async (input, ctx) => ctx.compose("entity.create", input),
+});`,
+      },
+      name: 'Clean blaze using ctx.compose directly',
+    },
+    {
+      expected: {
+        diagnostics: [
+          {
+            filePath: 'destructured.ts',
+            line: 4,
+            message:
+              'Trail "entity.onboard" destructures compose from the blaze context. Use ctx.compose(...) directly so composition stays visible and Warden can recognize composed Result values.',
+            rule: 'no-destructured-compose',
+            severity: 'warn',
+          },
+        ],
+      },
+      input: {
+        filePath: 'destructured.ts',
+        sourceCode: `trail("entity.onboard", {
+  composes: ["entity.create"],
+  blaze: async (input, ctx) => {
+    const { compose } = ctx;
+    return compose("entity.create", input);
+  },
+});`,
+      },
+      name: 'Warns when compose is destructured from the blaze context',
+    },
+  ],
+  rule: noDestructuredCompose,
+});

package/src/trails/no-dev-permit-in-source.trail.ts

@@ -0,0 +1,16 @@
+import { noDevPermitInSource } from '../rules/no-dev-permit-in-source.js';
+import { wrapRule } from './wrap-rule.js';
+
+export const noDevPermitInSourceTrail = wrapRule({
+  examples: [
+    {
+      expected: { diagnostics: [] },
+      input: {
+        filePath: 'apps/example/src/cli.ts',
+        sourceCode: `import { tokenPreset } from '@ontrails/cli';\n`,
+      },
+      name: 'Source files without --dev-permit are clean',
+    },
+  ],
+  rule: noDevPermitInSource,
+});

package/src/trails/no-direct-implementation-call.trail.ts

@@ -0,0 +1,16 @@
+import { noDirectImplementationCall } from '../rules/no-direct-implementation-call.js';
+import { wrapRule } from './wrap-rule.js';
+
+export const noDirectImplementationCallTrail = wrapRule({
+  examples: [
+    {
+      expected: { diagnostics: [] },
+      input: {
+        filePath: 'clean.ts',
+        sourceCode: `const data = await ctx.compose("entity.show", { id: "1" });`,
+      },
+      name: 'Clean code using ctx.compose instead of .blaze()',
+    },
+  ],
+  rule: noDirectImplementationCall,
+});

package/src/trails/no-legacy-layer-imports.trail.ts

@@ -0,0 +1,41 @@
+import { noLegacyLayerImports } from '../rules/no-legacy-layer-imports.js';
+import { wrapRule } from './wrap-rule.js';
+
+export const noLegacyLayerImportsTrail = wrapRule({
+  examples: [
+    {
+      expected: { diagnostics: [] },
+      input: {
+        filePath: 'apps/example/src/cli.ts',
+        sourceCode: `import { tokenPreset } from '@ontrails/cli';\n`,
+      },
+      name: 'Source files without legacy layer references are clean',
+    },
+    {
+      expected: {
+        diagnostics: [
+          {
+            filePath: 'apps/example/src/cli.ts',
+            fix: {
+              class: 'term-rewrite',
+              reason:
+                "Legacy layer 'authLayer' was removed in TRL-475; Permit enforcement is intrinsic to executeTrail. Removal has no mechanical replacement, so it needs human migration.",
+              safety: 'review',
+            },
+            line: 1,
+            message:
+              "Legacy layer 'authLayer' was removed in TRL-475. Permit enforcement is intrinsic to executeTrail. See docs/adr/0043-layer-evolution.md.",
+            rule: 'no-legacy-layer-imports',
+            severity: 'error',
+          },
+        ],
+      },
+      input: {
+        filePath: 'apps/example/src/cli.ts',
+        sourceCode: `import { authLayer } from '@ontrails/permits';\n`,
+      },
+      name: 'Legacy layer imports produce migration diagnostics',
+    },
+  ],
+  rule: noLegacyLayerImports,
+});

package/src/trails/no-native-error-result.trail.ts

@@ -0,0 +1,18 @@
+import { noNativeErrorResult } from '../rules/no-native-error-result.js';
+import { wrapRule } from './wrap-rule.js';
+
+export const noNativeErrorResultTrail = wrapRule({
+  examples: [
+    {
+      expected: { diagnostics: [] },
+      input: {
+        filePath: 'entity.ts',
+        sourceCode: `import { InternalError, Result } from "@ontrails/core";
+
+export const load = () => Result.err(new InternalError("failed"));`,
+      },
+      name: 'Specific TrailsError subclasses stay clean',
+    },
+  ],
+  rule: noNativeErrorResult,
+});

package/src/trails/no-redundant-result-error-wrap.trail.ts

@@ -0,0 +1,55 @@
+import { noRedundantResultErrorWrap } from '../rules/no-redundant-result-error-wrap.js';
+import { wrapRule } from './wrap-rule.js';
+
+export const noRedundantResultErrorWrapTrail = wrapRule({
+  examples: [
+    {
+      expected: { diagnostics: [] },
+      input: {
+        filePath: 'entity.ts',
+        sourceCode: `import { Result, trail } from "@ontrails/core";
+
+trail("entity.load", {
+  blaze: async (input, ctx) => {
+    const loaded = await ctx.compose("entity.fetch", input);
+    if (loaded.isErr()) {
+      return loaded;
+    }
+    return Result.ok(loaded.value);
+  },
+});`,
+      },
+      name: 'Existing Result values pass through directly',
+    },
+    {
+      expected: {
+        diagnostics: [
+          {
+            filePath: 'entity.ts',
+            line: 7,
+            message:
+              'Trail "entity.load": Result.err(loaded.error) re-wraps a Result that already carries that error. Return loaded directly to preserve the original Result boundary.',
+            rule: 'no-redundant-result-error-wrap',
+            severity: 'warn',
+          },
+        ],
+      },
+      input: {
+        filePath: 'entity.ts',
+        sourceCode: `import { Result, trail } from "@ontrails/core";
+
+trail("entity.load", {
+  blaze: async (input, ctx) => {
+    const loaded = await ctx.compose("entity.fetch", input);
+    if (loaded.isErr()) {
+      return Result.err(loaded.error);
+    }
+    return Result.ok(loaded.value);
+  },
+});`,
+      },
+      name: 'Warns when an existing Result error is re-wrapped',
+    },
+  ],
+  rule: noRedundantResultErrorWrap,
+});

package/src/trails/no-retired-cross-vocabulary.trail.ts

@@ -0,0 +1,42 @@
+import { noRetiredCrossVocabulary } from '../rules/no-retired-cross-vocabulary.js';
+import { wrapRule } from './wrap-rule.js';
+
+export const noRetiredCrossVocabularyTrail = wrapRule({
+  examples: [
+    {
+      expected: { diagnostics: [] },
+      input: {
+        filePath: 'apps/example/src/trails/play.ts',
+        sourceCode: 'export const play = trail("play", { composes: [] });\n',
+      },
+      name: 'Source files using compose vocabulary are clean',
+    },
+    {
+      expected: {
+        diagnostics: [
+          {
+            filePath: 'apps/example/src/trails/play.ts',
+            fix: {
+              class: 'term-rewrite',
+              edits: [{ end: 43, replacement: 'composes', start: 36 }],
+              reason:
+                "Retired composition vocabulary 'crosses' has a mechanical beta.19 replacement 'composes'.",
+              safety: 'safe',
+            },
+            line: 1,
+            message:
+              "Retired composition vocabulary 'crosses' should be 'composes' after the beta.19 compose cutover.",
+            rule: 'no-retired-cross-vocabulary',
+            severity: 'error',
+          },
+        ],
+      },
+      input: {
+        filePath: 'apps/example/src/trails/play.ts',
+        sourceCode: 'export const play = trail("play", { crosses: [] });\n',
+      },
+      name: 'Retired crosses declarations produce safe migration diagnostics',
+    },
+  ],
+  rule: noRetiredCrossVocabulary,
+});

package/src/trails/no-sync-result-assumption.trail.ts

@@ -0,0 +1,19 @@
+import { noSyncResultAssumption } from '../rules/no-sync-result-assumption.js';
+import { wrapRule } from './wrap-rule.js';
+
+export const noSyncResultAssumptionTrail = wrapRule({
+  examples: [
+    {
+      expected: { diagnostics: [] },
+      input: {
+        filePath: 'clean.ts',
+        sourceCode: `const result = await myTrail.blaze(input, ctx);
+if (result.isOk()) {
+  console.log(result.value);
+}`,
+      },
+      name: 'Properly awaited .blaze() call',
+    },
+  ],
+  rule: noSyncResultAssumption,
+});

package/src/trails/no-throw-in-detour-recover.trail.ts

@@ -0,0 +1,24 @@
+import { noThrowInDetourRecover } from '../rules/no-throw-in-detour-recover.js';
+import { wrapRule } from './wrap-rule.js';
+
+export const noThrowInDetourRecoverTrail = wrapRule({
+  examples: [
+    {
+      expected: { diagnostics: [] },
+      input: {
+        filePath: 'clean.ts',
+        sourceCode: `trail("entity.save", {
+  detours: [
+    {
+      on: ConflictError,
+      recover: async () => Result.ok({ recovered: true }),
+    },
+  ],
+  blaze: () => Result.err(new ConflictError("conflict")),
+})`,
+      },
+      name: 'Detour recover without throw',
+    },
+  ],
+  rule: noThrowInDetourRecover,
+});

package/src/trails/no-throw-in-implementation.trail.ts

@@ -0,0 +1,20 @@
+import { noThrowInImplementation } from '../rules/no-throw-in-implementation.js';
+import { wrapRule } from './wrap-rule.js';
+
+export const noThrowInImplementationTrail = wrapRule({
+  examples: [
+    {
+      expected: { diagnostics: [] },
+      input: {
+        filePath: 'clean.ts',
+        sourceCode: `trail("entity.show", {
+  blaze: async (input, ctx) => {
+    return Result.ok({ name: "test" });
+  }
+})`,
+      },
+      name: 'Clean implementation without throw',
+    },
+  ],
+  rule: noThrowInImplementation,
+});