@variance-authority/core 0.9.0 → 0.10.0

package/dist/share/publish.d.ts

@@ -0,0 +1,79 @@
+/**
+ * What may replace what on a line, and what a reader is told.
+ *
+ * Decided here, once, over the {@link LineCell} a backend provides, so a
+ * directory, a bucket and a git ref hold a line by the same rules.
+ */
+import { type HeldEntry, type LineCell, type LineManifest, type ShareEntry, type ShareLine, type ShareMiss } from './line.js';
+/**
+ * Whether `descendant` strictly descends from `ancestor`, or `undefined` when
+ * the history needed to say is not at hand. Git owns this answer; the caller
+ * asks it.
+ */
+export type Descends = (descendant: string, ancestor: string) => Promise<boolean | undefined>;
+/** What a publish did, entry by entry. */
+export interface Published {
+    /** Entries this publish wrote. */
+    readonly written: readonly string[];
+    /** Entries the line kept instead, and why. */
+    readonly kept: readonly {
+        readonly name: string;
+        readonly commit: string;
+        readonly because: 'newer-commit' | 'newer-format';
+    }[];
+    /**
+     * Entries written although nobody could say whether the held one was newer.
+     * Replacing is the answer then, because a line that refuses when it cannot
+     * tell is a line one force-push jams for good.
+     */
+    readonly unanswered: readonly string[];
+    /** How many times the manifest was read before a write held. */
+    readonly attempts: number;
+}
+export interface PublishOptions {
+    readonly descends: Descends;
+    /** The bytes of an image the line does not hold yet, by digest. */
+    readonly image: (digest: string) => Promise<Uint8Array>;
+    /** Reads of the manifest before giving up on a line other writers keep moving. Defaults to 8. */
+    readonly attempts?: number;
+}
+/**
+ * Offer entries to a line.
+ *
+ * Each entry replaces the held entry in its slot — same family, same qualifier,
+ * any version — except on a mainline, where the held one is kept when its
+ * commit strictly descends from the offered one: a slow run of an older commit
+ * finishing last. A held entry in a newer format is kept on any line, so an old
+ * CLI cannot take a line back a version. Every other held entry is left as it
+ * is, which is how suites published by different jobs land on one line.
+ *
+ * A write that loses to another writer reads the line again and decides again.
+ */
+export declare function publishLine(cell: LineCell, line: ShareLine, entries: readonly ShareEntry[], options: PublishOptions): Promise<Published | ShareMiss>;
+/** A line as a reader holds it: the manifest, and its blobs on demand. */
+export interface HeldLine {
+    readonly line: ShareLine;
+    readonly manifest: LineManifest;
+    /** The bytes of one entry, checked against the digest the manifest names. */
+    entry(entry: HeldEntry): Promise<Uint8Array | ShareMiss>;
+    image(digest: string): Promise<Uint8Array | ShareMiss>;
+}
+/** Read what a line holds, or why it cannot be read. */
+export declare function readLine(cell: LineCell, line: ShareLine): Promise<HeldLine | ShareMiss>;
+/**
+ * The held entry a reader asked for by name, or why there is none.
+ *
+ * A reader of `suite-v1/web` that finds `suite-v2/web` is told `newer`, not
+ * `absent`: the line has what it wants, in a format it has to upgrade to read.
+ */
+export declare function findEntry(manifest: LineManifest, name: string): HeldEntry | ShareMiss;
+/**
+ * A line cell in this process, for tests and for a run that shares with itself.
+ *
+ * Holds real versions, so a test can stage a writer that moves the line between
+ * another writer's read and its write.
+ */
+export declare function memoryLineCell(): LineCell & {
+    readonly held: Map<string, Uint8Array>;
+};
+//# sourceMappingURL=publish.d.ts.map

package/dist/share/publish.js

