@ecoma-io/archkeep 0.13.0

package/src/governance/profile-registry.mjs

@@ -0,0 +1,366 @@
+/**
+ * Named boundary-law profiles: rule blocks a workspace can give a name to,
+ * stack on a base, and then select by name instead of by file.
+ *
+ * A profile is data, not a new dialect. Each profile body is a policy block of
+ * the exact four keys every boundaryConfig dialect already shares —
+ * `depConstraints`, `moduleBoundaryOptions`, `boundarySuppressions`, and
+ * `fitness` (`../../config.mjs`'s `findBoundaryConfigViolations`, documented in
+ * `../../../../docs/concepts/policies.md`) — validated by that same validator,
+ * so a profile cannot state a constraint the file dialects cannot. The
+ * resolution result is fed through `../../config.mjs`'s `policyFrom` tail, so
+ * there is exactly ONE enforcement path: a profile is a way to name and reuse a
+ * policy, never a second kind of policy that could disagree with a file about
+ * the same row.
+ *
+ * The profile list itself is JSON, named by the `profiles` plugin option
+ * (`../../options.mjs`). A profile has a `name`, an optional `base` (the name
+ * of another profile whose effective block it inherits), and a `block` of the
+ * four keys. Precedence is deterministic and documented in
+ * `../../../../docs/concepts/profiles.md`: a child profile's `depConstraints`
+ * rows are appended AFTER its base's rows (the composition semantics of
+ * `@nx/enforce-module-boundaries`, where a dependency must satisfy EVERY row
+ * whose `sourceTag` its source project carries, so axes compose rather than
+ * replace); its `moduleBoundaryOptions` keys overwrite the base's key by key;
+ * its `boundarySuppressions` rows — and its `fitness` rows — are appended
+ * after the base's. `base` may
+ * chain by name — `b` on `a`, `c` on `b` — resolved depth-first, earlier
+ * profiles first, so a chain reads in the order it was written.
+ *
+ * ## What is loud, and why
+ *
+ * A profile registry that silently compensated for its own defects would
+ * repeat the one failure this tool exists to end. Three conditions are thrown,
+ * all by name:
+ *
+ * - A profile whose reference is **unknown** — `base` names a profile that
+ *   does not exist. Read as "no base", the profile would shed the rows it was
+ *   meant to inherit: the stack stops enforcing its base block, and nothing
+ *   says so.
+ * - A **cycle** in a base chain — `a` on `b` on `a`. A cycle has no
+ *   deterministic resolution; stopping it loudly is the only correct answer.
+ * - A profile with **no name**, or no `block` — the first states a rule nobody
+ *   can refer to, the second parses as an empty policy (which `policyFrom`
+ *   would refuse for its own reasons, but the registry names it as a profile
+ *   defect so the reader is looking at the right file).
+ *
+ * Missing `name` is an exit-3 class (`../../../cli.mjs`, `EXIT.error`): the
+ * registry cannot be read, so no command that depends on it can reach a
+ * verdict.
+ *
+ * ## Loading
+ *
+ * `loadProfileRegistry` reads the file named by the `profiles` option. It does
+ * not `import()` the way a `.mjs` boundary config does: a registry whose
+ * entries are data earns the same strict reading as a `.json` boundary law —
+ * plain `JSON.parse`, never JSONC (`../../config.mjs`'s header argues that
+ * dialect). The injectable `readFile` seam is the same one
+ * `../../options.mjs`'s readers take, and everything except the read itself is
+ * pure.
+ */
+import { readFileSync } from "node:fs";
+
+import { policyFrom } from "../config.mjs";
+
+/**
+ * The top-level keys a profiles file may carry. `version` is checked AFTER
+ * defaulting: a file that does not state one is schema 1 by definition, so a
+ * later reader can still tell a v1 registry from a hypothetical v2 — the
+ * default is applied here, at the one place the version is read. `profiles`
+ * is the list. `$schema` is tolerated for editor validation, the same
+ * carve-out the `.json` boundary dialect makes.
+ */
+const REGISTRY_KEYS = ["profiles", "version", "$schema"];
+
+/** A version a reader that predates it must refuse, per `docs/reference/profiles.md`. */
+export const PROFILE_REGISTRY_SCHEMA_VERSION = 1;
+
+/** The registry's schema version: stated, or schema 1 when absent. */
+function registrySchemaVersion(raw) {
+  return raw.version === undefined
+    ? PROFILE_REGISTRY_SCHEMA_VERSION
+    : /** @type {unknown} */ (raw.version);
+}
+
+/**
+ * The four keys a profile's `block` may carry — the boundary laws `policyFrom`
+ * reads, minus `customRules`, deliberately: a profile is a shareable law pack,
+ * and a custom-rule row names a wasm artifact by workspace-relative path and
+ * hash, which does not travel with a registry. A block naming it is refused by
+ * name below, loudly, until profile-carried rules are designed on purpose.
+ */
+const BLOCK_KEYS = ["depConstraints", "moduleBoundaryOptions", "boundarySuppressions", "fitness"];
+
+/**
+ * A profile `name`, matched exactly by `resolveProfile` and typed by an
+ * operator at `--config`/`boundaryConfig`. Restricted to the same safe set
+ * `../architecture-intent/model.mjs`'s boundary names and
+ * `./fitness-registry.mjs`'s fitness names already use, and for the identical
+ * reason: a name is a selector, not a label, so two names that a human reads
+ * as identical must not be able to exist as two different values. Unicode
+ * (a zero-width character, a homoglyph from another script, two normalisation
+ * forms of the same visible glyph) can make two byte-distinct strings render
+ * identically — the duplicate check below compares the raw string, which
+ * would accept both as "unique" and then resolve whichever one an operator's
+ * literal `--config` argument happened to byte-match, silently enforcing the
+ * OTHER one's block. Refusing every character outside this set closes that
+ * off at the source: two names that display the same are now always the same
+ * string, so the existing duplicate check is sufficient again.
+ */
+const NAME_PATTERN = /^[a-zA-Z0-9_-]+$/u;
+
+/** @type {(value: unknown) => value is Record<string, unknown>} */
+const isPlainObject = (value) =>
+  typeof value === "object" && value !== null && !Array.isArray(value);
+
+function describe(value) {
+  if (Array.isArray(value)) return `an array (${JSON.stringify(value)})`;
+  if (value === null) return "null";
+  return `${typeof value} (${JSON.stringify(value) ?? String(value)})`;
+}
+
+/** A profile's declared block, kept ONLY for this command's own data. */
+export function listNames(registry) {
+  return registry.profiles.map((profile) => profile.name);
+}
+
+/**
+ * Everything wrong with a registry, as messages; empty when it is well-formed.
+ * Pure, so a test drives it without a file on disk.
+ *
+ * Every condition is a silent-direction guard: a registry the reader cannot
+ * trust must not be read as smaller than it is.
+ *
+ * @param {unknown} raw The parsed JSON value.
+ * @returns {string[]}
+ */
+export function profileRegistryViolations(raw) {
+  if (!isPlainObject(raw)) {
+    return [`profiles: expected a JSON object, got ${describe(raw)}`];
+  }
+  const violations = [];
+  for (const key of Object.keys(raw)) {
+    if (!REGISTRY_KEYS.includes(key)) {
+      violations.push(
+        `${key}: not a recognised profiles-file key — expected one of ${REGISTRY_KEYS.join(", ")}`,
+      );
+    }
+  }
+  if (registrySchemaVersion(raw) !== PROFILE_REGISTRY_SCHEMA_VERSION) {
+    violations.push(
+      `version: expected ${PROFILE_REGISTRY_SCHEMA_VERSION}, got ${describe(registrySchemaVersion(raw))} — ` +
+        `a registry this reader does not understand must refuse rather than guess`,
+    );
+  }
+  if (!Array.isArray(raw.profiles)) {
+    violations.push(`profiles: must be an array of profiles, got ${describe(raw.profiles)}`);
+    return violations;
+  }
+  const names = new Set();
+  raw.profiles.forEach((profile, index) => {
+    const at = `profiles[${index}]`;
+    if (!isPlainObject(profile)) {
+      violations.push(`${at}: must be an object, got ${describe(profile)}`);
+      return;
+    }
+    const extra = Object.keys(profile).filter((key) => !["name", "base", "block"].includes(key));
+    for (const key of extra) {
+      violations.push(
+        `${at}.${key}: not a profile field — a profile may carry only name, base, block`,
+      );
+    }
+    if (typeof profile.name !== "string" || !NAME_PATTERN.test(profile.name)) {
+      violations.push(
+        `${at}.name: must be a non-empty string of letters, digits, "-" or "_", got ${describe(profile.name)}`,
+      );
+    } else if (names.has(profile.name)) {
+      violations.push(
+        `${at}.name: "${profile.name}" is declared more than once — every profile name must be unique`,
+      );
+    } else {
+      names.add(profile.name);
+    }
+    if (profile.base !== undefined && profile.base !== null) {
+      if (typeof profile.base !== "string" || profile.base.trim() === "") {
+        violations.push(
+          `${at}.base: must be a non-empty string naming another profile, got ${describe(profile.base)}`,
+        );
+      }
+    }
+    if (!isPlainObject(profile.block)) {
+      violations.push(`${at}.block: must be a policy block object, got ${describe(profile.block)}`);
+      return;
+    }
+    const blockExtra = Object.keys(profile.block).filter((key) => !BLOCK_KEYS.includes(key));
+    for (const key of blockExtra) {
+      violations.push(
+        `${at}.block.${key}: not a policy block field — expected one of ${BLOCK_KEYS.join(", ")}`,
+      );
+    }
+  });
+  return violations;
+}
+
+/**
+ * Everything wrong with a profile's reference graph — unknown `base` and
+ * `base` cycles. Separated from `profileRegistryViolations` so a test can pin
+ * each loud condition by name.
+ *
+ * @param {object[]} profiles Validated profile objects.
+ * @returns {string[]}
+ */
+export function profileReferenceViolations(profiles) {
+  const violations = [];
+  const byName = new Map(profiles.map((profile) => [profile.name, profile]));
+  for (const profile of profiles) {
+    if (profile.base === undefined || profile.base === null) continue;
+    const stack = new Set([profile.name]);
+    let current = /** @type {string} */ (profile.base);
+    while (current !== undefined && current !== null) {
+      if (stack.has(current)) {
+        violations.push(
+          `profiles: "${profile.name}"'s base chain contains a cycle through "${current}" — ` +
+            `a cycle has no deterministic resolution`,
+        );
+        break;
+      }
+      const next = byName.get(current);
+      if (next === undefined) {
+        violations.push(
+          `profiles: "${profile.name}" names base "${current}" but no profile with that name exists — ` +
+            `read as "no base", the stack would shed the rows it was meant to inherit`,
+        );
+        break;
+      }
+      stack.add(current);
+      current =
+        next.base === null || next.base === undefined
+          ? undefined
+          : /** @type {string} */ (next.base);
+    }
+  }
+  return violations;
+}
+
+/**
+ * The effective policy block for a profile, its base chain resolved depth-first
+ * with the documented precedence: rows append, option keys overwrite.
+ *
+ * @param {object[]} profiles The registry's full profile list.
+ * @param {string} name The profile to resolve.
+ * @param {Set<string>} [seen] Inheritance stack (used internally by recursion).
+ * @returns {{depConstraints: object[], moduleBoundaryOptions: object, boundarySuppressions: object[],
+ *   fitness?: object[]}} `fitness` is present only when the profile (or a base
+ *   it inherits) declares one — the same absent-is-a-decision posture
+ *   `policyFrom` keeps, so a profile-selected workspace reaches the fitness
+ *   command's "declares no fitness functions" refusal rather than a
+ *   config-loading failure.
+ * @throws {Error} when `name` does not exist or its base chain cycles — never
+ *   silently resolved as "no profile".
+ */
+export function resolveProfile(profiles, name, seen = new Set()) {
+  const profile = profiles.find((candidate) => candidate.name === name);
+  if (profile === undefined) {
+    throw new Error(
+      `archkeep: profile "${name}" does not exist — a policy that selects an unknown profile ` +
+        `enforces nothing and says nothing`,
+    );
+  }
+  if (seen.has(name)) {
+    throw new Error(
+      `archkeep: profile "${name}"'s base chain contains a cycle through "${name}" — ` +
+        `a cycle has no deterministic resolution`,
+    );
+  }
+  seen.add(name);
+  const base =
+    profile.base === undefined || profile.base === null
+      ? null
+      : resolveProfile(profiles, /** @type {string} */ (profile.base), seen);
+  const block = profile.block;
+  const options =
+    base === null
+      ? { ...block.moduleBoundaryOptions }
+      : { ...base.moduleBoundaryOptions, ...block.moduleBoundaryOptions };
+  return {
+    depConstraints: [...(base?.depConstraints ?? []), ...(block.depConstraints ?? [])],
+    moduleBoundaryOptions: options,
+    boundarySuppressions: [
+      ...(base?.boundarySuppressions ?? []),
+      ...(block.boundarySuppressions ?? []),
+    ],
+    // Child `fitness` rows append after base rows, the same composition
+    // semantics every other list-keyed block field uses.
+    ...(base?.fitness !== undefined || block.fitness !== undefined
+      ? { fitness: [...(base?.fitness ?? []), ...(block.fitness ?? [])] }
+      : {}),
+  };
+}
+
+/**
+ * Loads the profiles registry named by the `profiles` plugin option, validates
+ * it by name, and throws loudly on any defect.
+ *
+ * @param {string} path Absolute path of the profiles file.
+ * @param {{readFile?: (path: string) => string|null}} [io] Injectable read,
+ *   the same seam `../../options.mjs`'s readers take; answers `null` when the
+ *   file is not there.
+ * @returns {{profiles: object[]}}
+ * @throws {Error} on a missing/unreadable/unparseable file, or on any
+ *   profile-registry or reference-graph defect.
+ */
+export function loadProfileRegistry(
+  path,
+  {
+    readFile = (p) => {
+      try {
+        return readFileSync(p, "utf8");
+      } catch {
+        return null;
+      }
+    },
+  } = {},
+) {
+  const text = readFile(path);
+  if (text === null) {
+    throw new Error(`archkeep: cannot read profiles file ${path}`);
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(text);
+  } catch (cause) {
+    throw new Error(`archkeep: cannot parse profiles file ${path}: ${cause?.message ?? cause}`, {
+      cause,
+    });
+  }
+  const violations = [
+    ...profileRegistryViolations(parsed),
+    ...(parsed && Array.isArray(parsed.profiles)
+      ? profileReferenceViolations(parsed.profiles)
+      : []),
+  ];
+  if (violations.length > 0) {
+    throw new Error(`archkeep: ${path} is malformed:\n  ${violations.join("\n  ")}`);
+  }
+  /** @type {{profiles: object[]}} */ (parsed);
+  return parsed;
+}
+
+/**
+ * The full profile path `cli.mjs`'s `check` takes when a workspace selects a
+ * profile by name: load the registry, resolve the named profile to its
+ * effective block, and run that through the SAME `policyFrom` tail every
+ * boundary-config dialect uses — one enforcement path, named.
+ *
+ * @param {string} registryPath Absolute path of the profiles file.
+ * @param {string} profileName The profile to resolve.
+ * @param {string} sourceLabel What failed, named in the thrown message.
+ * @param {{readFile?: (path: string) => string|null}} [io]
+ * @returns {{depConstraints: object[], options: object, suppressions: object[], fitness?: object[]}}
+ * @throws {Error} when the registry or the named profile is defective.
+ */
+export function profilePolicy(registryPath, profileName, sourceLabel, io = {}) {
+  const registry = loadProfileRegistry(registryPath, io);
+  const effective = resolveProfile(registry.profiles, profileName);
+  return policyFrom(effective, `${sourceLabel} (profile "${profileName}")`);
+}

