@ontrails/warden 0.2.0

package/src/project-rules.ts

@@ -0,0 +1,290 @@
+import { statSync } from 'node:fs';
+import { basename, join } from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+import type {
+  ProjectAwareWardenRule,
+  TopoAwareWardenRule,
+  WardenDiagnostic,
+  WardenRuleMetadata,
+  WardenRule,
+} from './rules/types.js';
+
+const PROJECT_WARDEN_RULES_FILE = '.trails/rules.ts';
+const PROJECT_WARDEN_RULES_DIR = '.trails/rules';
+const LEGACY_PROJECT_WARDEN_RULES_DIR = 'trails/warden/rules';
+
+export interface ProjectWardenRules {
+  readonly diagnostics: readonly WardenDiagnostic[];
+  readonly sourceRules: readonly WardenRule[];
+  readonly topoRules: readonly TopoAwareWardenRule[];
+}
+
+interface RuleModule {
+  readonly default?: unknown;
+  readonly rule?: unknown;
+  readonly rules?: unknown;
+  readonly sourceRule?: unknown;
+  readonly sourceRules?: unknown;
+  readonly topoRule?: unknown;
+  readonly topoRules?: unknown;
+}
+
+interface ProjectRuleModulePaths {
+  readonly diagnostics: readonly WardenDiagnostic[];
+  readonly files: readonly string[];
+}
+
+interface LoadedRuleFile extends ProjectWardenRules {
+  readonly filePath: string;
+}
+
+const diagnostic = (message: string, filePath: string): WardenDiagnostic => ({
+  filePath,
+  line: 1,
+  message,
+  rule: 'project-warden-rules',
+  severity: 'error',
+});
+
+const asArray = (value: unknown): readonly unknown[] => {
+  if (value === undefined) {
+    return [];
+  }
+  return Array.isArray(value) ? value : [value];
+};
+
+const isSourceRule = (value: unknown): value is WardenRule => {
+  if (typeof value !== 'object' || value === null) {
+    return false;
+  }
+  const maybe = value as Partial<WardenRule>;
+  return (
+    typeof maybe.name === 'string' &&
+    typeof maybe.description === 'string' &&
+    (maybe.severity === 'error' || maybe.severity === 'warn') &&
+    typeof maybe.check === 'function'
+  );
+};
+
+const isTopoRule = (value: unknown): value is TopoAwareWardenRule => {
+  if (typeof value !== 'object' || value === null) {
+    return false;
+  }
+  const maybe = value as Partial<TopoAwareWardenRule>;
+  return (
+    typeof maybe.name === 'string' &&
+    typeof maybe.description === 'string' &&
+    (maybe.severity === 'error' || maybe.severity === 'warn') &&
+    typeof maybe.checkTopo === 'function'
+  );
+};
+
+const defaultProjectRuleDepth = (
+  tier: WardenRuleMetadata['tier']
+): WardenRuleMetadata['depth'] => {
+  if (tier === 'topo-aware') {
+    return 'topo';
+  }
+  if (tier === 'project-static') {
+    return 'project';
+  }
+  return 'source';
+};
+
+const defaultProjectRuleMetadata = (
+  rule: { readonly description: string },
+  tier: WardenRuleMetadata['tier']
+): WardenRuleMetadata => ({
+  concern: 'general',
+  depth: defaultProjectRuleDepth(tier),
+  invariant: rule.description,
+  lifecycle: { state: 'durable' },
+  scope: 'repo-local',
+  tier,
+});
+
+const isProjectAwareSourceRule = (
+  rule: WardenRule
+): rule is ProjectAwareWardenRule =>
+  'checkWithContext' in rule && typeof rule.checkWithContext === 'function';
+
+const withSourceRuleMetadata = (rule: WardenRule): WardenRule => ({
+  ...rule,
+  metadata:
+    rule.metadata ??
+    defaultProjectRuleMetadata(
+      rule,
+      isProjectAwareSourceRule(rule) ? 'project-static' : 'source-static'
+    ),
+});
+
+const withTopoRuleMetadata = (
+  rule: TopoAwareWardenRule
+): TopoAwareWardenRule => ({
+  ...rule,
+  metadata: rule.metadata ?? defaultProjectRuleMetadata(rule, 'topo-aware'),
+});
+
+const ruleCandidatesFromModule = (module: RuleModule): readonly unknown[] => [
+  ...asArray(module.default),
+  ...asArray(module.rule),
+  ...asArray(module.rules),
+  ...asArray(module.sourceRule),
+  ...asArray(module.sourceRules),
+];
+
+const topoRuleCandidatesFromModule = (
+  module: RuleModule
+): readonly unknown[] => [
+  ...asArray(module.topoRule),
+  ...asArray(module.topoRules),
+];
+
+const isFile = (path: string): boolean => {
+  try {
+    return statSync(path).isFile();
+  } catch {
+    return false;
+  }
+};
+
+const isDirectory = (path: string): boolean => {
+  try {
+    return statSync(path).isDirectory();
+  } catch {
+    return false;
+  }
+};
+
+const collectProjectRuleFiles = (rootDir: string): readonly string[] => {
+  const files: string[] = [];
+  const rulesFile = join(rootDir, PROJECT_WARDEN_RULES_FILE);
+  const rulesDir = join(rootDir, PROJECT_WARDEN_RULES_DIR);
+
+  if (isFile(rulesFile)) {
+    files.push(rulesFile);
+  }
+
+  if (!isDirectory(rulesDir)) {
+    return files;
+  }
+
+  const glob = new Bun.Glob('*.ts');
+  files.push(
+    ...[...glob.scanSync({ cwd: rulesDir, onlyFiles: true })]
+      .filter(
+        (entry) =>
+          !entry.endsWith('.test.ts') && !basename(entry).startsWith('_')
+      )
+      .map((entry) => join(rulesDir, entry))
+  );
+  return files.toSorted((left, right) => left.localeCompare(right));
+};
+
+const collectProjectRuleModulePaths = (
+  rootDir: string
+): ProjectRuleModulePaths => {
+  const diagnostics: WardenDiagnostic[] = [];
+  const legacyRulesDir = join(rootDir, LEGACY_PROJECT_WARDEN_RULES_DIR);
+
+  if (isDirectory(legacyRulesDir)) {
+    diagnostics.push(
+      diagnostic(
+        'Project Warden rules moved from trails/warden/rules to .trails/rules.ts or direct .trails/rules/*.ts files.',
+        legacyRulesDir
+      )
+    );
+  }
+
+  return {
+    diagnostics,
+    files: collectProjectRuleFiles(rootDir),
+  };
+};
+
+const loadRuleFile = async (filePath: string): Promise<LoadedRuleFile> => {
+  let module: RuleModule;
+  try {
+    module = (await import(pathToFileURL(filePath).href)) as RuleModule;
+  } catch (error) {
+    return {
+      diagnostics: [
+        diagnostic(
+          error instanceof Error
+            ? `Failed to load project Warden rule module: ${error.message}`
+            : 'Failed to load project Warden rule module.',
+          filePath
+        ),
+      ],
+      filePath,
+      sourceRules: [],
+      topoRules: [],
+    };
+  }
+
+  const sourceRules = ruleCandidatesFromModule(module)
+    .filter(isSourceRule)
+    .map(withSourceRuleMetadata);
+  const topoRules = topoRuleCandidatesFromModule(module)
+    .filter(isTopoRule)
+    .map(withTopoRuleMetadata);
+  if (sourceRules.length === 0 && topoRules.length === 0) {
+    return {
+      diagnostics: [
+        diagnostic(
+          'Project Warden rule module must export a WardenRule or TopoAwareWardenRule.',
+          filePath
+        ),
+      ],
+      filePath,
+      sourceRules: [],
+      topoRules: [],
+    };
+  }
+
+  return { diagnostics: [], filePath, sourceRules, topoRules };
+};
+
+const duplicateRuleDiagnostics = (
+  loaded: readonly LoadedRuleFile[]
+): readonly WardenDiagnostic[] => {
+  const seen = new Map<string, string>();
+  const diagnostics: WardenDiagnostic[] = [];
+
+  for (const result of loaded) {
+    for (const rule of [...result.sourceRules, ...result.topoRules]) {
+      const previousFilePath = seen.get(rule.name);
+      if (previousFilePath === undefined) {
+        seen.set(rule.name, result.filePath);
+        continue;
+      }
+      diagnostics.push(
+        diagnostic(
+          `Duplicate project Warden rule id "${rule.name}" also exported from "${previousFilePath}". Project-local rule ids must be unique.`,
+          result.filePath
+        )
+      );
+    }
+  }
+
+  return diagnostics;
+};
+
+export const loadProjectWardenRules = async (
+  rootDir: string
+): Promise<ProjectWardenRules> => {
+  const collected = collectProjectRuleModulePaths(rootDir);
+  const { files } = collected;
+  const loaded = await Promise.all(files.map(loadRuleFile));
+
+  return {
+    diagnostics: [
+      ...collected.diagnostics,
+      ...loaded.flatMap((result) => result.diagnostics),
+      ...duplicateRuleDiagnostics(loaded),
+    ],
+    sourceRules: loaded.flatMap((result) => result.sourceRules),
+    topoRules: loaded.flatMap((result) => result.topoRules),
+  };
+};

