@xemahq/edition-tooling 0.0.0-stage → 0.1.0

package/edition/distribution-paths.mjs

@@ -0,0 +1,191 @@
+import { existsSync, readFileSync, readdirSync, realpathSync } from 'node:fs';
+import { isAbsolute, join, relative, resolve, sep } from 'node:path';
+
+const DISTRIBUTION_ID_PATTERN =
+  /^[a-zA-Z0-9](?:[a-zA-Z0-9._-]{0,126}[a-zA-Z0-9])?$/;
+
+export function assertCanonicalDistributionId(distributionId) {
+  if (
+    typeof distributionId !== 'string' ||
+    !DISTRIBUTION_ID_PATTERN.test(distributionId)
+  ) {
+    throw new Error(
+      'distribution id must be a canonical 1-128 character identifier',
+    );
+  }
+  return distributionId;
+}
+
+function assertContained(root, candidate, label) {
+  const rel = relative(root, candidate);
+  if (rel === '..' || rel.startsWith(`..${sep}`) || isAbsolute(rel)) {
+    throw new Error(`${label} escapes the distributions root`);
+  }
+}
+
+export function resolveDistributionDirectory(
+  distributionsRoot,
+  distributionId,
+) {
+  assertCanonicalDistributionId(distributionId);
+  const root = realpathSync(distributionsRoot);
+  const expectedDirectory = join(root, distributionId);
+  if (!existsSync(expectedDirectory)) {
+    throw new Error(`distribution "${distributionId}" does not exist`);
+  }
+  const directory = realpathSync(expectedDirectory);
+  assertContained(root, directory, `distribution "${distributionId}"`);
+  if (directory !== expectedDirectory) {
+    throw new Error(
+      `distribution "${distributionId}" directory must not be a symlink`,
+    );
+  }
+  return { root, directory };
+}
+
+export function resolveDistributionFile(
+  distributionsRoot,
+  distributionId,
+  fileName,
+) {
+  const { directory } = resolveDistributionDirectory(
+    distributionsRoot,
+    distributionId,
+  );
+  const expectedPath = join(directory, fileName);
+  if (!existsSync(expectedPath)) {
+    throw new Error(
+      `distribution "${distributionId}" has no ${fileName} (${expectedPath})`,
+    );
+  }
+  const path = realpathSync(expectedPath);
+  assertContained(directory, path, `${fileName} for "${distributionId}"`);
+  if (path !== expectedPath) {
+    throw new Error(
+      `${fileName} for distribution "${distributionId}" must not be a symlink`,
+    );
+  }
+  return path;
+}
+
+export function readBoundDistributionFile({
+  distributionsRoot,
+  distributionId,
+  fileName,
+  parse,
+}) {
+  const path = resolveDistributionFile(
+    distributionsRoot,
+    distributionId,
+    fileName,
+  );
+  const value = parse(JSON.parse(readFileSync(path, 'utf8')));
+  if (value.distributionId !== distributionId) {
+    throw new Error(
+      `${fileName} distributionId "${value.distributionId}" does not match requested distribution "${distributionId}"`,
+    );
+  }
+  return { path, value };
+}
+
+/**
+ * Every edition under `distributionsRoot`, sorted — DISCOVERED, never listed.
+ *
+ * An edition is a directory carrying `xema-distribution.json`; that file is
+ * what makes the directory an edition, so nothing else can be mistaken for one
+ * and a new edition needs no registration anywhere.
+ *
+ * Throws on an empty scan. A gate that iterates editions and finds none must
+ * fail rather than report success over nothing — the repeated defect in this
+ * tree is a check that reports green while executing nothing, and a literal
+ * id list is the other half of it: a narrowed list reads as coverage.
+ *
+ * `refresh-distribution-plane.mjs` carried this three-line scan privately;
+ * it lives here so the write path and the read paths cannot disagree about
+ * what an edition is.
+ */
+export function discoverDistributionIds(distributionsRoot) {
+  const root = realpathSync(distributionsRoot);
+  const ids = readdirSync(root, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory())
+    .map((entry) => entry.name)
+    .filter((name) => existsSync(join(root, name, 'xema-distribution.json')))
+    .sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
+  if (ids.length === 0) {
+    throw new Error(
+      `found no edition under ${root} — an empty scan is not a result`,
+    );
+  }
+  return ids;
+}
+
+export function distributionOutputPath(
+  distributionsRoot,
+  distributionId,
+  fileName,
+) {
+  const { directory } = resolveDistributionDirectory(
+    distributionsRoot,
+    distributionId,
+  );
+  const path = resolve(directory, fileName);
+  assertContained(directory, path, `${fileName} output`);
+  if (existsSync(path) && realpathSync(path) !== path) {
+    throw new Error(
+      `${fileName} output for distribution "${distributionId}" must not be a symlink`,
+    );
+  }
+  return path;
+}
+
+/**
+ * The directory name holding editions that are NOT yet promoted.
+ *
+ * `discoverDistributionIds` is deliberately a single-level scan, so an edition
+ * one level down is invisible to it and to `dist:check` — which is the whole
+ * mechanism of the holding pen, not an oversight.
+ */
+export const PENDING_EDITIONS_DIRNAME = 'editions-pending-merge';
+
+/**
+ * Every edition under `distributionsRoot`, in BOTH tiers, as
+ * `{ id, directory, pending }` — sorted, promoted tier first.
+ *
+ * WHY BOTH TIERS. A generic test suite must be able to name its subjects
+ * without naming a customer, and a customer's edition is exactly the thing that
+ * is either pending here or has moved to a root of its own. Discovering both
+ * means one expression covers the edition wherever it currently sits, so
+ * promoting it — or removing it — changes no test.
+ *
+ * THE EMPTY CASES ARE ASYMMETRIC ON PURPOSE.
+ *
+ *   * The PROMOTED tier delegates to {@link discoverDistributionIds}, which
+ *     THROWS on an empty scan. An empty promoted tier means the root is wrong,
+ *     and a checker that iterated zero editions and reported success is this
+ *     tree's most-repeated defect.
+ *   * The PENDING tier may legitimately be empty — that is what a fully
+ *     promoted fleet looks like — so it is not an error. A CALLER that narrows
+ *     to a subset of these and finds nothing must say so out loud rather than
+ *     pass in silence; that reporting duty is the caller's, because only the
+ *     caller knows what it narrowed to.
+ */
+export function discoverEditionDirectories(distributionsRoot) {
+  const root = realpathSync(distributionsRoot);
+  const promoted = discoverDistributionIds(root).map((id) => ({
+    id,
+    directory: join(root, id),
+    pending: false,
+  }));
+  const pendingRoot = join(root, PENDING_EDITIONS_DIRNAME);
+  const pending = !existsSync(pendingRoot)
+    ? []
+    : readdirSync(pendingRoot, { withFileTypes: true })
+        .filter((entry) => entry.isDirectory())
+        .map((entry) => entry.name)
+        .filter((name) =>
+          existsSync(join(pendingRoot, name, 'xema-distribution.json')),
+        )
+        .sort((a, b) => (a < b ? -1 : a > b ? 1 : 0))
+        .map((id) => ({ id, directory: join(pendingRoot, id), pending: true }));
+  return [...promoted, ...pending];
+}