@adrkit/core 0.1.0

package/dist/schema/emit.js

@@ -0,0 +1,200 @@
+// src/schema/adr.schema.ts
+import { z } from "zod";
+var SCHEMA_VERSION = "0.1.0";
+var Identity = z.string().regex(/^(@[A-Za-z0-9-]+|team:[a-z0-9-]+|[^@\s]+@[^@\s]+\.[^@\s]+)$/, "Expected @handle, team:slug, or an email address");
+var 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");
+var IsoDate = z.string().date();
+var IsoDateTime = z.string().datetime({ offset: true });
+var Slug = z.string().regex(/^[a-z0-9][a-z0-9-]*$/);
+var strictObject = (shape) => z.strictObject(shape);
+var uniqueArray = (item) => z.array(item).refine((xs) => new Set(xs.map((x) => JSON.stringify(x))).size === xs.length, {
+  message: "Items must be unique"
+}).meta({ uniqueItems: true });
+var Status = z.enum([
+  "draft",
+  "proposed",
+  "accepted",
+  "rejected",
+  "superseded",
+  "deprecated"
+]);
+var Scope = z.enum(["component", "domain", "org"]);
+var Reversibility = z.enum(["two-way-door", "one-way-door", "unknown"]);
+var BlastRadius = z.enum(["component", "team", "cross-team", "org"]);
+var ReviewTier = z.enum(["auto", "async", "arb"]);
+var Severity = z.enum(["error", "warn", "info"]);
+var 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"
+]);
+var AffectsType = z.enum([
+  "path",
+  "entity",
+  "package",
+  "resource",
+  "api",
+  "data"
+]);
+var AffectsMatcher = strictObject({
+  type: AffectsType,
+  pattern: z.string().min(1),
+  repo: z.string().optional(),
+  negate: z.boolean().default(false),
+  note: z.string().optional()
+});
+var 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
+});
+var Provenance = strictObject({
+  authoredBy: z.enum(["human", "agent", "agent-drafted"]).default("human"),
+  agent: strictObject({
+    name: z.string().optional(),
+    model: z.string().optional(),
+    harness: z.string().optional(),
+    runId: z.string().optional()
+  }).optional(),
+  ratifiedBy: Identity.optional(),
+  sourceArtifact: z.string().optional(),
+  importedFrom: strictObject({
+    sourceKind: z.enum(["madr", "agent-log", "plan-artifact", "other"]),
+    sourceRef: z.string(),
+    fingerprint: z.string(),
+    importedAt: IsoDateTime.optional()
+  }).optional()
+});
+var Objection = strictObject({
+  by: Identity,
+  summary: z.string().optional(),
+  resolved: z.boolean().default(false)
+});
+var Review = strictObject({
+  tier: ReviewTier.optional(),
+  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([])
+});
+var DeterministicFinding = strictObject({
+  rule: z.string(),
+  severity: Severity,
+  message: z.string().optional(),
+  adr: AdrRef.optional()
+});
+var Evaluation = strictObject({
+  ranAt: IsoDateTime.optional(),
+  evaluatorVersion: z.string().optional(),
+  rubricVersion: z.string().optional(),
+  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([])
+});
+var 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()
+});
+var 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})$/),
+  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([]),
+  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([]),
+  complianceControls: uniqueArray(z.string()).default([]),
+  reviewBy: IsoDate.optional()
+}).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"]
+});
+
+// src/schema/emit.ts
+import { z as z2 } from "zod";
+var ADR_SCHEMA_ID = `https://adrkit.dev/schema/adr/v${SCHEMA_VERSION}/adr.schema.json`;
+function sortJson(value) {
+  if (Array.isArray(value)) {
+    return value.map((item) => sortJson(item));
+  }
+  if (value && typeof value === "object") {
+    const input = value;
+    const output = {};
+    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}`);
+}
+function emitJsonSchema() {
+  const schema = z2.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);
+}
+function stringifyJsonSchema(schema = emitJsonSchema()) {
+  return `${JSON.stringify(schema, null, 2)}
+`;
+}
+export {
+  stringifyJsonSchema,
+  emitJsonSchema,
+  ADR_SCHEMA_ID
+};

package/dist/schema/index.d.ts

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

package/dist/schema/index.js

@@ -0,0 +1,220 @@
+// src/schema/adr.schema.ts
+import { z } from "zod";
+var SCHEMA_VERSION = "0.1.0";
+var Identity = z.string().regex(/^(@[A-Za-z0-9-]+|team:[a-z0-9-]+|[^@\s]+@[^@\s]+\.[^@\s]+)$/, "Expected @handle, team:slug, or an email address");
+var 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");
+var IsoDate = z.string().date();
+var IsoDateTime = z.string().datetime({ offset: true });
+var Slug = z.string().regex(/^[a-z0-9][a-z0-9-]*$/);
+var strictObject = (shape) => z.strictObject(shape);
+var uniqueArray = (item) => z.array(item).refine((xs) => new Set(xs.map((x) => JSON.stringify(x))).size === xs.length, {
+  message: "Items must be unique"
+}).meta({ uniqueItems: true });
+var Status = z.enum([
+  "draft",
+  "proposed",
+  "accepted",
+  "rejected",
+  "superseded",
+  "deprecated"
+]);
+var Scope = z.enum(["component", "domain", "org"]);
+var Reversibility = z.enum(["two-way-door", "one-way-door", "unknown"]);
+var BlastRadius = z.enum(["component", "team", "cross-team", "org"]);
+var ReviewTier = z.enum(["auto", "async", "arb"]);
+var Severity = z.enum(["error", "warn", "info"]);
+var 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"
+]);
+var AffectsType = z.enum([
+  "path",
+  "entity",
+  "package",
+  "resource",
+  "api",
+  "data"
+]);
+var AffectsMatcher = strictObject({
+  type: AffectsType,
+  pattern: z.string().min(1),
+  repo: z.string().optional(),
+  negate: z.boolean().default(false),
+  note: z.string().optional()
+});
+var 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
+});
+var Provenance = strictObject({
+  authoredBy: z.enum(["human", "agent", "agent-drafted"]).default("human"),
+  agent: strictObject({
+    name: z.string().optional(),
+    model: z.string().optional(),
+    harness: z.string().optional(),
+    runId: z.string().optional()
+  }).optional(),
+  ratifiedBy: Identity.optional(),
+  sourceArtifact: z.string().optional(),
+  importedFrom: strictObject({
+    sourceKind: z.enum(["madr", "agent-log", "plan-artifact", "other"]),
+    sourceRef: z.string(),
+    fingerprint: z.string(),
+    importedAt: IsoDateTime.optional()
+  }).optional()
+});
+var Objection = strictObject({
+  by: Identity,
+  summary: z.string().optional(),
+  resolved: z.boolean().default(false)
+});
+var Review = strictObject({
+  tier: ReviewTier.optional(),
+  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([])
+});
+var DeterministicFinding = strictObject({
+  rule: z.string(),
+  severity: Severity,
+  message: z.string().optional(),
+  adr: AdrRef.optional()
+});
+var Evaluation = strictObject({
+  ranAt: IsoDateTime.optional(),
+  evaluatorVersion: z.string().optional(),
+  rubricVersion: z.string().optional(),
+  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([])
+});
+var 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()
+});
+var 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})$/),
+  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([]),
+  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([]),
+  complianceControls: uniqueArray(z.string()).default([]),
+  reviewBy: IsoDate.optional()
+}).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"]
+});
+
+// src/schema/emit.ts
+import { z as z2 } from "zod";
+var ADR_SCHEMA_ID = `https://adrkit.dev/schema/adr/v${SCHEMA_VERSION}/adr.schema.json`;
+function sortJson(value) {
+  if (Array.isArray(value)) {
+    return value.map((item) => sortJson(item));
+  }
+  if (value && typeof value === "object") {
+    const input = value;
+    const output = {};
+    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}`);
+}
+function emitJsonSchema() {
+  const schema = z2.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);
+}
+function stringifyJsonSchema(schema = emitJsonSchema()) {
+  return `${JSON.stringify(schema, null, 2)}
+`;
+}
+export {
+  stringifyJsonSchema,
+  emitJsonSchema,
+  Status,
+  Severity,
+  Scope,
+  SCHEMA_VERSION,
+  ReviewTier,
+  Review,
+  Reversibility,
+  Provenance,
+  Objection,
+  Identity,
+  ExternalRef,
+  Evaluation,
+  EscalationReason,
+  DeterministicFinding,
+  BlastRadius,
+  Assertion,
+  AffectsType,
+  AffectsMatcher,
+  AdrRef,
+  AdrFrontmatter,
+  ADR_SCHEMA_ID
+};

package/dist/validate/contract.d.ts

@@ -0,0 +1,9 @@
+import { type Adr } from '../schema/adr.schema.js';
+import type { ParsedAdrFile } from '../load/corpus.js';
+import type { Finding } from './findings.js';
+export interface ContractValidationResult {
+    record?: Adr;
+    findings: Finding[];
+}
+export declare function validateParsedAdr(parsed: ParsedAdrFile): ContractValidationResult;
+export declare function validateAdrFrontmatter(data: unknown, path: string): ContractValidationResult;

package/dist/validate/corpus-invariants.d.ts

@@ -0,0 +1,3 @@
+import type { Adr } from '../schema/adr.schema.js';
+import type { Finding } from './findings.js';
+export declare function validateCorpusInvariants(records: readonly Adr[]): Finding[];

package/dist/validate/findings.d.ts

@@ -0,0 +1,19 @@
+export declare const IMPORT_FINDING_RULES: readonly ["import-incomplete", "import-status-unrecognized", "import-not-madr"];
+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;
+}
+export declare function sortFindings(findings: readonly Finding[]): Finding[];
+export declare function countFindings(findings: readonly Finding[]): {
+    errors: number;
+    warnings: number;
+    infos: number;
+};
+export declare function exitCodeForFindings(findings: readonly Finding[]): 0 | 1;

package/dist/validate/import-incomplete.d.ts

@@ -0,0 +1,3 @@
+import type { Adr } from '../schema/adr.schema.js';
+import type { Finding } from './findings.js';
+export declare function validateImportIncomplete(records: readonly Adr[]): Finding[];

package/dist/validate/index.d.ts

@@ -0,0 +1,13 @@
+import type { Adr } from '../schema/adr.schema.js';
+import { type Finding } from './findings.js';
+export interface LintCorpusOptions {
+    dir?: string;
+    paths?: string[];
+    cwd?: string;
+}
+export interface LintCorpusResult {
+    checked: number;
+    findings: Finding[];
+    records: Adr[];
+}
+export declare function lintCorpus(options?: LintCorpusOptions): Promise<LintCorpusResult>;

package/package.json

@@ -0,0 +1,76 @@
+{
+  "name": "@adrkit/core",
+  "version": "0.1.0",
+  "description": "Pure ADR parsing, validation, migration, and affects resolution for adrkit.",
+  "type": "module",
+  "license": "Apache-2.0",
+  "homepage": "https://adrkit.dev",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mbeacom/adrkit.git",
+    "directory": "packages/core"
+  },
+  "bugs": {
+    "url": "https://github.com/mbeacom/adrkit/issues"
+  },
+  "keywords": [
+    "adr",
+    "architecture-decision-records",
+    "governance"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": {
+      "bun": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./schema": {
+      "bun": "./src/schema/index.ts",
+      "types": "./dist/schema/index.d.ts",
+      "import": "./dist/schema/index.js",
+      "default": "./dist/schema/index.js"
+    },
+    "./schema/adr.schema": {
+      "bun": "./src/schema/adr.schema.ts",
+      "types": "./dist/schema/adr.schema.d.ts",
+      "import": "./dist/schema/adr.schema.js",
+      "default": "./dist/schema/adr.schema.js"
+    },
+    "./schema/emit": {
+      "bun": "./src/schema/emit.ts",
+      "types": "./dist/schema/emit.d.ts",
+      "import": "./dist/schema/emit.js",
+      "default": "./dist/schema/emit.js"
+    }
+  },
+  "scripts": {
+    "build": "rm -rf dist && bun build ./src/index.ts ./src/schema/index.ts ./src/schema/adr.schema.ts ./src/schema/emit.ts --target=node --outdir=dist --packages=external && tsc --project tsconfig.build.json && bun ../../scripts/normalize-dts-imports.ts dist && cp ../../LICENSE ../../NOTICE dist/",
+    "lint": "bun run typecheck",
+    "prepack": "bun run build",
+    "schema:emit": "bun ./src/schema/emit.cli.ts",
+    "typecheck": "tsc --noEmit --customConditions bun --project ../../tsconfig.json"
+  },
+  "dependencies": {
+    "picomatch": "^4",
+    "semver": "^7",
+    "yaml": "latest",
+    "zod": "^4"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "@types/picomatch": "^4",
+    "@types/semver": "^7"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "src"
+  ]
+}

package/src/affects/catalog.ts

@@ -0,0 +1,17 @@
+export type EntityId = string;
+
+export interface CatalogSnapshotEntity {
+  id: EntityId;
+  refs?: readonly string[];
+  paths?: readonly string[];
+}
+
+export interface CatalogSnapshot {
+  entities: readonly CatalogSnapshotEntity[];
+}
+
+export interface CatalogPort {
+  resolveEntity(ref: string): readonly EntityId[];
+  entitiesForPaths(paths: readonly string[]): readonly EntityId[];
+  snapshot(): CatalogSnapshot;
+}