@adrkit/core 0.1.0

package/src/scaffold/new.ts

@@ -0,0 +1,208 @@
+import { mkdir, writeFile } from 'node:fs/promises';
+import { basename, dirname, resolve } from 'node:path';
+import { Status, SCHEMA_VERSION, AdrFrontmatter } from '../schema/adr.schema.ts';
+import { discoverAdrFiles, normalizeDisplayPath } from '../load/corpus.ts';
+
+export interface NewAdrOptions {
+  title: string;
+  status?: string;
+  dir?: string;
+  cwd?: string;
+  date?: string;
+  write?: boolean;
+}
+
+export interface NewAdrResult {
+  id: string;
+  path: string;
+  content: string;
+}
+
+export class ScaffoldError extends Error {
+  readonly code: 'usage' | 'exists';
+
+  constructor(code: 'usage' | 'exists', message: string) {
+    super(message);
+    this.name = 'ScaffoldError';
+    this.code = code;
+  }
+}
+
+function todayIsoDate(): string {
+  return new Date().toISOString().slice(0, 10);
+}
+
+export function slugifyTitle(title: string): string {
+  const slug = title
+    .normalize('NFKD')
+    .replace(/[\u0300-\u036f]/g, '')
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .replace(/-{2,}/g, '-');
+
+  if (!slug) {
+    throw new ScaffoldError('usage', 'Title must contain at least one ASCII letter or digit');
+  }
+
+  return slug.slice(0, 80).replace(/-+$/g, '');
+}
+
+function statusForInput(input: string | undefined): string {
+  const status = input ?? 'draft';
+  const parsed = Status.safeParse(status);
+  if (!parsed.success) {
+    throw new ScaffoldError('usage', `Invalid status "${status}"`);
+  }
+  if (status === 'accepted' || status === 'superseded') {
+    throw new ScaffoldError(
+      'usage',
+      `adr new cannot scaffold status "${status}" without additional required fields`,
+    );
+  }
+  return status;
+}
+
+export async function nextSequentialId(dir: string, cwd: string): Promise<string> {
+  const files = await discoverAdrFiles(dir, cwd).catch(() => []);
+  let max = 0;
+  for (const file of files) {
+    const match = /^([0-9]+)-/.exec(basename(file));
+    if (match?.[1]) {
+      max = Math.max(max, Number(match[1]));
+    }
+  }
+  return String(max + 1).padStart(4, '0');
+}
+
+export function renderAdrRecord(options: {
+  id: string;
+  title: string;
+  status: string;
+  date: string;
+}): string {
+  const frontmatter = {
+    schemaVersion: SCHEMA_VERSION,
+    id: options.id,
+    title: options.title,
+    status: options.status,
+    date: options.date,
+    deciders: [],
+    tags: [],
+    scope: 'component',
+    reversibility: 'unknown',
+    blastRadius: 'component',
+    relatesTo: [],
+    affects: [],
+    provenance: {
+      authoredBy: 'human',
+    },
+  };
+
+  const validation = AdrFrontmatter.safeParse(frontmatter);
+  if (!validation.success) {
+    throw new ScaffoldError('usage', validation.error.issues.map((issue) => issue.message).join('; '));
+  }
+
+  return `---
+schemaVersion: ${frontmatter.schemaVersion}
+id: "${frontmatter.id}"
+title: ${JSON.stringify(frontmatter.title)}
+status: ${frontmatter.status}
+date: ${frontmatter.date}
+deciders: []
+tags: []
+scope: ${frontmatter.scope}
+reversibility: ${frontmatter.reversibility}
+blastRadius: ${frontmatter.blastRadius}
+relatesTo: []
+affects: []
+provenance:
+  authoredBy: human
+---
+
+# ADR-${frontmatter.id}: ${frontmatter.title}
+
+## Context
+
+What forces are at play? What makes this a decision rather than a preference?
+Why now — what changed?
+
+State the problem, not the solution. If this section is a restatement of the
+option you already picked, the record scores 2 at best on D1.
+
+## Decision
+
+What we are doing, in the active voice. "We will…"
+
+## Options considered
+
+At least two genuine alternatives, including doing nothing. An option no
+competent engineer would choose is a straw man and scores zero.
+
+### Option A: <chosen>
+
+| Dimension | Assessment |
+|---|---|
+| | |
+
+### Option B: <alternative>
+
+**Pros:**
+**Cons:**
+
+### Option C: Do nothing
+
+## Trade-offs
+
+What the chosen option costs. State the downsides as plainly as the benefits —
+a decision whose chosen option has no listed downsides is not a decision.
+
+## Consequences
+
+- Easier:
+- Harder:
+- **How we would know this was wrong:** a metric, a threshold, an exit
+  condition, or a review date. This is the field that most separates records
+  that stay alive from records that rot.
+- Revisit if:
+
+## Action items
+
+1. [ ]
+`;
+}
+
+export async function createAdr(options: NewAdrOptions): Promise<NewAdrResult> {
+  const cwd = options.cwd ?? process.cwd();
+  const dir = options.dir ?? 'docs/adr';
+  const title = options.title.trim();
+  const status = statusForInput(options.status);
+
+  if (title.length < 3 || title.length > 120) {
+    throw new ScaffoldError('usage', 'Title must be between 3 and 120 characters');
+  }
+  if (/[\r\n]/.test(title)) {
+    throw new ScaffoldError('usage', 'Title must fit on a single line');
+  }
+
+  const id = await nextSequentialId(dir, cwd);
+  const fileName = `${id}-${slugifyTitle(title)}.md`;
+  const path = resolve(cwd, dir, fileName);
+  const displayPath = normalizeDisplayPath(path, cwd);
+  const content = renderAdrRecord({ id, title, status, date: options.date ?? todayIsoDate() });
+
+  if (options.write !== false) {
+    await mkdir(dirname(path), { recursive: true });
+    try {
+      await writeFile(path, content, { encoding: 'utf8', flag: 'wx' });
+    } catch (error) {
+      if (error && typeof error === 'object' && 'code' in error && error.code === 'EEXIST') {
+        throw new ScaffoldError('exists', `Refusing to overwrite existing ADR file ${displayPath}`);
+      }
+      throw error;
+    }
+  }
+
+  return { id, path: displayPath, content };
+}