@@ -0,0 +1,231 @@
+/**
+ * What may replace what on a line, and what a reader is told.
+ *
+ * Decided here, once, over the {@link LineCell} a backend provides, so a
+ * directory, a bucket and a git ref hold a line by the same rules.
+ */
+import { decodeManifest, encodeManifest, entryDigest, entryProblem, parseEntryName, sameSlot, } from './line.js';
+/**
+ * Offer entries to a line.
+ *
+ * Each entry replaces the held entry in its slot — same family, same qualifier,
+ * any version — except on a mainline, where the held one is kept when its
+ * commit strictly descends from the offered one: a slow run of an older commit
+ * finishing last. A held entry in a newer format is kept on any line, so an old
+ * CLI cannot take a line back a version. Every other held entry is left as it
+ * is, which is how suites published by different jobs land on one line.
+ *
+ * A write that loses to another writer reads the line again and decides again.
+ */
+export async function publishLine(cell, line, entries, options) {
+    for (const entry of entries) {
+        const problem = entryProblem(entry);
+        if (problem !== undefined)
+            throw new Error(`cannot publish ${problem}`);
+    }
+    const limit = options.attempts ?? 8;
+    for (let attempt = 1; attempt <= limit; attempt += 1) {
+        const loaded = await cell.load(line);
+        let held;
+        let expected;
+        if ('manifest' in loaded) {
+            const decoded = decodeManifest(loaded.manifest);
+            // A line a newer writer owns is not this writer's to replace; one that is
+            // unreadable is, since nothing can read it anyway.
+            if ('kind' in decoded) {
+                if (decoded.kind === 'newer')
+                    return decoded;
+                held = { format: 1, entries: [] };
+            }
+            else {
+                held = decoded;
+            }
+            expected = loaded.version;
+        }
+        else if (loaded.kind === 'absent') {
+            held = { format: 1, entries: [] };
+        }
+        else {
+            return loaded;
+        }
+        const plan = await decide(line, held, entries, options.descends);
+        if (plan.write.length === 0) {
+            return { written: [], kept: plan.kept, unanswered: [], attempts: attempt };
+        }
+        const next = nextManifest(held, plan.write);
+        const blobs = await blobsFor(held, next, plan.write, options.image);
+        const outcome = await cell.store(line, {
+            manifest: encodeManifest(next),
+            blobs,
+            ...(expected !== undefined ? { expected } : {}),
+        });
+        if (outcome === 'written') {
+            return {
+                written: plan.write.map((entry) => entry.name),
+                kept: plan.kept,
+                unanswered: plan.unanswered,
+                attempts: attempt,
+            };
+        }
+        if (outcome !== 'conflict')
+            return outcome;
+    }
+    return {
+        kind: 'unreachable',
+        detail: `the line moved under ${String(limit)} writes in a row; nothing was published`,
+    };
+}
+async function decide(line, held, entries, descends) {
+    const write = [];
+    const kept = [];
+    const unanswered = [];
+    for (const entry of entries) {
+        const offered = parseEntryName(entry.name);
+        let occupant;
+        let version = 0;
+        for (const candidate of held.entries) {
+            const slot = parseEntryName(candidate.name);
+            if (sameSlot(slot, offered) && slot.version > version) {
+                occupant = candidate;
+                version = slot.version;
+            }
+        }
+        if (occupant === undefined) {
+            write.push(entry);
+            continue;
+        }
+        if (version > offered.version) {
+            kept.push({ name: occupant.name, commit: occupant.commit, because: 'newer-format' });
+            continue;
+        }
+        // TODO: shards of one run publish at one commit, so each replaces the
+        // last one's `suite-index-v1` and `report-v1`, and the line keeps the index
+        // and report of whichever shard published last, covering its subjects only.
+        // Nothing here merges two entries of one slot.
+        if (line.kind === 'branch' || occupant.commit === entry.commit) {
+            write.push(entry);
+            continue;
+        }
+        const newer = await descends(occupant.commit, entry.commit);
+        if (newer === true) {
+            kept.push({ name: occupant.name, commit: occupant.commit, because: 'newer-commit' });
+            continue;
+        }
+        if (newer === undefined)
+            unanswered.push(entry.name);
+        write.push(entry);
+    }
+    return { write, kept, unanswered };
+}
+function nextManifest(held, write) {
+    const replaced = write.map((entry) => parseEntryName(entry.name));
+    const survivors = held.entries.filter((entry) => !replaced.some((slot) => sameSlot(slot, parseEntryName(entry.name))));
+    const added = write.map((entry) => ({
+        name: entry.name,
+        commit: entry.commit,
+        ...(entry.head !== undefined ? { head: entry.head } : {}),
+        ...(entry.images !== undefined ? { images: [...new Set(entry.images)] } : {}),
+        digest: entryDigest(entry.bytes),
+        size: entry.bytes.length,
+    }));
+    return { format: 1, entries: [...survivors, ...added] };
+}
+/** Only what the held line lacks: entry bytes are new by construction, images often are not. */
+async function blobsFor(held, next, write, image) {
+    const blobs = new Map();
+    const heldDigests = new Set(held.entries.map((entry) => entry.digest));
+    for (const entry of write) {
+        const digest = entryDigest(entry.bytes);
+        if (!heldDigests.has(digest))
+            blobs.set(`entries/${digest}`, entry.bytes);
+    }
+    const heldImages = new Set(held.entries.flatMap((entry) => entry.images ?? []));
+    for (const digest of new Set(next.entries.flatMap((entry) => entry.images ?? []))) {
+        if (!heldImages.has(digest))
+            blobs.set(`images/${digest}`, await image(digest));
+    }
+    return blobs;
+}
+/** Read what a line holds, or why it cannot be read. */
+export async function readLine(cell, line) {
+    const loaded = await cell.load(line);
+    if (!('manifest' in loaded))
+        return loaded;
+    const manifest = decodeManifest(loaded.manifest);
+    if ('kind' in manifest)
+        return manifest;
+    return {
+        line,
+        manifest,
+        async entry(entry) {
+            const bytes = await cell.blob(line, `entries/${entry.digest}`);
+            if (!(bytes instanceof Uint8Array))
+                return bytes;
+            if (entryDigest(bytes) !== entry.digest) {
+                return { kind: 'unreadable', detail: `${entry.name}: the bytes do not match the manifest's digest` };
+            }
+            return bytes;
+        },
+        image(digest) {
+            return cell.blob(line, `images/${digest}`);
+        },
+    };
+}
+/**
+ * The held entry a reader asked for by name, or why there is none.
+ *
+ * A reader of `suite-v1/web` that finds `suite-v2/web` is told `newer`, not
+ * `absent`: the line has what it wants, in a format it has to upgrade to read.
+ */
+export function findEntry(manifest, name) {
+    const wanted = parseEntryName(name);
+    if (wanted === undefined)
+        throw new Error(`"${name}" is not <family>-v<version>[/<qualifier>]`);
+    const exact = manifest.entries.find((entry) => entry.name === name);
+    if (exact !== undefined)
+        return exact;
+    const newer = manifest.entries
+        .filter((entry) => {
+        const held = parseEntryName(entry.name);
+        return sameSlot(held, wanted) && held.version > wanted.version;
+    })
+        .map((entry) => entry.name);
+    return newer.length > 0 ? { kind: 'newer', names: newer } : { kind: 'absent' };
+}
+/**
+ * A line cell in this process, for tests and for a run that shares with itself.
+ *
+ * Holds real versions, so a test can stage a writer that moves the line between
+ * another writer's read and its write.
+ */
+export function memoryLineCell() {
+    const held = new Map();
+    const versions = new Map();
+    const key = (line) => `${line.kind}\u0000${line.name}`;
+    return {
+        held,
+        async load(line) {
+            const manifest = held.get(`${key(line)}\u0000manifest`);
+            if (manifest === undefined)
+                return { kind: 'absent' };
+            return { manifest, version: String(versions.get(key(line)) ?? 0) };
+        },
+        async blob(line, path) {
+            const bytes = held.get(path.startsWith('images/') ? path : `${key(line)}\u0000${path}`);
+            return bytes === undefined ? { kind: 'absent' } : bytes.slice();
+        },
+        async store(line, write) {
+            const current = versions.get(key(line));
+            const now = current === undefined ? undefined : String(current);
+            if (now !== write.expected)
+                return 'conflict';
+            for (const [path, bytes] of write.blobs) {
+                held.set(path.startsWith('images/') ? path : `${key(line)}\u0000${path}`, bytes.slice());
+            }
+            held.set(`${key(line)}\u0000manifest`, write.manifest.slice());
+            versions.set(key(line), (current ?? 0) + 1);
+            return 'written';
+        },
+    };
+}
+//# sourceMappingURL=publish.js.map

