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

package/src/rules/index.ts

@@ -1,38 +1,79 @@
-import { contextNoTrailheadTypes } from './context-no-trailhead-types.js';
+import { circularRefs } from './circular-refs.js';
+import { contourExists } from './contour-exists.js';
+import { contextNoSurfaceTypes } from './context-no-surface-types.js';
 import { crossDeclarations } from './cross-declarations.js';
+import { deadInternalTrail } from './dead-internal-trail.js';
+import { draftFileMarking } from './draft-file-marking.js';
+import { draftVisibleDebt } from './draft-visible-debt.js';
+import { errorMappingCompleteness } from './error-mapping-completeness.js';
+import { exampleValid } from './example-valid.js';
+import { firesDeclarations } from './fires-declarations.js';
 import { implementationReturnsResult } from './implementation-returns-result.js';
+import { incompleteAccessorForStandardOp } from './incomplete-accessor-for-standard-op.js';
+import { incompleteCrud } from './incomplete-crud.js';
+import { intentPropagation } from './intent-propagation.js';
+import { missingVisibility } from './missing-visibility.js';
+import { missingReconcile } from './missing-reconcile.js';
 import { noDirectImplInRoute } from './no-direct-impl-in-route.js';
 import { noDirectImplementationCall } from './no-direct-implementation-call.js';
 import { noSyncResultAssumption } from './no-sync-result-assumption.js';
-import { noThrowInDetourTarget } from './no-throw-in-detour-target.js';
+import { noThrowInDetourRecover } from './no-throw-in-detour-recover.js';
 import { noThrowInImplementation } from './no-throw-in-implementation.js';
+import { onReferencesExist } from './on-references-exist.js';
+import { orphanedSignal } from './orphaned-signal.js';
+import { permitGovernance } from './permit-governance.js';
 import { preferSchemaInference } from './prefer-schema-inference.js';
-import { provisionDeclarations } from './provision-declarations.js';
-import { provisionExists } from './provision-exists.js';
-import type { WardenRule } from './types.js';
+import { referenceExists } from './reference-exists.js';
+import { resourceDeclarations } from './resource-declarations.js';
+import { resourceExists } from './resource-exists.js';
+import { resourceIdGrammar } from './resource-id-grammar.js';
+import type { TopoAwareWardenRule, WardenRule } from './types.js';
+import { unreachableDetourShadowing } from './unreachable-detour-shadowing.js';
+import { validDetourContract } from './valid-detour-contract.js';
 import { validDescribeRefs } from './valid-describe-refs.js';
-import { validDetourRefs } from './valid-detour-refs.js';
+import { wardenExportSymmetry } from './warden-export-symmetry.js';
+import { wardenRulesUseAst } from './warden-rules-use-ast.js';
 
 export type {
   ProjectAwareWardenRule,
   ProjectContext,
+  TopoAwareWardenRule,
   WardenDiagnostic,
   WardenRule,
   WardenSeverity,
 } from './types.js';
 
 export { noThrowInImplementation } from './no-throw-in-implementation.js';
-export { contextNoTrailheadTypes } from './context-no-trailhead-types.js';
+export { circularRefs } from './circular-refs.js';
+export { contourExists } from './contour-exists.js';
+export { contextNoSurfaceTypes } from './context-no-surface-types.js';
 export { crossDeclarations } from './cross-declarations.js';
-export { validDetourRefs } from './valid-detour-refs.js';
+export { deadInternalTrail } from './dead-internal-trail.js';
+export { draftFileMarking } from './draft-file-marking.js';
+export { draftVisibleDebt } from './draft-visible-debt.js';
+export { errorMappingCompleteness } from './error-mapping-completeness.js';
+export { exampleValid } from './example-valid.js';
+export { firesDeclarations } from './fires-declarations.js';
+export { incompleteAccessorForStandardOp } from './incomplete-accessor-for-standard-op.js';
+export { incompleteCrud } from './incomplete-crud.js';
+export { intentPropagation } from './intent-propagation.js';
+export { missingVisibility } from './missing-visibility.js';
+export { missingReconcile } from './missing-reconcile.js';
+export { onReferencesExist } from './on-references-exist.js';
 export { noDirectImplInRoute } from './no-direct-impl-in-route.js';
 export { noDirectImplementationCall } from './no-direct-implementation-call.js';
 export { noSyncResultAssumption } from './no-sync-result-assumption.js';
 export { implementationReturnsResult } from './implementation-returns-result.js';
