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

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
+ * Compares the committed `trails.lock` hash against a freshly generated
  * trailhead map hash to detect when the trail topology has changed without
- * updating the lock file.
+ * 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 {
+  createTopoStore,
+  NotFoundError,
+  ValidationError,
+} from '@ontrails/core';
+import { resolveTrailsDir } from '@ontrails/core/internal/trails-db';
 import {
   generateTrailheadMap,
   hashTrailheadMap,
-  readTrailheadLock,
+  readTrailheadLockData,
 } 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 = resolveTrailsDir({ rootDir });
+    const committedLock =
+      existsSync(rootDir) && statSync(rootDir).isDirectory()
+        ? await readTrailheadLockData({ 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()?.trailheadHash;
+      } catch (error) {
+        if (error instanceof NotFoundError) {
+          return;
+        }
+        throw error;
+      }
+    })();
+    const currentHash =
+      storedHash ??
+      (topo === undefined
+        ? 'unknown'
+        : hashTrailheadMap(generateTrailheadMap(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

@@ -19,6 +19,8 @@ export type {
 // Individual rules
 export { noThrowInImplementation } from './rules/no-throw-in-implementation.js';
 export { contextNoTrailheadTypes } from './rules/context-no-trailhead-types.js';
+export { draftFileMarking } from './rules/draft-file-marking.js';
+export { draftVisibleDebt } from './rules/draft-visible-debt.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';
@@ -48,6 +50,25 @@ export {
 export type { DriftResult } from './drift.js';
 export { checkDrift } from './drift.js';
 
+// 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 gate
 export { wardenTopo } from './trails/topo.js';
 export { runWardenTrails } from './trails/run.js';

package/src/rules/ast.ts

@@ -155,6 +155,44 @@ export const extractStringLiteral = (
 ): string | null =>
   node && isStringLiteral(node) ? getStringValue(node) : null;
 
+export interface StringLiteralMatch {
+  readonly end: number;
+  readonly node: AstNode;
+  readonly start: number;
+  readonly value: string;
+}
+
+export const findStringLiterals = (
+  ast: AstNode,
+  predicate?: (value: string, node: AstNode) => boolean
+): StringLiteralMatch[] => {
+  const matches: StringLiteralMatch[] = [];
+
+  walk(ast, (node) => {
+    if (!isStringLiteral(node)) {
+      return;
+    }
+
+    const value = getStringValue(node);
+    if (value === null) {
+      return;
+    }
+
+    if (predicate && !predicate(value, node)) {
+      return;
+    }
+
+    matches.push({
+      end: node.end,
+      node,
+      start: node.start,
+      value,
+    });
+  });
+
+  return matches;
+};
+
 /** Extract the first string argument from a CallExpression. */
 export const extractFirstStringArg = (node: AstNode): string | null => {
   if (node.type !== 'CallExpression') {

package/src/rules/draft-file-marking.ts

@@ -0,0 +1,112 @@
+import { isDraftId } from '@ontrails/core';
+
+import { isDraftMarkedFile } from '../draft.js';
+import { findStringLiterals, offsetToLine, parse } from './ast.js';
+import type { WardenDiagnostic, WardenRule } from './types.js';
+
+const messageForMissingMarker = (draftId: string): string =>
+  `Draft id "${draftId}" appears in source, but the file is not draft-marked. ` +
+  'Rename it with an _draft. prefix or a .draft. trailing segment.';
+
+const makeDiagnostic = (
+  sourceCode: string,
+  filePath: string,
+  start: number,
+  message: string,
+  severity: WardenDiagnostic['severity']
+): WardenDiagnostic => ({
+  filePath,
+  line: offsetToLine(sourceCode, start),
+  message,
+  rule: 'draft-file-marking',
+  severity,
+});
+
+const draftMissingMarkerDiagnostic = (
+  sourceCode: string,
+  filePath: string,
+  ast: NonNullable<ReturnType<typeof parse>>
+): WardenDiagnostic | null => {
+  const draftMatches = findStringLiterals(ast, (value) => isDraftId(value));
+  if (!draftMatches.length || isDraftMarkedFile(filePath)) {
+    return null;
+  }
+
+  const [first] = draftMatches;
+  if (!first) {
+    return null;
+  }
+
+  return makeDiagnostic(
+    sourceCode,
+    filePath,
+    first.start,
+    messageForMissingMarker(first.value),
+    'error'
+  );
+};
+
+const draftMarkedWithoutIdsDiagnostic = (
+  filePath: string,
+  ast: NonNullable<ReturnType<typeof parse>>
+): WardenDiagnostic | null => {
+  if (findStringLiterals(ast, (value) => isDraftId(value)).length > 0) {
+    return null;
+  }
+
+  if (!isDraftMarkedFile(filePath)) {
+    return null;
+  }
+
+  return {
+    filePath,
+    line: 1,
+    message:
+      'File is draft-marked but no longer contains draft ids. Remove the draft filename marker or finish the promotion cleanup.',
+    rule: 'draft-file-marking',
+    severity: 'warn',
+  };
+};
+
+const collectDraftFileMarkingDiagnostics = (
+  sourceCode: string,
+  filePath: string,
+  ast: NonNullable<ReturnType<typeof parse>>
+): WardenDiagnostic[] => {
+  const missingMarkerDiagnostic = draftMissingMarkerDiagnostic(
+    sourceCode,
+    filePath,
+    ast
+  );
+  if (missingMarkerDiagnostic) {
+    return [missingMarkerDiagnostic];
+  }
+
+  const markedWithoutIdsDiagnostic = draftMarkedWithoutIdsDiagnostic(
+    filePath,
+    ast
+  );
+  if (markedWithoutIdsDiagnostic) {
+    return [markedWithoutIdsDiagnostic];
+  }
+
+  return [];
+};
+
+/**
+ * Ensures files containing draft ids are visibly marked as draft-bearing files.
+ */
+export const draftFileMarking: WardenRule = {
+  check(sourceCode: string, filePath: string): readonly WardenDiagnostic[] {
+    const ast = parse(filePath, sourceCode);
+    if (!ast) {
+      return [];
+    }
+
+    return collectDraftFileMarkingDiagnostics(sourceCode, filePath, ast);
+  },
+  description:
+    'Require draft-bearing files to use _draft.* or *.draft.* filename markers.',
+  name: 'draft-file-marking',
+  severity: 'error',
+};

package/src/rules/draft-visible-debt.ts

@@ -0,0 +1,62 @@
+import { isDraftId } from '@ontrails/core';
+
+import { findStringLiterals, offsetToLine, parse } from './ast.js';
+import type { WardenDiagnostic, WardenRule } from './types.js';
+
+const createDiagnostic = (
+  sourceCode: string,
+  filePath: string,
+  match: { start: number; value: string }
+): WardenDiagnostic => ({
+  filePath,
+  line: offsetToLine(sourceCode, match.start),
+  message:
+    `Draft id "${match.value}" is still visible debt. ` +
+    'Established trailheads, lock export, and OpenAPI generation will reject it until it is promoted.',
+  rule: 'draft-visible-debt',
+  severity: 'warn',
+});
+
+const collectDraftVisibleDebtDiagnostics = (
+  sourceCode: string,
+  filePath: string,
+  ast: NonNullable<ReturnType<typeof parse>>
+): WardenDiagnostic[] => {
+  const seen = new Set<string>();
+  const diagnostics: WardenDiagnostic[] = [];
+
+  for (const match of findStringLiterals(ast, (value) => isDraftId(value))) {
+    const key = `${match.value}:${String(match.start)}`;
+    if (seen.has(key)) {
+      continue;
+    }
+    seen.add(key);
+    diagnostics.push(createDiagnostic(sourceCode, filePath, match));
+  }
+
+  return diagnostics;
+};
+
+/**
+ * Warns when draft ids are still present so the debt stays visible during
+ * review even when the file is correctly marked.
+ *
+ * Severity is intentionally `warn`, not `error`. The hard rejection gate for
+ * draft state leaking into established outputs is `validateEstablishedTopo` at
+ * runtime — it blocks topo export, trailhead projection, and lockfile writes.
+ * This rule surfaces the debt for human reviewers without duplicating that gate.
+ */
+export const draftVisibleDebt: WardenRule = {
+  check(sourceCode: string, filePath: string): readonly WardenDiagnostic[] {
+    const ast = parse(filePath, sourceCode);
+    if (!ast) {
+      return [];
+    }
+
+    return collectDraftVisibleDebtDiagnostics(sourceCode, filePath, ast);
+  },
+  description:
+    'Warn when draft ids remain in source so the debt stays visible during review.',
+  name: 'draft-visible-debt',
+  severity: 'warn',
+};

package/src/rules/index.ts

@@ -1,5 +1,7 @@
 import { contextNoTrailheadTypes } from './context-no-trailhead-types.js';
 import { crossDeclarations } from './cross-declarations.js';
+import { draftFileMarking } from './draft-file-marking.js';
+import { draftVisibleDebt } from './draft-visible-debt.js';
 import { implementationReturnsResult } from './implementation-returns-result.js';
 import { noDirectImplInRoute } from './no-direct-impl-in-route.js';
 import { noDirectImplementationCall } from './no-direct-implementation-call.js';
@@ -24,6 +26,8 @@ export type {
 export { noThrowInImplementation } from './no-throw-in-implementation.js';
 export { contextNoTrailheadTypes } from './context-no-trailhead-types.js';
 export { crossDeclarations } from './cross-declarations.js';
+export { draftFileMarking } from './draft-file-marking.js';
+export { draftVisibleDebt } from './draft-visible-debt.js';
 export { validDetourRefs } from './valid-detour-refs.js';
 export { noDirectImplInRoute } from './no-direct-impl-in-route.js';
 export { noDirectImplementationCall } from './no-direct-implementation-call.js';
@@ -43,6 +47,8 @@ export const wardenRules: ReadonlyMap<string, WardenRule> = new Map<
   [noThrowInImplementation.name, noThrowInImplementation],
   [contextNoTrailheadTypes.name, contextNoTrailheadTypes],
   [crossDeclarations.name, crossDeclarations],
+  [draftFileMarking.name, draftFileMarking],
+  [draftVisibleDebt.name, draftVisibleDebt],
   [provisionDeclarations.name, provisionDeclarations],
   [provisionExists.name, provisionExists],
   [preferSchemaInference.name, preferSchemaInference],

package/src/rules/provision-exists.ts

@@ -1,3 +1,5 @@
+import { isDraftId } from '@ontrails/core';
+
 import {
   collectNamedProvisionIds,
   collectProvisionDefinitionIds,
@@ -94,7 +96,7 @@ const reportMissingProvisions = (
     def.config,
     provisionIdsByName
   )) {
-    if (!knownProvisionIds.has(provisionId)) {
+    if (!knownProvisionIds.has(provisionId) && !isDraftId(provisionId)) {
       diagnostics.push(
         buildMissingProvisionDiagnostic(def.id, provisionId, filePath, line)
       );

package/src/rules/valid-detour-refs.ts

@@ -1,3 +1,5 @@
+import { isDraftId } from '@ontrails/core';
+
 import { collectTrailIds } from './specs.js';
 import type {
   ProjectAwareWardenRule,
@@ -44,7 +46,7 @@ const findMissingDetourTargets = (
   const missing: string[] = [];
   for (const m of text.matchAll(/target\s*:\s*["'`]([^"'`]+)["'`]/g)) {
     const [, id] = m;
-    if (id && !knownIds.has(id)) {
+    if (id && !knownIds.has(id) && !isDraftId(id)) {
       missing.push(id);
     }
   }
@@ -59,7 +61,7 @@ const findMissingPlainDetours = (
   const cleaned = text.replaceAll(/target\s*:\s*["'`][^"'`]+["'`]/g, '');
   for (const m of cleaned.matchAll(/["'`]([^"'`]+)["'`]/g)) {
     const [, id] = m;
-    if (id && id.includes('.') && !knownIds.has(id)) {
+    if (id && id.includes('.') && !knownIds.has(id) && !isDraftId(id)) {
       missing.push(id);
     }
   }

package/tsconfig.tsbuildinfo

@@ -1 +1 @@
-{"root":["./src/cli.ts","./src/drift.ts","./src/formatters.ts","./src/index.ts","./src/rules/ast.ts","./src/rules/context-no-trailhead-types.ts","./src/rules/cross-declarations.ts","./src/rules/implementation-returns-result.ts","./src/rules/index.ts","./src/rules/no-direct-impl-in-route.ts","./src/rules/no-direct-implementation-call.ts","./src/rules/no-sync-result-assumption.ts","./src/rules/no-throw-in-detour-target.ts","./src/rules/no-throw-in-implementation.ts","./src/rules/prefer-schema-inference.ts","./src/rules/provision-declarations.ts","./src/rules/provision-exists.ts","./src/rules/scan.ts","./src/rules/specs.ts","./src/rules/structure.ts","./src/rules/types.ts","./src/rules/valid-describe-refs.ts","./src/rules/valid-detour-refs.ts","./src/trails/context-no-trailhead-types.trail.ts","./src/trails/cross-declarations.trail.ts","./src/trails/implementation-returns-result.trail.ts","./src/trails/index.ts","./src/trails/no-direct-impl-in-route.trail.ts","./src/trails/no-direct-implementation-call.trail.ts","./src/trails/no-sync-result-assumption.trail.ts","./src/trails/no-throw-in-detour-target.trail.ts","./src/trails/no-throw-in-implementation.trail.ts","./src/trails/prefer-schema-inference.trail.ts","./src/trails/provision-declarations.trail.ts","./src/trails/provision-exists.trail.ts","./src/trails/run.ts","./src/trails/schema.ts","./src/trails/topo.ts","./src/trails/valid-describe-refs.trail.ts","./src/trails/valid-detour-refs.trail.ts","./src/trails/wrap-rule.ts"],"version":"5.9.3"}
+{"root":["./src/cli.ts","./src/draft.ts","./src/drift.ts","./src/formatters.ts","./src/index.ts","./src/rules/ast.ts","./src/rules/context-no-trailhead-types.ts","./src/rules/cross-declarations.ts","./src/rules/draft-file-marking.ts","./src/rules/draft-visible-debt.ts","./src/rules/implementation-returns-result.ts","./src/rules/index.ts","./src/rules/no-direct-impl-in-route.ts","./src/rules/no-direct-implementation-call.ts","./src/rules/no-sync-result-assumption.ts","./src/rules/no-throw-in-detour-target.ts","./src/rules/no-throw-in-implementation.ts","./src/rules/prefer-schema-inference.ts","./src/rules/provision-declarations.ts","./src/rules/provision-exists.ts","./src/rules/scan.ts","./src/rules/specs.ts","./src/rules/structure.ts","./src/rules/types.ts","./src/rules/valid-describe-refs.ts","./src/rules/valid-detour-refs.ts","./src/trails/context-no-trailhead-types.trail.ts","./src/trails/cross-declarations.trail.ts","./src/trails/implementation-returns-result.trail.ts","./src/trails/index.ts","./src/trails/no-direct-impl-in-route.trail.ts","./src/trails/no-direct-implementation-call.trail.ts","./src/trails/no-sync-result-assumption.trail.ts","./src/trails/no-throw-in-detour-target.trail.ts","./src/trails/no-throw-in-implementation.trail.ts","./src/trails/prefer-schema-inference.trail.ts","./src/trails/provision-declarations.trail.ts","./src/trails/provision-exists.trail.ts","./src/trails/run.ts","./src/trails/schema.ts","./src/trails/topo.ts","./src/trails/valid-describe-refs.trail.ts","./src/trails/valid-detour-refs.trail.ts","./src/trails/wrap-rule.ts"],"version":"5.9.3"}