@xemahq/xema 0.59.0 → 0.60.1

package/edition/customer-definition.mjs

@@ -1,174 +0,0 @@
-// customer-definition — reading a CUSTOMER edition definition, and the image
-// registry mirror it may declare.
-//
-// A definition resolved against a catalogue is a customer edition. Its rules
-// live in the kernel (`parseCustomerEditionDefinition`, `customerTrustCeilingIssues`);
-// this module calls them and owns only the `imageRegistryMirror`, which is CLI
-// configuration the kernel document does not carry.
-
-import { SOURCE_IMAGE_FLAG } from './customer-flags.mjs';
-import { SOURCE_PINS_KEY } from './edition-source-pins.mjs';
-
-export class CustomerDefinitionError extends Error {
-  constructor(message, options) {
-    super(message, options);
-    this.name = 'CustomerDefinitionError';
-  }
-}
-
-/** The mirror's refusals (overlap, ambiguity, partial segment, tag/digest alteration, self-mapping, uncovered row). */
-export class ImageRegistryMirrorError extends Error {
-  constructor(message) {
-    super(message);
-    this.name = 'ImageRegistryMirrorError';
-  }
-}
-
-export const MIRROR_KEY = 'imageRegistryMirror';
-
-/**
- * Parse a raw customer definition. The RULES are the kernel's, in one place:
- * `parseCustomerEditionDefinition` (a closed vocabulary - visibility, extends,
- * exclude and sweeping selectors are not in it; `trustCeiling` required iff
- * `sources`; `sources[].ref` a branch or a tag, never a commit; git-only
- * sources; the one `{biome}` selector grammar). The CLI adds nothing to them
- * except what the kernel document does not carry: it removes the mirror (CLI
- * configuration, parsed by `parseImageRegistryMirror`) before the kernel sees
- * the document, and refuses a source that states the registry its images come
- * from, because that is handed in with `--source-image` and has no default.
- * Returns the kernel's parsed definition and the raw mirror.
- */
-export function parseCustomerDefinition(schemas, raw) {
-  if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) {
-    throw new CustomerDefinitionError('a customer definition must be a JSON object');
-  }
-  // `sourcePins` holds a first-party repository of the VENDOR graph at a commit; a customer builds none.
-  if (Object.hasOwn(raw, SOURCE_PINS_KEY)) {
-    throw new CustomerDefinitionError(
-      `customer definition "${raw.id}": "${SOURCE_PINS_KEY}" is a vendor-edition key and is refused here; ` +
-        'a customer pins an external source with sources[].ref',
-    );
-  }
-  const { [MIRROR_KEY]: mirror, ...document } = raw;
-  for (const source of Array.isArray(document.sources) ? document.sources : []) {
-    const stated = ['imageRegistry', 'imageNamePrefix'].find((key) => source !== null && typeof source === 'object' && key in source);
-    if (stated !== undefined) {
-      throw new CustomerDefinitionError(
-        `customer definition "${raw.id}": source "${source.name}" states ${stated}; the registry is configuration, ` +
-          `handed in with ${SOURCE_IMAGE_FLAG} ${source.name}=<registry>/<prefix>`,
-      );
-    }
-  }
-  let definition;
-  try {
-    definition = schemas.parseCustomerEditionDefinition(document);
-  } catch (error) {
-    throw new CustomerDefinitionError(error.message, { cause: error });
-  }
-  return { definition, mirror };
-}
-
-/**
- * The trustCeiling must assign every customer-source biome (a biome the resolved lock draws
- * from the definition's own `sources[]`) and no other, and none in a domain the catalogue's ceiling reserves: the kernel's `customerTrustCeilingIssues`.
- */
-export function assertTrustCeilingAssignsCustomerBiomes(schemas, definition, customerBiomeIds, catalogueTrustCeiling) {
-  const issues = schemas.customerTrustCeilingIssues(definition, customerBiomeIds, catalogueTrustCeiling);
-  if (issues.length > 0) {
-    throw new CustomerDefinitionError(`customer definition "${definition.id}": ${issues.join('; ')}`);
-  }
-}
-
-const HOST_PATH = /^[a-z0-9.-]+(:[0-9]+)?(\/[a-z0-9._-]+)*$/;
-const segmentsOf = (prefix) => prefix.split('/');
-const isSegmentPrefix = (shorter, longer) => {
-  const a = segmentsOf(shorter);
-  const b = segmentsOf(longer);
-  return a.length <= b.length && a.every((segment, index) => segment === b[index]);
-};
-
-/** The strict parse of `imageRegistryMirror`: `{complete: boolean, map: [{source, target}]}`, no defaults. */
-export function parseImageRegistryMirror(value) {
-  if (value === undefined) {return undefined;}
-  const exact = (candidate, keys, where) => {
-    if (candidate === null || typeof candidate !== 'object' || Array.isArray(candidate) || Object.keys(candidate).sort().join() !== [...keys].sort().join()) {
-      throw new ImageRegistryMirrorError(`${where} must be exactly {${keys.join(', ')}}`);
-    }
-  };
-  if (value === null || typeof value !== 'object' || !('complete' in value)) {
-    throw new ImageRegistryMirrorError(`${MIRROR_KEY}.complete is required and must be a boolean (no default)`);
-  }
-  exact(value, ['complete', 'map'], MIRROR_KEY);
-  if (typeof value.complete !== 'boolean') {
-    throw new ImageRegistryMirrorError(`${MIRROR_KEY}.complete is required and must be a boolean (no default)`);
-  }
-  if (!Array.isArray(value.map) || value.map.length === 0) {
-    throw new ImageRegistryMirrorError(`${MIRROR_KEY}.map must be a non-empty array of {source, target}`);
-  }
-  for (const entry of value.map) {
-    exact(entry, ['source', 'target'], `${MIRROR_KEY}.map entry`);
-    for (const side of ['source', 'target']) {
-      if (typeof entry[side] !== 'string' || !HOST_PATH.test(entry[side]) || !entry[side].includes('/')) {
-        throw new ImageRegistryMirrorError(
-          `${MIRROR_KEY}.map ${side} ${JSON.stringify(entry[side])} is not <host>/<path-prefix> ` +
-            '(lowercase, whole path segments, no tag, no digest, no wildcard)',
-        );
-      }
-    }
-    if (entry.source === entry.target) {
-      throw new ImageRegistryMirrorError(`${MIRROR_KEY}.map maps ${entry.source} to itself`);
-    }
-  }
-  const sources = value.map.map((entry) => entry.source);
-  sources.forEach((source, index) => {
-    sources.slice(index + 1).forEach((other) => {
-      if (isSegmentPrefix(source, other) || isSegmentPrefix(other, source)) {
-        throw new ImageRegistryMirrorError(
-          source === other
-            ? `${MIRROR_KEY}.map lists source ${source} twice`
-            : `${MIRROR_KEY}.map sources ${source} and ${other} overlap (one is a path-segment prefix of the other); a ref would match both`,
-        );
-      }
-    });
-  });
-  return { complete: value.complete, map: value.map.map(({ source, target }) => ({ source, target })) };
-}
-
-const REF_NAME = /^[a-z0-9.-]+(:[0-9]+)?(\/[a-z0-9._-]+)+$/;
-
-/**
- * Re-home one image ref (name only, as the images lock records it) under the
- * mirror. Whole path segments only; the remaining path is untouched; a ref that
- * carries a tag or digest is refused. Returns the ref unchanged when no entry
- * covers it (the caller decides whether that is an error: `complete`).
- */
-export function mirrorImageRef(imageRef, mirror) {
-  if (typeof imageRef !== 'string' || !REF_NAME.test(imageRef)) {
-    throw new ImageRegistryMirrorError(`image ref ${JSON.stringify(imageRef)} is not a bare <host>/<path> name (a tag or digest cannot be rewritten)`);
-  }
-  const partial = mirror.map.find((entry) => imageRef.startsWith(entry.source) && !isSegmentPrefix(entry.source, imageRef));
-  if (partial !== undefined) {
-    throw new ImageRegistryMirrorError(
-      `${MIRROR_KEY} source ${partial.source} matches ${imageRef} only in part of a path segment; prefixes match whole segments`,
-    );
-  }
-  const matches = mirror.map.filter((entry) => isSegmentPrefix(entry.source, imageRef) && entry.source !== imageRef);
-  if (matches.length === 0) {return { imageRef, covered: false };}
-  const [{ source, target }] = matches;
-  const rest = segmentsOf(imageRef).slice(segmentsOf(source).length).join('/');
-  return { imageRef: `${target}/${rest}`, covered: true };
-}
-
-/** Re-home the vendor image rows; `complete: true` refuses a row no entry covers. */
-export function mirrorVendorSubjects(subjects, mirror) {
-  if (mirror === undefined) {return subjects;}
-  return subjects.map((subject) => {
-    const { imageRef, covered } = mirrorImageRef(subject.imageRef, mirror);
-    if (!covered && mirror.complete) {
-      throw new ImageRegistryMirrorError(
-        `${MIRROR_KEY} is complete:true but no map entry covers ${subject.kind}:${subject.id} (${subject.imageRef})`,
-      );
-    }
-    return { ...subject, imageRef };
-  });
-}