@ontrails/warden 1.0.0-beta.4 → 1.0.0-beta.41

package/src/config.ts

@@ -0,0 +1,193 @@
+import { z } from 'zod';
+
+import type { WardenDiagnostic } from './rules/types.js';
+
+export const wardenDepthValues = ['source', 'project', 'topo', 'all'] as const;
+export const wardenFailOnValues = ['error', 'warning'] as const;
+export const wardenFormatValues = ['summary', 'github', 'json'] as const;
+export const wardenLockValues = ['auto', 'cached', 'refresh', 'skip'] as const;
+export const wardenDraftsValues = ['include', 'exclude', 'only'] as const;
+
+const appNameSchema = z.string().min(1);
+
+const wardenScopeSchema = z
+  .object({
+    exclude: z.array(z.string().min(1)).default([]),
+  })
+  .strict()
+  .default({ exclude: [] });
+
+const wardenConfigObjectSchema = z
+  .object({
+    apps: z.array(appNameSchema).min(1).optional(),
+    depth: z.enum(wardenDepthValues).default('all'),
+    drafts: z.enum(wardenDraftsValues).default('include'),
+    failOn: z.enum(wardenFailOnValues).default('error'),
+    format: z.enum(wardenFormatValues).default('summary'),
+    lock: z.enum(wardenLockValues).default('auto'),
+    scope: wardenScopeSchema,
+  })
+  .strict();
+
+export const wardenConfigSchema = wardenConfigObjectSchema
+  .optional()
+  .transform((value) => wardenConfigObjectSchema.parse(value ?? {}));
+
+export type WardenConfig = z.output<typeof wardenConfigSchema>;
+export type WardenConfigInput = z.input<typeof wardenConfigSchema>;
+export type WardenDepth = (typeof wardenDepthValues)[number];
+export type WardenDraftsMode = (typeof wardenDraftsValues)[number];
+export type WardenFailOn = (typeof wardenFailOnValues)[number];
+export type WardenFormat = (typeof wardenFormatValues)[number];
+export type WardenScope = z.output<typeof wardenScopeSchema>;
+export type WardenLockMode = (typeof wardenLockValues)[number];
+
+export interface WardenConfigLayer extends Partial<WardenConfig> {
+  readonly noLockMutation?: boolean | undefined;
+}
+
+export interface EffectiveWardenConfig extends WardenConfig {
+  readonly noLockMutation: boolean;
+}
+
+export interface ResolveWardenConfigOptions {
+  readonly cli?: WardenConfigLayer | undefined;
+  readonly config?: WardenConfigInput | undefined;
+  readonly defaults?: Partial<WardenConfig> | undefined;
+  readonly env?: Record<string, string | undefined> | undefined;
+}
+
+export interface WardenConfigResolution {
+  readonly diagnostics: readonly WardenDiagnostic[];
+  readonly effectiveConfig: EffectiveWardenConfig;
+}
+
+const baseWardenConfig = (): WardenConfig => {
+  const omittedSection: unknown = undefined;
+  return wardenConfigSchema.parse(omittedSection);
+};
+
+const cleanUndefinedValues = <T extends Record<string, unknown>>(
+  value: T
+): Partial<T> =>
+  Object.fromEntries(
+    Object.entries(value).filter(([, entry]) => entry !== undefined)
+  ) as Partial<T>;
+
+const splitApps = (value: string): readonly string[] =>
+  value
+    .split(',')
+    .map((entry) => entry.trim())
+    .filter((entry) => entry.length > 0);
+
+const readEnvLayer = (
+  env: Record<string, string | undefined>
+): Partial<WardenConfig> =>
+  cleanUndefinedValues({
+    apps: env['TRAILS_APPS'] ? splitApps(env['TRAILS_APPS']) : undefined,
+    depth: env['TRAILS_DEPTH'],
+    drafts: env['TRAILS_DRAFTS'],
+    failOn: env['TRAILS_FAIL_ON'],
+    format: env['TRAILS_FORMAT'],
+    lock: env['TRAILS_LOCK'],
+  }) as Partial<WardenConfig>;
+
+const configDiagnostic = (message: string): WardenDiagnostic => ({
+  filePath: '<warden-config>',
+  line: 1,
+  message,
+  rule: 'warden-config',
+  severity: 'error',
+});
+
+const formatIssues = (error: z.ZodError): string =>
+  error.issues
+    .map((issue) => {
+      const path = issue.path.length > 0 ? issue.path.join('.') : '<root>';
+      return `${path}: ${issue.message}`;
+    })
+    .join('; ');
+
+const parseConfigLayer = (
+  label: string,
+  value: WardenConfigInput | undefined
+): {
+  readonly data: Partial<WardenConfig>;
+  readonly diagnostics: readonly WardenDiagnostic[];
+} => {
+  if (value === undefined) {
+    return { data: {}, diagnostics: [] };
+  }
+
+  const parsed = wardenConfigSchema.safeParse(value);
+  if (parsed.success) {
+    if (typeof value !== 'object' || value === null) {
+      return { data: parsed.data, diagnostics: [] };
+    }
+
+    return {
+      data: Object.fromEntries(
+        Object.keys(value).map((key) => [
+          key,
+          parsed.data[key as keyof WardenConfig],
+        ])
+      ) as Partial<WardenConfig>,
+      diagnostics: [],
+    };
+  }
+
+  return {
+    data: {},
+    diagnostics: [
+      configDiagnostic(
+        `Invalid ${label} Warden config: ${formatIssues(parsed.error)}`
+      ),
+    ],
+  };
+};
+
+export const resolveWardenConfig = ({
+  cli,
+  config,
+  defaults,
+  env = {},
+}: ResolveWardenConfigOptions = {}): WardenConfigResolution => {
+  const { noLockMutation = false, ...cliConfig } = cli ?? {};
+  const defaultLayer = wardenConfigSchema.parse({
+    ...baseWardenConfig(),
+    ...defaults,
+  });
+  const configLayer = parseConfigLayer('file', config);
+  const envLayer = parseConfigLayer('environment', readEnvLayer(env));
+  const merged = {
+    ...defaultLayer,
+    ...configLayer.data,
+    ...envLayer.data,
+    ...cleanUndefinedValues(cliConfig),
+  };
+  const parsed = wardenConfigSchema.safeParse(merged);
+  const diagnostics = [...configLayer.diagnostics, ...envLayer.diagnostics];
+
+  if (!parsed.success) {
+    return {
+      diagnostics: [
+        ...diagnostics,
+        configDiagnostic(
+          `Invalid effective Warden config: ${formatIssues(parsed.error)}`
+        ),
+      ],
+      effectiveConfig: {
+        ...defaultLayer,
+        noLockMutation,
+      },
+    };
+  }
+
+  return {
+    diagnostics,
+    effectiveConfig: {
+      ...parsed.data,
+      noLockMutation,
+    },
+  };
+};

