《互联网产品的客户端架构·规模化与架构演进》11.1 架构决策记录与契约

// file: src/governance/adr-contract.ts
// tier: L1
// verify: node --test test/governance/adr-contract.test.ts

export type AdrStatus = "proposed" | "accepted" | "deprecated" | "superseded";
export type ContractChangeKind = "breaking" | "additive" | "fix";

export type Adr = {
  id: string;
  title: string;
  status: AdrStatus;
  date: string;
  context: string;
  decision: string;
  consequences: string;
  alternatives: string[];
  owners: string[];
  supersedes?: string;
  supersededBy?: string;
  contracts: string[];
};

export type ContractChange = {
  contractId: string;
  version: string;
  adrId: string;
  kind: ContractChangeKind;
  date: string;
};

export type FieldIssue = { field: string; code: "missing" | "invalid"; detail: string };
export type AdrCheck = { valid: boolean; errors: FieldIssue[] };

export type IntegrityIssue = {
  code: "duplicate-id" | "unknown-target" | "asymmetric-link" | "status-mismatch" | "multiple-successors";
  detail: string;
};

export type IntegrityReport = { valid: boolean; issues: IntegrityIssue[] };
export type TransitionResult = { ok: true; adr: Adr } | { ok: false; reason: string };
export type Registration = { ok: boolean; errors: string[]; changes: ContractChange[] };

export const ADR_STATUSES: AdrStatus[] = ["proposed", "accepted", "deprecated", "superseded"];
export const CONTRACT_CHANGE_KINDS: ContractChangeKind[] = ["breaking", "additive", "fix"];
export const ADR_REQUIRED_FIELDS: string[] = [
  "id",
  "title",
  "status",
  "date",
  "context",
  "decision",
  "consequences",
  "alternatives",
  "owners",
];

const ADR_ID_PATTERN = /^ADR-\d{3,4}$/;
const DATE_PATTERN = /^\d{4}-\d{2}-\d{2}$/;
const VERSION_PATTERN = /^\d+\.\d+(\.\d+)?$/;

const TRANSITIONS: Record<AdrStatus, AdrStatus[]> = {
  proposed: ["accepted", "deprecated"],
  accepted: ["deprecated", "superseded"],
  deprecated: [],
  superseded: [],
};

function filled(value: unknown): boolean {
  if (typeof value === "string") {
    return value.trim().length > 0;
  }
  if (Array.isArray(value)) {
    return value.length > 0;
  }
  return value !== undefined && value !== null;
}

export function isAdrStatus(value: unknown): value is AdrStatus {
  return (ADR_STATUSES as unknown[]).includes(value);
}

export function missingAdrFields(input: Partial<Adr>): string[] {
  const record = input as Record<string, unknown>;
  return ADR_REQUIRED_FIELDS.filter((field) => !filled(record[field]));
}

export function validateAdr(input: Partial<Adr>): AdrCheck {
  const errors: FieldIssue[] = [];
  for (const field of missingAdrFields(input)) {
    errors.push({ field, code: "missing", detail: `${field} 不能为空` });
  }
  if (input.id !== undefined && !ADR_ID_PATTERN.test(input.id)) {
    errors.push({ field: "id", code: "invalid", detail: "id 必须形如 ADR-001" });
  }
  if (input.status !== undefined && !isAdrStatus(input.status)) {
    errors.push({ field: "status", code: "invalid", detail: "未知的 ADR 状态" });
  }
  if (input.date !== undefined && !DATE_PATTERN.test(input.date)) {
    errors.push({ field: "date", code: "invalid", detail: "date 必须形如 2026-11-02" });
  }
  if (input.status === "superseded" && !filled(input.supersededBy)) {
    errors.push({ field: "supersededBy", code: "missing", detail: "superseded 必须指向后继 ADR" });
  }
  if (input.status !== undefined && input.status !== "superseded" && filled(input.supersededBy)) {
    errors.push({ field: "supersededBy", code: "invalid", detail: "只有 superseded 才能带 supersededBy" });
  }
  return { valid: errors.length === 0, errors };
}

export function canTransition(from: AdrStatus, to: AdrStatus): boolean {
  return TRANSITIONS[from].includes(to);
}

