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

package/src/drift.ts

@@ -1,32 +1,43 @@
 /**
- * Trailhead lock drift detection.
+ * Topo lock drift detection.
  *
- * Compares the committed `trailhead.lock` hash against a freshly generated
- * trailhead map hash to detect when the trail topology has changed without
- * updating the lock file.
+ * Compares the committed `trails.lock` hash against a freshly generated
+ * surface map hash to detect when the trail topology has changed without
+ * updating the lock file. The committed lock may be structured JSON or the
+ * legacy single-line hash format.
  */
 
+import { existsSync, statSync } from 'node:fs';
+
 import type { Topo } from '@ontrails/core';
 import {
-  generateTrailheadMap,
-  hashTrailheadMap,
-  readTrailheadLock,
+  createTopoStore,
+  NotFoundError,
+  ValidationError,
+} from '@ontrails/core';
+import { deriveTrailsDir } from '@ontrails/core/internal/trails-db';
+import {
+  deriveSurfaceMap,
+  deriveSurfaceMapHash,
+  readSurfaceLockData,
 } from '@ontrails/schema';
 
 /**
- * Result of a drift check comparing committed trailhead.lock against the current state.
+ * Result of a drift check comparing committed trails.lock against the current state.
  */
 export interface DriftResult {
+  /** Why drift could not be computed for the established graph, when blocked. */
+  readonly blockedReason?: string | undefined;
   /** Whether the committed lock is out of date */
   readonly stale: boolean;
-  /** Hash from the committed trailhead.lock file, or null if not found */
+  /** Hash from the committed trails.lock file, or null if not found */
   readonly committedHash: string | null;
   /** Hash computed from the current trail topology */
   readonly currentHash: string;
 }
 
 /**
- * Check whether the committed trailhead.lock is stale compared to the current topology.
+ * Check whether the committed trails.lock is stale compared to the current topology.
  *
  * When no topo is provided, returns a clean result (no drift detectable without runtime info).
  */
@@ -34,17 +45,48 @@ export const checkDrift = async (
   rootDir: string,
   topo?: Topo | undefined
 ): Promise<DriftResult> => {
-  if (!topo) {
-    return { committedHash: null, currentHash: 'unknown', stale: false };
-  }
+  try {
+    const trailsDir = deriveTrailsDir({ rootDir });
+    const committedLock =
+      existsSync(rootDir) && statSync(rootDir).isDirectory()
+        ? await readSurfaceLockData({ dir: trailsDir })
+        : null;
+    // Prefer the stored hash (computed by the export pipeline) to avoid
+    // divergence between the schema and store hash pipelines.
+    const storedHash = (() => {
+      try {
+        return createTopoStore({ rootDir }).exports.get()?.surfaceHash;
+      } catch (error) {
+        if (error instanceof NotFoundError) {
+          return;
+        }
+        throw error;
+      }
+    })();
+    const currentHash =
+      storedHash ??
+      (topo === undefined
+        ? 'unknown'
+        : deriveSurfaceMapHash(deriveSurfaceMap(topo)));
 
-  const trailheadMap = generateTrailheadMap(topo);
-  const currentHash = hashTrailheadMap(trailheadMap);
-  const committedHash = await readTrailheadLock({ dir: rootDir });
+    return {
+      committedHash: committedLock?.hash ?? null,
+      currentHash,
+      stale:
+        committedLock !== null &&
+        currentHash !== 'unknown' &&
+        committedLock.hash !== currentHash,
+    };
+  } catch (error) {
+    if (!(error instanceof ValidationError)) {
+      throw error;
+    }
 
-  return {
-    committedHash,
-    currentHash,
-    stale: committedHash !== null && committedHash !== currentHash,
-  };
+    return {
+      blockedReason: error.message,
+      committedHash: null,
+      currentHash: 'blocked',
+      stale: true,
+    };
+  }
 };

package/src/formatters.ts

