@ontrails/warden 1.0.0-beta.13 → 1.0.0-beta.15

package/src/trails/circular-refs.trail.ts

@@ -0,0 +1,29 @@
+import { circularRefs } from '../rules/circular-refs.js';
+import { wrapRule } from './wrap-rule.js';
+
+export const circularRefsTrail = wrapRule({
+  examples: [
+    {
+      expected: { diagnostics: [] },
+      input: {
+        contourReferencesByName: {
+          gist: ['user'],
+          user: [],
+        },
+        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: 'Acyclic contour references stay clean',
+    },
+  ],
+  rule: circularRefs,
+});

package/src/trails/{context-no-trailhead-types.trail.ts → context-no-surface-types.trail.ts}

@@ -1,7 +1,7 @@
-import { contextNoTrailheadTypes } from '../rules/context-no-trailhead-types.js';
+import { contextNoSurfaceTypes } from '../rules/context-no-surface-types.js';
 import { wrapRule } from './wrap-rule.js';
 
-export const contextNoTrailheadTypesTrail = wrapRule({
+export const contextNoSurfaceTypesTrail = wrapRule({
   examples: [
     {
       expected: { diagnostics: [] },
@@ -14,8 +14,8 @@ trail("entity.show", {
   }
 })`,
       },
-      name: 'Clean trail without trailhead imports',
+      name: 'Clean trail without surface imports',
     },
   ],
-  rule: contextNoTrailheadTypes,
+  rule: contextNoSurfaceTypes,
 });

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

@@ -0,0 +1,21 @@
+import { contourExists } from '../rules/contour-exists.js';
+import { wrapRule } from './wrap-rule.js';
+
+export const contourExistsTrail = wrapRule({
+  examples: [
+    {
+      expected: { diagnostics: [] },
+      input: {
+        filePath: 'entity.ts',
+        knownContourIds: ['user'],
+        knownTrailIds: ['user.create'],
+        sourceCode: `trail("user.create", {
+  contours: [user],
+  blaze: async (input, ctx) => Result.ok({ ok: true }),
+})`,
+      },
+      name: 'Declared contours resolve to known project contours',
+    },
+  ],
+  rule: contourExists,
+});

package/src/trails/dead-internal-trail.trail.ts

@@ -0,0 +1,26 @@
+import { deadInternalTrail } from '../rules/dead-internal-trail.js';
+import { wrapRule } from './wrap-rule.js';
+
+export const deadInternalTrailTrail = wrapRule({
+  examples: [
+    {
+      expected: { diagnostics: [] },
+      input: {
+        crossTargetTrailIds: ['entity.sync'],
+        filePath: 'clean.ts',
+        knownTrailIds: ['entity.public', 'entity.sync'],
+        sourceCode: `trail('entity.public', {
+  crosses: ['entity.sync'],
+  blaze: async (_input, ctx) => ctx.cross('entity.sync', {}),
+});
+
+trail('entity.sync', {
+  visibility: 'internal',
+  blaze: async () => Result.ok({}),
+});`,
+      },
+      name: 'Internal trails stay clean when another trail crosses them',
+    },
+  ],
+  rule: deadInternalTrail,
+});

package/src/trails/draft-file-marking.trail.ts

@@ -0,0 +1,16 @@
+import { draftFileMarking } from '../rules/draft-file-marking.js';
+import { wrapRule } from './wrap-rule.js';
+
+export const draftFileMarkingTrail = wrapRule({
+  examples: [
+    {
+      expected: { diagnostics: [] },
+      input: {
+        filePath: 'clean.ts',
+        sourceCode: `export const id = "notes.list";`,
+      },
+      name: 'File without draft ids passes',
+    },
+  ],
+  rule: draftFileMarking,
+});

package/src/trails/draft-visible-debt.trail.ts

@@ -0,0 +1,16 @@
+import { draftVisibleDebt } from '../rules/draft-visible-debt.js';
+import { wrapRule } from './wrap-rule.js';
+
+export const draftVisibleDebtTrail = wrapRule({
+  examples: [
+    {
+      expected: { diagnostics: [] },
+      input: {
+        filePath: 'clean.ts',
+        sourceCode: `export const id = "notes.list";`,
+      },
+      name: 'File without draft ids emits no visible-debt diagnostics',
+    },
+  ],
+  rule: draftVisibleDebt,
+});

package/src/trails/error-mapping-completeness.trail.ts

@@ -0,0 +1,29 @@
+import { errorMappingCompleteness } from '../rules/error-mapping-completeness.js';
+import { wrapRule } from './wrap-rule.js';
+
+export const errorMappingCompletenessTrail = wrapRule({
+  examples: [
+    {
+      expected: { diagnostics: [] },
+      input: {
+        filePath: 'transport-error-map.ts',
+        sourceCode: `import { createTransportErrorMapper } from "@ontrails/core";
+
+const cliMapper = createTransportErrorMapper({
+  auth: 9,
+  cancelled: 130,
+  conflict: 3,
+  internal: 8,
+  network: 7,
+  not_found: 2,
+  permission: 4,
+  rate_limit: 6,
+  timeout: 5,
+  validation: 1,
+});`,
+      },
+      name: 'Complete transport error mapper',
+    },
+  ],
+  rule: errorMappingCompleteness,
+});

package/src/trails/example-valid.trail.ts

@@ -0,0 +1,25 @@
+import { exampleValid } from '../rules/example-valid.js';
+import { wrapRule } from './wrap-rule.js';
+
+export const exampleValidTrail = wrapRule({
+  examples: [
+    {
+      expected: { diagnostics: [] },
+      input: {
+        filePath: 'contours.ts',
+        sourceCode: `const user = contour("user", {
+  id: z.string().uuid(),
+  name: z.string(),
+}, {
+  examples: [{
+    id: "550e8400-e29b-41d4-a716-446655440000",
+    name: "Ada",
+  }],
+  identity: "id",
+});`,
+      },
+      name: 'Contour examples validate against their schema',
+    },
+  ],
+  rule: exampleValid,
+});

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

@@ -0,0 +1,22 @@
+import { firesDeclarations } from '../rules/fires-declarations.js';
+import { wrapRule } from './wrap-rule.js';
+
+export const firesDeclarationsTrail = wrapRule({
+  examples: [
+    {
+      expected: { diagnostics: [] },
+      input: {
+        filePath: 'clean.ts',
+        sourceCode: `trail("entity.onboard", {
+  fires: ["entity.created"],
+  blaze: async (input, ctx) => {
+    await ctx.fire("entity.created", { id: input.id });
+    return Result.ok({});
+  }
+})`,
+      },
+      name: 'Matched fires declarations and calls',
+    },
+  ],
+  rule: firesDeclarations,
+});

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

@@ -1,16 +1,49 @@
-export { contextNoTrailheadTypesTrail } from './context-no-trailhead-types.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 { crossDeclarationsTrail } from './cross-declarations.trail.js';
+export { deadInternalTrailTrail } from './dead-internal-trail.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 { 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 { missingVisibilityTrail } from './missing-visibility.trail.js';
+export { missingReconcileTrail } from './missing-reconcile.trail.js';
+export { onReferencesExistTrail } from './on-references-exist.trail.js';
 export { noDirectImplInRouteTrail } from './no-direct-impl-in-route.trail.js';
 export { noDirectImplementationCallTrail } from './no-direct-implementation-call.trail.js';
 export { noSyncResultAssumptionTrail } from './no-sync-result-assumption.trail.js';
-export { noThrowInDetourTargetTrail } from './no-throw-in-detour-target.trail.js';
+export { noThrowInDetourRecoverTrail } from './no-throw-in-detour-recover.trail.js';
 export { noThrowInImplementationTrail } from './no-throw-in-implementation.trail.js';
+export { orphanedSignalTrail } from './orphaned-signal.trail.js';
+export { permitGovernanceTrail } from './permit-governance.trail.js';
 export { preferSchemaInferenceTrail } from './prefer-schema-inference.trail.js';
-export { provisionDeclarationsTrail } from './provision-declarations.trail.js';
-export { provisionExistsTrail } from './provision-exists.trail.js';
+export { referenceExistsTrail } from './reference-exists.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 { unreachableDetourShadowingTrail } from './unreachable-detour-shadowing.trail.js';
+export { validDetourContractTrail } from './valid-detour-contract.trail.js';
 export { validDescribeRefsTrail } from './valid-describe-refs.trail.js';
-export { validDetourRefsTrail } from './valid-detour-refs.trail.js';
+export { wardenExportSymmetryTrail } from './warden-export-symmetry.trail.js';
+export { wardenRulesUseAstTrail } from './warden-rules-use-ast.trail.js';
 
-export { ruleInput, ruleOutput, diagnosticSchema } from './schema.js';
-export type { RuleInput, RuleOutput } from './schema.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',
+  crosses: ['entity.lookup'],
+  blaze: async (_input, ctx) => ctx.cross('entity.lookup', {}),
+});
+
+trail('entity.lookup', {
+  intent: 'read',
+  blaze: async () => Result.ok({}),
+});`,
+        trailIntentsById: {
+          'entity.lookup': 'read',
+          'entity.read': 'read',
+        },
+      },
+      name: 'Read trails may cross other read trails',
+    },
+  ],
+  rule: intentPropagation,
+});

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: {
+        crossTargetTrailIds: ['entity.resolve'],
+        filePath: 'clean.ts',
+        knownTrailIds: ['entity.resolve'],
+        sourceCode: `trail('entity.resolve', {
+  visibility: 'internal',
+  crossInput: z.object({ forkedFrom: z.string() }),
+  blaze: async () => Result.ok({}),
+});`,
+      },
+      name: 'Composition-only trails stay quiet when already internal',
+    },
+  ],
+  rule: missingVisibility,
+});

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/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 listeners exist',
+    },
+  ],
+  rule: orphanedSignal,
+});

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/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/{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,
 });