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

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/drift.ts

@@ -1,26 +1,27 @@
 /**
  * Topo lock drift detection.
  *
- * 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. The committed lock may be structured JSON or the
- * legacy single-line hash format.
+ * 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 {
-  createTopoStore,
+  deriveTrailsDir,
   NotFoundError,
   ValidationError,
 } from '@ontrails/core';
-import { resolveTrailsDir } from '@ontrails/core/internal/trails-db';
 import {
-  generateTrailheadMap,
-  hashTrailheadMap,
-  readTrailheadLockData,
-} from '@ontrails/schema';
+  createTopoStore,
+  deriveTopoGraph,
+  deriveTopoGraphHash,
+  isTopoArtifactRegenerationError,
+  readLockManifest,
+} from '@ontrails/topographer';
+import type { LockManifest } from '@ontrails/topographer';
 
 /**
  * Result of a drift check comparing committed trails.lock against the current state.
@@ -36,6 +37,44 @@ export interface DriftResult {
   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 trails.lock is stale compared to the current topology.
  *
@@ -46,47 +85,50 @@ export const checkDrift = async (
   topo?: Topo | undefined
 ): Promise<DriftResult> => {
   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 = (() => {
+    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 topo compile`.'
+      );
+    }
+    const readStoredHash = (): string | undefined => {
       try {
-        return createTopoStore({ rootDir }).exports.get()?.trailheadHash;
+        return createTopoStore({ rootDir }).exports.get()?.topoGraphHash;
       } catch (error) {
         if (error instanceof NotFoundError) {
           return;
         }
         throw error;
       }
-    })();
+    };
     const currentHash =
-      storedHash ??
-      (topo === undefined
-        ? 'unknown'
-        : hashTrailheadMap(generateTrailheadMap(topo)));
+      topo === undefined
+        ? (readStoredHash() ?? 'unknown')
+        : deriveTopoGraphHash(deriveTopoGraph(topo));
 
     return {
-      committedHash: committedLock?.hash ?? null,
+      committedHash: topoArtifact?.sha256 ?? null,
       currentHash,
       stale:
-        committedLock !== null &&
+        topoArtifact !== null &&
         currentHash !== 'unknown' &&
-        committedLock.hash !== currentHash,
+        topoArtifact.sha256 !== currentHash,
     };
   } catch (error) {
-    if (!(error instanceof ValidationError)) {
+    if (
+      !(error instanceof ValidationError) &&
+      !isTopoArtifactRegenerationError(error)
+    ) {
       throw error;
     }
 
-    return {
-      blockedReason: error.message,
-      committedHash: null,
-      currentHash: 'blocked',
-      stale: true,
-    };
+    return blockedDrift(error.message);
   }
 };

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> = {
@@ -36,7 +36,7 @@ export const formatGitHubAnnotations = (report: WardenReport): string => {
     lines.push(`::error::drift: ${report.drift.blockedReason}`);
   } else if (report.drift?.stale) {
     lines.push(
-      '::error::drift: trails.lock is stale (regenerate with `trails topo export`)'
+      '::error::drift: trails.lock is stale (regenerate with `trails topo compile`)'
     );
   }
 
@@ -68,9 +68,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 = (
@@ -80,7 +127,7 @@ 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. */
@@ -99,7 +146,7 @@ const driftSection = (drift: WardenReport['drift']): readonly string[] => {
   return [
     '',
     '### Drift',
-    '- trails.lock is stale (regenerate with `trails topo export`)',
+    '- trails.lock is stale (regenerate with `trails topo compile`)',
   ];
 };
 

package/src/guide.ts

