@adrkit/core 0.1.0

package/src/validate/contract.ts

@@ -0,0 +1,120 @@
+import type { z } from 'zod';
+import { AdrFrontmatter, type Adr } from '../schema/adr.schema.ts';
+import type { ParsedAdrFile } from '../load/corpus.ts';
+import type { Finding } from './findings.ts';
+
+export interface ContractValidationResult {
+  record?: Adr;
+  findings: Finding[];
+}
+
+function fieldPath(path: readonly PropertyKey[]): string | undefined {
+  return path.length === 0 ? undefined : path.map(String).join('.');
+}
+
+function rawId(data: unknown): string | undefined {
+  if (data && typeof data === 'object' && 'id' in data) {
+    const id = (data as { id?: unknown }).id;
+    return typeof id === 'string' ? id : undefined;
+  }
+  return undefined;
+}
+
+function ruleForIssue(issue: z.core.$ZodIssue): string {
+  if (issue.code === 'unrecognized_keys') {
+    return 'strict-unknown-key';
+  }
+
+  if (issue.code === 'custom') {
+    if (issue.message === 'status "superseded" requires supersededBy') {
+      return 'superseded-requires-supersededBy';
+    }
+    if (issue.message === 'supersededBy is set but status is not "superseded"') {
+      return 'supersededBy-requires-superseded-status';
+    }
+    if (issue.message === 'an accepted decision must name at least one decider, unless it was imported') {
+      return 'accepted-requires-decider-unless-imported';
+    }
+    if (
+      issue.message ===
+      'an agent-authored record cannot reach "accepted" without a named human ratifier'
+    ) {
+      return 'agent-accepted-requires-ratifier';
+    }
+    if (issue.message === 'one-way-door decisions may not take the auto-approve fast path') {
+      return 'one-way-door-disallows-auto';
+    }
+    if (issue.message === 'Items must be unique') {
+      return 'unique-items';
+    }
+    return 'contract-refinement';
+  }
+
+  if (issue.code === 'invalid_type') {
+    return issue.message.includes('undefined') ? 'required-field' : 'invalid-type';
+  }
+
+  if (issue.code === 'invalid_value') {
+    return 'invalid-enum-value';
+  }
+
+  if (issue.code === 'invalid_format') {
+    return 'invalid-format';
+  }
+
+  if (issue.code === 'too_small' || issue.code === 'too_big') {
+    return 'invalid-size';
+  }
+
+  return `contract-${issue.code}`;
+}
+
+function issueFindings(issue: z.core.$ZodIssue, path: string, id?: string): Finding[] {
+  if (issue.code === 'unrecognized_keys') {
+    return issue.keys.map((key) => {
+      const field = fieldPath([...issue.path, key]) ?? key;
+      return {
+        rule: 'strict-unknown-key',
+        severity: 'error' as const,
+        message: `Unknown frontmatter field "${field}" is not allowed`,
+        path,
+        id,
+        field,
+      };
+    });
+  }
+
+  return [
+    {
+      rule: ruleForIssue(issue),
+      severity: 'error',
+      message: issue.message,
+      path,
+      id,
+      field: fieldPath(issue.path),
+    },
+  ];
+}
+
+export function validateParsedAdr(parsed: ParsedAdrFile): ContractValidationResult {
+  const result = AdrFrontmatter.safeParse(parsed.data);
+  if (result.success) {
+    return {
+      findings: [],
+      record: {
+        frontmatter: result.data,
+        body: parsed.body,
+        path: parsed.path,
+      },
+    };
+  }
+
+  const id = rawId(parsed.data);
+  return {
+    findings: result.error.issues.flatMap((issue) => issueFindings(issue, parsed.path, id)),
+  };
+}
+
+export function validateAdrFrontmatter(data: unknown, path: string): ContractValidationResult {
+  return validateParsedAdr({ data, body: '', path, absolutePath: path });
+}

