@adrkit/cli 0.1.0

package/dist/index.js

@@ -0,0 +1,1037 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import { parseArgs } from "node:util";
+import {
+  buildAdrGraph,
+  checkChanges,
+  countFindings,
+  createAdr,
+  exitCodeForFindings,
+  lintCorpus as lintCorpus2,
+  migrateMadr,
+  resolveAffects,
+  renderDotGraph,
+  renderJsonGraph,
+  ScaffoldError,
+  sortFindings
+} from "@adrkit/core";
+
+// src/evaluate.ts
+import { readFile } from "node:fs/promises";
+import { dirname } from "node:path";
+import { lintCorpus, normalizeDisplayPath } from "@adrkit/core";
+import {
+  canonicalBytes,
+  createAssertionEngineRegistry,
+  createJsonPathEngine,
+  createPackageTargetResolver,
+  createPathTargetResolver,
+  createTargetResolutionRegistry,
+  evaluatePass0
+} from "@adrkit/evaluator";
+
+// src/evaluate-snapshot.ts
+import {
+  canonicalTargetKey,
+  isCanonicalAssertionKey,
+  makeTargetId,
+  validateRegoWasmPolicyEnvelopeV1
+} from "@adrkit/evaluator";
+
+class SnapshotContractError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "SnapshotContractError";
+  }
+}
+
+class StrictJsonReader {
+  s;
+  static MAX_DEPTH = 128;
+  i = 0;
+  constructor(s) {
+    this.s = s;
+  }
+  read() {
+    this.ws();
+    const value = this.value(0);
+    this.ws();
+    if (this.i !== this.s.length)
+      this.fail("unexpected trailing content");
+    return value;
+  }
+  fail(message) {
+    throw new SnapshotContractError(`Malformed snapshot JSON: ${message} (offset ${this.i})`);
+  }
+  ws() {
+    while (this.i < this.s.length) {
+      const c = this.s.charCodeAt(this.i);
+      if (c === 32 || c === 9 || c === 10 || c === 13)
+        this.i += 1;
+      else
+        break;
+    }
+  }
+  value(depth) {
+    if (depth > StrictJsonReader.MAX_DEPTH) {
+      this.fail(`nesting exceeds ${StrictJsonReader.MAX_DEPTH}`);
+    }
+    const c = this.s[this.i];
+    if (c === "{")
+      return this.object(depth);
+    if (c === "[")
+      return this.array(depth);
+    if (c === '"')
+      return this.string();
+    if (c === "-" || c !== undefined && c >= "0" && c <= "9")
+      return this.number();
+    if (this.s.startsWith("true", this.i))
+      return this.i += 4, true;
+    if (this.s.startsWith("false", this.i))
+      return this.i += 5, false;
+    if (this.s.startsWith("null", this.i))
+      return this.i += 4, null;
+    this.fail("unexpected token");
+  }
+  object(depth) {
+    this.i += 1;
+    const obj = Object.create(null);
+    const seen = new Set;
+    this.ws();
+    if (this.s[this.i] === "}")
+      return this.i += 1, obj;
+    for (;; ) {
+      this.ws();
+      if (this.s[this.i] !== '"')
+        this.fail("expected string key");
+      const key = this.string();
+      if (seen.has(key))
+        throw new SnapshotContractError(`Duplicate key "${key}" in snapshot bundle`);
+      seen.add(key);
+      this.ws();
+      if (this.s[this.i] !== ":")
+        this.fail('expected ":"');
+      this.i += 1;
+      this.ws();
+      obj[key] = this.value(depth + 1);
+      this.ws();
+      const ch = this.s[this.i];
+      if (ch === ",") {
+        this.i += 1;
+        continue;
+      }
+      if (ch === "}") {
+        this.i += 1;
+        break;
+      }
+      this.fail('expected "," or "}"');
+    }
+    return obj;
+  }
+  array(depth) {
+    this.i += 1;
+    const arr = [];
+    this.ws();
+    if (this.s[this.i] === "]")
+      return this.i += 1, arr;
+    for (;; ) {
+      this.ws();
+      arr.push(this.value(depth + 1));
+      this.ws();
+      const ch = this.s[this.i];
+      if (ch === ",") {
+        this.i += 1;
+        continue;
+      }
+      if (ch === "]") {
+        this.i += 1;
+        break;
+      }
+      this.fail('expected "," or "]"');
+    }
+    return arr;
+  }
+  string() {
+    const start = this.i;
+    this.i += 1;
+    while (this.i < this.s.length) {
+      const ch = this.s[this.i];
+      if (ch === "\\") {
+        this.i += 2;
+        continue;
+      }
+      if (ch === '"') {
+        this.i += 1;
+        break;
+      }
+      this.i += 1;
+    }
+    const raw = this.s.slice(start, this.i);
+    try {
+      const parsed = JSON.parse(raw);
+      if (typeof parsed !== "string")
+        this.fail("invalid string literal");
+      return parsed;
+    } catch {
+      this.fail("invalid string literal");
+    }
+  }
+  number() {
+    const start = this.i;
+    const isDigit = (c) => c !== undefined && c >= "0" && c <= "9";
+    if (this.s[this.i] === "-")
+      this.i += 1;
+    if (this.s[this.i] === "0") {
+      this.i += 1;
+    } else if (this.s[this.i] !== undefined && this.s[this.i] >= "1" && this.s[this.i] <= "9") {
+      this.i += 1;
+      while (isDigit(this.s[this.i]))
+        this.i += 1;
+    } else {
+      this.fail("invalid number: expected an integer part");
+    }
+    if (this.s[this.i] === ".") {
+      this.i += 1;
+      if (!isDigit(this.s[this.i]))
+        this.fail("invalid number: expected a digit after the decimal point");
+      while (isDigit(this.s[this.i]))
+        this.i += 1;
+    }
+    if (this.s[this.i] === "e" || this.s[this.i] === "E") {
+      this.i += 1;
+      if (this.s[this.i] === "+" || this.s[this.i] === "-")
+        this.i += 1;
+      if (!isDigit(this.s[this.i]))
+        this.fail("invalid number: expected a digit in the exponent");
+      while (isDigit(this.s[this.i]))
+        this.i += 1;
+    }
+    const raw = this.s.slice(start, this.i);
+    const n = Number(raw);
+    if (raw.length === 0 || !Number.isFinite(n))
+      this.fail("invalid number");
+    return n;
+  }
+}
+function parseSnapshotJson(text) {
+  return new StrictJsonReader(text).read();
+}
+var AFFECTS_TYPES = ["path", "entity", "package", "resource", "api", "data"];
+function parseAffectsType(value) {
+  return AFFECTS_TYPES.find((type) => type === value);
+}
+function isPlainObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function requireObject(value, where) {
+  if (!isPlainObject(value))
+    throw new SnapshotContractError(`${where} must be an object`);
+  return value;
+}
+function requireString(value, where) {
+  if (typeof value !== "string")
+    throw new SnapshotContractError(`${where} must be a string`);
+  return value;
+}
+function requireBoolean(value, where) {
+  if (typeof value !== "boolean")
+    throw new SnapshotContractError(`${where} must be a boolean`);
+  return value;
+}
+function requireNumber(value, where) {
+  if (typeof value !== "number")
+    throw new SnapshotContractError(`${where} must be a number`);
+  return value;
+}
+function requireStringArray(value, where) {
+  if (!Array.isArray(value))
+    throw new SnapshotContractError(`${where} must be an array`);
+  return value.map((item, idx) => requireString(item, `${where}[${idx}]`));
+}
+function rejectUnknownKeys(obj, allowed, where) {
+  const allowedSet = new Set(allowed);
+  for (const key of Object.keys(obj)) {
+    if (!allowedSet.has(key))
+      throw new SnapshotContractError(`Unknown key "${key}" in ${where}`);
+  }
+}
+function isCanonicalTargetKey(key) {
+  const idx = key.indexOf(":");
+  if (idx <= 0)
+    return false;
+  const kind = parseAffectsType(key.slice(0, idx));
+  if (!kind)
+    return false;
+  const id = key.slice(idx + 1);
+  if (id.length === 0)
+    return false;
+  return canonicalTargetKey(makeTargetId(kind, id)) === key;
+}
+function requireCanonicalTargetKeys(value, where) {
+  const keys = requireStringArray(value, where);
+  for (const key of keys) {
+    if (!isCanonicalTargetKey(key))
+      throw new SnapshotContractError(`"${key}" in ${where} is not a canonical target key`);
+  }
+  return keys;
+}
+function requireCanonicalAssertionKeys(obj, where) {
+  for (const key of Object.keys(obj)) {
+    if (!isCanonicalAssertionKey(key)) {
+      throw new SnapshotContractError(`Assertion key "${key}" in ${where} is not canonical`);
+    }
+  }
+}
+function validateFederatedLogs(value) {
+  if (!Array.isArray(value))
+    throw new SnapshotContractError("federatedLogs must be an array");
+  return value.map((item, idx) => {
+    const obj = requireObject(item, `federatedLogs[${idx}]`);
+    rejectUnknownKeys(obj, ["log", "adrIds", "sourceRef"], `federatedLogs[${idx}]`);
+    const log = requireString(obj.log ?? null, `federatedLogs[${idx}].log`);
+    const adrIds = requireStringArray(obj.adrIds ?? null, `federatedLogs[${idx}].adrIds`);
+    return {
+      log,
+      adrIds,
+      ...obj.sourceRef !== undefined ? { sourceRef: requireString(obj.sourceRef, `federatedLogs[${idx}].sourceRef`) } : {}
+    };
+  });
+}
+function validateTargets(value) {
+  const obj = requireObject(value, "targets");
+  rejectUnknownKeys(obj, ["trackedPaths", "dependencies", "entities", "resources", "apis", "data"], "targets");
+  const targets = {};
+  if (obj.trackedPaths !== undefined)
+    targets.trackedPaths = requireStringArray(obj.trackedPaths, "targets.trackedPaths");
+  if (obj.dependencies !== undefined) {
+    if (!Array.isArray(obj.dependencies))
+      throw new SnapshotContractError("targets.dependencies must be an array");
+    targets.dependencies = obj.dependencies.map((item, idx) => {
+      const dep = requireObject(item, `targets.dependencies[${idx}]`);
+      rejectUnknownKeys(dep, ["name", "version"], `targets.dependencies[${idx}]`);
+      return {
+        name: requireString(dep.name ?? null, `targets.dependencies[${idx}].name`),
+        ...dep.version !== undefined ? { version: requireString(dep.version, `targets.dependencies[${idx}].version`) } : {}
+      };
+    });
+  }
+  if (obj.entities !== undefined) {
+    if (!Array.isArray(obj.entities))
+      throw new SnapshotContractError("targets.entities must be an array");
+    targets.entities = obj.entities.map((item, idx) => {
+      const ent = requireObject(item, `targets.entities[${idx}]`);
+      rejectUnknownKeys(ent, ["id", "owner"], `targets.entities[${idx}]`);
+      return {
+        id: requireString(ent.id ?? null, `targets.entities[${idx}].id`),
+        ...ent.owner !== undefined ? { owner: requireString(ent.owner, `targets.entities[${idx}].owner`) } : {}
+      };
+    });
+  }
+  if (obj.resources !== undefined) {
+    if (!Array.isArray(obj.resources))
+      throw new SnapshotContractError("targets.resources must be an array");
+    targets.resources = obj.resources.map((item, idx) => {
+      const r = requireObject(item, `targets.resources[${idx}]`);
+      rejectUnknownKeys(r, ["id", "securitySurface", "production", "regulated"], `targets.resources[${idx}]`);
+      return {
+        id: requireString(r.id ?? null, `targets.resources[${idx}].id`),
+        ...r.securitySurface !== undefined ? { securitySurface: requireBoolean(r.securitySurface, `targets.resources[${idx}].securitySurface`) } : {},
+        ...r.production !== undefined ? { production: requireBoolean(r.production, `targets.resources[${idx}].production`) } : {},
+        ...r.regulated !== undefined ? { regulated: requireBoolean(r.regulated, `targets.resources[${idx}].regulated`) } : {}
+      };
+    });
+  }
+  if (obj.apis !== undefined) {
+    if (!Array.isArray(obj.apis))
+      throw new SnapshotContractError("targets.apis must be an array");
+    targets.apis = obj.apis.map((item, idx) => {
+      const a = requireObject(item, `targets.apis[${idx}]`);
+      rejectUnknownKeys(a, ["id", "securitySurface", "production"], `targets.apis[${idx}]`);
+      return {
+        id: requireString(a.id ?? null, `targets.apis[${idx}].id`),
+        ...a.securitySurface !== undefined ? { securitySurface: requireBoolean(a.securitySurface, `targets.apis[${idx}].securitySurface`) } : {},
+        ...a.production !== undefined ? { production: requireBoolean(a.production, `targets.apis[${idx}].production`) } : {}
+      };
+    });
+  }
+  if (obj.data !== undefined) {
+    if (!Array.isArray(obj.data))
+      throw new SnapshotContractError("targets.data must be an array");
+    targets.data = obj.data.map((item, idx) => {
+      const d = requireObject(item, `targets.data[${idx}]`);
+      rejectUnknownKeys(d, ["id", "residency", "regulated"], `targets.data[${idx}]`);
+      return {
+        id: requireString(d.id ?? null, `targets.data[${idx}].id`),
+        ...d.residency !== undefined ? { residency: requireString(d.residency, `targets.data[${idx}].residency`) } : {},
+        ...d.regulated !== undefined ? { regulated: requireBoolean(d.regulated, `targets.data[${idx}].regulated`) } : {}
+      };
+    });
+  }
+  return targets;
+}
+function validateAssertionSource(value, where) {
+  const obj = requireObject(value, where);
+  rejectUnknownKeys(obj, ["fileContent", "sourceRef", "compiledArtifact"], where);
+  const source = {};
+  if (obj.fileContent !== undefined)
+    source.fileContent = requireString(obj.fileContent, `${where}.fileContent`);
+  if (obj.sourceRef !== undefined)
+    source.sourceRef = requireString(obj.sourceRef, `${where}.sourceRef`);
+  if (obj.compiledArtifact !== undefined) {
+    const validation = validateRegoWasmPolicyEnvelopeV1(obj.compiledArtifact);
+    if (!validation.ok)
+      throw new SnapshotContractError(`${where}.compiledArtifact: ${validation.message}`);
+    source.compiledArtifact = validation.envelope;
+  }
+  return source;
+}
+function validateAssertionInputs(value) {
+  const obj = requireObject(value, "assertionInputs");
+  rejectUnknownKeys(obj, ["sources", "inputs"], "assertionInputs");
+  const sources = {};
+  const inputs = {};
+  if (obj.sources !== undefined) {
+    const src = requireObject(obj.sources, "assertionInputs.sources");
+    requireCanonicalAssertionKeys(src, "assertionInputs.sources");
+    for (const [key, val] of Object.entries(src)) {
+      sources[key] = validateAssertionSource(val, `assertionInputs.sources["${key}"]`);
+    }
+  }
+  if (obj.inputs !== undefined) {
+    const inp = requireObject(obj.inputs, "assertionInputs.inputs");
+    requireCanonicalAssertionKeys(inp, "assertionInputs.inputs");
+    for (const [key, val] of Object.entries(inp)) {
+      const entry = requireObject(val, `assertionInputs.inputs["${key}"]`);
+      rejectUnknownKeys(entry, ["document"], `assertionInputs.inputs["${key}"]`);
+      if (entry.document === undefined)
+        throw new SnapshotContractError(`assertionInputs.inputs["${key}"].document is required`);
+      inputs[key] = { document: entry.document };
+    }
+  }
+  return { sources, inputs };
+}
+function validateIdentity(value) {
+  const obj = requireObject(value, "identity");
+  rejectUnknownKeys(obj, ["principals", "teams", "codeowners", "catalogOwners"], "identity");
+  if (!Array.isArray(obj.principals))
+    throw new SnapshotContractError("identity.principals must be an array");
+  const seenPrincipals = new Set;
+  const principals = obj.principals.map((item, idx) => {
+    const p = requireObject(item, `identity.principals[${idx}]`);
+    rejectUnknownKeys(p, ["id", "active", "kind"], `identity.principals[${idx}]`);
+    const id = requireString(p.id ?? null, `identity.principals[${idx}].id`);
+    if (seenPrincipals.has(id))
+      throw new SnapshotContractError(`Duplicate principal id "${id}"`);
+    seenPrincipals.add(id);
+    const kind = requireString(p.kind ?? null, `identity.principals[${idx}].kind`);
+    if (kind !== "human" && kind !== "team")
+      throw new SnapshotContractError(`identity.principals[${idx}].kind must be "human" or "team"`);
+    return { id, active: requireBoolean(p.active ?? null, `identity.principals[${idx}].active`), kind };
+  });
+  const teams = Array.isArray(obj.teams) ? obj.teams.map((item, idx) => {
+    const t = requireObject(item, `identity.teams[${idx}]`);
+    rejectUnknownKeys(t, ["id", "members"], `identity.teams[${idx}]`);
+    return {
+      id: requireString(t.id ?? null, `identity.teams[${idx}].id`),
+      members: requireStringArray(t.members ?? null, `identity.teams[${idx}].members`)
+    };
+  }) : obj.teams === undefined ? [] : (() => {
+    throw new SnapshotContractError("identity.teams must be an array");
+  })();
+  const identity = { principals, teams };
+  const principalKindById = new Map(principals.map((p) => [p.id, p.kind]));
+  const teamIds = new Set;
+  for (const team of teams) {
+    if (teamIds.has(team.id))
+      throw new SnapshotContractError(`Duplicate team id "${team.id}"`);
+    teamIds.add(team.id);
+    const kind = principalKindById.get(team.id);
+    if (kind === undefined)
+      throw new SnapshotContractError(`Team "${team.id}" has no matching principal`);
+    if (kind !== "team")
+      throw new SnapshotContractError(`Team "${team.id}" collides with a non-team principal`);
+  }
+  for (const p of principals) {
+    if (p.kind === "team" && !teamIds.has(p.id)) {
+      throw new SnapshotContractError(`Team principal "${p.id}" has no membership entry`);
+    }
+  }
+  if (obj.codeowners !== undefined) {
+    if (!Array.isArray(obj.codeowners))
+      throw new SnapshotContractError("identity.codeowners must be an array");
+    identity.codeowners = obj.codeowners.map((item, idx) => {
+      const rule = requireObject(item, `identity.codeowners[${idx}]`);
+      rejectUnknownKeys(rule, ["pattern", "owners"], `identity.codeowners[${idx}]`);
+      return {
+        pattern: requireString(rule.pattern ?? null, `identity.codeowners[${idx}].pattern`),
+        owners: requireStringArray(rule.owners ?? null, `identity.codeowners[${idx}].owners`)
+      };
+    });
+  }
+  if (obj.catalogOwners !== undefined) {
+    const co = requireObject(obj.catalogOwners, "identity.catalogOwners");
+    const map = Object.create(null);
+    for (const [key, owners] of Object.entries(co)) {
+      map[key] = requireStringArray(owners, `identity.catalogOwners["${key}"]`);
+    }
+    identity.catalogOwners = map;
+  }
+  return identity;
+}
+function validateScopeEvidence(value) {
+  const obj = requireObject(value, "scopeEvidence");
+  rejectUnknownKeys(obj, ["baseInputs"], "scopeEvidence");
+  if (obj.baseInputs === undefined)
+    return {};
+  const base = requireObject(obj.baseInputs, "scopeEvidence.baseInputs");
+  requireCanonicalAssertionKeys(base, "scopeEvidence.baseInputs");
+  const baseInputs = {};
+  for (const [key, val] of Object.entries(base)) {
+    const entry = requireObject(val, `scopeEvidence.baseInputs["${key}"]`);
+    rejectUnknownKeys(entry, ["document"], `scopeEvidence.baseInputs["${key}"]`);
+    if (entry.document === undefined)
+      throw new SnapshotContractError(`scopeEvidence.baseInputs["${key}"].document is required`);
+    baseInputs[key] = { document: entry.document };
+  }
+  return { baseInputs };
+}
+function validateRoutingEvidence(value) {
+  const obj = requireObject(value, "routingEvidence");
+  rejectUnknownKeys(obj, ["costEvidence", "dataResidency", "humanRequested", "securitySurfaceTargetKeys", "regulatedTargetKeys", "productionTargetKeys"], "routingEvidence");
+  const evidence = {};
+  if (obj.costEvidence !== undefined) {
+    const c = requireObject(obj.costEvidence, "routingEvidence.costEvidence");
+    rejectUnknownKeys(c, ["normalizedCost", "threshold"], "routingEvidence.costEvidence");
+    evidence.costEvidence = {
+      normalizedCost: requireNumber(c.normalizedCost ?? null, "routingEvidence.costEvidence.normalizedCost"),
+      threshold: requireNumber(c.threshold ?? null, "routingEvidence.costEvidence.threshold")
+    };
+  }
+  if (obj.dataResidency !== undefined) {
+    const d = requireObject(obj.dataResidency, "routingEvidence.dataResidency");
+    rejectUnknownKeys(d, ["present"], "routingEvidence.dataResidency");
+    evidence.dataResidency = { present: requireBoolean(d.present ?? null, "routingEvidence.dataResidency.present") };
+  }
+  if (obj.humanRequested !== undefined) {
+    const h = requireObject(obj.humanRequested, "routingEvidence.humanRequested");
+    rejectUnknownKeys(h, ["requester"], "routingEvidence.humanRequested");
+    evidence.humanRequested = { requester: requireString(h.requester ?? null, "routingEvidence.humanRequested.requester") };
+  }
+  if (obj.securitySurfaceTargetKeys !== undefined) {
+    evidence.securitySurfaceTargets = new Set(requireCanonicalTargetKeys(obj.securitySurfaceTargetKeys, "routingEvidence.securitySurfaceTargetKeys"));
+  }
+  if (obj.regulatedTargetKeys !== undefined) {
+    evidence.regulatedTargets = new Set(requireCanonicalTargetKeys(obj.regulatedTargetKeys, "routingEvidence.regulatedTargetKeys"));
+  }
+  if (obj.productionTargetKeys !== undefined) {
+    evidence.productionTargets = new Set(requireCanonicalTargetKeys(obj.productionTargetKeys, "routingEvidence.productionTargetKeys"));
+  }
+  return evidence;
+}
+function loadSnapshotBundle(text) {
+  const raw = parseSnapshotJson(text);
+  const bundle = requireObject(raw, "snapshot bundle");
+  rejectUnknownKeys(bundle, ["schemaVersion", "federatedLogs", "log", "targets", "assertionInputs", "identity", "scopeEvidence", "routingEvidence"], "snapshot bundle");
+  if (bundle.schemaVersion !== "adrkit.pass0.snapshot/v1") {
+    throw new SnapshotContractError('snapshot schemaVersion must be exactly "adrkit.pass0.snapshot/v1"');
+  }
+  const normalized = {
+    targets: bundle.targets !== undefined ? validateTargets(bundle.targets) : {},
+    assertionInputs: bundle.assertionInputs !== undefined ? validateAssertionInputs(bundle.assertionInputs) : { sources: {}, inputs: {} }
+  };
+  if (bundle.log !== undefined)
+    normalized.resolutionLog = requireString(bundle.log, "log");
+  if (bundle.federatedLogs !== undefined)
+    normalized.federatedLogs = validateFederatedLogs(bundle.federatedLogs);
+  if (bundle.identity !== undefined)
+    normalized.identity = validateIdentity(bundle.identity);
+  if (bundle.scopeEvidence !== undefined)
+    normalized.scopeEvidence = validateScopeEvidence(bundle.scopeEvidence);
+  if (bundle.routingEvidence !== undefined)
+    normalized.routingEvidence = validateRoutingEvidence(bundle.routingEvidence);
+  return normalized;
+}
+
+// src/evaluate.ts
+var TARGET_REGISTRY = createTargetResolutionRegistry([createPathTargetResolver(), createPackageTargetResolver()]);
+var ASSERTION_ENGINES = createAssertionEngineRegistry({ jsonpath: createJsonPathEngine() });
+var ISO_DATE = /^\d{4}-\d{2}-\d{2}$/;
+function isValidIsoDate(value) {
+  if (!ISO_DATE.test(value))
+    return false;
+  const [y, m, d] = value.split("-").map(Number);
+  if (m < 1 || m > 12 || d < 1 || d > 31)
+    return false;
+  const date = new Date(Date.UTC(y, m - 1, d));
+  return date.getUTCFullYear() === y && date.getUTCMonth() === m - 1 && date.getUTCDate() === d;
+}
+function buildInput(proposalPath, corpus, snapshot, date) {
+  return {
+    corpus,
+    proposalPath,
+    ...snapshot.federatedLogs ? { federatedLogs: snapshot.federatedLogs } : {},
+    ...snapshot.resolutionLog !== undefined ? { resolutionLog: snapshot.resolutionLog } : {},
+    targets: snapshot.targets,
+    targetRegistry: TARGET_REGISTRY,
+    assertionInputs: snapshot.assertionInputs,
+    assertionEngines: ASSERTION_ENGINES,
+    ...snapshot.identity ? { identity: snapshot.identity } : {},
+    ...snapshot.scopeEvidence ? { scopeEvidence: snapshot.scopeEvidence } : {},
+    ...snapshot.routingEvidence ? { routingEvidence: snapshot.routingEvidence } : {},
+    evaluationDate: date
+  };
+}
+function renderHuman(report) {
+  const lines = [`Pass 0 evaluation of ${report.proposalPath} — outcome: ${report.outcome}`];
+  for (const result of report.results) {
+    const severity = result.status === "fail" && result.severity ? ` (${result.severity})` : "";
+    lines.push(`  ${result.rule}: ${result.status}${severity} — ${result.reason}`);
+  }
+  const { routing } = report;
+  const target = routing.target.kind === "resolved" ? `${routing.target.human} (via ${routing.target.via})` : routing.target.kind;
+  lines.push(`  routing: ${routing.escalate ? `escalate [${routing.reasons.join(", ")}]` : "no escalation"}, target: ${target}`);
+  return `${lines.join(`
+`)}
+`;
+}
+async function evaluate(options) {
+  const cwd = options.cwd ?? process.cwd();
+  if (!isValidIsoDate(options.date)) {
+    return { exitCode: 2, stdout: "", stderr: `adr evaluate: --date must be a valid YYYY-MM-DD (got "${options.date}")
+` };
+  }
+  let snapshot;
+  try {
+    const text = await readFile(options.snapshotPath, "utf8");
+    snapshot = loadSnapshotBundle(text);
+  } catch (error) {
+    if (error instanceof SnapshotContractError) {
+      return { exitCode: 2, stdout: "", stderr: `adr evaluate: ${error.message}
+` };
+    }
+    return {
+      exitCode: 2,
+      stdout: "",
+      stderr: `adr evaluate: could not read snapshot "${options.snapshotPath}": ${error instanceof Error ? error.message : String(error)}
+`
+    };
+  }
+  const dir = options.dir ?? dirname(options.proposalPath);
+  const corpus = await lintCorpus({ paths: [dir, options.proposalPath], cwd });
+  const proposalPath = normalizeDisplayPath(options.proposalPath, cwd);
+  const outcome = evaluatePass0(buildInput(proposalPath, corpus, snapshot, options.date));
+  if (outcome.kind === "input-error") {
+    return {
+      exitCode: 2,
+      stdout: "",
+      stderr: `adr evaluate: ${outcome.error.code} — "${proposalPath}" has status "${outcome.error.actualStatus}", not draft/proposed
+`
+    };
+  }
+  const { report, patch } = outcome.result;
+  const exitCode = report.outcome === "returned" ? 1 : 0;
+  if (options.json) {
+    const envelope = {
+      result: { report, patch },
+      metadata: { evaluatorVersion: "0.1.0" }
+    };
+    return { exitCode, stdout: canonicalBytes(envelope), stderr: "" };
+  }
+  return { exitCode, stdout: renderHuman(report), stderr: "" };
+}
+
+// src/main-module.ts
+import { existsSync, realpathSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+function isMainModule(moduleUrl, argvPath) {
+  if (!argvPath || !existsSync(argvPath))
+    return false;
+  return realpathSync(fileURLToPath(moduleUrl)) === realpathSync(argvPath);
+}
+
+// src/index.ts
+function writeStdout(text) {
+  process.stdout.write(text);
+}
+function writeStderr(text) {
+  process.stderr.write(text);
+}
+function usage(message) {
+  if (message)
+    writeStderr(`${message}
+`);
+  writeStderr(`Usage:
+  adr lint [paths...] [--json] [--dir docs/adr]
+  adr migrate --from madr [--dir docs/adr] [--dry-run] [--json]
+  adr new <title> [--status draft] [--dir docs/adr] [--json]
+  adr graph [--dir docs/adr] [--format dot|json]
+  adr explain <path> [--dir docs/adr] [--json]
+  adr check <files...> [--dir docs/adr] [--json]
+  adr evaluate <proposal-path> --snapshot <bundle.json> --date YYYY-MM-DD [--json] [--dir docs/adr]
+
+Round-trip sync is explicitly unsupported (ADR-0008); migrate is one-way and non-destructive.
+`);
+  return 2;
+}
+function parseCommandArgs(args, options) {
+  return parseArgs({ args, options, allowPositionals: true, strict: true });
+}
+function renderFinding(finding) {
+  const field = finding.field ? ` ${finding.field}` : "";
+  const id = finding.id ? ` ${finding.id}` : "";
+  const pattern = finding.pattern ? ` ${finding.pattern}` : "";
+  return `  ${finding.severity} ${finding.rule}${id}${field}${pattern}: ${finding.message}
+`;
+}
+function renderHumanLint(findings) {
+  const grouped = new Map;
+  for (const finding of findings) {
+    const group = finding.path ?? "(corpus)";
+    let list = grouped.get(group);
+    if (!list) {
+      list = [];
+      grouped.set(group, list);
+    }
+    list.push(finding);
+  }
+  let output = "";
+  for (const [path, groupFindings] of [...grouped.entries()].sort(([a], [b]) => a.localeCompare(b))) {
+    output += `${path}
+`;
+    for (const finding of groupFindings) {
+      output += renderFinding(finding);
+    }
+  }
+  return output;
+}
+async function runLint(args) {
+  let parsed;
+  try {
+    parsed = parseCommandArgs(args, {
+      json: { type: "boolean", default: false },
+      dir: { type: "string", default: "docs/adr" }
+    });
+  } catch (error) {
+    return usage(error instanceof Error ? error.message : String(error));
+  }
+  const result = await lintCorpus2({
+    dir: String(parsed.values.dir),
+    paths: parsed.positionals
+  });
+  const findings = sortFindings(result.findings);
+  const counts = countFindings(findings);
+  if (parsed.values.json) {
+    writeStdout(`${JSON.stringify({ checked: result.checked, findings }, null, 2)}
+`);
+  } else {
+    const humanFindings = renderHumanLint(findings);
+    if (humanFindings)
+      writeStderr(humanFindings);
+    writeStdout(`checked ${result.checked} records, ${counts.errors} errors, ${counts.warnings} warnings
+`);
+  }
+  return exitCodeForFindings(findings);
+}
+function renderHumanMigrate(result) {
+  const counts = {
+    migrated: 0,
+    updated: 0,
+    unchanged: 0,
+    diverged: 0,
+    skipped: 0
+  };
+  let output = "";
+  for (const item of result.results) {
+    counts[item.outcome] += 1;
+    output += `${item.outcome}  ${item.path}
+`;
+  }
+  output += `summary: migrated ${counts.migrated}, updated ${counts.updated}, unchanged ${counts.unchanged}, diverged ${counts.diverged}, skipped ${counts.skipped}
+`;
+  output += `Divergence (report only):
+`;
+  if (result.divergence.length === 0) {
+    output += `  none
+`;
+  } else {
+    for (const item of result.divergence) {
+      output += `  ${item.path}  sourceRef=${item.sourceRef}
+`;
+    }
+  }
+  if (result.findings.length > 0) {
+    output += `Findings:
+`;
+    for (const finding of result.findings) {
+      output += renderFinding(finding);
+    }
+  }
+  return output;
+}
+async function runMigrate(args) {
+  let parsed;
+  try {
+    parsed = parseCommandArgs(args, {
+      from: { type: "string" },
+      dir: { type: "string", default: "docs/adr" },
+      "dry-run": { type: "boolean", default: false },
+      json: { type: "boolean", default: false }
+    });
+  } catch (error) {
+    return usage(error instanceof Error ? error.message : String(error));
+  }
+  if (parsed.positionals.length > 0)
+    return usage("adr migrate does not accept positional arguments");
+  const from = parsed.values.from;
+  if (from !== "madr") {
+    return usage(from ? `adr migrate --from ${String(from)} is not supported yet; only --from madr is available, and round-trip sync is unsupported (ADR-0008)` : "adr migrate requires --from madr; non-MADR sources and round-trip sync are unsupported in this phase (ADR-0008)");
+  }
+  const result = await migrateMadr({
+    dir: String(parsed.values.dir),
+    write: parsed.values["dry-run"] !== true
+  });
+  if (parsed.values.json) {
+    writeStdout(`${JSON.stringify(result, null, 2)}
+`);
+  } else {
+    writeStdout(renderHumanMigrate(result));
+  }
+  return 0;
+}
+async function runNew(args) {
+  let parsed;
+  try {
+    parsed = parseCommandArgs(args, {
+      json: { type: "boolean", default: false },
+      dir: { type: "string", default: "docs/adr" },
+      status: { type: "string", default: "draft" }
+    });
+  } catch (error) {
+    return usage(error instanceof Error ? error.message : String(error));
+  }
+  const title = parsed.positionals.join(" ").trim();
+  if (!title)
+    return usage("adr new requires a title");
+  try {
+    const result = await createAdr({
+      title,
+      status: String(parsed.values.status),
+      dir: String(parsed.values.dir)
+    });
+    if (parsed.values.json) {
+      writeStdout(`${JSON.stringify({ id: result.id, path: result.path }, null, 2)}
+`);
+    } else {
+      writeStdout(`${result.path}
+`);
+    }
+    return 0;
+  } catch (error) {
+    if (error instanceof ScaffoldError) {
+      writeStderr(`${error.message}
+`);
+      return error.code === "exists" ? 1 : 2;
+    }
+    throw error;
+  }
+}
+async function runGraph(args) {
+  let parsed;
+  try {
+    parsed = parseCommandArgs(args, {
+      dir: { type: "string", default: "docs/adr" },
+      format: { type: "string", default: "dot" }
+    });
+  } catch (error) {
+    return usage(error instanceof Error ? error.message : String(error));
+  }
+  if (parsed.positionals.length > 0)
+    return usage("adr graph does not accept positional arguments");
+  const format = String(parsed.values.format);
+  if (format !== "dot" && format !== "json")
+    return usage("adr graph --format must be dot or json");
+  const result = await lintCorpus2({ dir: String(parsed.values.dir) });
+  const graph = buildAdrGraph(result.records);
+  writeStdout(format === "json" ? renderJsonGraph(graph) : renderDotGraph(graph));
+  return 0;
+}
+async function runExplain(args) {
+  let parsed;
+  try {
+    parsed = parseCommandArgs(args, {
+      json: { type: "boolean", default: false },
+      dir: { type: "string", default: "docs/adr" }
+    });
+  } catch (error) {
+    return usage(error instanceof Error ? error.message : String(error));
+  }
+  if (parsed.positionals.length !== 1)
+    return usage("adr explain requires exactly one path");
+  const path = parsed.positionals[0];
+  if (!path)
+    return usage("adr explain requires exactly one path");
+  const corpus = await lintCorpus2({ dir: String(parsed.values.dir) });
+  const corpusFindings = sortFindings(corpus.findings);
+  if (exitCodeForFindings(corpusFindings) !== 0) {
+    if (parsed.values.json) {
+      writeStdout(`${JSON.stringify({ path, governedBy: [], findings: corpusFindings }, null, 2)}
+`);
+    } else {
+      const humanFindings = renderHumanLint(corpusFindings);
+      if (humanFindings)
+        writeStderr(humanFindings);
+    }
+    return 1;
+  }
+  const recordsById = new Map(corpus.records.map((record) => [record.frontmatter.id, record]));
+  const resolution = resolveAffects({ records: corpus.records, changedFiles: [path] });
+  const governedBy = resolution.matches.map((match) => ({
+    recordId: match.recordId,
+    title: recordsById.get(match.recordId)?.frontmatter.title ?? "",
+    firedMatchers: match.firedMatchers
+  }));
+  const findings = sortFindings(resolution.findings);
+  if (parsed.values.json) {
+    writeStdout(`${JSON.stringify({ path, governedBy, findings }, null, 2)}
+`);
+    return 0;
+  }
+  if (governedBy.length === 0) {
+    writeStdout(`No decision governs ${path}.
+`);
+  } else {
+    for (const match of governedBy) {
+      writeStdout(`${match.recordId}  ${match.title}
+`);
+      for (const matcher of match.firedMatchers) {
+        writeStdout(`  via ${matcher.type}: ${matcher.pattern}
+`);
+      }
+    }
+  }
+  if (findings.length > 0) {
+    writeStdout(`Findings:
+`);
+    for (const finding of findings) {
+      writeStdout(renderFinding(finding));
+    }
+  }
+  return 0;
+}
+function renderHumanCheck(outcome) {
+  let output = "";
+  if (outcome.governedBy.length === 0) {
+    output += `No decisions govern the changed files.
+`;
+  } else {
+    output += `Decisions governing this change:
+`;
+    for (const decision of outcome.governedBy) {
+      output += `  ${decision.recordId}  ${decision.title}
+`;
+      for (const matcher of decision.firedMatchers) {
+        output += `    via ${matcher.type}: ${matcher.pattern}
+`;
+      }
+    }
+  }
+  if (outcome.findings.length > 0) {
+    output += `Findings:
+`;
+    output += renderHumanLint(outcome.findings);
+  }
+  const changedRecordErrors = outcome.findings.filter((finding) => finding.severity === "error" && finding.path && outcome.changedRecords.includes(finding.path)).length;
+  output += `checked: ${outcome.governedBy.length} governing, ${outcome.changedRecords.length} changed records, ${changedRecordErrors} changed-record errors
+`;
+  return output;
+}
+async function runCheck(args) {
+  let parsed;
+  try {
+    parsed = parseCommandArgs(args, {
+      json: { type: "boolean", default: false },
+      dir: { type: "string", default: "docs/adr" }
+    });
+  } catch (error) {
+    return usage(error instanceof Error ? error.message : String(error));
+  }
+  const dir = String(parsed.values.dir);
+  const lint = await lintCorpus2({ dir });
+  const outcome = checkChanges({ lint, changedFiles: parsed.positionals, dir });
+  if (parsed.values.json) {
+    writeStdout(`${JSON.stringify(outcome, null, 2)}
+`);
+  } else {
+    writeStdout(renderHumanCheck(outcome));
+  }
+  return outcome.ok ? 0 : 1;
+}
+async function runEvaluate(args) {
+  let parsed;
+  try {
+    parsed = parseCommandArgs(args, {
+      snapshot: { type: "string" },
+      date: { type: "string" },
+      json: { type: "boolean", default: false },
+      dir: { type: "string" }
+    });
+  } catch (error) {
+    return usage(error instanceof Error ? error.message : String(error));
+  }
+  if (parsed.positionals.length !== 1)
+    return usage("adr evaluate requires exactly one proposal path");
+  const proposalPath = parsed.positionals[0];
+  if (!proposalPath)
+    return usage("adr evaluate requires a proposal path");
+  const snapshot = parsed.values.snapshot;
+  if (typeof snapshot !== "string" || snapshot.length === 0) {
+    return usage("adr evaluate requires --snapshot <bundle.json>");
+  }
+  const date = parsed.values.date;
+  if (typeof date !== "string" || date.length === 0) {
+    return usage("adr evaluate requires --date YYYY-MM-DD");
+  }
+  const result = await evaluate({
+    proposalPath,
+    snapshotPath: snapshot,
+    date,
+    json: parsed.values.json === true,
+    ...typeof parsed.values.dir === "string" ? { dir: parsed.values.dir } : {}
+  });
+  if (result.stderr)
+    writeStderr(result.stderr);
+  if (result.stdout)
+    writeStdout(result.stdout);
+  return result.exitCode;
+}
+async function main(argv = process.argv.slice(2)) {
+  const [command, ...args] = argv;
+  try {
+    if (command === "lint")
+      return await runLint(args);
+    if (command === "migrate")
+      return await runMigrate(args);
+    if (command === "new")
+      return await runNew(args);
+    if (command === "graph")
+      return await runGraph(args);
+    if (command === "explain")
+      return await runExplain(args);
+    if (command === "check")
+      return await runCheck(args);
+    if (command === "evaluate")
+      return await runEvaluate(args);
+    return usage(command ? `Unknown command "${command}"` : undefined);
+  } catch (error) {
+    writeStderr(`${error instanceof Error ? error.message : String(error)}
+`);
+    return 1;
+  }
+}
+if (isMainModule(import.meta.url, process.argv[1])) {
+  process.exitCode = await main();
+}
+export {
+  main
+};