@adrkit/core 0.1.0

package/src/import/merge.ts

@@ -0,0 +1,321 @@
+import { stringify } from 'yaml';
+import { AdrFrontmatter, SCHEMA_VERSION, type Adr } from '../schema/adr.schema.ts';
+import type { Finding } from '../validate/findings.ts';
+import type { MadrSourceFile } from './madr.ts';
+import { mapMadrStatus } from './status.ts';
+
+export class MadrMergeError extends Error {
+  readonly findings: Finding[];
+
+  constructor(message: string, findings: Finding[]) {
+    super(message);
+    this.name = 'MadrMergeError';
+    this.findings = findings;
+  }
+}
+
+export interface MergeMadrOptions {
+  source: MadrSourceFile;
+  id: string;
+  sourceRef: string;
+  fingerprint: string;
+}
+
+export interface MergeMadrResult {
+  frontmatter: AdrFrontmatter;
+  content: string;
+  findings: Finding[];
+}
+
+type MutableRecord = Record<string, unknown>;
+
+const FALLBACKS: Record<string, unknown> = {
+  deciders: [],
+  consulted: [],
+  informed: [],
+  tags: [],
+  scope: 'component',
+  reversibility: 'unknown',
+  blastRadius: 'component',
+  supersedes: [],
+  relatesTo: [],
+  conflictsWith: [],
+  affects: [],
+  assertions: [],
+  externalRefs: [],
+  complianceControls: [],
+};
+
+const OPTIONAL_COPY_KEYS = [
+  'created',
+  'deciders',
+  'consulted',
+  'informed',
+  'tags',
+  'scope',
+  'domain',
+  'reversibility',
+  'blastRadius',
+  'supersedes',
+  'supersededBy',
+  'relatesTo',
+  'conflictsWith',
+  'affects',
+  'assertions',
+  'review',
+  'evaluation',
+  'externalRefs',
+  'complianceControls',
+  'reviewBy',
+] as const;
+
+const OPTIONAL_REMOVE_KEYS = new Set<string>([
+  'created',
+  'domain',
+  'supersededBy',
+  'review',
+  'evaluation',
+  'reviewBy',
+]);
+
+const FRONTMATTER_ORDER = [
+  'schemaVersion',
+  'id',
+  'title',
+  'status',
+  'date',
+  'created',
+  'deciders',
+  'consulted',
+  'informed',
+  'tags',
+  'scope',
+  'domain',
+  'reversibility',
+  'blastRadius',
+  'supersedes',
+  'supersededBy',
+  'relatesTo',
+  'conflictsWith',
+  'affects',
+  'assertions',
+  'provenance',
+  'review',
+  'evaluation',
+  'externalRefs',
+  'complianceControls',
+  'reviewBy',
+] as const;
+
+function isRecord(value: unknown): value is MutableRecord {
+  return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+
+function isValidId(value: unknown): value is string {
+  return typeof value === 'string' && /^([0-9]{4,}|[0-9A-HJKMNP-TV-Za-hjkmnp-tv-z]{26})$/.test(value);
+}
+
+function isValidSchemaVersion(value: unknown): value is string {
+  return typeof value === 'string' && /^\d+\.\d+\.\d+$/.test(value);
+}
+
+function dateFrom(value: unknown): string | undefined {
+  if (value instanceof Date && !Number.isNaN(value.valueOf())) {
+    return value.toISOString().slice(0, 10);
+  }
+  if (typeof value !== 'string') return undefined;
+  const trimmed = value.trim();
+  if (!/^\d{4}-\d{2}-\d{2}$/.test(trimmed)) return undefined;
+  const parsed = new Date(`${trimmed}T00:00:00.000Z`);
+  return parsed.toISOString().slice(0, 10) === trimmed ? trimmed : undefined;
+}
+
+function titleFinding(path: string, id?: string): Finding {
+  return {
+    rule: 'import-not-madr',
+    severity: 'warn',
+    message: 'MADR source is missing a usable title',
+    path,
+    id,
+    field: 'title',
+  };
+}
+
+function importedAtFrom(value: unknown): string | undefined {
+  if (!isRecord(value)) return undefined;
+  const importedFrom = value.importedFrom;
+  if (!isRecord(importedFrom)) return undefined;
+  return typeof importedFrom.importedAt === 'string' ? importedFrom.importedAt : undefined;
+}
+
+function provenanceFrom(raw: MutableRecord, sourceRef: string, fingerprint: string): MutableRecord {
+  const sourceProvenance = isRecord(raw.provenance) ? { ...raw.provenance } : {};
+  const authoredBy = sourceProvenance.authoredBy;
+  if (authoredBy !== 'human' && authoredBy !== 'agent' && authoredBy !== 'agent-drafted') {
+    sourceProvenance.authoredBy = 'human';
+  }
+
+  const importedFrom: MutableRecord = {
+    sourceKind: 'madr',
+    sourceRef,
+    fingerprint,
+  };
+  const importedAt = importedAtFrom(sourceProvenance);
+  if (importedAt) importedFrom.importedAt = importedAt;
+
+  return {
+    ...sourceProvenance,
+    importedFrom,
+  };
+}
+
+function initialCandidate(options: MergeMadrOptions, findings: Finding[]): MutableRecord {
+  const raw = options.source.frontmatter;
+  const id = isValidId(raw.id) ? raw.id : options.id;
+  const title = options.source.title;
+  if (!title || title.length < 3 || title.length > 120) {
+    throw new MadrMergeError('MADR source is missing a usable title', [titleFinding(options.source.path, id)]);
+  }
+
+  const status = mapMadrStatus(raw.status, { path: options.source.path, id });
+  findings.push(...status.findings);
+
+  const candidate: MutableRecord = {};
+  for (const key of OPTIONAL_COPY_KEYS) {
+    if (key in raw) candidate[key] = raw[key];
+  }
+
+  candidate.schemaVersion = isValidSchemaVersion(raw.schemaVersion) ? raw.schemaVersion : SCHEMA_VERSION;
+  candidate.id = id;
+  candidate.title = title;
+  candidate.status = status.status;
+  candidate.date = dateFrom(raw.date) ?? dateFrom(raw.created) ?? '1970-01-01';
+
+  for (const [key, value] of Object.entries(FALLBACKS)) {
+    if (!(key in candidate) || candidate[key] === undefined || candidate[key] === null) {
+      candidate[key] = Array.isArray(value) ? [...value] : value;
+    }
+  }
+
+  candidate.provenance = provenanceFrom(raw, options.sourceRef, options.fingerprint);
+  return candidate;
+}
+
+function safeParseCandidate(candidate: MutableRecord, sourcePath: string): AdrFrontmatter {
+  const working = { ...candidate };
+  for (let attempt = 0; attempt < 20; attempt += 1) {
+    const parsed = AdrFrontmatter.safeParse(working);
+    if (parsed.success) return parsed.data;
+
+    let changed = false;
+    for (const issue of parsed.error.issues) {
+      const top = issue.path[0];
+      if (typeof top !== 'string') continue;
+
+      if (top in FALLBACKS) {
+        const fallback = FALLBACKS[top];
+        working[top] = Array.isArray(fallback) ? [...fallback] : fallback;
+        changed = true;
+        continue;
+      }
+
+      if (OPTIONAL_REMOVE_KEYS.has(top)) {
+        delete working[top];
+        changed = true;
+        continue;
+      }
+
+      if (top === 'provenance') {
+        working.provenance = candidate.provenance;
+        changed = true;
+      }
+    }
+
+    if (!changed) {
+      throw new MadrMergeError(
+        `Migrated frontmatter for ${sourcePath} would not satisfy the adrkit schema`,
+        parsed.error.issues.map((issue) => ({
+          rule: 'import-not-madr',
+          severity: 'warn' as const,
+          message: issue.message,
+          path: sourcePath,
+          id: typeof working.id === 'string' ? working.id : undefined,
+          field: issue.path.length > 0 ? issue.path.map(String).join('.') : 'frontmatter',
+        })),
+      );
+    }
+  }
+
+  throw new MadrMergeError(`Unable to produce valid frontmatter for ${sourcePath}`, [
+    {
+      rule: 'import-not-madr',
+      severity: 'warn',
+      message: 'Unable to produce valid frontmatter after removing invalid optional fields',
+      path: sourcePath,
+      id: typeof working.id === 'string' ? working.id : undefined,
+      field: 'frontmatter',
+    },
+  ]);
+}
+
+function orderedObject(value: MutableRecord, order: readonly string[]): MutableRecord {
+  const output: MutableRecord = {};
+  for (const key of order) {
+    if (value[key] !== undefined) output[key] = value[key];
+  }
+  for (const key of Object.keys(value).sort()) {
+    if (!(key in output) && value[key] !== undefined) output[key] = value[key];
+  }
+  return output;
+}
+
+function orderProvenance(provenance: NonNullable<AdrFrontmatter['provenance']>): MutableRecord {
+  const output: MutableRecord = {};
+  for (const key of ['authoredBy', 'agent', 'ratifiedBy', 'sourceArtifact'] as const) {
+    if (provenance[key] !== undefined) output[key] = provenance[key];
+  }
+  if (provenance.importedFrom) {
+    const importedFrom: MutableRecord = {
+      sourceKind: provenance.importedFrom.sourceKind,
+      sourceRef: provenance.importedFrom.sourceRef,
+      fingerprint: provenance.importedFrom.fingerprint,
+    };
+    if (provenance.importedFrom.importedAt) importedFrom.importedAt = provenance.importedFrom.importedAt;
+    output.importedFrom = importedFrom;
+  }
+  return output;
+}
+
+function orderedFrontmatter(frontmatter: AdrFrontmatter): MutableRecord {
+  const raw = frontmatter as unknown as MutableRecord;
+  const output = orderedObject(raw, FRONTMATTER_ORDER);
+  if (frontmatter.provenance) output.provenance = orderProvenance(frontmatter.provenance);
+  return output;
+}
+
+export function renderMigratedContent(frontmatter: AdrFrontmatter, body: string): string {
+  const yaml = stringify(orderedFrontmatter(frontmatter), {
+    lineWidth: 0,
+    sortMapEntries: false,
+  }).trimEnd();
+  return `---\n${yaml}\n---\n${body}`;
+}
+
+export function mergeMadr(options: MergeMadrOptions): MergeMadrResult {
+  const findings: Finding[] = [];
+  const candidate = initialCandidate(options, findings);
+  const frontmatter = safeParseCandidate(candidate, options.source.path);
+  return {
+    frontmatter,
+    content: renderMigratedContent(frontmatter, options.source.body),
+    findings,
+  };
+}
+
+export function recordFromMerge(result: MergeMadrResult, source: MadrSourceFile): Adr {
+  return {
+    frontmatter: result.frontmatter,
+    body: source.body,
+    path: source.path,
+  };
+}

package/src/import/status.ts

@@ -0,0 +1,48 @@
+import type { AdrFrontmatter } from '../schema/adr.schema.ts';
+import type { Finding } from '../validate/findings.ts';
+
+export const MADR_RECOGNIZED_STATUSES = [
+  'draft',
+  'proposed',
+  'accepted',
+  'rejected',
+  'superseded',
+  'deprecated',
+] as const satisfies readonly AdrFrontmatter['status'][];
+
+const STATUS_SET = new Set<string>(MADR_RECOGNIZED_STATUSES);
+
+export interface MadrStatusMapping {
+  status: AdrFrontmatter['status'];
+  findings: Finding[];
+}
+
+function rawStatusText(status: unknown): string | undefined {
+  if (typeof status !== 'string') return undefined;
+  const trimmed = status.trim();
+  return trimmed.length > 0 ? trimmed : undefined;
+}
+
+export function mapMadrStatus(status: unknown, context: { path: string; id?: string }): MadrStatusMapping {
+  const raw = rawStatusText(status);
+  const normalized = raw?.toLowerCase();
+  if (normalized && STATUS_SET.has(normalized)) {
+    return { status: normalized as AdrFrontmatter['status'], findings: [] };
+  }
+
+  return {
+    status: 'proposed',
+    findings: [
+      {
+        rule: 'import-status-unrecognized',
+        severity: 'warn',
+        message: raw
+          ? `MADR status "${raw}" is not recognized; using "proposed"`
+          : 'MADR status is missing; using "proposed"',
+        path: context.path,
+        id: context.id,
+        field: 'status',
+      },
+    ],
+  };
+}

package/src/index.ts

@@ -0,0 +1,13 @@
+export * from './schema/index.ts';
+export * from './parse/frontmatter.ts';
+export * from './load/corpus.ts';
+export * from './validate/findings.ts';
+export * from './validate/contract.ts';
+export * from './validate/corpus-invariants.ts';
+export * from './validate/import-incomplete.ts';
+export * from './validate/index.ts';
+export * from './scaffold/new.ts';
+export * from './graph/build.ts';
+export * from './affects/index.ts';
+export * from './check/index.ts';
+export * from './import/index.ts';

package/src/load/corpus.ts

@@ -0,0 +1,101 @@
+import { readdir, readFile, stat } from 'node:fs/promises';
+import { basename, isAbsolute, join, relative, resolve, sep } from 'node:path';
+import { AdrFrontmatter, type Adr } from '../schema/adr.schema.ts';
+import { parseFrontmatter } from '../parse/frontmatter.ts';
+
+export const RECORD_FILE_PATTERN = /^[0-9]{4,}-.+\.md$/;
+export const TEMPLATE_FILE_NAME = '0000-template.md';
+
+export interface ParsedAdrFile {
+  data: unknown;
+  body: string;
+  path: string;
+  absolutePath: string;
+}
+
+export interface Corpus {
+  records: Adr[];
+  byId: Map<string, Adr>;
+}
+
+export function isRecordFileName(fileName: string): boolean {
+  return fileName !== TEMPLATE_FILE_NAME && RECORD_FILE_PATTERN.test(fileName);
+}
+
+export function normalizeDisplayPath(path: string, cwd = process.cwd()): string {
+  const absolutePath = isAbsolute(path) ? path : resolve(cwd, path);
+  const displayPath = relative(cwd, absolutePath) || basename(absolutePath);
+  return displayPath.split(sep).join('/');
+}
+
+function toAbsolutePath(path: string, cwd = process.cwd()): string {
+  return isAbsolute(path) ? path : resolve(cwd, path);
+}
+
+export async function discoverAdrFiles(dir = 'docs/adr', cwd = process.cwd()): Promise<string[]> {
+  const absoluteDir = toAbsolutePath(dir, cwd);
+  const entries = await readdir(absoluteDir, { withFileTypes: true });
+  return entries
+    .filter((entry) => entry.isFile() && isRecordFileName(entry.name))
+    .map((entry) => join(absoluteDir, entry.name))
+    .sort((a, b) => normalizeDisplayPath(a, cwd).localeCompare(normalizeDisplayPath(b, cwd)));
+}
+
+export async function expandRecordInputs(
+  paths: string[] | undefined,
+  dir = 'docs/adr',
+  cwd = process.cwd(),
+): Promise<string[]> {
+  if (!paths || paths.length === 0) {
+    return discoverAdrFiles(dir, cwd);
+  }
+
+  const expanded: string[] = [];
+  for (const inputPath of paths) {
+    const absolutePath = toAbsolutePath(inputPath, cwd);
+    try {
+      const inputStat = await stat(absolutePath);
+      if (inputStat.isDirectory()) {
+        expanded.push(...(await discoverAdrFiles(absolutePath, cwd)));
+      } else if (inputStat.isFile()) {
+        expanded.push(absolutePath);
+      }
+    } catch {
+      expanded.push(absolutePath);
+    }
+  }
+
+  return Array.from(new Set(expanded)).sort((a, b) =>
+    normalizeDisplayPath(a, cwd).localeCompare(normalizeDisplayPath(b, cwd)),
+  );
+}
+
+export async function parseAdrFile(path: string, cwd = process.cwd()): Promise<ParsedAdrFile> {
+  const absolutePath = toAbsolutePath(path, cwd);
+  const source = await readFile(absolutePath, 'utf8');
+  const parsed = parseFrontmatter(source);
+  return {
+    ...parsed,
+    absolutePath,
+    path: normalizeDisplayPath(absolutePath, cwd),
+  };
+}
+
+export async function loadAdrFile(path: string, cwd = process.cwd()): Promise<Adr> {
+  const parsed = await parseAdrFile(path, cwd);
+  return {
+    frontmatter: AdrFrontmatter.parse(parsed.data),
+    body: parsed.body,
+    path: parsed.path,
+  };
+}
+
+export async function loadCorpus(dir = 'docs/adr', cwd = process.cwd()): Promise<Corpus> {
+  const files = await discoverAdrFiles(dir, cwd);
+  const records = await Promise.all(files.map((file) => loadAdrFile(file, cwd)));
+  const byId = new Map<string, Adr>();
+  for (const record of records) {
+    byId.set(record.frontmatter.id, record);
+  }
+  return { records, byId };
+}

package/src/parse/frontmatter.ts

@@ -0,0 +1,73 @@
+import { parseDocument } from 'yaml';
+
+export type FrontmatterErrorCode =
+  | 'missing-frontmatter'
+  | 'unterminated-frontmatter'
+  | 'invalid-yaml';
+
+export class FrontmatterError extends Error {
+  readonly code: FrontmatterErrorCode;
+
+  constructor(code: FrontmatterErrorCode, message: string) {
+    super(message);
+    this.name = 'FrontmatterError';
+    this.code = code;
+  }
+}
+
+export interface ParsedFrontmatter {
+  data: unknown;
+  body: string;
+}
+
+function lineContent(source: string, start: number, end: number): string {
+  const raw = source.slice(start, end);
+  return raw.endsWith('\r') ? raw.slice(0, -1) : raw;
+}
+
+export function parseFrontmatter(source: string): ParsedFrontmatter {
+  const firstLineEnd = source.indexOf('\n');
+  const firstLine = firstLineEnd === -1 ? source : source.slice(0, firstLineEnd);
+
+  if ((firstLine.endsWith('\r') ? firstLine.slice(0, -1) : firstLine) !== '---') {
+    throw new FrontmatterError(
+      'missing-frontmatter',
+      'ADR files must start with a leading --- YAML frontmatter fence',
+    );
+  }
+
+  if (firstLineEnd === -1) {
+    throw new FrontmatterError(
+      'unterminated-frontmatter',
+      'ADR frontmatter is missing its closing --- fence',
+    );
+  }
+
+  let lineStart = firstLineEnd + 1;
+  while (lineStart <= source.length) {
+    const nextNewline = source.indexOf('\n', lineStart);
+    const lineEnd = nextNewline === -1 ? source.length : nextNewline;
+    if (lineContent(source, lineStart, lineEnd) === '---') {
+      const yamlSource = source.slice(firstLineEnd + 1, lineStart);
+      const bodyStart = nextNewline === -1 ? source.length : nextNewline + 1;
+      const document = parseDocument(yamlSource, { strict: true, prettyErrors: false });
+      if (document.errors.length > 0) {
+        throw new FrontmatterError(
+          'invalid-yaml',
+          document.errors.map((error) => error.message).join('; '),
+        );
+      }
+      return { data: document.toJS(), body: source.slice(bodyStart) };
+    }
+
+    if (nextNewline === -1) {
+      break;
+    }
+    lineStart = nextNewline + 1;
+  }
+
+  throw new FrontmatterError(
+    'unterminated-frontmatter',
+    'ADR frontmatter is missing its closing --- fence',
+  );
+}