package/src/draft.ts

@@ -0,0 +1,22 @@
+import { basename } from 'node:path';
+
+export const DRAFT_FILE_PREFIX = '_draft.';
+export const DRAFT_FILE_SEGMENT = '.draft.';
+
+const DRAFT_TRAILING_SEGMENT = /\.draft(?=\.[^.]+$)/;
+
+export const isDraftMarkedFile = (filePath: string): boolean => {
+  const fileName = basename(filePath);
+  return (
+    fileName.startsWith(DRAFT_FILE_PREFIX) ||
+    fileName.includes(DRAFT_FILE_SEGMENT)
+  );
+};
+
+export const stripDraftFileMarkers = (fileName: string): string => {
+  if (fileName.startsWith(DRAFT_FILE_PREFIX)) {
+    return fileName.slice(DRAFT_FILE_PREFIX.length);
+  }
+
+  return fileName.replace(DRAFT_TRAILING_SEGMENT, '');
+};

package/src/drift.ts

@@ -1,50 +1,260 @@
 /**
- * Surface lock drift detection.
+ * Trails lock drift detection.
  *
- * Compares the committed `surface.lock` hash against a freshly generated
- * surface map hash to detect when the trail topology has changed without
- * updating the lock file.
+ * Compares the committed `trails.lock` TopoGraph hash against a freshly
+ * generated TopoGraph hash to detect when the trail topology changed without
+ * updating the committed resolved truth.
  */
 