package/src/regrade-history.ts

@@ -0,0 +1,188 @@
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { join, relative } from 'node:path';
+
+import {
+  getGovernedVocabularyTransition,
+  listGovernedVocabularyTransitions,
+} from './rules/retired-vocabulary.js';
+import { resolveReceiptForWarden } from './regrade-receipt.js';
+import type {
+  GovernedVocabularyHistoryEvidence,
+  GovernedVocabularyHistoryIssue,
+} from './rules/types.js';
+
+export interface GovernedVocabularyHistoryIndex {
+  readonly byTransitionId: ReadonlyMap<
+    string,
+    GovernedVocabularyHistoryEvidence
+  >;
+  readonly issues: readonly GovernedVocabularyHistoryIssue[];
+}
+
+const normalizePath = (value: string): string => value.replaceAll('\\', '/');
+
+type HistoryFileResult =
+  | {
+      readonly kind: 'evidence';
+      readonly value: GovernedVocabularyHistoryEvidence;
+    }
+  | { readonly kind: 'ignore' }
+  | { readonly kind: 'issue'; readonly value: GovernedVocabularyHistoryIssue };
+
+const historyIssue = (
+  path: string,
+  message: string,
+  transitionId?: string
+): HistoryFileResult => ({
+  kind: 'issue',
+  value: {
+    message,
+    path,
+    ...(transitionId === undefined ? {} : { transitionId }),
+  },
+});
+
+type GovernedReceiptPlan =
+  | { readonly kind: 'class' }
+  | {
+      readonly from: string;
+      readonly id?: string | undefined;
+      readonly kind: 'vocabulary';
+      readonly to: string;
+    };
+
+const governedTransitionForPlan = (
+  plan: GovernedReceiptPlan,
+  transitionIds: readonly (string | undefined)[] = []
+) => {
+  if (plan.kind !== 'vocabulary') {
+    return;
+  }
+  for (const transitionId of [plan.id, ...transitionIds]) {
+    if (transitionId === undefined) {
+      continue;
+    }
+    const transition = getGovernedVocabularyTransition(transitionId);
+    if (transition !== undefined) {
+      return transition;
+    }
+  }
+  return listGovernedVocabularyTransitions().find(
+    (transition) =>
+      transition.from === plan.from &&
+      (transition.target.kind === 'single'
+        ? transition.target.to === plan.to
+        : transition.target.options.some((option) => option.to === plan.to))
+  );
+};
+
+const loadReceiptHistoryFile = (
+  json: unknown,
+  observedPath: string
+): HistoryFileResult => {
+  const resolved = resolveReceiptForWarden(json);
+  if (resolved.value === undefined) {
+    return historyIssue(
+      observedPath,
+      `Committed Regrade receipt has invalid deterministic evidence (${resolved.error ?? 'unknown error'}).`
+    );
+  }
+  const { artifact, runs } = resolved.value;
+  if (normalizePath(artifact.path) !== observedPath) {
+    return historyIssue(
+      observedPath,
+      'Committed Regrade history path does not match its observed file.'
+    );
+  }
+  const latest = runs.at(-1);
+  const transition =
+    latest === undefined
+      ? undefined
+      : governedTransitionForPlan(latest.plan, [artifact.id]);
+  if (transition === undefined) {
+    return { kind: 'ignore' };
+  }
+  const allRunsMatchTransition = runs.every(({ plan }) => {
+    if (
+      plan.kind !== 'vocabulary' ||
+      governedTransitionForPlan(plan, [artifact.id])?.id !== transition.id ||
+      plan.from !== transition.from
+    ) {
+      return false;
+    }
+    return transition.target.kind === 'single'
+      ? transition.target.to === plan.to
+      : transition.target.options.some((option) => option.to === plan.to);
+  });
+  if (!allRunsMatchTransition) {
+    return historyIssue(
+      observedPath,
+      'Committed Regrade history does not match its governed registry transition.',
+      transition.id
+    );
+  }
+  return {
+    kind: 'evidence',
+    value: {
+      caseSensitive: latest?.caseSensitive ?? false,
+      id: artifact.id,
+      latestFormJudgments: latest?.forms ?? [],
+      path: artifact.path,
+      runCount: runs.length,
+      transitionId: transition.id,
+    },
+  };
+};
+
+const loadHistoryFile = (rootDir: string, name: string): HistoryFileResult => {
+  const absolutePath = join(rootDir, '.trails', 'regrade', 'history', name);
+  const observedPath = normalizePath(relative(rootDir, absolutePath));
+  let json: unknown;
+  try {
+    json = JSON.parse(readFileSync(absolutePath, 'utf8'));
+  } catch {
+    return historyIssue(
+      observedPath,
+      'Committed Regrade history is not valid JSON.'
+    );
+  }
+  return loadReceiptHistoryFile(json, observedPath);
+};
+
+export const loadGovernedVocabularyHistory = (
+  rootDir: string
+): GovernedVocabularyHistoryIndex => {
+  const directory = join(rootDir, '.trails', 'regrade', 'history');
+  if (!existsSync(directory)) {
+    return { byTransitionId: new Map(), issues: [] };
+  }
+
+  const byTransitionId = new Map<string, GovernedVocabularyHistoryEvidence>();
+  const issues: GovernedVocabularyHistoryIssue[] = [];
+  const files = readdirSync(directory)
+    .filter((name) => name.endsWith('.json'))
+    .toSorted();
+
+  for (const name of files) {
+    const result = loadHistoryFile(rootDir, name);
+    if (result.kind === 'ignore') {
+      continue;
+    }
+    if (result.kind === 'issue') {
+      issues.push(result.value);
+      continue;
+    }
+    if (byTransitionId.has(result.value.transitionId)) {
+      issues.push({
+        message:
+          'Multiple committed Regrade histories claim the same governed transition.',
+        path: result.value.path,
+        transitionId: result.value.transitionId,
+      });
+      continue;
+    }
+    byTransitionId.set(result.value.transitionId, result.value);
+  }
+
+  return { byTransitionId, issues };
+};