@xemahq/xema 0.59.1 → 0.60.1

package/edition/edition-source-pins.mjs

@@ -1,211 +0,0 @@
-// edition-source-pins — a vendor edition's per-edition source pins: the one
-// place that parses the declaration, computes the effective repository pins and
-// authorizes a held commit.
-//
-// A vendor edition's `xema-distribution.json` MAY carry the CLI-owned top-level
-// key `sourcePins`, `[{ repo, ref, until }]`: this edition resolves `repo` at the
-// exact commit `ref` instead of at the data root's shared `repositoryPins`, and
-// `until` states the condition under which the hold ends. Entries are sparse:
-// one exists only for a repository the edition holds back, so an entry equal to
-// the shared pin is refused (it is not a hold). `xema edition pin|unpin` are the
-// only supported way to change them. The kernel's Distribution schema models and
-// validates the key (`DistributionSourcePinsSchema`), so the definition reaches
-// `parseDistribution` unchanged and a reader that parses with the kernel takes
-// `sourcePins` from the parsed manifest (`readKernelEditionSourcePins`).
-// `parseEditionSourcePins` remains for the one reader that runs before any kernel
-// exists (the source checkout plan, `readEditionSourcePins`) and for the pin verbs.
-//
-// `effectiveRepositoryPins` is the ONLY computation of an edition's pins: the
-// committed pins untouched (the same array) when the edition holds nothing,
-// else a copy whose held repositories carry the ref on BOTH axes (`sourceCommit`
-// and `vendoredSourceCommit`), as `createExactCommitSourceAuthority` does.
-//
-// A held commit is authorized, never trusted (`assertEditionPinsAuthorized`):
-// the commit object exists, it is contained in the published ref, and it is a
-// BUILT commit (the same predicate `publishedSourceCommit` uses). No flag or
-// path overrides any of the three.
-//
-// This module is pure of the index builders on purpose: the evidence verifier
-// reads the declaration through it and must not bundle the release builders
-// (edition-pinned-inputs.mjs owns those).
-
-import { execFileSync } from 'node:child_process';
-import { existsSync } from 'node:fs';
-import { join, resolve } from 'node:path';
-
-import { editionsRoot, sourcesRoot } from './edition-workspace.mjs';
-import { COMMIT_PATTERN } from './evidence-grammars.mjs';
-import { builtCommits, PUBLISHED_SOURCE_REF } from './source-authority.mjs';
-import { readStrictJsonFile } from './strict-json.mjs';
-
-export const SOURCE_PINS_KEY = 'sourcePins';
-
-const SOURCE_PIN_KEYS = Object.freeze(['ref', 'repo', 'until']);
-const GRAPH_REPO = /^(repos|submodules)\/[a-z0-9][a-z0-9-]*$/;
-
-/** A refusal of an edition's `sourcePins` declaration or of a held commit. */
-export class EditionSourcePinsError extends Error {
-  constructor(message, options) {
-    super(message, options);
-    this.name = 'EditionSourcePinsError';
-  }
-}
-
-const label = (id) => (id === undefined ? '' : `edition "${id}": `);
-
-/**
- * Strictly parse the value of `sourcePins`. Absent (`undefined`) is no pins.
- * Present, it is a non-empty array of exactly `{repo, ref, until}` objects,
- * `repo` a graph repository path, `ref` an exact lowercase 40-hex commit (never
- * a branch, which would move under a lock), `until` the non-empty exit
- * condition of the hold, no repository twice.
- */
-export function parseEditionSourcePins(raw, id) {
-  if (raw === undefined) {return [];}
-  if (!Array.isArray(raw) || raw.length === 0) {
-    throw new EditionSourcePinsError(`${label(id)}"${SOURCE_PINS_KEY}" must be a non-empty array of {repo, ref, until}; got ${JSON.stringify(raw)}`);
-  }
-  const seen = new Set();
-  return raw.map((entry, index) => {
-    const where = `${label(id)}${SOURCE_PINS_KEY}[${index}] ${JSON.stringify(entry)}`;
-    if (entry === null || typeof entry !== 'object' || Array.isArray(entry) || Object.keys(entry).sort().join() !== SOURCE_PIN_KEYS.join()) {
-      throw new EditionSourcePinsError(`${where} must be exactly {repo, ref, until}; \`until\` (the exit condition of the hold) is required`);
-    }
-    if (typeof entry.repo !== 'string' || !GRAPH_REPO.test(entry.repo)) {
-      throw new EditionSourcePinsError(`${where}: repo must be a repository path (repos/<name> or submodules/<name>)`);
-    }
-    if (typeof entry.ref !== 'string' || !COMMIT_PATTERN.test(entry.ref)) {
-      throw new EditionSourcePinsError(`${where}: ref must be an exact lowercase 40-hex commit, not a branch, tag or abbreviation`);
-    }
-    if (typeof entry.until !== 'string' || entry.until.trim().length === 0) {
-      throw new EditionSourcePinsError(`${where}: until must be non-empty text stating when the hold ends`);
-    }
-    if (seen.has(entry.repo)) {
-      throw new EditionSourcePinsError(`${where}: repo ${entry.repo} is pinned twice`);
-    }
-    seen.add(entry.repo);
-    return Object.freeze({ repo: entry.repo, ref: entry.ref, until: entry.until });
-  });
-}
-
-/** The raw definition of edition `id` in the configured editions root. */
-function readEditionDefinition(id) {
-  const path = join(editionsRoot(), id, 'xema-distribution.json');
-  if (!existsSync(path)) {
-    throw new Error(`distribution "${id}" not found: ${path} does not exist`);
-  }
-  return readStrictJsonFile(path);
-}
-
-/** The `sourcePins` of a kernel-parsed Distribution manifest; absent is none. */
-export const manifestSourcePins = (manifest) => manifest.sourcePins ?? [];
-
-/** The `sourcePins` of edition `id`, parsed by the kernel's `parseDistribution` (the one validator). */
-export function readKernelEditionSourcePins(id, parseDistribution) {
-  return manifestSourcePins(parseDistribution(readEditionDefinition(id)));
-}
-
-/** The `sourcePins` of edition `id` where no kernel is loaded yet (the source checkout plan). */
-export function readEditionSourcePins(id) {
-  const raw = readEditionDefinition(id);
-  return raw !== null && typeof raw === 'object' && !Array.isArray(raw) ? parseEditionSourcePins(raw[SOURCE_PINS_KEY], id) : [];
-}
-
-/** A repository URL without a trailing `.git`, so the two forms a pin may carry compare equal. */
-const canonicalRepositoryUrl = (url) => String(url).replace(/\.git$/u, '');
-
-/**
- * The repository pins edition `id` resolves at. With nothing held, the
- * committed array itself. A held repository must be in the graph (committed
- * pins) and must not be the kernel contract repository, read from the index's
- * own `contractAuthority.repositoryUrl` (data, so the evidence verifier applies
- * the same rule): the kernel contract authority stays data-root-wide.
- */
-export function effectiveRepositoryPins(committedRepositoryPins, sourcePins, { id, contractAuthority } = {}) {
-  if (sourcePins === undefined || sourcePins.length === 0) {return committedRepositoryPins;}
-  if (typeof contractAuthority?.repositoryUrl !== 'string') {
-    throw new EditionSourcePinsError(`${label(id)}held pins are computed against the index's contractAuthority, and none was given`);
-  }
-  const kernelUrl = canonicalRepositoryUrl(contractAuthority.repositoryUrl);
-  const held = new Map(sourcePins.map((pin) => [pin.repo, pin.ref]));
-  for (const repo of held.keys()) {
-    const committed = committedRepositoryPins.find((pin) => pin.repo === repo);
-    if (committed === undefined) {
-      throw new EditionSourcePinsError(
-        `${label(id)}${SOURCE_PINS_KEY} holds ${repo}, which has no repository pin in runtime-image-source-index.json (not an image source repository)`,
-      );
-    }
-    const ref = held.get(repo);
-    if (committed.sourceCommit === ref && committed.vendoredSourceCommit === ref) {
-      throw new EditionSourcePinsError(
-        `${label(id)}${SOURCE_PINS_KEY} entry for ${repo} is not a hold: ${ref} is the shared repository pin; remove it (xema edition unpin)`,
-      );
-    }
-    if (canonicalRepositoryUrl(committed.repositoryUrl) === kernelUrl) {
-      throw new EditionSourcePinsError(
-        `${label(id)}${SOURCE_PINS_KEY} may not hold ${repo}: it is the kernel contract repository, whose authority is the data root's alone`,
-      );
-    }
-  }
-  return committedRepositoryPins.map((pin) =>
-    held.has(pin.repo) ? { ...pin, sourceCommit: held.get(pin.repo), vendoredSourceCommit: held.get(pin.repo) } : pin,
-  );
-}
-
-function git(directory, args) {
-  return execFileSync('git', ['-C', directory, ...args], {
-    encoding: 'utf8',
-    stdio: ['ignore', 'pipe', 'pipe'],
-  }).trim();
-}
-
-function refusalsOf({ pin, directory, ledger }) {
-  const { repo, ref } = pin;
-  let resolved;
-  try {
-    resolved = git(directory, ['rev-parse', '--verify', `${ref}^{commit}`]);
-  } catch {
-    return [`${repo}@${ref}: no such commit in ${directory}; fetch it before holding it`];
-  }
-  if (resolved !== ref) {return [`${repo}@${ref}: resolves to ${resolved}; name the commit itself`];}
-  try {
-    git(directory, ['rev-parse', '--verify', `${PUBLISHED_SOURCE_REF}^{commit}`]);
-  } catch {
-    return [`${repo}@${ref}: ${repo} has no ${PUBLISHED_SOURCE_REF}, so containment cannot be shown; a held commit must be published`];
-  }
-  try {
-    git(directory, ['merge-base', '--is-ancestor', ref, PUBLISHED_SOURCE_REF]);
-  } catch {
-    return [`${repo}@${ref}: not contained in ${PUBLISHED_SOURCE_REF}; a held commit must be published, or a consumer cannot fetch it`];
-  }
-  const built = builtCommits(directory, PUBLISHED_SOURCE_REF, repo, ledger);
-  // A held repository always has a runtime-image-source pin, so `null` (neither record knows it) means the build evidence is missing.
-  if (built === null) {return [`${repo}@${ref}: no build record for ${repo}; a held commit must be one an image was built from`];}
-  if (built.has(ref)) {return [];}
-  return [`${repo}@${ref}: not a built commit (in neither the build ledger nor the evidence tree); a held commit must be one an image was built from`];
-}
-
-/**
- * Authorize every held commit of edition `id` against its source checkout
- * under `repoRoot`: present, contained in the published ref (a missing ref
- * refuses, never skips) and built. Throws once, listing every refusal.
- */
-export function assertEditionPinsAuthorized({ id, sourcePins, repoRoot = sourcesRoot(), ledger }) {
-  const refusals = sourcePins.flatMap((pin) => refusalsOf({ pin, directory: resolve(repoRoot, pin.repo), ledger }));
-  if (refusals.length > 0) {
-    throw new EditionSourcePinsError(
-      `${label(id)}${refusals.length} held source pin(s) refused:\n  ${refusals.join('\n  ')}`,
-    );
-  }
-}
-
-/**
- * The report `xema edition check` prints: one line per active hold of the given
- * editions, then a count line. Informational, never a failure.
- */
-export function describeEditionHolds(ids, read = readEditionSourcePins) {
-  const lines = ids.flatMap((id) =>
-    read(id).map((pin) => `[dist:check] hold: ${id} ${pin.repo} @${pin.ref.slice(0, 12)} until: ${pin.until}`),
-  );
-  return [...lines, lines.length === 0 ? '[dist:check] no holds' : `[dist:check] ${lines.length} hold(s) active`];
-}

