@ontrails/warden 1.0.0-beta.0

package/src/cli.ts

@@ -0,0 +1,343 @@
+/**
+ * Warden CLI command runner.
+ *
+ * Scans TypeScript files, runs all warden rules, optionally checks drift,
+ * and returns a structured report.
+ */
+
+import { resolve } from 'node:path';
+
+import type { Topo } from '@ontrails/core';
+
+import type { DriftResult } from './drift.js';
+import { checkDrift } from './drift.js';
+import {
+  findConfigProperty,
+  findTrailDefinitions,
+  parse,
+  walk,
+} from './rules/ast.js';
+import { wardenRules } from './rules/index.js';
+import type {
+  ProjectAwareWardenRule,
+  ProjectContext,
+  WardenDiagnostic,
+  WardenRule,
+} from './rules/types.js';
+
+/**
+ * Options for the warden CLI runner.
+ */
+export interface WardenOptions {
+  /** Root directory to scan for TypeScript files. Defaults to cwd. */
+  readonly rootDir?: string | undefined;
+  /** Only run lint rules, skip drift detection */
+  readonly lintOnly?: boolean | undefined;
+  /** Only run drift detection, skip lint rules */
+  readonly driftOnly?: boolean | undefined;
+  /** App topology for drift detection. When provided, enables real surface lock comparison. */
+  readonly topo?: Topo | undefined;
+}
+
+/**
+ * Result of a warden run.
+ */
+export interface WardenReport {
+  /** All diagnostics from lint rules */
+  readonly diagnostics: readonly WardenDiagnostic[];
+  /** Count of error-severity diagnostics */
+  readonly errorCount: number;
+  /** Count of warn-severity diagnostics */
+  readonly warnCount: number;
+  /** Drift detection result, or null if skipped */
+  readonly drift: DriftResult | null;
+  /** Whether the warden run passed (no errors, no drift) */
+  readonly passed: boolean;
+}
+
+/**
+ * Collect all .ts files under a directory, excluding node_modules, dist, and .git.
+ */
+const isSourceFile = (match: string): boolean =>
+  !match.endsWith('.d.ts') &&
+  !match.startsWith('node_modules/') &&
+  !match.startsWith('dist/') &&
+  !match.startsWith('.git/') &&
+  !match.includes('__tests__/') &&
+  !match.includes('__test__/') &&
+  !match.endsWith('.test.ts') &&
+  !match.endsWith('.spec.ts');
+
+const collectTsFiles = (dir: string): readonly string[] => {
+  const glob = new Bun.Glob('**/*.ts');
+  let matches: IterableIterator<string>;
+  try {
+    matches = glob.scanSync({ cwd: dir, dot: false, onlyFiles: true });
+  } catch {
+    return [];
+  }
+
+  const files: string[] = [];
+  for (const match of matches) {
+    if (isSourceFile(match)) {
+      files.push(`${dir}/${match}`);
+    }
+  }
+  return files;
+};
+
+interface SourceFile {
+  readonly filePath: string;
+  readonly sourceCode: string;
+}
+
+const collectKnownTrailIds = (
+  sourceCode: string,
+  filePath: string,
+  knownTrailIds: Set<string>
+): void => {
+  const ast = parse(filePath, sourceCode);
+  if (!ast) {
+    return;
+  }
+  for (const def of findTrailDefinitions(ast)) {
+    knownTrailIds.add(def.id);
+  }
+};
+
+const collectDetourTargetTrailIds = (
+  sourceCode: string,
+  filePath: string,
+  detourTargetTrailIds: Set<string>
+): void => {
+  const ast = parse(filePath, sourceCode);
+  if (!ast) {
+    return;
+  }
+  for (const def of findTrailDefinitions(ast)) {
+    const detoursProp = findConfigProperty(def.config, 'detours');
+    if (!detoursProp) {
+      continue;
+    }
+    // Walk the detours value for string literals that look like trail IDs
+    walk(detoursProp, (node) => {
+      if (node.type !== 'Literal') {
+        return;
+      }
+      const val = (node as unknown as { value?: string }).value;
+      if (val && val.includes('.')) {
+        detourTargetTrailIds.add(val);
+      }
+    });
+  }
+};
+
+const loadSourceFiles = async (
+  rootDir: string
+): Promise<readonly SourceFile[]> => {
+  const sourceFiles: SourceFile[] = [];
+
+  for (const filePath of collectTsFiles(rootDir)) {
+    try {
+      sourceFiles.push({
+        filePath,
+        sourceCode: await Bun.file(filePath).text(),
+      });
+    } catch {
+      continue;
+    }
+  }
+
+  return sourceFiles;
+};
+
+const buildProjectContextFromTopo = (appTopo: Topo): ProjectContext => {
+  const knownTrailIds = new Set<string>([
+    ...appTopo.trails.keys(),
+    ...appTopo.hikes.keys(),
+  ]);
+
+  const detourTargetTrailIds = new Set<string>();
+  for (const t of appTopo.trails.values()) {
+    const detours = (t as unknown as Record<string, unknown>)['detours'] as
+      | Readonly<Record<string, readonly string[]>>
+      | undefined;
+    if (!detours) {
+      continue;
+    }
+    for (const targets of Object.values(detours)) {
+      for (const id of targets) {
+        detourTargetTrailIds.add(id);
+      }
+    }
+  }
+
+  return { detourTargetTrailIds, knownTrailIds };
+};
+
+const buildProjectContextFromFiles = (
+  sourceFiles: readonly SourceFile[]
+): ProjectContext => {
+  const knownTrailIds = new Set<string>();
+  const detourTargetTrailIds = new Set<string>();
+
+  for (const sourceFile of sourceFiles) {
+    collectKnownTrailIds(
+      sourceFile.sourceCode,
+      sourceFile.filePath,
+      knownTrailIds
+    );
+    collectDetourTargetTrailIds(
+      sourceFile.sourceCode,
+      sourceFile.filePath,
+      detourTargetTrailIds
+    );
+  }
+
+  return {
+    detourTargetTrailIds,
+    knownTrailIds,
+  };
+};
+
+const isProjectAwareRule = (rule: WardenRule): rule is ProjectAwareWardenRule =>
+  'checkWithContext' in rule;
+
+/**
+ * Lint all files against all warden rules.
+ */
+const lintFiles = async (
+  rootDir: string,
+  appTopo?: Topo | undefined
+): Promise<WardenDiagnostic[]> => {
+  const allDiagnostics: WardenDiagnostic[] = [];
+  const sourceFiles = await loadSourceFiles(rootDir);
+  const context = appTopo
+    ? buildProjectContextFromTopo(appTopo)
+    : buildProjectContextFromFiles(sourceFiles);
+
+  for (const sourceFile of sourceFiles) {
+    for (const rule of wardenRules.values()) {
+      if (isProjectAwareRule(rule)) {
+        allDiagnostics.push(
+          ...rule.checkWithContext(
+            sourceFile.sourceCode,
+            sourceFile.filePath,
+            context
+          )
+        );
+        continue;
+      }
+
+      allDiagnostics.push(
+        ...rule.check(sourceFile.sourceCode, sourceFile.filePath)
+      );
+    }
+  }
+
+  return allDiagnostics;
+};
+
+/**
+ * Run all warden checks and return a structured report.
+ */
+export const runWarden = async (
+  options: WardenOptions = {}
+): Promise<WardenReport> => {
+  const rootDir = resolve(options.rootDir ?? process.cwd());
+  const allDiagnostics = options.driftOnly
+    ? []
+    : await lintFiles(rootDir, options.topo);
+  const drift = options.lintOnly
+    ? null
+    : await checkDrift(rootDir, options.topo);
+
+  const errorCount = allDiagnostics.filter(
+    (d) => d.severity === 'error'
+  ).length;
+  const warnCount = allDiagnostics.filter((d) => d.severity === 'warn').length;
+
+  return {
+    diagnostics: allDiagnostics,
+    drift,
+    errorCount,
+    passed: errorCount === 0 && !(drift?.stale ?? false),
+    warnCount,
+  };
+};
+
+/**
+ * Format the lint section of the report.
+ */
+const formatLintSection = (report: WardenReport): string[] => {
+  if (report.diagnostics.length === 0) {
+    return ['Lint: clean'];
+  }
+
+  const lines = [
+    `Lint: ${report.errorCount} errors, ${report.warnCount} warnings`,
+  ];
+
+  for (const d of report.diagnostics) {
+    const prefix = d.severity === 'error' ? 'ERROR' : 'WARN';
+    lines.push(
+      `  ${d.filePath}:${String(d.line)}  [${prefix}] ${d.rule}  ${d.message}`
+    );
+  }
+
+  return lines;
+};
+
+/**
+ * Format the drift section of the report.
+ */
+const formatDriftSection = (drift: DriftResult | null): string[] => {
+  if (drift === null) {
+    return [];
+  }
+  const label = drift.stale
+    ? 'Drift: surface.lock is stale (regenerate with `trails survey generate`)'
+    : 'Drift: clean';
+  return [label, ''];
+};
+
+/**
+ * Format the result line.
+ */
+const formatResultLine = (report: WardenReport): string => {
+  if (report.passed) {
+    return 'Result: PASS';
+  }
+  const parts: string[] = [];
+  if (report.errorCount > 0) {
+    parts.push(`${report.errorCount} errors`);
+  }
+  if (report.drift?.stale) {
+    parts.push('drift detected');
+  }
+  return `Result: FAIL (${parts.join(', ')})`;
+};
+
+/**
+ * Format a warden report as a human-readable string.
+ */
+export const formatWardenReport = (report: WardenReport): string => {
+  const lintLines = formatLintSection(report);
+  const driftLines = formatDriftSection(report.drift);
+
+  if (lintLines.length === 0 && driftLines.length === 0) {
+    return ['Warden Report', '=============', '', 'No checks were run.'].join(
+      '\n'
+    );
+  }
+
+  return [
+    'Warden Report',
+    '=============',
+    '',
+    ...lintLines,
+    '',
+    ...driftLines,
+    formatResultLine(report),
+  ].join('\n');
+};