export function applyTransition(adr: Adr, next: AdrStatus, patch: Partial<Adr> = {}): TransitionResult {
  if (!canTransition(adr.status, next)) {
    return { ok: false, reason: `${adr.status} -> ${next} 不允许` };
  }
  const merged: Adr = { ...adr, ...patch, status: next };
  if (next === "superseded" && !filled(merged.supersededBy)) {
    return { ok: false, reason: "superseded 必须提供 supersededBy" };
  }
  if (next !== "superseded" && filled(merged.supersededBy)) {
    return { ok: false, reason: "只有 superseded 才能带 supersededBy" };
  }
  return { ok: true, adr: merged };
}

export function integrityReport(adrs: Adr[]): IntegrityReport {
  const issues: IntegrityIssue[] = [];
  const byId = new Map<string, Adr>();
  for (const adr of adrs) {
    if (byId.has(adr.id)) {
      issues.push({ code: "duplicate-id", detail: adr.id });
    } else {
      byId.set(adr.id, adr);
    }
  }
  const successors = new Map<string, string[]>();
  for (const adr of adrs) {
    if (adr.supersededBy !== undefined) {
      const target = byId.get(adr.supersededBy);
      if (target === undefined) {
        issues.push({ code: "unknown-target", detail: `${adr.id} -> ${adr.supersededBy}` });
      } else {
        if (target.supersedes !== adr.id) {
          issues.push({ code: "asymmetric-link", detail: `${adr.id} -> ${adr.supersededBy}` });
        }
        if (adr.status !== "superseded") {
          issues.push({ code: "status-mismatch", detail: `${adr.id} 状态为 ${adr.status}` });
        }
      }
      const list = successors.get(adr.id) ?? [];
      list.push(adr.supersededBy);
      successors.set(adr.id, list);
    }
    if (adr.supersedes !== undefined) {
      const target = byId.get(adr.supersedes);
      if (target === undefined) {
        issues.push({ code: "unknown-target", detail: `${adr.id} supersedes ${adr.supersedes}` });
      } else if (target.supersededBy !== adr.id) {
        issues.push({ code: "asymmetric-link", detail: `${adr.id} supersedes ${adr.supersedes}` });
      }
    }
  }
  for (const [id, list] of successors) {
    if (list.length > 1) {
      issues.push({ code: "multiple-successors", detail: `${id}: ${list.join(",")}` });
    }
  }
  return { valid: issues.length === 0, issues };
}

export function registerContractChange(
  existing: ContractChange[],
  change: ContractChange,
  adrs: Adr[],
): Registration {
  const errors: string[] = [];
  const adr = adrs.find((item) => item.id === change.adrId);
  if (adr === undefined) {
    errors.push(`unknown-adr: ${change.adrId}`);
  } else if (adr.status !== "accepted") {
    errors.push(`adr-not-accepted: ${change.adrId}=${adr.status}`);
  }
  if (!(CONTRACT_CHANGE_KINDS as string[]).includes(change.kind)) {
    errors.push(`unknown-kind: ${String(change.kind)}`);
  }
  if (!VERSION_PATTERN.test(change.version)) {
    errors.push(`invalid-version: ${change.version}`);
  }
  if (!DATE_PATTERN.test(change.date)) {
    errors.push(`invalid-date: ${change.date}`);
  }
  const duplicated = existing.some(
    (item) => item.contractId === change.contractId && item.version === change.version,
  );
  if (duplicated) {
    errors.push(`duplicate-version: ${change.contractId}@${change.version}`);
  }
  if (errors.length > 0) {
    return { ok: false, errors, changes: existing };
  }
  return { ok: true, errors: [], changes: [...existing, change] };
}

export function breakingChanges(changes: ContractChange[]): ContractChange[] {
  return changes.filter((change) => change.kind === "breaking");
}

export function acceptedAdrs(adrs: Adr[]): Adr[] {
  return adrs.filter((adr) => adr.status === "accepted");
}

export function contractsOf(adrs: Adr[], contractId: string): string[] {
  return adrs
    .filter((adr) => adr.contracts.includes(contractId))
    .map((adr) => adr.id)
    .sort();
}