-export { noThrowInDetourTarget } from './no-throw-in-detour-target.js';
+export { noThrowInDetourRecover } from './no-throw-in-detour-recover.js';
+export { orphanedSignal } from './orphaned-signal.js';
+export { permitGovernance } from './permit-governance.js';
 export { preferSchemaInference } from './prefer-schema-inference.js';
-export { provisionDeclarations } from './provision-declarations.js';
-export { provisionExists } from './provision-exists.js';
+export { referenceExists } from './reference-exists.js';
+export { resourceDeclarations } from './resource-declarations.js';
+export { resourceExists } from './resource-exists.js';
+export { resourceIdGrammar } from './resource-id-grammar.js';
+export { unreachableDetourShadowing } from './unreachable-detour-shadowing.js';
+export { validDetourContract } from './valid-detour-contract.js';
 export { validDescribeRefs } from './valid-describe-refs.js';
 
 /** All built-in warden rules, keyed by rule name. */
@@ -41,16 +82,54 @@ export const wardenRules: ReadonlyMap<string, WardenRule> = new Map<
   WardenRule
 >([
   [noThrowInImplementation.name, noThrowInImplementation],
-  [contextNoTrailheadTypes.name, contextNoTrailheadTypes],
+  [circularRefs.name, circularRefs],
+  [contourExists.name, contourExists],
+  [contextNoSurfaceTypes.name, contextNoSurfaceTypes],
   [crossDeclarations.name, crossDeclarations],
-  [provisionDeclarations.name, provisionDeclarations],
-  [provisionExists.name, provisionExists],
+  [deadInternalTrail.name, deadInternalTrail],
+  [draftFileMarking.name, draftFileMarking],
+  [draftVisibleDebt.name, draftVisibleDebt],
+  [errorMappingCompleteness.name, errorMappingCompleteness],
+  [exampleValid.name, exampleValid],
+  [firesDeclarations.name, firesDeclarations],
+  [incompleteCrud.name, incompleteCrud],
+  [intentPropagation.name, intentPropagation],
+  [missingVisibility.name, missingVisibility],
+  [missingReconcile.name, missingReconcile],
+  [onReferencesExist.name, onReferencesExist],
+  [orphanedSignal.name, orphanedSignal],
+  [resourceDeclarations.name, resourceDeclarations],
+  [referenceExists.name, referenceExists],
+  [resourceIdGrammar.name, resourceIdGrammar],
+  [resourceExists.name, resourceExists],
   [preferSchemaInference.name, preferSchemaInference],
   [validDescribeRefs.name, validDescribeRefs],
-  [validDetourRefs.name, validDetourRefs],
   [noDirectImplementationCall.name, noDirectImplementationCall],
   [noSyncResultAssumption.name, noSyncResultAssumption],
   [implementationReturnsResult.name, implementationReturnsResult],
-  [noThrowInDetourTarget.name, noThrowInDetourTarget],
+  [noThrowInDetourRecover.name, noThrowInDetourRecover],
   [noDirectImplInRoute.name, noDirectImplInRoute],
+  [unreachableDetourShadowing.name, unreachableDetourShadowing],
+  [wardenExportSymmetry.name, wardenExportSymmetry],
+  [wardenRulesUseAst.name, wardenRulesUseAst],
 ]);
+
+/**
+ * Built-in topo-aware warden rules, keyed by rule name.
+ *
+ * These rules inspect the compiled runtime trail graph once per topo,
+ * rather than scanning source files. Kept in a separate registry because
+ * their dispatch shape differs from `WardenRule` / `ProjectAwareWardenRule`.
+ *
+ * @remarks
+ * Topo-aware rules only fire when the warden runtime is invoked with a
+ * resolved `Topo` (see `WardenOptions.topo`). Runs without a topo — e.g.
+ * pure source-directory lints — silently skip this registry. Rules
+ * registered here must tolerate non-execution when no topo is available.
+ */
+export const wardenTopoRules: ReadonlyMap<string, TopoAwareWardenRule> =
+  new Map<string, TopoAwareWardenRule>([
+    [incompleteAccessorForStandardOp.name, incompleteAccessorForStandardOp],
+    [permitGovernance.name, permitGovernance],
+    [validDetourContract.name, validDetourContract],
+  ]);