package/src/governance/provenance-record.mjs

@@ -0,0 +1,177 @@
+/**
+ * The provenance record: WHO decided a governance row, with WHICH tool, and
+ * optionally WHEN — the auditable half of decision provenance.
+ *
+ * ## Shape
+ *
+ * ```json
+ * { "by": "jane@example.com", "tool": "archkeep:v1", "on": "2026-08-16" }
+ * ```
+ *
+ * `by` and `tool` are required non-empty strings; `on` is optional and is only
+ * ever PRODUCED by the shared clock (`./clock.mjs`). This module has two
+ * surfaces, and the split is the determinism rule made concrete:
+ *
+ * - **Read** — `originViolations`/`validateOrigin` shape-check an `origin`
+ *   already committed in a declaration file. An `on` present there is a static
+ *   fact about committed bytes, byte-identical across every read regardless of
+ *   wall clock, so no clock is needed to read it.
+ * - **Write** — `recordOrigin` is the ONLY producer of `on`. It refuses to run
+ *   without a clock, loudly, and calls `clock.now()` exactly once for the
+ *   record. A workspace that omits `on` entirely calls `recordOrigin` with the
+ *   same clock and gets byte-identical bytes across runs; a workspace that
+ *   records `on` hands a hermetic clock (a build id, a pinned value) so the
+ *   claim is reproducible.
+ *
+ * ## Determinism — asserted both ways
+ *
+ * - Two runs over unchanged rows with the same clock are byte-identical.
+ * - Two runs with different clocks differ — the clock is the single
+ *   non-determinism door, which is exactly why it is the only door.
+ *
+ * ## Null-prototype safety
+ *
+ * `origin` and every nested object are read through plain-object checks that
+ * reject arrays and non-plain objects, and enumeration uses `Object.keys`
+ * (own, enumerable, never the prototype chain) — a crafted `{"__proto__": …}`
+ * or a polluted prototype cannot smuggle keys into a validated origin. This
+ * module builds nothing from untrusted keys; it validates and, at write time,
+ * builds a fresh object with only the three permitted keys.
+ */
+
+import { clockViolations } from "./clock.mjs";
+
+/** The only keys a validated `origin` may carry. */
+export const ORIGIN_KEYS = Object.freeze(["by", "tool", "on"]);
+
+/**
+ * @typedef {object} OriginRecord
+ * @property {string} by Who decided the row — a non-empty string (a name, an
+ *   email, a handle). Free form; no format is enforced.
+ * @property {string} tool Which tool or process recorded the decision — a
+ *   non-empty string (`archkeep:v1`, `claude`, an ADR editor). Free form.
+ * @property {string} [on] When the decision was recorded — present ONLY when
+ *   `recordOrigin` produced it through the shared clock.
+ */
+
+/** @type {(value: unknown) => value is Record<string, unknown>} */
+const isPlainObject = (value) =>
+  value !== null && typeof value === "object" && !Array.isArray(value);
+
+/** A value's type, for an error message that shows what was actually there. */
+function describe(value) {
+  if (Array.isArray(value)) return `an array (${JSON.stringify(value)})`;
+  if (value === null) return "null";
+  return `${typeof value} (${JSON.stringify(value) ?? String(value)})`;
+}
+
+/**
+ * Everything wrong with a raw `origin` record at READ time, as messages; empty
+ * when it is well-formed. Shape only — an `on` committed in a declaration file
+ * is a static fact, so no clock is needed to read it.
+ *
+ * An `io.clock` may be supplied by a caller in a WRITE context (a command that
+ * is about to emit `on`, or a test pinning determinism); it is then validated
+ * itself and every `on` must equal its answer — a raw `on` can never ride
+ * along beside a clock that would say something else.
+ *
+ * @param {unknown} raw
+ * @param {{clock?: import("./clock.mjs").Clock}} [io]
+ * @returns {string[]}
+ */
+export function originViolations(raw, io = {}) {
+  if (!isPlainObject(raw)) {
+    return [`origin must be an object, got ${describe(raw)}`];
+  }
+
+  const violations = [];
+  const allowed = ORIGIN_KEYS;
+  for (const key of Object.keys(raw)) {
+    if (!allowed.includes(key)) {
+      violations.push(
+        `origin.${key}: unknown key — an origin may carry only ${allowed.join(", ")}`,
+      );
+    }
+  }
+
+  if (typeof raw.by !== "string" || raw.by.trim() === "") {
+    violations.push(
+      `origin.by: must be a non-empty string naming who decided, got ${describe(raw.by)}`,
+    );
+  }
+  if (typeof raw.tool !== "string" || raw.tool.trim() === "") {
+    violations.push(
+      `origin.tool: must be a non-empty string naming the tool that recorded the decision, got ${describe(raw.tool)}`,
+    );
+  }
+  if ("on" in raw && (typeof raw.on !== "string" || raw.on.trim() === "")) {
+    violations.push(`origin.on: must be a non-empty string when present, got ${describe(raw.on)}`);
+  }
+
+  // Write-context strictness: a caller that supplied a clock is about to emit
+  // `on`, and the clock is the single door.
+  if (io.clock !== undefined) {
+    violations.push(...clockViolations(io.clock));
+    if ("on" in raw && raw.on !== io.clock.now()) {
+      violations.push(
+        `origin.on: must equal the clock's answer (${JSON.stringify(io.clock.now())}), got ${describe(raw.on)} — the clock is the only producer of 'on'`,
+      );
+    }
+  }
+
+  return violations;
+}
+
+/**
+ * Shape-validates an `origin` at read time and returns the row's own object
+ * when valid; throws one Error naming every violation otherwise.
+ *
+ * Never walks the prototype chain and never builds from untrusted keys, so a
+ * crafted `__proto__` cannot leak into a fresh object.
+ *
+ * @param {unknown} raw
+ * @param {{clock?: import("./clock.mjs").Clock}} [io]
+ * @param {string} at Dotted path of the field, for the message.
+ * @returns {OriginRecord}
+ * @throws {Error} naming every violation at once, prefixed by `at`.
+ */
+export function validateOrigin(raw, io = {}, at = "origin") {
+  const violations = originViolations(raw, io).map((message) =>
+    message.startsWith("origin.")
+      ? `${at}.${message.slice("origin.".length)}`
+      : `${at}: ${message}`,
+  );
+  if (violations.length > 0) {
+    throw new Error(violations.join("; "));
+  }
+  return /** @type {OriginRecord} */ (raw);
+}
+
+/**
+ * The one way a governance record obtains `on`: through the shared clock, and
+ * nowhere else.
+ *
+ * @param {{by: string, tool: string, clock: import("./clock.mjs").Clock}} author
+ *   The two required fields (shape checked like any read-time origin) plus the
+ *   clock that supplies `on`. `clock` is required — an `on` produced without a
+ *   clock is the non-determinism this module exists to exclude, so the absence
+ *   is a loud Error, never a default.
+ * @returns {OriginRecord} `{by, tool, on: clock.now()}`, and ONLY those three
+ *   keys — a fresh object, so nothing from untrusted input rides along.
+ * @throws {Error} on an invalid author, an unusable clock, or a
+ *   non-string/empty clock answer.
+ */
+export function recordOrigin({ by, tool, clock }) {
+  const origin = { by, tool };
+  const shape = originViolations(origin);
+  if (shape.length > 0) {
+    throw new Error(shape.join("; "));
+  }
+  const clockProblems = clockViolations(clock);
+  if (clockProblems.length > 0) {
+    throw new Error(`origin.on: ${clockProblems.join("; ")}`);
+  }
+  // The clock is the single door, and it is called exactly once for this
+  // record, so two calls with the same clock are byte-identical.
+  return { by, tool, on: clock.now() };
+}