@ontrails/warden 1.0.0-beta.2 → 1.0.0-beta.21

package/src/config.ts

@@ -0,0 +1,184 @@
+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 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'),
+  })
+  .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 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,32 +1,82 @@
 /**
- * Surface lock drift detection.
+ * Topo 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 `topo.lock` artifact hash listed in `trails.lock` against a
+ * freshly generated TopoGraph hash to detect when the trail topology has
+ * changed without updating the artifact family.
  */
 
+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 {
+  createTopoStore,
+  deriveTopoGraph,
+  deriveTopoGraphHash,
+  isTopoArtifactRegenerationError,
+  readLockManifest,
+} from '@ontrails/topographer';
+import type { LockManifest } from '@ontrails/topographer';
 
 /**
- * Result of a drift check comparing committed surface.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 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;
 }
 
+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> => {
+  const trailsDir = deriveTrailsDir({ rootDir });
+  try {
+    return existsSync(rootDir) && statSync(rootDir).isDirectory()
+      ? await readLockManifest({ dir: trailsDir })
+      : null;
+  } 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';
+
 /**
- * Check whether the committed surface.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 +84,51 @@ export const checkDrift = async (
   rootDir: string,
   topo?: Topo | 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));
 
-  const surfaceMap = generateSurfaceMap(topo);
-  const currentHash = hashSurfaceMap(surfaceMap);
-  const committedHash = await readSurfaceLock({ dir: rootDir });
+    return {
+      committedHash: topoArtifact?.sha256 ?? null,
+      currentHash,
+      stale:
+        topoArtifact !== null &&
+        currentHash !== 'unknown' &&
+        topoArtifact.sha256 !== currentHash,
+    };
+  } 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,120 @@
+/**
+ * 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[] = [];
+
+  for (const diagnostic of diagnostics) {
+    if (hasSafeFixEdits(diagnostic)) {
+      applied.push(diagnostic);
+      for (const edit of diagnostic.fix.edits) {
+        edits.push({
+          end: edit.end,
+          replacement: edit.replacement,
+          start: edit.start,
+        });
+      }
+    } 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 };
+};

package/src/formatters.ts

@@ -7,7 +7,7 @@
  */
 
 import type { WardenReport } from './cli.js';
-import type { WardenSeverity } from './rules/types.js';
+import type { WardenGuidanceLink, WardenSeverity } from './rules/types.js';
 
 /** Map warden severity to GitHub Actions annotation level. */
 const ghLevel: Record<WardenSeverity, string> = {
@@ -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: surface.lock is stale (regenerate with `trails survey generate`)'
+      '::error::drift: trails.lock is stale (regenerate with `trails compile`)'
     );
   }
 
@@ -57,6 +60,7 @@ export const formatJson = (report: WardenReport): string => {
     {
       diagnostics: report.diagnostics,
       drift: report.drift,
+      fixes: report.fixes,
       passed: report.passed,
       summary,
     },
@@ -65,9 +69,56 @@ export const formatJson = (report: WardenReport): string => {
   );
 };
 
-/** Format a diagnostic as a markdown list item. */
-const diagnosticLine = (d: WardenReport['diagnostics'][number]): string =>
-  `- \`${d.filePath}:${String(d.line)}\` — ${d.rule}: ${d.message}`;
+const formatGuidanceLink = (link: WardenGuidanceLink): string => {
+  if (link.path !== undefined) {
+    return `[${link.label}](${link.path})`;
+  }
+  if (link.url !== undefined) {
+    return `[${link.label}](${link.url})`;
+  }
+  return link.label;
+};
+
+/** Format diagnostic guidance as indented markdown lines. */
+const diagnosticGuidanceLines = (
+  d: WardenReport['diagnostics'][number]
+): readonly string[] => {
+  const { guidance } = d;
+  if (guidance === undefined) {
+    return [];
+  }
+
+  const lines = [`  - Next: ${guidance.summary}`];
+  if (guidance.steps !== undefined && guidance.steps.length > 0) {
+    lines.push(
+      `  - Steps: ${guidance.steps
+        .map((step, index) => `${String(index + 1)}. ${step}`)
+        .join(' ')}`
+    );
+  }
+  if (guidance.docs !== undefined && guidance.docs.length > 0) {
+    lines.push(`  - Docs: ${guidance.docs.map(formatGuidanceLink).join(', ')}`);
+  }
+  if (guidance.commands !== undefined && guidance.commands.length > 0) {
+    lines.push(
+      `  - Commands: ${guidance.commands.map((cmd) => `\`${cmd}\``).join(', ')}`
+    );
+  }
+  if (guidance.relatedRules !== undefined && guidance.relatedRules.length > 0) {
+    lines.push(
+      `  - Related: ${guidance.relatedRules.map((rule) => `\`${rule}\``).join(', ')}`
+    );
+  }
+  return lines;
+};
+
+/** Format a diagnostic as markdown lines. */
+const diagnosticLines = (
+  d: WardenReport['diagnostics'][number]
+): readonly string[] => [
+  `- \`${d.filePath}:${String(d.line)}\` — ${d.rule}: ${d.message}`,
+  ...diagnosticGuidanceLines(d),
+];
 
 /** Render a severity group as a headed markdown section, or empty array. */
 const severitySection = (
@@ -77,18 +128,36 @@ const severitySection = (
   if (diagnostics.length === 0) {
     return [];
   }
-  return ['', `### ${heading}`, ...diagnostics.map(diagnosticLine)];
+  return ['', `### ${heading}`, ...diagnostics.flatMap(diagnosticLines)];
 };
 
 /** 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',
-    '- surface.lock is stale (regenerate with `trails survey generate`)',
+    '- trails.lock is stale (regenerate with `trails compile`)',
+  ];
+};
+
+/** Render safe-fix counts when a fix pass was requested. */
+const fixSummaryLine = (fixes: WardenReport['fixes']): readonly string[] => {
+  if (fixes === undefined) {
+    return [];
+  }
+  return [
+    `**Fixes:** ${String(fixes.applied)} applied, ${String(fixes.filesChanged)} files changed, ${String(fixes.skipped)} skipped`,
   ];
 };
 
@@ -106,6 +175,7 @@ export const formatSummary = (report: WardenReport): string => {
     '## Warden Report',
     '',
     `**Result: ${result}** | ${String(report.errorCount)} errors, ${String(report.warnCount)} warnings`,
+    ...fixSummaryLine(report.fixes),
     ...severitySection('Errors', errors),
     ...severitySection('Warnings', warnings),
     ...driftSection(report.drift),