package/src/rules/intent-propagation.ts

@@ -0,0 +1,142 @@
+import type { Intent } from '@ontrails/core';
+import {
+  collectNamedTrailIds,
+  collectTrailIntentsById,
+  extractDefinitionCrossTargetIds,
+  findConfigProperty,
+  findTrailDefinitions,
+  getStringValue,
+  isStringLiteral,
+  offsetToLine,
+  parse,
+} from './ast.js';
+import type { AstNode } from './ast.js';
+import { isTestFile } from './scan.js';
+import type {
+  ProjectAwareWardenRule,
+  ProjectContext,
+  WardenDiagnostic,
+} from './types.js';
+
+const extractTrailIntent = (config: AstNode): Intent => {
+  const intentProp = findConfigProperty(config, 'intent');
+  const intentValue = intentProp?.value as AstNode | undefined;
+  if (!intentValue || !isStringLiteral(intentValue)) {
+    return 'write';
+  }
+
+  const value = getStringValue(intentValue);
+  return value === 'destroy' || value === 'read' ? value : 'write';
+};
+
+const buildIntentPropagationDiagnostic = (
+  trailId: string,
+  targetTrailId: string,
+  targetIntent: Exclude<Intent, 'read'>,
+  filePath: string,
+  line: number
+): WardenDiagnostic => ({
+  filePath,
+  line,
+  message: `Trail "${trailId}" declares intent: 'read' but crosses "${targetTrailId}" with intent: '${targetIntent}'. Read trails must not compose write or destroy side effects.`,
+  rule: 'intent-propagation',
+  severity: 'warn',
+});
+
+const buildDiagnosticsForCrossTargets = (
+  trailId: string,
+  targetTrailIds: readonly string[],
+  filePath: string,
+  line: number,
+  trailIntentsById: ReadonlyMap<string, Intent>
+): readonly WardenDiagnostic[] =>
+  targetTrailIds.flatMap((targetTrailId) => {
+    const targetIntent = trailIntentsById.get(targetTrailId);
+    if (!targetIntent || targetIntent === 'read') {
+      return [];
+    }
+
+    return [
+      buildIntentPropagationDiagnostic(
+        trailId,
+        targetTrailId,
+        targetIntent,
+        filePath,
+        line
+      ),
+    ];
+  });
+
+const buildDiagnosticsForTrail = (
+  def: ReturnType<typeof findTrailDefinitions>[number],
+  sourceCode: string,
+  filePath: string,
+  namedTrailIds: ReadonlyMap<string, string>,
+  trailIntentsById: ReadonlyMap<string, Intent>
+): readonly WardenDiagnostic[] => {
+  if (def.kind !== 'trail' || extractTrailIntent(def.config) !== 'read') {
+    return [];
+  }
+
+  return buildDiagnosticsForCrossTargets(
+    def.id,
+    extractDefinitionCrossTargetIds(def.config, sourceCode, namedTrailIds),
+    filePath,
+    offsetToLine(sourceCode, def.start),
+    trailIntentsById
+  );
+};
+
+const checkIntentPropagation = (
+  ast: AstNode | null,
+  sourceCode: string,
+  filePath: string,
+  trailIntentsById: ReadonlyMap<string, Intent>
+): readonly WardenDiagnostic[] => {
+  if (isTestFile(filePath) || !ast) {
+    return [];
+  }
+
+  const namedTrailIds = collectNamedTrailIds(ast);
+  return findTrailDefinitions(ast).flatMap((def) =>
+    buildDiagnosticsForTrail(
+      def,
+      sourceCode,
+      filePath,
+      namedTrailIds,
+      trailIntentsById
+    )
+  );
+};
+
+export const intentPropagation: ProjectAwareWardenRule = {
+  check(sourceCode: string, filePath: string): readonly WardenDiagnostic[] {
+    const ast = parse(filePath, sourceCode);
+    return checkIntentPropagation(
+      ast,
+      sourceCode,
+      filePath,
+      ast ? collectTrailIntentsById(ast) : new Map<string, Intent>()
+    );
+  },
+  checkWithContext(
+    sourceCode: string,
+    filePath: string,
+    context: ProjectContext
+  ): readonly WardenDiagnostic[] {
+    const ast = parse(filePath, sourceCode);
+    const localTrailIntentsById = ast
+      ? collectTrailIntentsById(ast)
+      : new Map<string, Intent>();
+    return checkIntentPropagation(
+      ast,
+      sourceCode,
+      filePath,
+      context.trailIntentsById ?? localTrailIntentsById
+    );
+  },
+  description:
+    "Warn when a trail declaring intent: 'read' crosses a trail whose normalized intent is write or destroy.",
+  name: 'intent-propagation',
+  severity: 'warn',
+};