+import { existsSync, statSync } from 'node:fs';
+
 import type { Topo } from '@ontrails/core';
 import {
-  generateSurfaceMap,
-  hashSurfaceMap,
-  readSurfaceLock,
-} from '@ontrails/schema';
+  deriveTrailsDir,
+  NotFoundError,
+  ValidationError,
+} from '@ontrails/core';
+import {
+  collectTopoGraphOverlays,
+  createTopoStore,
+  deriveTopoGraph,
+  deriveTopoGraphHash,
+  isTopoArtifactRegenerationError,
+  LOCK_MANIFEST_SCHEMA_VERSION,
+  readLockManifest,
+  readTopoGraph,
+  readTrailsLock,
+} from '@ontrails/topography';
+import type {
+  DeriveTopoGraphOptions,
+  LockManifest,
+  TopoGraphOverlays,
+} from '@ontrails/topography';
 
 /**
- * Result of a drift check comparing committed surface.lock against the current state.
+ * Derive options `checkDrift` accepts so the fresh comparison graph carries
+ * the same app-module overlays the committed lock embeds.
+ *
+ * @example
+ * ```ts
+ * import type { CheckDriftOptions } from '@ontrails/warden';
+ *
+ * const options: CheckDriftOptions = { overlays: lease.overlays };
+ * ```
+ */
+export type CheckDriftOptions = Pick<DeriveTopoGraphOptions, 'overlays'>;
+
+/**
+ * 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 surface.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;
+  /**
+   * Overlay namespaces whose committed facts differ from the freshly derived
+   * facts, sorted lexicographically. Present only when the lock is stale and
+   * the caller supplied a topo plus derive options.
+   */
+  readonly driftedOverlayNamespaces?: readonly string[] | undefined;
+}
+
+interface BlockedLockRead {
+  readonly drift: DriftResult;
+  readonly kind: 'blocked-lock-read';
 }
 