package/src/drift.ts

@@ -0,0 +1,50 @@
+/**
+ * Surface 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.
+ */
+
+import type { Topo } from '@ontrails/core';
+import {
+  generateSurfaceMap,
+  hashSurfaceMap,
+  readSurfaceLock,
+} from '@ontrails/schema';
+
+/**
+ * Result of a drift check comparing committed surface.lock against the current state.
+ */
+export interface DriftResult {
+  /** Whether the committed lock is out of date */
+  readonly stale: boolean;
+  /** Hash from the committed surface.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 surface.lock is stale compared to the current topology.
+ *
+ * When no topo is provided, returns a clean result (no drift detectable without runtime info).
+ */
+export const checkDrift = async (
+  rootDir: string,
+  topo?: Topo | undefined
+): Promise<DriftResult> => {
+  if (!topo) {
+    return { committedHash: null, currentHash: 'unknown', stale: false };
+  }
+
+  const surfaceMap = generateSurfaceMap(topo);
+  const currentHash = hashSurfaceMap(surfaceMap);
+  const committedHash = await readSurfaceLock({ dir: rootDir });
+
+  return {
+    committedHash,
+    currentHash,
+    stale: committedHash !== null && committedHash !== currentHash,
+  };
+};

package/src/formatters.ts

@@ -0,0 +1,113 @@
+/**
+ * CI-oriented formatters for warden reports.
+ *
+ * Each formatter takes a `WardenReport` and produces output suited to a
+ * specific CI environment: GitHub Actions annotations, structured JSON,
+ * or a concise markdown summary.
+ */
+
+import type { WardenReport } from './cli.js';
+import type { WardenSeverity } from './rules/types.js';
+
+/** Map warden severity to GitHub Actions annotation level. */
+const ghLevel: Record<WardenSeverity, string> = {
+  error: 'error',
+  warn: 'warning',
+};
+
+/**
+ * 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.
+ */
+export const formatGitHubAnnotations = (report: WardenReport): string => {
+  const lines: string[] = [];
+
+  for (const d of report.diagnostics) {
+    const level = ghLevel[d.severity];
+    lines.push(
+      `::${level} file=${d.filePath},line=${String(d.line)}::${d.rule}: ${d.message}`
+    );
+  }
+
+  if (report.drift?.stale) {
+    lines.push(
+      '::error::drift: surface.lock is stale (regenerate with `trails survey generate`)'
+    );
+  }
+
+  return lines.join('\n');
+};
+
+/**
+ * Produce a structured JSON string from the report.
+ *
+ * Includes a `summary` object with error, warning, and suggestion counts
+ * for easy consumption by downstream tooling.
+ */
+export const formatJson = (report: WardenReport): string => {
+  const summary = {
+    errors: report.errorCount,
+    suggestions: 0,
+    warnings: report.warnCount,
+  };
+
+  return JSON.stringify(
+    {
+      diagnostics: report.diagnostics,
+      drift: report.drift,
+      passed: report.passed,
+      summary,
+    },
+    null,
+    2
+  );
+};
+
+/** Format a diagnostic as a markdown list item. */
+const diagnosticLine = (d: WardenReport['diagnostics'][number]): string =>
+  `- \`${d.filePath}:${String(d.line)}\` — ${d.rule}: ${d.message}`;
+
+/** Render a severity group as a headed markdown section, or empty array. */
+const severitySection = (
+  heading: string,
+  diagnostics: WardenReport['diagnostics']
+): readonly string[] => {
+  if (diagnostics.length === 0) {
+    return [];
+  }
+  return ['', `### ${heading}`, ...diagnostics.map(diagnosticLine)];
+};
+
+/** Render a drift section if stale, otherwise empty array. */
+const driftSection = (drift: WardenReport['drift']): readonly string[] => {
+  if (!drift?.stale) {
+    return [];
+  }
+  return [
+    '',
+    '### Drift',
+    '- surface.lock is stale (regenerate with `trails survey generate`)',
+  ];
+};
+
+/**
+ * Produce a concise markdown summary suitable for a GitHub job summary or PR comment.
+ *
+ * Groups diagnostics by severity and includes drift status when relevant.
+ */
+export const formatSummary = (report: WardenReport): string => {
+  const result = report.passed ? 'PASS' : 'FAIL';
+  const errors = report.diagnostics.filter((d) => d.severity === 'error');
+  const warnings = report.diagnostics.filter((d) => d.severity === 'warn');
+
+  return [
+    '## Warden Report',
+    '',
+    `**Result: ${result}** | ${String(report.errorCount)} errors, ${String(report.warnCount)} warnings`,
+    ...severitySection('Errors', errors),
+    ...severitySection('Warnings', warnings),
+    ...driftSection(report.drift),
+  ].join('\n');
+};

package/src/index.ts

@@ -0,0 +1,47 @@
+/**
+ * Warden - Governance package for Trails.
+ *
+ * Provides lint rules, drift detection, and a CLI runner to enforce
+ * contract-first discipline at development time.
+ *
+ * Package: `@ontrails/warden`
+ */
+
+// Rule types
+export type {
+  ProjectAwareWardenRule,
+  ProjectContext,
+  WardenDiagnostic,
+  WardenRule,
+  WardenSeverity,
+} from './rules/index.js';
+
+// Individual rules
+export { noThrowInImplementation } from './rules/no-throw-in-implementation.js';
+export { contextNoSurfaceTypes } from './rules/context-no-surface-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 { validDescribeRefs } from './rules/valid-describe-refs.js';
+
+// Rule registry
+export { wardenRules } from './rules/index.js';
+
+// CLI runner
+export type { WardenOptions, WardenReport } from './cli.js';
+export { formatWardenReport, runWarden } from './cli.js';
+
+// CI formatters
+export {
+  formatGitHubAnnotations,
+  formatJson,
+  formatSummary,
+} from './formatters.js';
+
+// Drift detection
+export type { DriftResult } from './drift.js';
+export { checkDrift } from './drift.js';