package/src/rules/missing-reconcile.ts

@@ -0,0 +1,98 @@
+import {
+  collectCrudTableIds,
+  collectReconcileTableIds,
+  findStoreTableDefinitions,
+  offsetToLine,
+  parse,
+} from './ast.js';
+import type { AstNode } from './ast.js';
+import { isTestFile } from './scan.js';
+import type {
+  ProjectAwareWardenRule,
+  ProjectContext,
+  WardenDiagnostic,
+} from './types.js';
+
+const buildMissingReconcileDiagnostic = (
+  tableId: string,
+  filePath: string,
+  line: number
+): WardenDiagnostic => ({
+  filePath,
+  line,
+  message: `Versioned store table "${tableId}" is used with CRUD factories but has no reconcile trail. Add reconcile(...) to complete the versioned store pattern.`,
+  rule: 'missing-reconcile',
+  severity: 'warn',
+});
+
+const checkMissingReconcile = (
+  ast: AstNode | null,
+  sourceCode: string,
+  filePath: string,
+  crudTableIds: ReadonlySet<string>,
+  reconcileTableIds: ReadonlySet<string>
+): readonly WardenDiagnostic[] => {
+  if (isTestFile(filePath) || !ast) {
+    return [];
+  }
+
+  const diagnostics: WardenDiagnostic[] = [];
+
+  for (const definition of findStoreTableDefinitions(ast)) {
+    if (
+      !definition.versioned ||
+      !crudTableIds.has(definition.key) ||
+      reconcileTableIds.has(definition.key)
+    ) {
+      continue;
+    }
+
+    diagnostics.push(
+      buildMissingReconcileDiagnostic(
+        definition.name,
+        filePath,
+        offsetToLine(sourceCode, definition.start)
+      )
+    );
+  }
+
+  return diagnostics;
+};
+
+export const missingReconcile: ProjectAwareWardenRule = {
+  check(sourceCode: string, filePath: string): readonly WardenDiagnostic[] {
+    const ast = parse(filePath, sourceCode);
+    return checkMissingReconcile(
+      ast,
+      sourceCode,
+      filePath,
+      ast ? collectCrudTableIds(ast) : new Set<string>(),
+      ast ? collectReconcileTableIds(ast) : new Set<string>()
+    );
+  },
+  checkWithContext(
+    sourceCode: string,
+    filePath: string,
+    context: ProjectContext
+  ): readonly WardenDiagnostic[] {
+    const ast = parse(filePath, sourceCode);
+    const localCrudTableIds = ast
+      ? collectCrudTableIds(ast)
+      : new Set<string>();
+    const localReconcileTableIds = ast
+      ? collectReconcileTableIds(ast)
+      : new Set<string>();
+
+    return checkMissingReconcile(
+      ast,
+      sourceCode,
+      filePath,
+      context.crudTableIds ?? localCrudTableIds,
+      context.reconcileTableIds ?? localReconcileTableIds
+    );
+  },
+  description:
+    'Warn when a versioned store table participates in CRUD factory generation without a matching reconcile trail.',
+  name: 'missing-reconcile',
+  severity: 'warn',
+};

package/src/rules/missing-visibility.ts