+const blockedDrift = (reason: string): DriftResult => ({
+  blockedReason: reason,
+  committedHash: null,
+  currentHash: 'blocked',
+  stale: true,
+});
+
+const blockedLockRead = (reason: string): BlockedLockRead => ({
+  drift: blockedDrift(reason),
+  kind: 'blocked-lock-read',
+});
+
+const readCommittedLockManifest = async (
+  rootDir: string
+): Promise<BlockedLockRead | LockManifest | null> => {
+  try {
+    if (!(existsSync(rootDir) && statSync(rootDir).isDirectory())) {
+      return null;
+    }
+    const rootLock = await readTrailsLock({ dir: rootDir });
+    if (rootLock !== null) {
+      return {
+        artifacts: [
+          {
+            path: 'topo.lock',
+            role: 'topo',
+            sha256: rootLock.topoGraphHash,
+          },
+        ],
+        scope: rootLock.scope,
+        summary: rootLock.summary,
+        version: LOCK_MANIFEST_SCHEMA_VERSION,
+      };
+    }
+    return await readLockManifest({ dir: deriveTrailsDir({ rootDir }) });
+  } catch (error) {
+    if (isTopoArtifactRegenerationError(error)) {
+      return blockedLockRead(error.message);
+    }
+    throw error;
+  }
+};
+
+const isBlockedLockRead = (
+  result: BlockedLockRead | LockManifest | null
+): result is BlockedLockRead =>
+  result !== null && 'kind' in result && result.kind === 'blocked-lock-read';
+
+/**
+ * Read the committed lock's embedded graph overlays, tolerating both the v4
+ * root `trails.lock` envelope and the legacy `.trails/` artifact layout.
+ */
+const readCommittedGraphOverlays = async (
+  rootDir: string
+): Promise<TopoGraphOverlays | undefined> => {
+  const committedGraph =
+    (await readTopoGraph({ dir: rootDir })) ??
+    (await readTopoGraph({ dir: deriveTrailsDir({ rootDir }) }));
+  return committedGraph?.overlays;
+};
+
 /**
- * Check whether the committed surface.lock is stale compared to the current topology.
+ * Name the overlay namespaces whose committed facts drifted from the freshly
+ * derived facts. Compares canonical JSON per namespace across the union of
+ * committed and current namespaces; returns a sorted list.
+ */
+const collectDriftedOverlayNamespaces = async (
+  rootDir: string,
+  topo: Topo,
+  options: CheckDriftOptions
+): Promise<readonly string[]> => {
+  let committed: TopoGraphOverlays | undefined;
+  try {
+    committed = await readCommittedGraphOverlays(rootDir);
+  } catch {
+    return [];
+  }
+  const current = collectTopoGraphOverlays(topo, options.overlays);
+  const namespaces = new Set([
+    ...Object.keys(committed ?? {}),
+    ...Object.keys(current ?? {}),
+  ]);
+  return [...namespaces]
+    .filter(
+      (namespace) =>
+        JSON.stringify(committed?.[namespace]) !==
+        JSON.stringify(current?.[namespace])
+    )
+    .toSorted();
+};
+
+/**
+ * Format a stale drift result into one human-readable sentence.
+ *
+ * Names the drifted overlay namespaces when the drift check identified them,
+ * and always points at `trails compile` as the remediation.
+ *
+ * @example
+ * ```ts
+ * import { staleDriftMessage } from './drift.js';
+ *
+ * staleDriftMessage({
+ *   committedHash: 'aaa',
+ *   currentHash: 'bbb',
+ *   driftedOverlayNamespaces: ['surfaces'],
+ *   stale: true,
+ * });
+ * // => 'trails.lock is stale — drifted overlay namespaces: surfaces (regenerate with `trails compile`)'
+ * ```
+ */
+export const staleDriftMessage = (drift: DriftResult): string => {
+  const namespaces = drift.driftedOverlayNamespaces;
+  const detail =
+    namespaces !== undefined && namespaces.length > 0
+      ? ` — drifted overlay namespaces: ${namespaces.join(', ')}`
+      : '';
+  return `trails.lock is stale${detail} (regenerate with \`trails compile\`)`;
+};
+
+/**
+ * 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).
+ * When a topo is provided, `options.overlays` carries the app-module overlay
+ * registrations so the fresh comparison graph embeds the same namespaced
+ * facts the compile path writes into the committed lock.
  */
 export const checkDrift = async (
   rootDir: string,
-  topo?: Topo | undefined
+  topo?: Topo | undefined,
+  options?: CheckDriftOptions | undefined
 ): Promise<DriftResult> => {
-  if (!topo) {
-    return { committedHash: null, currentHash: 'unknown', stale: false };
-  }
+  try {
+    const lockManifest = await readCommittedLockManifest(rootDir);
+    if (isBlockedLockRead(lockManifest)) {
+      return lockManifest.drift;
+    }
+    const topoArtifact =
+      lockManifest?.artifacts.find(
+        (artifact) => artifact.role === 'topo' && artifact.path === 'topo.lock'
+      ) ?? null;
+    if (lockManifest !== null && topoArtifact === null) {
+      return blockedDrift(
+        'trails.lock does not contain a topo.lock artifact. Regenerate with `trails compile`.'
+      );
+    }
+    const readStoredHash = (): string | undefined => {
+      try {
+        return createTopoStore({ rootDir }).exports.get()?.topoGraphHash;
+      } catch (error) {
+        if (error instanceof NotFoundError) {
+          return;
+        }
+        throw error;
+      }
+    };
+    const currentHash =
+      topo === undefined
+        ? (readStoredHash() ?? 'unknown')
+        : deriveTopoGraphHash(deriveTopoGraph(topo, options));
+    const stale =
+      topoArtifact !== null &&
+      currentHash !== 'unknown' &&
+      topoArtifact.sha256 !== currentHash;
+    const driftedOverlayNamespaces =
+      stale && topo !== undefined && options !== undefined
+        ? await collectDriftedOverlayNamespaces(rootDir, topo, options)
+        : undefined;
 
-  const surfaceMap = generateSurfaceMap(topo);
-  const currentHash = hashSurfaceMap(surfaceMap);
-  const committedHash = await readSurfaceLock({ dir: rootDir });
+    return {
+      committedHash: topoArtifact?.sha256 ?? null,
+      currentHash,
+      ...(driftedOverlayNamespaces === undefined ||
+      driftedOverlayNamespaces.length === 0
+        ? {}
+        : { driftedOverlayNamespaces }),
+      stale,
+    };
+  } catch (error) {
+    if (
+      !(error instanceof ValidationError) &&
+      !isTopoArtifactRegenerationError(error)
+    ) {
+      throw error;
+    }
 
-  return {
-    committedHash,
-    currentHash,
-    stale: committedHash !== null && committedHash !== currentHash,
-  };
+    return blockedDrift(error.message);
+  }
 };

package/src/fix.ts