@@ -19,7 +19,8 @@ const ghLevel: Record<WardenSeverity, string> = {
  * Produce GitHub Actions workflow command annotations, one per diagnostic.
  *
  * Severity mapping: `error` to `::error`, `warn` to `::warning`.
- * Drift staleness is emitted as a single `::error` annotation when detected.
+ * Drift staleness or established-export blocking is emitted as a single
+ * `::error` annotation when detected.
  */
 export const formatGitHubAnnotations = (report: WardenReport): string => {
   const lines: string[] = [];
@@ -31,9 +32,11 @@ export const formatGitHubAnnotations = (report: WardenReport): string => {
     );
   }
 
-  if (report.drift?.stale) {
+  if (report.drift?.blockedReason !== undefined) {
+    lines.push(`::error::drift: ${report.drift.blockedReason}`);
+  } else if (report.drift?.stale) {
     lines.push(
-      '::error::drift: trailhead.lock is stale (regenerate with `trails survey generate`)'
+      '::error::drift: trails.lock is stale (regenerate with `trails topo export`)'
     );
   }
 
@@ -82,13 +85,21 @@ const severitySection = (
 
 /** Render a drift section if stale, otherwise empty array. */
 const driftSection = (drift: WardenReport['drift']): readonly string[] => {
+  if (drift?.blockedReason !== undefined) {
+    return [
+      '',
+      '### Drift',
+      `- established exports are blocked: ${drift.blockedReason}`,
+    ];
+  }
+
   if (!drift?.stale) {
     return [];
   }
   return [
     '',
     '### Drift',
-    '- trailhead.lock is stale (regenerate with `trails survey generate`)',
+    '- trails.lock is stale (regenerate with `trails topo export`)',
   ];
 };
 

package/src/index.ts

@@ -11,27 +11,17 @@
 export type {
   ProjectAwareWardenRule,
   ProjectContext,
+  TopoAwareWardenRule,
   WardenDiagnostic,
   WardenRule,
   WardenSeverity,
 } from './rules/index.js';
 
-// Individual rules
-export { noThrowInImplementation } from './rules/no-throw-in-implementation.js';
-export { contextNoTrailheadTypes } from './rules/context-no-trailhead-types.js';
-export { validDetourRefs } from './rules/valid-detour-refs.js';
-export { noDirectImplInRoute } from './rules/no-direct-impl-in-route.js';
-export { noDirectImplementationCall } from './rules/no-direct-implementation-call.js';
-export { noSyncResultAssumption } from './rules/no-sync-result-assumption.js';
-export { implementationReturnsResult } from './rules/implementation-returns-result.js';
-export { noThrowInDetourTarget } from './rules/no-throw-in-detour-target.js';
-export { preferSchemaInference } from './rules/prefer-schema-inference.js';
-export { provisionDeclarations } from './rules/provision-declarations.js';
-export { provisionExists } from './rules/provision-exists.js';
-export { validDescribeRefs } from './rules/valid-describe-refs.js';
-
 // Rule registry
-export { wardenRules } from './rules/index.js';
+export { wardenRules, wardenTopoRules } from './rules/index.js';
+
+// Rule-scoped cache controls for long-lived consumers (watch mode, LSPs).
+export { clearImplementationReturnsResultCache } from './rules/implementation-returns-result.js';
 
 // CLI runner
 export type { WardenOptions, WardenReport } from './cli.js';
@@ -48,25 +38,74 @@ export {
 export type { DriftResult } from './drift.js';
 export { checkDrift } from './drift.js';
 
-// Trail gate
+// Draft helpers
+export {
+  DRAFT_FILE_PREFIX,
+  DRAFT_FILE_SEGMENT,
+  isDraftMarkedFile,
+  stripDraftFileMarkers,
+} from './draft.js';
+
+// AST helpers for repo-local tooling
+export {
+  findStringLiterals,
+  getStringValue,
+  isStringLiteral,
+  offsetToLine,
+  parse,
+  walk,
+} from './rules/ast.js';
+export type { AstNode, StringLiteralMatch } from './rules/ast.js';
+
+// Trail layer
 export { wardenTopo } from './trails/topo.js';
-export { runWardenTrails } from './trails/run.js';
+export { runTopoAwareWardenTrails, runWardenTrails } from './trails/run.js';
 export {
-  contextNoTrailheadTypesTrail,
+  circularRefsTrail,
+  contourExistsTrail,
+  contextNoSurfaceTypesTrail,
   crossDeclarationsTrail,
+  deadInternalTrailTrail,
   diagnosticSchema,
+  draftFileMarkingTrail,
+  draftVisibleDebtTrail,
+  errorMappingCompletenessTrail,
+  exampleValidTrail,
+  firesDeclarationsTrail,
   implementationReturnsResultTrail,
+  incompleteAccessorForStandardOpTrail,
+  incompleteCrudTrail,
+  intentPropagationTrail,
+  missingVisibilityTrail,
+  missingReconcileTrail,
   noDirectImplInRouteTrail,
   noDirectImplementationCallTrail,
   noSyncResultAssumptionTrail,
-  noThrowInDetourTargetTrail,
+  noThrowInDetourRecoverTrail,
   noThrowInImplementationTrail,
+  onReferencesExistTrail,
+  orphanedSignalTrail,
+  permitGovernanceTrail,
   preferSchemaInferenceTrail,
+  projectAwareRuleInput,
+  referenceExistsTrail,
   ruleInput,
   ruleOutput,
-  provisionDeclarationsTrail,
-  provisionExistsTrail,
+  resourceDeclarationsTrail,
+  resourceIdGrammarTrail,
+  resourceExistsTrail,
+  topoAwareRuleInput,
+  unreachableDetourShadowingTrail,
+  validDetourContractTrail,
   validDescribeRefsTrail,
-  validDetourRefsTrail,
+  wardenExportSymmetryTrail,
+  wardenRulesUseAstTrail,
+  wrapRule,
+  wrapTopoRule,
+} from './trails/index.js';
+export type {
+  ProjectAwareRuleInput,
+  RuleInput,
+  RuleOutput,
+  TopoAwareRuleInput,
 } from './trails/index.js';
-export type { RuleInput, RuleOutput } from './trails/index.js';