@@ -0,0 +1,110 @@
+import { collectCrossTargetTrailIds, parse } from './ast.js';
+import { isTestFile } from './scan.js';
+import {
+  findTrailLikeSpecs,
+  parseStringLiteral,
+  parseZodObjectShape,
+} from './specs.js';
+import type { TrailLikeSpec } from './specs.js';
+import type {
+  ProjectAwareWardenRule,
+  ProjectContext,
+  WardenDiagnostic,
+} from './types.js';
+
+/** Check legacy `meta: { internal: true }` convention (mirrors runtime effectiveVisibility). */
+const hasLegacyMetaInternal = (spec: TrailLikeSpec): boolean => {
+  const meta = spec.properties.get('meta')?.value ?? '';
+  return /(?:^|[{,])\s*internal\s*:\s*true/.test(meta);
+};
+
+const trailVisibility = (spec: TrailLikeSpec): 'internal' | 'public' => {
+  if (
+    parseStringLiteral(spec.properties.get('visibility')?.value ?? '') ===
+    'internal'
+  ) {
+    return 'internal';
+  }
+  return hasLegacyMetaInternal(spec) ? 'internal' : 'public';
+};
+
+const hasRequiredCrossInput = (spec: TrailLikeSpec): boolean => {
+  const crossInput = spec.properties.get('crossInput');
+  if (!crossInput) {
+    return false;
+  }
+
+  const fields = parseZodObjectShape(crossInput.value);
+  return [...fields.values()].some((field) => field.required);
+};
+
+const buildMissingVisibilityDiagnostic = (
+  trailId: string,
+  filePath: string,
+  line: number
+): WardenDiagnostic => ({
+  filePath,
+  line,
+  message: `Trail "${trailId}" is crossed elsewhere and declares required crossInput fields, but it is still public. Consider visibility: 'internal' so trailheads do not expose a trail that only works through ctx.cross().`,
+  rule: 'missing-visibility',
+  severity: 'warn',
+});
+
+const checkMissingVisibility = (
+  sourceCode: string,
+  filePath: string,
+  crossedTrailIds: ReadonlySet<string>
+): readonly WardenDiagnostic[] => {
+  if (isTestFile(filePath)) {
+    return [];
+  }
+
+  const diagnostics: WardenDiagnostic[] = [];
+
+  for (const spec of findTrailLikeSpecs(sourceCode)) {
+    if (
+      spec.kind !== 'trail' ||
+      trailVisibility(spec) === 'internal' ||
+      !crossedTrailIds.has(spec.id) ||
+      !hasRequiredCrossInput(spec)
+    ) {
+      continue;
+    }
+
+    diagnostics.push(
+      buildMissingVisibilityDiagnostic(spec.id, filePath, spec.line)
+    );
+  }
+
+  return diagnostics;
+};
+
+export const missingVisibility: ProjectAwareWardenRule = {
+  check(sourceCode: string, filePath: string): readonly WardenDiagnostic[] {
+    const ast = parse(filePath, sourceCode);
+    return checkMissingVisibility(
+      sourceCode,
+      filePath,
+      ast ? collectCrossTargetTrailIds(ast, sourceCode) : new Set<string>()
+    );
+  },
+  checkWithContext(
+    sourceCode: string,
+    filePath: string,
+    context: ProjectContext
+  ): readonly WardenDiagnostic[] {
+    const ast = parse(filePath, sourceCode);
+    const localCrossTargetTrailIds = ast
+      ? collectCrossTargetTrailIds(ast, sourceCode)
+      : new Set<string>();
+    return checkMissingVisibility(
+      sourceCode,
+      filePath,
+      context.crossTargetTrailIds ?? localCrossTargetTrailIds
+    );
+  },
+  description:
+    'Coach when a crossed trail still looks composition-only because it declares required crossInput but remains public.',
+  name: 'missing-visibility',
+  severity: 'warn',
+};

package/src/rules/no-direct-impl-in-route.ts

@@ -53,10 +53,6 @@ const hasCrossesProperty = (config: AstNode): boolean =>
  */
 export const noDirectImplInRoute: WardenRule = {
   check(sourceCode: string, filePath: string): readonly WardenDiagnostic[] {
-    if (!/\btrail\s*\(/.test(sourceCode)) {
-      return [];
-    }
-
     const ast = parse(filePath, sourceCode);
     if (!ast) {
       return [];

package/src/rules/no-direct-implementation-call.ts

@@ -31,7 +31,7 @@ export const noDirectImplementationCall: WardenRule = {
           filePath,
           line: offsetToLine(sourceCode, node.start),
           message:
-            'Use ctx.cross("trailId", input) instead of direct .blaze() calls. Direct implementation access bypasses validation, tracing, and gates.',
+            'Use ctx.cross("trailId", input) instead of direct .blaze() calls. Direct implementation access bypasses validation, tracing, and layers.',
           rule: 'no-direct-implementation-call',
           severity: 'warn',
         });