@@ -0,0 +1,234 @@
+import type {
+  WardenGuidance,
+  WardenGuidanceLink,
+  WardenRuleConcern,
+  WardenRuleLifecycle,
+  WardenRuleScope,
+  WardenRuleTier,
+  WardenSeverity,
+} from './rules/index.js';
+import {
+  listWardenRuleMetadata,
+  wardenRules,
+  wardenTopoRules,
+} from './rules/index.js';
+import type { WardenDepth } from './config.js';
+
+export const wardenGuideFormatValues = [
+  'markdown',
+  'agent-json',
+  'manifest',
+] as const;
+
+export type WardenGuideFormat = (typeof wardenGuideFormatValues)[number];
+
+export interface WardenRuleGuideEntry {
+  readonly concern: WardenRuleConcern;
+  readonly depth: WardenDepth;
+  readonly description: string;
+  readonly docs: readonly WardenGuidanceLink[];
+  readonly guidance?: WardenGuidance | undefined;
+  readonly id: string;
+  readonly invariant: string;
+  readonly lifecycle: WardenRuleLifecycle;
+  readonly scope: WardenRuleScope;
+  readonly severity: WardenSeverity;
+  readonly tier: WardenRuleTier;
+}
+
+export interface WardenGuideManifest {
+  readonly generatedFrom: {
+    readonly package: '@ontrails/warden';
+    readonly registries: readonly ['wardenRules', 'wardenTopoRules'];
+    readonly source: 'builtin-rule-metadata';
+  };
+  readonly kind: 'trails-warden-guide-manifest';
+  readonly ruleCount: number;
+  readonly rules: readonly WardenRuleGuideEntry[];
+  readonly version: 1;
+}
+
+interface WardenAgentRuleGuide {
+  readonly appliesAt: {
+    readonly depth: WardenDepth;
+    readonly scope: WardenRuleScope;
+    readonly tier: WardenRuleTier;
+  };
+  readonly concern: WardenRuleConcern;
+  readonly guidance?: WardenGuidance | undefined;
+  readonly id: string;
+  readonly invariant: string;
+  readonly severity: WardenSeverity;
+}
+
+interface WardenAgentGuide {
+  readonly instructions: readonly string[];
+  readonly kind: 'trails-warden-agent-guide';
+  readonly rules: readonly WardenAgentRuleGuide[];
+  readonly version: 1;
+}
+
+const lookupRule = (id: string) =>
+  wardenRules.get(id) ?? wardenTopoRules.get(id);
+
+const compareRuleEntries = (
+  [left]: readonly [string, unknown],
+  [right]: readonly [string, unknown]
+): number => left.localeCompare(right);
+
+export const buildWardenGuideManifest = (): WardenGuideManifest => {
+  const rules = listWardenRuleMetadata()
+    .toSorted(compareRuleEntries)
+    .map(([id, metadata]) => {
+      const rule = lookupRule(id);
+      const docs = metadata.guidance?.docs ?? [];
+      return {
+        concern: metadata.concern,
+        depth: metadata.depth,
+        description: rule?.description ?? '',
+        docs,
+        guidance: metadata.guidance,
+        id,
+        invariant: metadata.invariant,
+        lifecycle: metadata.lifecycle,
+        scope: metadata.scope,
+        severity: rule?.severity ?? 'warn',
+        tier: metadata.tier,
+      } satisfies WardenRuleGuideEntry;
+    });
+
+  return {
+    generatedFrom: {
+      package: '@ontrails/warden',
+      registries: ['wardenRules', 'wardenTopoRules'],
+      source: 'builtin-rule-metadata',
+    },
+    kind: 'trails-warden-guide-manifest',
+    ruleCount: rules.length,
+    rules,
+    version: 1,
+  };
+};
+
+const formatGuideLink = (link: WardenGuidanceLink): string => {
+  if (link.path) {
+    return `[${link.label}](${link.path})`;
+  }
+  if (link.url) {
+    return `[${link.label}](${link.url})`;
+  }
+  return link.label;
+};
+
+const renderOptionalList = (
+  lines: string[],
+  label: string,
+  items: readonly string[] | undefined
+): void => {
+  if (items === undefined || items.length === 0) {
+    return;
+  }
+
+  lines.push(`- ${label}:`);
+  for (const [index, item] of items.entries()) {
+    lines.push(`  ${index + 1}. ${item}`);
+  }
+};
+
+const renderRuleMarkdown = (rule: WardenRuleGuideEntry): readonly string[] => {
+  const lines = [
+    `### \`${rule.id}\``,
+    '',
+    `- Severity: \`${rule.severity}\``,
+    `- Concern: \`${rule.concern}\``,
+    `- Depth: \`${rule.depth}\``,
+    `- Tier: \`${rule.tier}\``,
+    `- Scope: \`${rule.scope}\``,
+    `- Lifecycle: \`${rule.lifecycle.state}\``,
+    `- Invariant: ${rule.invariant}`,
+    `- Description: ${rule.description}`,
+  ];
+
+  if (rule.lifecycle.retireWhen) {
+    lines.push(`- Retire when: ${rule.lifecycle.retireWhen}`);
+  }
+
+  if (rule.guidance) {
+    lines.push('', `Guidance: ${rule.guidance.summary}`);
+    renderOptionalList(lines, 'Steps', rule.guidance.steps);
+    renderOptionalList(lines, 'Commands', rule.guidance.commands);
+    if (rule.docs.length > 0) {
+      lines.push(`- Docs: ${rule.docs.map(formatGuideLink).join(', ')}`);
+    }
+    if (rule.guidance.relatedRules && rule.guidance.relatedRules.length > 0) {
+      lines.push(
+        `- Related rules: ${rule.guidance.relatedRules.map((id) => `\`${id}\``).join(', ')}`
+      );
+    }
+  }
+
+  return lines;
+};
+
+export const formatWardenGuideMarkdown = (
+  manifest: WardenGuideManifest
+): string => {
+  const lines = [
+    '# Trails Warden Guide',
+    '',
+    'Generated from `@ontrails/warden` built-in rule metadata and live rule registries.',
+    '',
+    '## Summary',
+    '',
+    `- Rules: ${manifest.ruleCount}`,
+    `- Guided rules: ${manifest.rules.filter((rule) => rule.guidance).length}`,
+    '',
+    '## Rules',
+    '',
+  ];
+
+  for (const rule of manifest.rules) {
+    lines.push(...renderRuleMarkdown(rule), '');
+  }
+
+  return lines.join('\n').trimEnd();
+};
+
+export const buildWardenAgentGuide = (
+  manifest: WardenGuideManifest
+): WardenAgentGuide => ({
+  instructions: [
+    'Treat Warden rules as enforceable Trails doctrine when working in this repository.',
+    'Prefer the rule guidance summary and ordered steps over diagnostic prose when deciding how to remediate a finding.',
+    'When guidance is absent, use the invariant, concern, tier, and scope as classification metadata rather than inventing a rule-specific fix.',
+  ],
+  kind: 'trails-warden-agent-guide',
+  rules: manifest.rules.map((rule) => ({
+    appliesAt: {
+      depth: rule.depth,
+      scope: rule.scope,
+      tier: rule.tier,
+    },
+    concern: rule.concern,
+    guidance: rule.guidance,
+    id: rule.id,
+    invariant: rule.invariant,
+    severity: rule.severity,
+  })),
+  version: 1,
+});
+
+export const formatWardenGuide = (
+  manifest: WardenGuideManifest,
+  format: WardenGuideFormat
+): string => {
+  if (format === 'markdown') {
+    return formatWardenGuideMarkdown(manifest);
+  }
+
+  if (format === 'agent-json') {
+    return JSON.stringify(buildWardenAgentGuide(manifest), null, 2);
+  }
+
+  return JSON.stringify(manifest, null, 2);
+};