@@ -0,0 +1,126 @@
+/**
+ * Safe-fix execution for `warden --fix` (TRL-833).
+ *
+ * Consumes the structured {@link WardenFix} metadata a rule attaches to its
+ * diagnostics (TRL-831) and applies only the edits marked `safe`. Findings
+ * whose fix is `review`-required, or that carry no edits, are never applied —
+ * they stay reported so a human (or a downstream regrade) resolves them.
+ *
+ * The applicator is pure: it takes a file's source plus that file's
+ * diagnostics and returns the patched source plus which diagnostics were
+ * applied or skipped. The CLI layer owns reading and writing files.
+ */
+
+import type { WardenDiagnostic, WardenFixEdit } from './rules/types.js';
+
+/** A safe edit resolved from a diagnostic, ready to apply to a source string. */
+interface ResolvedEdit {
+  readonly start: number;
+  readonly end: number;
+  readonly replacement: string;
+}
+
+/**
+ * Apply a set of edits to a source string, last-to-first.
+ *
+ * Edits are applied in descending start order so earlier offsets stay valid as
+ * later spans are spliced. Overlapping edits are a programming error in the
+ * rule that produced them; this throws rather than silently corrupt source.
+ */
+const applyEdits = (source: string, edits: readonly ResolvedEdit[]): string => {
+  for (const edit of edits) {
+    if (!Number.isSafeInteger(edit.start) || !Number.isSafeInteger(edit.end)) {
+      throw new RangeError(
+        `Fix edit [${String(edit.start)}, ${String(edit.end)}) must use safe integer offsets.`
+      );
+    }
+  }
+
+  const ordered = [...edits].toSorted(
+    (left, right) => right.start - left.start
+  );
+  let result = source;
+  let lastStart = Number.POSITIVE_INFINITY;
+  for (const edit of ordered) {
+    if (edit.start < 0 || edit.end > source.length || edit.start > edit.end) {
+      throw new RangeError(
+        `Fix edit [${edit.start}, ${edit.end}) is out of bounds for source of length ${source.length}.`
+      );
+    }
+    if (edit.end > lastStart) {
+      throw new RangeError(
+        `Fix edit [${edit.start}, ${edit.end}) overlaps a later edit starting at ${lastStart}.`
+      );
+    }
+    result =
+      result.slice(0, edit.start) + edit.replacement + result.slice(edit.end);
+    lastStart = edit.start;
+  }
+  return result;
+};
+
+/** Whether a diagnostic carries an applicable safe fix with concrete edits. */
+export const hasSafeFixEdits = (
+  diagnostic: WardenDiagnostic
+): diagnostic is WardenDiagnostic & {
+  readonly fix: { readonly edits: readonly WardenFixEdit[] };
+} =>
+  diagnostic.fix?.safety === 'safe' &&
+  diagnostic.fix.edits !== undefined &&
+  diagnostic.fix.edits.length > 0;
+
+/** Result of applying safe fixes to a single file's source. */
+export interface WardenFileFixResult {
+  /** Source after applying every safe edit; unchanged when none applied. */
+  readonly patched: string;
+  /** Whether any edit was applied (i.e. `patched` differs from input). */
+  readonly changed: boolean;
+  /** Diagnostics whose safe fix was applied. */
+  readonly applied: readonly WardenDiagnostic[];
+  /** Diagnostics left reported (review-required, or no safe edits). */
+  readonly skipped: readonly WardenDiagnostic[];
+}
+
+/**
+ * Apply the safe fixes among a file's diagnostics to its source.
+ *
+ * Pure and filesystem-free. Only `safety: 'safe'` fixes with edits are applied;
+ * everything else is returned in `skipped`. Edits from all applicable
+ * diagnostics are pooled and applied last-to-first in one pass.
+ */
+export const applySafeFixesToSource = (
+  source: string,
+  diagnostics: readonly WardenDiagnostic[]
+): WardenFileFixResult => {
+  const applied: WardenDiagnostic[] = [];
+  const skipped: WardenDiagnostic[] = [];
+  const edits: ResolvedEdit[] = [];
+  const seenEdits = new Set<string>();
+
+  for (const diagnostic of diagnostics) {
+    if (hasSafeFixEdits(diagnostic)) {
+      applied.push(diagnostic);
+      for (const edit of diagnostic.fix.edits) {
+        const resolvedEdit = {
+          end: edit.end,
+          replacement: edit.replacement,
+          start: edit.start,
+        };
+        const key = `${String(resolvedEdit.start)}\0${String(resolvedEdit.end)}\0${resolvedEdit.replacement}`;
+        if (!seenEdits.has(key)) {
+          seenEdits.add(key);
+          edits.push(resolvedEdit);
+        }
+      }
+    } else {
+      skipped.push(diagnostic);
+    }
+  }
+
+  if (edits.length === 0) {
+    return { applied, changed: false, patched: source, skipped };
+  }
+
+  const patched = applyEdits(source, edits);
+  return { applied, changed: patched !== source, patched, skipped };
+};