package/src/schema/adr.schema.ts

@@ -0,0 +1,338 @@
+/**
+ * @adrkit/core — ADR frontmatter schema
+ *
+ * Single source of truth for the typed half of a decision record. The JSON
+ * Schema in ./adr.schema.json is generated from this file (`bun run schema:emit`)
+ * so non-TS consumers — editors, CI in other languages, IDP plugins — get the
+ * same contract.
+ *
+ * Targets Zod 4. Deliberately avoids `.brand()` and other Zod-only constructs
+ * in the public shapes so the JSON Schema emit stays lossless.
+ */
+
+import { z } from 'zod';
+
+export const SCHEMA_VERSION = '0.1.0' as const;
+
+/* ------------------------------------------------------------------ *
+ * Primitives
+ * ------------------------------------------------------------------ */
+
+/** `@handle`, `team:platform`, or an email address. */
+export const Identity = z
+  .string()
+  .regex(
+    /^(@[A-Za-z0-9-]+|team:[a-z0-9-]+|[^@\s]+@[^@\s]+\.[^@\s]+)$/,
+    'Expected @handle, team:slug, or an email address',
+  );
+
+/** `0042` (same log) or `payments:0012` (federated). */
+export const AdrRef = z
+  .string()
+  .regex(
+    /^(([a-z0-9][a-z0-9-]*):)?([0-9]{4,}|[0-9A-HJKMNP-TV-Za-hjkmnp-tv-z]{26})$/,
+    'Expected an ADR id, optionally prefixed with a log name',
+  );
+
+/** Calendar-correct `YYYY-MM-DD`; rejects impossible dates like `2026-02-31`. */
+const IsoDate = z.string().date();
+const IsoDateTime = z.string().datetime({ offset: true });
+
+const Slug = z.string().regex(/^[a-z0-9][a-z0-9-]*$/);
+
+const strictObject = <T extends z.ZodRawShape>(shape: T) => z.strictObject(shape);
+
+/**
+ * Array whose items must be unique. Mirrors JSON Schema `uniqueItems: true`
+ * so TS and non-TS consumers reject duplicate entries identically.
+ */
+const uniqueArray = <T extends z.ZodTypeAny>(item: T) =>
+  z
+    .array(item)
+    .refine((xs) => new Set(xs.map((x) => JSON.stringify(x))).size === xs.length, {
+      message: 'Items must be unique',
+    })
+    .meta({ uniqueItems: true });
+
+/* ------------------------------------------------------------------ *
+ * Enums
+ * ------------------------------------------------------------------ */
+
+/**
+ * `rejected` is retained on purpose. The decision *not* to do something is the
+ * one most often re-litigated, and the graveyard is where "we tried that in
+ * 2023" knowledge lives.
+ */
+export const Status = z.enum([
+  'draft',
+  'proposed',
+  'accepted',
+  'rejected',
+  'superseded',
+  'deprecated',
+]);
+
+export const Scope = z.enum(['component', 'domain', 'org']);
+export const Reversibility = z.enum(['two-way-door', 'one-way-door', 'unknown']);
+export const BlastRadius = z.enum(['component', 'team', 'cross-team', 'org']);
+export const ReviewTier = z.enum(['auto', 'async', 'arb']);
+export const Severity = z.enum(['error', 'warn', 'info']);
+
+export const EscalationReason = z.enum([
+  'one-way-door',
+  'cost-threshold',
+  'security-surface',
+  'data-residency',
+  'regulatory',
+  'contradicts-accepted-adr',
+  'low-confidence',
+  'pass-disagreement',
+  'agent-authored-production',
+  'novel-no-precedent',
+  'human-requested',
+]);
+
+/* ------------------------------------------------------------------ *
+ * affects — the hinge
+ * ------------------------------------------------------------------ *
+ * Without this, an ADR is a document. With it, CI can answer "which
+ * decisions govern the code in this PR?" and put the answer where the
+ * next decision is actually being made.
+ */
+
+export const AffectsType = z.enum([
+  'path', // repo-relative glob, picomatch semantics
+  'entity', // IDP catalog ref, Backstage-compatible: component:default/payments-api
+  'package', // dependency, optional semver range: react@>=19
+  'resource', // IaC resource type: azurerm_storage_account
+  'api', // OpenAPI/AsyncAPI path or operationId
+  'data', // dataset / table identifier
+]);
+
+export const AffectsMatcher = strictObject({
+  type: AffectsType,
+  pattern: z.string().min(1),
+  /** Qualifier for federated logs. Omit for same-repo. */
+  repo: z.string().optional(),
+  /** Exclusions are evaluated after includes. */
+  negate: z.boolean().default(false),
+  note: z.string().optional(),
+});
+
+/* ------------------------------------------------------------------ *
+ * assertions — optional executable guardrails
+ * ------------------------------------------------------------------ */
+
+export const Assertion = strictObject({
+  id: Slug,
+  description: z.string().optional(),
+  engine: z.enum(['rego', 'jsonpath', 'grep', 'custom']),
+  expression: z.string().optional(),
+  expressionFile: z.string().optional(),
+  input: z
+    .enum(['source', 'iac-plan', 'sbom', 'openapi', 'catalog', 'custom'])
+    .default('source'),
+  severity: Severity,
+});
+
+/* ------------------------------------------------------------------ *
+ * provenance — capture from day one; cannot be backfilled
+ * ------------------------------------------------------------------ */
+
+export const Provenance = strictObject({
+  authoredBy: z.enum(['human', 'agent', 'agent-drafted']).default('human'),
+  agent: strictObject({
+    name: z.string().optional(),
+    model: z.string().optional(),
+    /** e.g. spec-kit, claude-code, copilot */
+    harness: z.string().optional(),
+    runId: z.string().optional(),
+  }).optional(),
+  ratifiedBy: Identity.optional(),
+  /** Path/URI of the plan or spec this record was derived from. */
+  sourceArtifact: z.string().optional(),
+  /**
+   * Present when an importer created this record rather than an author here.
+   * Its presence exempts the record from the deciders-required invariant: the
+   * decision was made elsewhere, and fabricating a decider from git blame is
+   * worse than an empty field.
+   */
+  importedFrom: strictObject({
+    sourceKind: z.enum(['madr', 'agent-log', 'plan-artifact', 'other']),
+    /** Source-local identifier: file path, entry id, or URI. */
+    sourceRef: z.string(),
+    /** Content hash of the source entry at import time; drives re-import classification. */
+    fingerprint: z.string(),
+    importedAt: IsoDateTime.optional(),
+  }).optional(),
+});
+
+/* ------------------------------------------------------------------ *
+ * review — ARB routing state
+ * ------------------------------------------------------------------ */
+
+export const Objection = strictObject({
+  by: Identity,
+  summary: z.string().optional(),
+  resolved: z.boolean().default(false),
+});
+
+export const Review = strictObject({
+  tier: ReviewTier.optional(),
+  /** Required when a human overrides the router's tier. */
+  tierReason: z.string().optional(),
+  queuedAt: IsoDateTime.optional(),
+  slaDays: z.number().int().min(0).optional(),
+  escalatedAt: IsoDateTime.optional(),
+  decidedAt: IsoDateTime.optional(),
+  quorum: z.number().int().min(1).optional(),
+  approvals: z.array(Identity).default([]),
+  objections: z.array(Objection).default([]),
+});
+
+/* ------------------------------------------------------------------ *
+ * evaluation — written by tooling, never by hand
+ * ------------------------------------------------------------------ */
+
+export const DeterministicFinding = strictObject({
+  rule: z.string(),
+  severity: Severity,
+  message: z.string().optional(),
+  adr: AdrRef.optional(),
+});
+
+export const Evaluation = strictObject({
+  ranAt: IsoDateTime.optional(),
+  evaluatorVersion: z.string().optional(),
+  rubricVersion: z.string().optional(),
+  /** Per-dimension 0–4, keyed by rubric dimension id. */
+  scores: z.record(z.string(), z.number().min(0).max(4)).optional(),
+  confidence: z.number().min(0).max(1).optional(),
+  escalate: z.boolean().optional(),
+  escalationReasons: z.array(EscalationReason).default([]),
+  deterministicFindings: z.array(DeterministicFinding).default([]),
+});
+
+export const ExternalRef = strictObject({
+  type: z.enum(['issue', 'pr', 'rfc', 'incident', 'doc', 'meeting', 'control', 'other']),
+  id: z.string().optional(),
+  url: z.string().url(),
+  label: z.string().optional(),
+});
+
+/* ------------------------------------------------------------------ *
+ * The record
+ * ------------------------------------------------------------------ */
+
+export const AdrFrontmatter = strictObject({
+  schemaVersion: z
+    .string()
+    .regex(/^\d+\.\d+\.\d+$/)
+    .default(SCHEMA_VERSION),
+
+  id: z.string().regex(/^([0-9]{4,}|[0-9A-HJKMNP-TV-Za-hjkmnp-tv-z]{26})$/),
+  /** Imperative phrase naming the decision, not the problem. */
+  title: z.string().min(3).max(120),
+  status: Status,
+  date: IsoDate,
+  created: IsoDate.optional(),
+
+  deciders: z.array(Identity).default([]),
+  consulted: z.array(Identity).default([]),
+  informed: z.array(Identity).default([]),
+
+  tags: uniqueArray(Slug).default([]),
+  scope: Scope.default('component'),
+  domain: z.string().optional(),
+
+  reversibility: Reversibility.default('unknown'),
+  blastRadius: BlastRadius.default('component'),
+
+  supersedes: uniqueArray(AdrRef).default([]),
+  supersededBy: AdrRef.optional(),
+  relatesTo: uniqueArray(AdrRef).default([]),
+  /** Knowingly-held tension. A lint warning on accepted records, not an error. */
+  conflictsWith: z.array(AdrRef).default([]),
+
+  affects: z.array(AffectsMatcher).default([]),
+  assertions: z.array(Assertion).default([]),
+
+  provenance: Provenance.optional(),
+  review: Review.optional(),
+  evaluation: Evaluation.optional(),
+
+  externalRefs: z.array(ExternalRef).default([]),
+  /** e.g. SOC2 CC8.1, ISO 27001 A.8.25 — audit evidence as a byproduct. */
+  complianceControls: uniqueArray(z.string()).default([]),
+  /** Decisions with an expiry get maintained. Decisions without one rot. */
+  reviewBy: IsoDate.optional(),
+  })
+  /* --- cross-field invariants ------------------------------------- */
+  .refine((a) => (a.status === 'superseded' ? Boolean(a.supersededBy) : true), {
+    message: 'status "superseded" requires supersededBy',
+    path: ['supersededBy'],
+  })
+  .refine((a) => (a.supersededBy ? a.status === 'superseded' : true), {
+    message: 'supersededBy is set but status is not "superseded"',
+    path: ['status'],
+  })
+  .refine(
+    (a) =>
+      a.status !== 'accepted' ||
+      a.deciders.length > 0 ||
+      Boolean(a.provenance?.importedFrom),
+    {
+      message:
+        'an accepted decision must name at least one decider, unless it was imported',
+      path: ['deciders'],
+    },
+  )
+  .refine(
+    (a) =>
+      a.status !== 'accepted' ||
+      a.provenance?.authoredBy !== 'agent' ||
+      Boolean(a.provenance?.ratifiedBy),
+    {
+      message:
+        'an agent-authored record cannot reach "accepted" without a named human ratifier',
+      path: ['provenance', 'ratifiedBy'],
+    },
+  )
+  .refine((a) => !(a.reversibility === 'one-way-door' && a.review?.tier === 'auto'), {
+    message: 'one-way-door decisions may not take the auto-approve fast path',
+    path: ['review', 'tier'],
+  });
+
+export type AdrFrontmatter = z.infer<typeof AdrFrontmatter>;
+
+export interface Adr {
+  frontmatter: AdrFrontmatter;
+  /** Raw markdown body below the frontmatter. */
+  body: string;
+  /** Repo-relative path, e.g. docs/adr/0042-use-postgres-for-the-index.md */
+  path: string;
+  /** Log name for federated corpora; undefined for single-repo. */
+  log?: string;
+}
+
+/* ------------------------------------------------------------------ *
+ * Type-only inference aliases (no runtime / JSON-schema change)
+ * ------------------------------------------------------------------ *
+ * These `z.infer` aliases sit beside their existing Zod values so first-party
+ * consumers (notably `@adrkit/evaluator`) can reuse the committed contract shapes
+ * by name instead of redefining them. A value and a type may share a name in
+ * TypeScript, so `AdrRef` (value) and `AdrRef` (type) coexist. Adding these
+ * changes no Zod schema and no emitted JSON Schema (data-model §1).
+ */
+export type AdrRef = z.infer<typeof AdrRef>;
+export type AffectsType = z.infer<typeof AffectsType>;
+export type AffectsMatcher = z.infer<typeof AffectsMatcher>;
+export type Assertion = z.infer<typeof Assertion>;
+export type Severity = z.infer<typeof Severity>;
+export type EscalationReason = z.infer<typeof EscalationReason>;
+export type DeterministicFinding = z.infer<typeof DeterministicFinding>;
+export type Evaluation = z.infer<typeof Evaluation>;
+export type Status = z.infer<typeof Status>;
+export type Scope = z.infer<typeof Scope>;
+export type Reversibility = z.infer<typeof Reversibility>;
+export type BlastRadius = z.infer<typeof BlastRadius>;