package/src/validate/corpus-invariants.ts

@@ -0,0 +1,77 @@
+import type { Adr } from '../schema/adr.schema.ts';
+import type { Finding, FindingSeverity } from './findings.ts';
+
+function addReferenceFinding(
+  findings: Finding[],
+  record: Adr,
+  field: string,
+  ref: string,
+  severity: FindingSeverity,
+): void {
+  findings.push({
+    rule: `dangling-${field}`,
+    severity,
+    message: `Reference "${ref}" in ${field} does not resolve to a record in the corpus`,
+    path: record.path,
+    id: record.frontmatter.id,
+    field,
+  });
+}
+
+export function validateCorpusInvariants(records: readonly Adr[]): Finding[] {
+  const findings: Finding[] = [];
+  const byId = new Map<string, Adr[]>();
+
+  for (const record of records) {
+    const recordsForId = byId.get(record.frontmatter.id) ?? [];
+    recordsForId.push(record);
+    byId.set(record.frontmatter.id, recordsForId);
+  }
+
+  for (const [id, duplicates] of byId) {
+    if (duplicates.length <= 1) continue;
+    const paths = duplicates.map((record) => record.path).sort();
+    for (const record of duplicates) {
+      findings.push({
+        rule: 'unique-id',
+        severity: 'error',
+        message: `ADR id "${id}" is used by multiple records: ${paths.join(', ')}`,
+        path: record.path,
+        id,
+        field: 'id',
+      });
+    }
+  }
+
+  const ids = new Set(byId.keys());
+  for (const record of records) {
+    for (const ref of record.frontmatter.supersedes) {
+      if (!ids.has(ref)) addReferenceFinding(findings, record, 'supersedes', ref, 'error');
+    }
+
+    if (record.frontmatter.supersededBy && !ids.has(record.frontmatter.supersededBy)) {
+      addReferenceFinding(findings, record, 'supersededBy', record.frontmatter.supersededBy, 'error');
+    }
+
+    for (const ref of record.frontmatter.relatesTo) {
+      if (!ids.has(ref)) addReferenceFinding(findings, record, 'relatesTo', ref, 'error');
+    }
+
+    for (const ref of record.frontmatter.conflictsWith) {
+      if (!ids.has(ref)) {
+        addReferenceFinding(findings, record, 'conflictsWith', ref, 'warn');
+      } else if (record.frontmatter.status === 'accepted') {
+        findings.push({
+          rule: 'accepted-conflictsWith',
+          severity: 'warn',
+          message: `Accepted ADR declares a known conflict with "${ref}"`,
+          path: record.path,
+          id: record.frontmatter.id,
+          field: 'conflictsWith',
+        });
+      }
+    }
+  }
+
+  return findings;
+}

package/src/validate/findings.ts

@@ -0,0 +1,51 @@
+export const IMPORT_FINDING_RULES = [
+  'import-incomplete',
+  'import-status-unrecognized',
+  'import-not-madr',
+] as const;
+
+export type ImportFindingRule = (typeof IMPORT_FINDING_RULES)[number];
+
+export type FindingSeverity = 'error' | 'warn' | 'info';
+
+export interface Finding {
+  rule: string;
+  severity: FindingSeverity;
+  message: string;
+  path?: string;
+  id?: string;
+  field?: string;
+  pattern?: string;
+}
+
+function compareOptional(a: string | undefined, b: string | undefined): number {
+  return (a ?? '').localeCompare(b ?? '');
+}
+
+export function sortFindings(findings: readonly Finding[]): Finding[] {
+  return [...findings].sort(
+    (a, b) =>
+      a.rule.localeCompare(b.rule) ||
+      compareOptional(a.id, b.id) ||
+      compareOptional(a.pattern, b.pattern) ||
+      compareOptional(a.path, b.path) ||
+      compareOptional(a.field, b.field) ||
+      a.message.localeCompare(b.message),
+  );
+}
+
+export function countFindings(findings: readonly Finding[]): { errors: number; warnings: number; infos: number } {
+  let errors = 0;
+  let warnings = 0;
+  let infos = 0;
+  for (const finding of findings) {
+    if (finding.severity === 'error') errors += 1;
+    if (finding.severity === 'warn') warnings += 1;
+    if (finding.severity === 'info') infos += 1;
+  }
+  return { errors, warnings, infos };
+}
+
+export function exitCodeForFindings(findings: readonly Finding[]): 0 | 1 {
+  return findings.some((finding) => finding.severity === 'error') ? 1 : 0;
+}