package/edition/edition-unpin.mjs

@@ -1,16 +0,0 @@
-#!/usr/bin/env node
-// `xema edition unpin <edition> [<repo>]`: release one hold (or all) of a vendor
-// edition, then re-resolve the edition. The logic is edition-pin-verbs.mjs.
-//
-// usage: xema edition unpin <edition> [<repo>] --data-root <dir> --editions-root <dir> --sources-root <dir> --kernel <dir>
-
-import { runUnpin } from './edition-pin-verbs.mjs';
-import { WorkspaceRoot, configureEditionWorkspaceFromProcess, isEntryModule } from './edition-workspace.mjs';
-
-if (isEntryModule(import.meta.url)) {
-  configureEditionWorkspaceFromProcess([WorkspaceRoot.Data, WorkspaceRoot.Editions, WorkspaceRoot.Sources, WorkspaceRoot.Kernel]);
-  runUnpin(process.argv.slice(2)).catch((error) => {
-    console.error(`[edition:unpin] ${error.message}`);
-    process.exit(1);
-  });
-}

package/edition/edition-workspace.mjs

@@ -1,204 +0,0 @@
-// The edition library's roots: every directory the tooling reads from is stated
-// by the entry, once, through `configureEditionWorkspace`. Nothing is derived
-// from where this file sits, and no root has a default: a getter on a root the
-// entry did not state throws, naming the flag that states it.
-
-import { existsSync, realpathSync, statSync } from 'node:fs';
-import { join, resolve } from 'node:path';
-import { pathToFileURL } from 'node:url';
-
-export const WorkspaceRoot = Object.freeze({
-  Data: 'dataRoot',
-  Editions: 'editionsRoot',
-  Sources: 'sourcesRoot',
-  Kernel: 'kernelPackageDir',
-  Deploy: 'deployRoot',
-  Cache: 'cacheDir',
-});
-
-export const WORKSPACE_FLAGS = Object.freeze({
-  [WorkspaceRoot.Data]: '--data-root',
-  [WorkspaceRoot.Editions]: '--editions-root',
-  [WorkspaceRoot.Sources]: '--sources-root',
-  [WorkspaceRoot.Kernel]: '--kernel',
-  [WorkspaceRoot.Deploy]: '--deploy-root',
-  [WorkspaceRoot.Cache]: '--cache-dir',
-});
-
-const ROOT_MEANING = Object.freeze({
-  [WorkspaceRoot.Data]:
-    'the directory holding the catalogue indices and the trust policy',
-  [WorkspaceRoot.Editions]:
-    'the directory holding <edition-id>/ definitions and locks',
-  [WorkspaceRoot.Sources]:
-    'the directory holding source checkouts at repos/<r> and submodules/<r>',
-  [WorkspaceRoot.Kernel]: 'the BUILT kernel-contracts package directory',
-  [WorkspaceRoot.Deploy]: 'the deploy (chart tree) checkout',
-  [WorkspaceRoot.Cache]: 'a writable directory for fetched artifacts',
-});
-
-const KERNEL_PACKAGE_SUBPATH = ['packages', 'kernel', 'kernel-contracts'];
-/** The kernel package's path inside the kernel-contracts repository, `/`-separated (a git tree path). */
-export const KERNEL_PACKAGE_REPO_PATH = KERNEL_PACKAGE_SUBPATH.join('/');
-
-let configured = Object.freeze({});
-
-function assertDirectory(name, value) {
-  if (typeof value !== 'string' || value.length === 0) {
-    throw new Error(`${name} must be a non-empty directory path`);
-  }
-  const path = resolve(value);
-  if (!existsSync(path) || !statSync(path).isDirectory()) {
-    throw new Error(`${name} ${path} is not an existing directory`);
-  }
-  return path;
-}
-
-/**
- * State the roots. Only the roots a caller passes are configured; the rest stay
- * unset and throw when read. Replaces any previous configuration.
- */
-export function configureEditionWorkspace(roots) {
-  const next = {};
-  for (const name of Object.values(WorkspaceRoot)) {
-    if (roots[name] !== undefined) {next[name] = assertDirectory(name, roots[name]);}
-  }
-  for (const name of Object.keys(roots)) {
-    if (!Object.values(WorkspaceRoot).includes(name)) {
-      throw new Error(`unknown workspace root "${name}"`);
-    }
-  }
-  configured = Object.freeze(next);
-  return configured;
-}
-
-/**
- * State the Kernel root AFTER configuration, for a customer verb that takes its kernel from the catalogue
- * (kernel-package.mjs) rather than from a flag. Every other configured root is kept; there is still no default.
- */
-export function stateKernelPackageDir(dir) {
-  configured = Object.freeze({ ...configured, [WorkspaceRoot.Kernel]: assertDirectory(WorkspaceRoot.Kernel, dir) });
-}
-
-function root(name) {
-  const value = configured[name];
-  if (value === undefined) {
-    throw new Error(
-      `the edition workspace has no ${name} (${ROOT_MEANING[name]}); state it with ${WORKSPACE_FLAGS[name]} <dir>`,
-    );
-  }
-  return value;
-}
-
-export const dataRoot = () => root(WorkspaceRoot.Data);
-export const editionsRoot = () => root(WorkspaceRoot.Editions);
-export const sourcesRoot = () => root(WorkspaceRoot.Sources);
-export const kernelPackageDir = () => root(WorkspaceRoot.Kernel);
-export const deployRoot = () => root(WorkspaceRoot.Deploy);
-export const cacheDir = () => root(WorkspaceRoot.Cache);
-
-/** A source checkout at its aggregator-relative path, e.g. `repos/xema-base`. */
-export const sourcePath = (repo) => join(sourcesRoot(), repo);
-
-/** The kernel-contracts checkout the built package directory sits in. */
-export function kernelRepoDir() {
-  return resolve(kernelPackageDir(), ...KERNEL_PACKAGE_SUBPATH.map(() => '..'));
-}
-
-/** A built subpath of the kernel package, e.g. `dist/distribution/index.js`. */
-export const kernelDistPath = (...segments) =>
-  join(kernelPackageDir(), 'dist', ...segments);
-
-export const biomeIndexPath = () => join(dataRoot(), 'biome-index.json');
-export const storePublisherIdentitiesPath = () => join(dataRoot(), 'store-publisher-identities.json');
-export const storeSourceRepositoriesPath = () =>
-  join(dataRoot(), 'vendor-ops', 'store-source-repositories.json');
-export const platformServiceIndexPath = () =>
-  join(dataRoot(), 'platform-service-index.json');
-export const runtimeImageSourceIndexPath = () =>
-  join(dataRoot(), 'runtime-image-source-index.json');
-
-/**
- * Parse the workspace flags out of an argv (both `--flag v` and `--flag=v`),
- * configure the roots, and return the remaining argv. `needs` names the roots
- * the entry requires: a missing one is refused here, before any work. With
- * `refuseOthers` a root flag whose root `needs` does not name is refused too
- * (a customer verb takes only the roots it needs).
- */
-export function configureEditionWorkspaceFromArgv(argv, needs, { refuseOthers = false } = {}) {
-  const byFlag = new Map(
-    Object.entries(WORKSPACE_FLAGS).map(([name, flag]) => [flag, name]),
-  );
-  const roots = {};
-  const rest = [];
-  for (let i = 0; i < argv.length; i += 1) {
-    const arg = argv[i];
-    const eq = arg?.indexOf('=') ?? -1;
-    const flag = eq > 0 ? arg.slice(0, eq) : arg;
-    const name = byFlag.get(flag);
-    if (name === undefined) {
-      rest.push(arg);
-      continue;
-    }
-    if (refuseOthers && !needs.includes(name)) {
-      throw new Error(
-        `${flag} is not a root this command takes (it takes: ${needs.length === 0 ? 'no root' : needs.map((root) => WORKSPACE_FLAGS[root]).join(' ')})`,
-      );
-    }
-    const value = eq > 0 ? arg.slice(eq + 1) : argv[(i += 1)];
-    if (typeof value !== 'string' || value.length === 0 || value.startsWith('--')) {
-      throw new Error(`${flag} requires a directory path`);
-    }
-    roots[name] = value;
-  }
-  for (const name of needs) {
-    if (roots[name] === undefined) {
-      throw new Error(
-        `${WORKSPACE_FLAGS[name]} <dir> is required (${ROOT_MEANING[name]})`,
-      );
-    }
-  }
-  configureEditionWorkspace(roots);
-  return rest;
-}
-
-/** The roots configured so far, as the object `configureEditionWorkspace` takes. */
-export const configuredWorkspace = () => ({ ...configured });
-
-/** The flags that re-state the configured roots, for a child entry process. */
-export function workspaceArgv() {
-  return Object.entries(configured).flatMap(([name, value]) => [
-    WORKSPACE_FLAGS[name],
-    value,
-  ]);
-}
-
-/** True when `moduleUrl` is the script node was started with. */
-export function isEntryModule(moduleUrl) {
-  return (
-    typeof process.argv[1] === 'string' &&
-    pathToFileURL(realpathSync(process.argv[1])).href === moduleUrl
-  );
-}
-
-/**
- * The entry's one call: configure the roots from `process.argv` and remove the
- * root flags from it, so the entry's own parser sees only its own arguments.
- * `options` are those of `configureEditionWorkspaceFromArgv`, plus `failureExitCode` (default 1): the exit code of
- * a refused root, for a verb whose exit 1 already means something else.
- */
-export function configureEditionWorkspaceFromProcess(needs, { failureExitCode = 1, ...options } = {}) {
-  let rest;
-  try {
-    rest = configureEditionWorkspaceFromArgv(process.argv.slice(2), needs, options);
-  } catch (error) {
-    // An entry calls this before it has a `main` to catch anything: a missing
-    // or malformed root is the operator's mistake, answered with the roots the
-    // command takes, not with a stack trace.
-    process.stderr.write(
-      `${error.message}\nusage: this command takes ${needs.map((name) => `${WORKSPACE_FLAGS[name]} <dir>`).join(' ')}\n`,
-    );
-    process.exit(failureExitCode);
-  }
-  process.argv.splice(2, process.argv.length - 2, ...rest);
-}