package/dist/share/publish.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"publish.js","sourceRoot":"","sources":["../../src/share/publish.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * What may replace what on a line, and what a reader is told.\n *\n * Decided here, once, over the {@link LineCell} a backend provides, so a\n * directory, a bucket and a git ref hold a line by the same rules.\n */\n\nimport {\n  decodeManifest,\n  encodeManifest,\n  entryDigest,\n  entryProblem,\n  parseEntryName,\n  sameSlot,\n  type BlobPath,\n  type HeldEntry,\n  type LineCell,\n  type LineManifest,\n  type ShareEntry,\n  type ShareLine,\n  type ShareMiss,\n} from './line.js';\n\n/**\n * Whether `descendant` strictly descends from `ancestor`, or `undefined` when\n * the history needed to say is not at hand. Git owns this answer; the caller\n * asks it.\n */\nexport type Descends = (descendant: string, ancestor: string) => Promise<boolean | undefined>;\n\n/** What a publish did, entry by entry. */\nexport interface Published {\n  /** Entries this publish wrote. */\n  readonly written: readonly string[];\n  /** Entries the line kept instead, and why. */\n  readonly kept: readonly { readonly name: string; readonly commit: string; readonly because: 'newer-commit' | 'newer-format' }[];\n  /**\n   * Entries written although nobody could say whether the held one was newer.\n   * Replacing is the answer then, because a line that refuses when it cannot\n   * tell is a line one force-push jams for good.\n   */\n  readonly unanswered: readonly string[];\n  /** How many times the manifest was read before a write held. */\n  readonly attempts: number;\n}\n\nexport interface PublishOptions {\n  readonly descends: Descends;\n  /** The bytes of an image the line does not hold yet, by digest. */\n  readonly image: (digest: string) => Promise<Uint8Array>;\n  /** Reads of the manifest before giving up on a line other writers keep moving. Defaults to 8. */\n  readonly attempts?: number;\n}\n\n/**\n * Offer entries to a line.\n *\n * Each entry replaces the held entry in its slot — same family, same qualifier,\n * any version — except on a mainline, where the held one is kept when its\n * commit strictly descends from the offered one: a slow run of an older commit\n * finishing last. A held entry in a newer format is kept on any line, so an old\n * CLI cannot take a line back a version. Every other held entry is left as it\n * is, which is how suites published by different jobs land on one line.\n *\n * A write that loses to another writer reads the line again and decides again.\n */\nexport async function publishLine(\n  cell: LineCell,\n  line: ShareLine,\n  entries: readonly ShareEntry[],\n  options: PublishOptions,\n): Promise<Published | ShareMiss> {\n  for (const entry of entries) {\n    const problem = entryProblem(entry);\n    if (problem !== undefined) throw new Error(`cannot publish ${problem}`);\n  }\n\n  const limit = options.attempts ?? 8;\n  for (let attempt = 1; attempt <= limit; attempt += 1) {\n    const loaded = await cell.load(line);\n    let held: LineManifest;\n    let expected: string | undefined;\n    if ('manifest' in loaded) {\n      const decoded = decodeManifest(loaded.manifest);\n      // A line a newer writer owns is not this writer's to replace; one that is\n      // unreadable is, since nothing can read it anyway.\n      if ('kind' in decoded) {\n        if (decoded.kind === 'newer') return decoded;\n        held = { format: 1, entries: [] };\n      } else {\n        held = decoded;\n      }\n      expected = loaded.version;\n    } else if (loaded.kind === 'absent') {\n      held = { format: 1, entries: [] };\n    } else {\n      return loaded;\n    }\n\n    const plan = await decide(line, held, entries, options.descends);\n    if (plan.write.length === 0) {\n      return { written: [], kept: plan.kept, unanswered: [], attempts: attempt };\n    }\n\n    const next = nextManifest(held, plan.write);\n    const blobs = await blobsFor(held, next, plan.write, options.image);\n    const outcome = await cell.store(line, {\n      manifest: encodeManifest(next),\n      blobs,\n      ...(expected !== undefined ? { expected } : {}),\n    });\n    if (outcome === 'written') {\n      return {\n        written: plan.write.map((entry) => entry.name),\n        kept: plan.kept,\n        unanswered: plan.unanswered,\n        attempts: attempt,\n      };\n    }\n    if (outcome !== 'conflict') return outcome;\n  }\n  return {\n    kind: 'unreachable',\n    detail: `the line moved under ${String(limit)} writes in a row; nothing was published`,\n  };\n}\n\nasync function decide(\n  line: ShareLine,\n  held: LineManifest,\n  entries: readonly ShareEntry[],\n  descends: Descends,\n): Promise<{ write: ShareEntry[]; kept: Published['kept'][number][]; unanswered: string[] }> {\n  const write: ShareEntry[] = [];\n  const kept: Published['kept'][number][] = [];\n  const unanswered: string[] = [];\n  for (const entry of entries) {\n    const offered = parseEntryName(entry.name)!;\n    let occupant: HeldEntry | undefined;\n    let version = 0;\n    for (const candidate of held.entries) {\n      const slot = parseEntryName(candidate.name)!;\n      if (sameSlot(slot, offered) && slot.version > version) {\n        occupant = candidate;\n        version = slot.version;\n      }\n    }\n    if (occupant === undefined) {\n      write.push(entry);\n      continue;\n    }\n    if (version > offered.version) {\n      kept.push({ name: occupant.name, commit: occupant.commit, because: 'newer-format' });\n      continue;\n    }\n    // TODO: shards of one run publish at one commit, so each replaces the\n    // last one's `suite-index-v1` and `report-v1`, and the line keeps the index\n    // and report of whichever shard published last, covering its subjects only.\n    // Nothing here merges two entries of one slot.\n    if (line.kind === 'branch' || occupant.commit === entry.commit) {\n      write.push(entry);\n      continue;\n    }\n    const newer = await descends(occupant.commit, entry.commit);\n    if (newer === true) {\n      kept.push({ name: occupant.name, commit: occupant.commit, because: 'newer-commit' });\n      continue;\n    }\n    if (newer === undefined) unanswered.push(entry.name);\n    write.push(entry);\n  }\n  return { write, kept, unanswered };\n}\n\nfunction nextManifest(held: LineManifest, write: readonly ShareEntry[]): LineManifest {\n  const replaced = write.map((entry) => parseEntryName(entry.name)!);\n  const survivors = held.entries.filter(\n    (entry) => !replaced.some((slot) => sameSlot(slot, parseEntryName(entry.name)!)),\n  );\n  const added: HeldEntry[] = write.map((entry) => ({\n    name: entry.name,\n    commit: entry.commit,\n    ...(entry.head !== undefined ? { head: entry.head } : {}),\n    ...(entry.images !== undefined ? { images: [...new Set(entry.images)] } : {}),\n    digest: entryDigest(entry.bytes),\n    size: entry.bytes.length,\n  }));\n  return { format: 1, entries: [...survivors, ...added] };\n}\n\n/** Only what the held line lacks: entry bytes are new by construction, images often are not. */\nasync function blobsFor(\n  held: LineManifest,\n  next: LineManifest,\n  write: readonly ShareEntry[],\n  image: (digest: string) => Promise<Uint8Array>,\n): Promise<Map<BlobPath, Uint8Array>> {\n  const blobs = new Map<BlobPath, Uint8Array>();\n  const heldDigests = new Set(held.entries.map((entry) => entry.digest));\n  for (const entry of write) {\n    const digest = entryDigest(entry.bytes);\n    if (!heldDigests.has(digest)) blobs.set(`entries/${digest}`, entry.bytes);\n  }\n  const heldImages = new Set(held.entries.flatMap((entry) => entry.images ?? []));\n  for (const digest of new Set(next.entries.flatMap((entry) => entry.images ?? []))) {\n    if (!heldImages.has(digest)) blobs.set(`images/${digest}`, await image(digest));\n  }\n  return blobs;\n}\n\n/** A line as a reader holds it: the manifest, and its blobs on demand. */\nexport interface HeldLine {\n  readonly line: ShareLine;\n  readonly manifest: LineManifest;\n  /** The bytes of one entry, checked against the digest the manifest names. */\n  entry(entry: HeldEntry): Promise<Uint8Array | ShareMiss>;\n  image(digest: string): Promise<Uint8Array | ShareMiss>;\n}\n\n/** Read what a line holds, or why it cannot be read. */\nexport async function readLine(cell: LineCell, line: ShareLine): Promise<HeldLine | ShareMiss> {\n  const loaded = await cell.load(line);\n  if (!('manifest' in loaded)) return loaded;\n  const manifest = decodeManifest(loaded.manifest);\n  if ('kind' in manifest) return manifest;\n  return {\n    line,\n    manifest,\n    async entry(entry) {\n      const bytes = await cell.blob(line, `entries/${entry.digest}`);\n      if (!(bytes instanceof Uint8Array)) return bytes;\n      if (entryDigest(bytes) !== entry.digest) {\n        return { kind: 'unreadable', detail: `${entry.name}: the bytes do not match the manifest's digest` };\n      }\n      return bytes;\n    },\n    image(digest) {\n      return cell.blob(line, `images/${digest}`);\n    },\n  };\n}\n\n/**\n * The held entry a reader asked for by name, or why there is none.\n *\n * A reader of `suite-v1/web` that finds `suite-v2/web` is told `newer`, not\n * `absent`: the line has what it wants, in a format it has to upgrade to read.\n */\nexport function findEntry(manifest: LineManifest, name: string): HeldEntry | ShareMiss {\n  const wanted = parseEntryName(name);\n  if (wanted === undefined) throw new Error(`\"${name}\" is not <family>-v<version>[/<qualifier>]`);\n  const exact = manifest.entries.find((entry) => entry.name === name);\n  if (exact !== undefined) return exact;\n  const newer = manifest.entries\n    .filter((entry) => {\n      const held = parseEntryName(entry.name)!;\n      return sameSlot(held, wanted) && held.version > wanted.version;\n    })\n    .map((entry) => entry.name);\n  return newer.length > 0 ? { kind: 'newer', names: newer } : { kind: 'absent' };\n}\n\n/**\n * A line cell in this process, for tests and for a run that shares with itself.\n *\n * Holds real versions, so a test can stage a writer that moves the line between\n * another writer's read and its write.\n */\nexport function memoryLineCell(): LineCell & { readonly held: Map<string, Uint8Array> } {\n  const held = new Map<string, Uint8Array>();\n  const versions = new Map<string, number>();\n  const key = (line: ShareLine): string => `${line.kind}\\u0000${line.name}`;\n  return {\n    held,\n    async load(line) {\n      const manifest = held.get(`${key(line)}\\u0000manifest`);\n      if (manifest === undefined) return { kind: 'absent' };\n      return { manifest, version: String(versions.get(key(line)) ?? 0) };\n    },\n    async blob(line, path) {\n      const bytes = held.get(path.startsWith('images/') ? path : `${key(line)}\\u0000${path}`);\n      return bytes === undefined ? { kind: 'absent' } : bytes.slice();\n    },\n    async store(line, write) {\n      const current = versions.get(key(line));\n      const now = current === undefined ? undefined : String(current);\n      if (now !== write.expected) return 'conflict';\n      for (const [path, bytes] of write.blobs) {\n        held.set(path.startsWith('images/') ? path : `${key(line)}\\u0000${path}`, bytes.slice());\n      }\n      held.set(`${key(line)}\\u0000manifest`, write.manifest.slice());\n      versions.set(key(line), (current ?? 0) + 1);\n      return 'written';\n    },\n  };\n}\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@variance-authority/core",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "description": "The Variance Authority format, rules, comparison, attribution and verdicts. Pure data in, pure data out, no DOM and no I/O.",
   "keywords": [
     "variance-authority",