package/src/validate/import-incomplete.ts

@@ -0,0 +1,23 @@
+import type { Adr } from '../schema/adr.schema.ts';
+import type { Finding } from './findings.ts';
+
+export function validateImportIncomplete(records: readonly Adr[]): Finding[] {
+  const findings: Finding[] = [];
+
+  for (const record of records) {
+    if (!record.frontmatter.provenance?.importedFrom) continue;
+
+    if (record.frontmatter.status === 'accepted' && record.frontmatter.deciders.length === 0) {
+      findings.push({
+        rule: 'import-incomplete',
+        severity: 'info',
+        message: 'Imported accepted decision has no deciders; provenance explains the gap, but it should be backfilled when known',
+        path: record.path,
+        id: record.frontmatter.id,
+        field: 'deciders',
+      });
+    }
+  }
+
+  return findings;
+}

package/src/validate/index.ts

@@ -0,0 +1,68 @@
+import { parseAdrFile, expandRecordInputs, normalizeDisplayPath } from '../load/corpus.ts';
+import type { Adr } from '../schema/adr.schema.ts';
+import { FrontmatterError } from '../parse/frontmatter.ts';
+import { validateParsedAdr } from './contract.ts';
+import { validateCorpusInvariants } from './corpus-invariants.ts';
+import { validateImportIncomplete } from './import-incomplete.ts';
+import { sortFindings, type Finding } from './findings.ts';
+
+export interface LintCorpusOptions {
+  dir?: string;
+  paths?: string[];
+  cwd?: string;
+}
+
+export interface LintCorpusResult {
+  checked: number;
+  findings: Finding[];
+  records: Adr[];
+}
+
+function parseErrorFinding(error: unknown, path: string): Finding {
+  if (error instanceof FrontmatterError) {
+    return {
+      rule: error.code === 'invalid-yaml' ? 'frontmatter-parse' : 'frontmatter-fence',
+      severity: 'error',
+      message: error.message,
+      path,
+      field: 'frontmatter',
+    };
+  }
+
+  return {
+    rule: 'file-read',
+    severity: 'error',
+    message: error instanceof Error ? error.message : String(error),
+    path,
+  };
+}
+
+export async function lintCorpus(options: LintCorpusOptions = {}): Promise<LintCorpusResult> {
+  const cwd = options.cwd ?? process.cwd();
+  const files = await expandRecordInputs(options.paths, options.dir ?? 'docs/adr', cwd);
+  const records: Adr[] = [];
+  const findings: Finding[] = [];
+
+  for (const file of files) {
+    const displayPath = normalizeDisplayPath(file, cwd);
+    try {
+      const parsed = await parseAdrFile(file, cwd);
+      const result = validateParsedAdr(parsed);
+      findings.push(...result.findings);
+      if (result.record) {
+        records.push(result.record);
+      }
+    } catch (error) {
+      findings.push(parseErrorFinding(error, displayPath));
+    }
+  }
+
+  findings.push(...validateImportIncomplete(records));
+  findings.push(...validateCorpusInvariants(records));
+
+  return {
+    checked: files.length,
+    findings: sortFindings(findings),
+    records: [...records].sort((a, b) => a.frontmatter.id.localeCompare(b.frontmatter.id)),
+  };
+}