package/src/schema/emit.cli.ts

@@ -0,0 +1,9 @@
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { writeFile } from 'node:fs/promises';
+import { emitJsonSchema, stringifyJsonSchema } from './emit.ts';
+
+const repoRoot = resolve(dirname(fileURLToPath(import.meta.url)), '../../../..');
+const outputPath = resolve(repoRoot, 'schema/adr.schema.json');
+
+await writeFile(outputPath, stringifyJsonSchema(emitJsonSchema()), 'utf8');

package/src/schema/emit.ts

@@ -0,0 +1,55 @@
+import { z } from 'zod';
+import { AdrFrontmatter, SCHEMA_VERSION } from './adr.schema.ts';
+
+export const ADR_SCHEMA_ID = `https://adrkit.dev/schema/adr/v${SCHEMA_VERSION}/adr.schema.json`;
+
+export type JsonValue =
+  | null
+  | boolean
+  | number
+  | string
+  | JsonValue[]
+  | { [key: string]: JsonValue };
+
+function sortJson(value: unknown): JsonValue {
+  if (Array.isArray(value)) {
+    return value.map((item) => sortJson(item));
+  }
+
+  if (value && typeof value === 'object') {
+    const input = value as Record<string, unknown>;
+    const output: Record<string, JsonValue> = {};
+    for (const key of Object.keys(input).sort()) {
+      output[key] = sortJson(input[key]);
+    }
+    return output;
+  }
+
+  if (
+    value === null ||
+    typeof value === 'boolean' ||
+    typeof value === 'number' ||
+    typeof value === 'string'
+  ) {
+    return value;
+  }
+
+  throw new TypeError(`Cannot serialize JSON schema value of type ${typeof value}`);
+}
+
+export function emitJsonSchema(): JsonValue {
+  const schema = z.toJSONSchema(AdrFrontmatter, { io: 'input' });
+  const withMetadata = {
+    ...schema,
+    $id: ADR_SCHEMA_ID,
+    title: 'Architecture Decision Record',
+    description:
+      'Typed frontmatter for a decision record. A superset of MADR: every MADR field is present or derivable, plus governance, routing, provenance, and enforcement metadata. The markdown body below the frontmatter carries the prose.',
+  };
+
+  return sortJson(withMetadata);
+}
+
+export function stringifyJsonSchema(schema: JsonValue = emitJsonSchema()): string {
+  return `${JSON.stringify(schema, null, 2)}\n`;
+}

package/src/schema/index.ts

@@ -0,0 +1,2 @@
+export * from './adr.schema.ts';
+export * from './emit.ts';