@variance-authority/core 0.1.1 → 0.3.0

package/dist/share/index.js

@@ -0,0 +1,190 @@
+/**
+ * `@variance-authority/core/share` — one machine's evaluation, reachable from another.
+ *
+ * A run derives a great deal that is not about the run: what the suite is made
+ * of, which subjects exist, every name each one carries, which files declare
+ * which components. All of it is a fact about a *commit*, and all of it is
+ * expensive — a source scan, a browser, a composition pass — while being
+ * identical on every machine that starts from the same tree.
+ *
+ * So the second machine should not derive it again. A pull-request runner wants
+ * what mainline already knows, and mainline already knew it an hour ago on a
+ * runner that has since been destroyed. This module is the seam between those
+ * two: a place bytes can be left under a key, and a place they can be looked
+ * for, with nothing in between that knows what the bytes are.
+ *
+ * ## The rule, inherited
+ *
+ * > **A `SharedCache` never throws.**
+ *
+ * `get` answers `null` for a miss, an outage, a permission error, a truncated
+ * body and a response nobody can parse. `put` resolves whether or not anything
+ * was written. This is the same rule
+ * [`RenderCache`](../../../raster/src/store.ts) is defined by, and it is safe
+ * here for the same reason: everything a share holds is derivable from the tree
+ * it was derived at. A miss costs the derivation, which is the answer that was
+ * always available.
+ *
+ * What that costs, stated rather than hidden: a cache that is failing looks
+ * exactly like a cache that is cold, so a broken share makes CI slow and never
+ * makes it red. An operator watching the wall clock has to go looking. The
+ * alternative — failing a build because a bucket answered 503 — is worse.
+ *
+ * ## Why a key is a commit
+ *
+ * Everything shared here is derived, so the only question a reader has is *of
+ * what*, and the answer is a tree. A commit names one; a branch names whichever
+ * one it points at this second, and two runners resolving `main` four minutes
+ * apart would silently compare against different suites.
+ *
+ * Mainline moves while a branch is open, though, which is why the lookup is
+ * {@link firstShared} over a lineage rather than a single `get`: the runner asks
+ * for the commits its branch actually descends from, newest first, and takes the
+ * first one anybody published. What it gets back says which commit it is, so a
+ * reader is never in doubt about what it is holding.
+ *
+ * ## What this is not
+ *
+ * Not a baseline store. A baseline is the thing a comparison is *against*, it
+ * cannot be re-derived, and losing one silently is how a suite records whatever
+ * happened to be on screen — which is why
+ * [`RasterStore`](../../../raster/src/store.ts) throws on every failure and this
+ * throws on none. The two are configured separately because they are answers to
+ * different questions, and a share is disposable in a way a baseline may never
+ * be.
+ */
+/**
+ * Hold an implementation to the rule.
+ *
+ * Backends are built out of a disk, a socket or a bucket, every one of which
+ * throws, and every one of them would otherwise have to remember not to.
+ * Wrapping at construction makes the rule a property of the value rather than a
+ * promise in a comment.
+ */
+export function neverFails(cache) {
+    return {
+        async get(key) {
+            try {
+                return await cache.get(key);
+            }
+            catch {
+                // A miss and a failure are the same instruction: derive it.
+                return null;
+            }
+        },
+        async put(key, bytes) {
+            try {
+                await cache.put(key, bytes);
+            }
+            catch {
+                // Nothing to report and nothing to retry. The next run publishes again.
+            }
+        },
+    };
+}
+/**
+ * The key an artifact is published under.
+ *
+ * `project` is a namespace and not a secret: two suites in one monorepo share a
+ * bucket and must not share a key. `artifact` names the format, so a reader that
+ * does not understand version 2 of something asks for a key version 2 was never
+ * written to rather than parsing bytes it will reject.
+ */
+export function shareKey(parts) {
+    return `${segment(parts.project)}/${segment(parts.artifact)}/${segment(parts.commit)}.bin`;
+}
+/**
+ * The newest published artifact among commits this tree descends from.
+ *
+ * Newest-first because a nearer ancestor is a better description of the same
+ * suite, and `behind` is returned rather than discarded because it is the one
+ * number that tells an operator their publishing is failing: a share that is
+ * always forty commits behind is a share nothing is writing to, and it is
+ * otherwise indistinguishable from a healthy one.
+ *
+ * Stops at the first hit rather than collecting all of them. There is no merge
+ * across generations to perform — an evaluation describes one tree — and asking
+ * a network for forty keys that will be discarded is the cost this exists to
+ * avoid.
+ */
+export async function firstShared(cache, lineage, of) {
+    for (let behind = 0; behind < lineage.length; behind += 1) {
+        const commit = lineage[behind];
+        const bytes = await cache.get(of(commit));
+        if (bytes !== null)
+            return { commit, behind, bytes };
+    }
+    return null;
+}
+/**
+ * A cache in this process, for tests and for a run that shares with itself.
+ *
+ * Kept here rather than in a test helper because it is also the honest answer
+ * to "share, but I have nowhere to put it": the seam is exercised, the code
+ * path is the real one, and nothing survives the process.
+ */
+export function memoryShare() {
+    const held = new Map();
+    return {
+        async get(key) {
+            return held.get(key) ?? null;
+        },
+        async put(key, bytes) {
+            held.set(key, bytes.slice());
+        },
+    };
+}
+/**
+ * A share over HTTP: `GET` to read, `PUT` to write, the key as the path.
+ *
+ * One backend rather than four because a bucket, a signed URL, a static host
+ * and a tribunal deployment differ in exactly two ways — the base and the
+ * headers — and every one of them speaks this. S3 with `PUT` object access is
+ * this with an `Authorization` header; a presigned base is this with none; a
+ * deployment is this with a token. Writing three clients would have produced
+ * three sets of error handling for an object whose entire error handling is
+ * "return null".
+ *
+ * Nothing here signs anything. Credentials that must be computed per request —
+ * SigV4 against a raw bucket — belong to whatever already holds the operator's
+ * credentials, and the shape that reaches this is a base URL it produced. That
+ * keeps a secret out of this package and out of the config file it would
+ * otherwise have to be written in.
+ */
+export function httpShare(options) {
+    const base = options.endpoint.replace(/\/+$/, '');
+    const headers = options.headers ?? {};
+    return {
+        async get(key) {
+            const response = await fetch(`${base}/${key}`, { headers });
+            // A 404 is the common answer and not an event. Every other refusal is
+            // read the same way, because the caller's response to all of them is one
+            // response, and a cache that distinguished them would be inviting a
+            // caller to act on the difference.
+            if (!response.ok)
+                return null;
+            return new Uint8Array(await response.arrayBuffer());
+        },
+        async put(key, bytes) {
+            await fetch(`${base}/${key}`, {
+                method: options.method ?? 'PUT',
+                headers: { 'content-type': 'application/octet-stream', ...headers },
+                body: bytes,
+            });
+        },
+    };
+}
+/**
+ * One path segment, with everything that is not a key character removed.
+ *
+ * A project name comes from a config file and a commit from `git`, and both end
+ * up in a URL and on a filesystem. Escaping would be reversible and is not
+ * wanted: a name that needs escaping is a name whose two spellings should not
+ * address two different entries, so the mapping is deliberately many-to-one and
+ * the cost of a collision is a cache miss.
+ */
+function segment(value) {
+    const cleaned = value.replace(/[^A-Za-z0-9._-]+/g, '-').replace(/^[-.]+|[-.]+$/g, '');
+    return cleaned === '' ? 'unnamed' : cleaned;
+}
+//# sourceMappingURL=index.js.map

package/dist/share/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/share/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsDG;AA+BH;;;;;;;GAOG;AACH,MAAM,UAAU,UAAU,CAAC,KAAkB;IAC3C,OAAO;QACL,KAAK,CAAC,GAAG,CAAC,GAAG;YACX,IAAI,CAAC;gBACH,OAAO,MAAM,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;YAC9B,CAAC;YAAC,MAAM,CAAC;gBACP,4DAA4D;gBAC5D,OAAO,IAAI,CAAC;YACd,CAAC;QACH,CAAC;QACD,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK;YAClB,IAAI,CAAC;gBACH,MAAM,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;YAC9B,CAAC;YAAC,MAAM,CAAC;gBACP,wEAAwE;YAC1E,CAAC;QACH,CAAC;KACF,CAAC;AACJ,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,QAAQ,CAAC,KAIxB;IACC,OAAO,GAAG,OAAO,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,OAAO,CAAC,KAAK,CAAC,QAAQ,CAAC,IAAI,OAAO,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC;AAC7F,CAAC;AAWD;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAC/B,KAAkB,EAClB,OAA0B,EAC1B,EAA8B;IAE9B,KAAK,IAAI,MAAM,GAAG,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,MAAM,IAAI,CAAC,EAAE,CAAC;QAC1D,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,CAAE,CAAC;QAChC,MAAM,KAAK,GAAG,MAAM,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC;QAC1C,IAAI,KAAK,KAAK,IAAI;YAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC;IACvD,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,WAAW;IACzB,MAAM,IAAI,GAAG,IAAI,GAAG,EAAsB,CAAC;IAC3C,OAAO;QACL,KAAK,CAAC,GAAG,CAAC,GAAG;YACX,OAAO,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,IAAI,CAAC;QAC/B,CAAC;QACD,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK;YAClB,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,KAAK,EAAE,CAAC,CAAC;QAC/B,CAAC;KACF,CAAC;AACJ,CAAC;AAYD;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,SAAS,CAAC,OAAyB;IACjD,MAAM,IAAI,GAAG,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;IAClD,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,IAAI,EAAE,CAAC;IACtC,OAAO;QACL,KAAK,CAAC,GAAG,CAAC,GAAG;YACX,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,GAAG,IAAI,IAAI,GAAG,EAAE,EAAE,EAAE,OAAO,EAAE,CAAC,CAAC;YAC5D,sEAAsE;YACtE,yEAAyE;YACzE,oEAAoE;YACpE,mCAAmC;YACnC,IAAI,CAAC,QAAQ,CAAC,EAAE;gBAAE,OAAO,IAAI,CAAC;YAC9B,OAAO,IAAI,UAAU,CAAC,MAAM,QAAQ,CAAC,WAAW,EAAE,CAAC,CAAC;QACtD,CAAC;QACD,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK;YAClB,MAAM,KAAK,CAAC,GAAG,IAAI,IAAI,GAAG,EAAE,EAAE;gBAC5B,MAAM,EAAE,OAAO,CAAC,MAAM,IAAI,KAAK;gBAC/B,OAAO,EAAE,EAAE,cAAc,EAAE,0BAA0B,EAAE,GAAG,OAAO,EAAE;gBACnE,IAAI,EAAE,KAAK;aACZ,CAAC,CAAC;QACL,CAAC;KACF,CAAC;AACJ,CAAC;AAED;;;;;;;;GAQG;AACH,SAAS,OAAO,CAAC,KAAa;IAC5B,MAAM,OAAO,GAAG,KAAK,CAAC,OAAO,CAAC,mBAAmB,EAAE,GAAG,CAAC,CAAC,OAAO,CAAC,gBAAgB,EAAE,EAAE,CAAC,CAAC;IACtF,OAAO,OAAO,KAAK,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,OAAO,CAAC;AAC9C,CAAC","sourcesContent":["/**\n * `@variance-authority/core/share` — one machine's evaluation, reachable from another.\n *\n * A run derives a great deal that is not about the run: what the suite is made\n * of, which subjects exist, every name each one carries, which files declare\n * which components. All of it is a fact about a *commit*, and all of it is\n * expensive — a source scan, a browser, a composition pass — while being\n * identical on every machine that starts from the same tree.\n *\n * So the second machine should not derive it again. A pull-request runner wants\n * what mainline already knows, and mainline already knew it an hour ago on a\n * runner that has since been destroyed. This module is the seam between those\n * two: a place bytes can be left under a key, and a place they can be looked\n * for, with nothing in between that knows what the bytes are.\n *\n * ## The rule, inherited\n *\n * > **A `SharedCache` never throws.**\n *\n * `get` answers `null` for a miss, an outage, a permission error, a truncated\n * body and a response nobody can parse. `put` resolves whether or not anything\n * was written. This is the same rule\n * [`RenderCache`](../../../raster/src/store.ts) is defined by, and it is safe\n * here for the same reason: everything a share holds is derivable from the tree\n * it was derived at. A miss costs the derivation, which is the answer that was\n * always available.\n *\n * What that costs, stated rather than hidden: a cache that is failing looks\n * exactly like a cache that is cold, so a broken share makes CI slow and never\n * makes it red. An operator watching the wall clock has to go looking. The\n * alternative — failing a build because a bucket answered 503 — is worse.\n *\n * ## Why a key is a commit\n *\n * Everything shared here is derived, so the only question a reader has is *of\n * what*, and the answer is a tree. A commit names one; a branch names whichever\n * one it points at this second, and two runners resolving `main` four minutes\n * apart would silently compare against different suites.\n *\n * Mainline moves while a branch is open, though, which is why the lookup is\n * {@link firstShared} over a lineage rather than a single `get`: the runner asks\n * for the commits its branch actually descends from, newest first, and takes the\n * first one anybody published. What it gets back says which commit it is, so a\n * reader is never in doubt about what it is holding.\n *\n * ## What this is not\n *\n * Not a baseline store. A baseline is the thing a comparison is *against*, it\n * cannot be re-derived, and losing one silently is how a suite records whatever\n * happened to be on screen — which is why\n * [`RasterStore`](../../../raster/src/store.ts) throws on every failure and this\n * throws on none. The two are configured separately because they are answers to\n * different questions, and a share is disposable in a way a baseline may never\n * be.\n */\n\n// Declared rather than imported, as elsewhere in this package: `core` takes no\n// platform's types, and `fetch` is present in every runtime it targets. Only the\n// three members used are named, so a runtime with a narrower one still fits.\ndeclare const fetch: (\n  url: string,\n  init?: {\n    method?: string;\n    headers?: Record<string, string>;\n    body?: Uint8Array;\n  },\n) => Promise<{\n  readonly ok: boolean;\n  readonly status: number;\n  arrayBuffer(): Promise<ArrayBuffer>;\n}>;\n\n/**\n * Bytes under a key, on terms where losing them is free.\n *\n * Deliberately the smallest interface that can carry an evaluation: no listing,\n * no deletion, no expiry. A backend that can do more is welcome to; nothing\n * here may depend on it, because the set of things every one of a directory, an\n * action cache, a bucket and a deployment can do is this.\n */\nexport interface SharedCache {\n  get(key: string): Promise<Uint8Array | null>;\n  put(key: string, bytes: Uint8Array): Promise<void>;\n}\n\n/**\n * Hold an implementation to the rule.\n *\n * Backends are built out of a disk, a socket or a bucket, every one of which\n * throws, and every one of them would otherwise have to remember not to.\n * Wrapping at construction makes the rule a property of the value rather than a\n * promise in a comment.\n */\nexport function neverFails(cache: SharedCache): SharedCache {\n  return {\n    async get(key): Promise<Uint8Array | null> {\n      try {\n        return await cache.get(key);\n      } catch {\n        // A miss and a failure are the same instruction: derive it.\n        return null;\n      }\n    },\n    async put(key, bytes): Promise<void> {\n      try {\n        await cache.put(key, bytes);\n      } catch {\n        // Nothing to report and nothing to retry. The next run publishes again.\n      }\n    },\n  };\n}\n\n/**\n * The key an artifact is published under.\n *\n * `project` is a namespace and not a secret: two suites in one monorepo share a\n * bucket and must not share a key. `artifact` names the format, so a reader that\n * does not understand version 2 of something asks for a key version 2 was never\n * written to rather than parsing bytes it will reject.\n */\nexport function shareKey(parts: {\n  readonly project: string;\n  readonly artifact: string;\n  readonly commit: string;\n}): string {\n  return `${segment(parts.project)}/${segment(parts.artifact)}/${segment(parts.commit)}.bin`;\n}\n\n/** What a lookup over a lineage found, and where. */\nexport interface SharedHit {\n  /** The commit the bytes were published at — never the one that was asked for first. */\n  readonly commit: string;\n  /** How many commits back that was, zero being the newest candidate offered. */\n  readonly behind: number;\n  readonly bytes: Uint8Array;\n}\n\n/**\n * The newest published artifact among commits this tree descends from.\n *\n * Newest-first because a nearer ancestor is a better description of the same\n * suite, and `behind` is returned rather than discarded because it is the one\n * number that tells an operator their publishing is failing: a share that is\n * always forty commits behind is a share nothing is writing to, and it is\n * otherwise indistinguishable from a healthy one.\n *\n * Stops at the first hit rather than collecting all of them. There is no merge\n * across generations to perform — an evaluation describes one tree — and asking\n * a network for forty keys that will be discarded is the cost this exists to\n * avoid.\n */\nexport async function firstShared(\n  cache: SharedCache,\n  lineage: readonly string[],\n  of: (commit: string) => string,\n): Promise<SharedHit | null> {\n  for (let behind = 0; behind < lineage.length; behind += 1) {\n    const commit = lineage[behind]!;\n    const bytes = await cache.get(of(commit));\n    if (bytes !== null) return { commit, behind, bytes };\n  }\n  return null;\n}\n\n/**\n * A cache in this process, for tests and for a run that shares with itself.\n *\n * Kept here rather than in a test helper because it is also the honest answer\n * to \"share, but I have nowhere to put it\": the seam is exercised, the code\n * path is the real one, and nothing survives the process.\n */\nexport function memoryShare(): SharedCache {\n  const held = new Map<string, Uint8Array>();\n  return {\n    async get(key) {\n      return held.get(key) ?? null;\n    },\n    async put(key, bytes) {\n      held.set(key, bytes.slice());\n    },\n  };\n}\n\n/** What an HTTP share needs to reach its endpoint. */\nexport interface HttpShareOptions {\n  /** Base URL. A key is appended to it, with exactly one `/` between. */\n  readonly endpoint: string;\n  /** Sent on every request. A bucket wants `Authorization`; a signed URL wants nothing. */\n  readonly headers?: Readonly<Record<string, string>>;\n  /** The verb a write uses. `PUT` for a bucket, `POST` for a deployment that routes on it. */\n  readonly method?: 'PUT' | 'POST';\n}\n\n/**\n * A share over HTTP: `GET` to read, `PUT` to write, the key as the path.\n *\n * One backend rather than four because a bucket, a signed URL, a static host\n * and a tribunal deployment differ in exactly two ways — the base and the\n * headers — and every one of them speaks this. S3 with `PUT` object access is\n * this with an `Authorization` header; a presigned base is this with none; a\n * deployment is this with a token. Writing three clients would have produced\n * three sets of error handling for an object whose entire error handling is\n * \"return null\".\n *\n * Nothing here signs anything. Credentials that must be computed per request —\n * SigV4 against a raw bucket — belong to whatever already holds the operator's\n * credentials, and the shape that reaches this is a base URL it produced. That\n * keeps a secret out of this package and out of the config file it would\n * otherwise have to be written in.\n */\nexport function httpShare(options: HttpShareOptions): SharedCache {\n  const base = options.endpoint.replace(/\\/+$/, '');\n  const headers = options.headers ?? {};\n  return {\n    async get(key) {\n      const response = await fetch(`${base}/${key}`, { headers });\n      // A 404 is the common answer and not an event. Every other refusal is\n      // read the same way, because the caller's response to all of them is one\n      // response, and a cache that distinguished them would be inviting a\n      // caller to act on the difference.\n      if (!response.ok) return null;\n      return new Uint8Array(await response.arrayBuffer());\n    },\n    async put(key, bytes) {\n      await fetch(`${base}/${key}`, {\n        method: options.method ?? 'PUT',\n        headers: { 'content-type': 'application/octet-stream', ...headers },\n        body: bytes,\n      });\n    },\n  };\n}\n\n/**\n * One path segment, with everything that is not a key character removed.\n *\n * A project name comes from a config file and a commit from `git`, and both end\n * up in a URL and on a filesystem. Escaping would be reversible and is not\n * wanted: a name that needs escaping is a name whose two spellings should not\n * address two different entries, so the mapping is deliberately many-to-one and\n * the cost of a collision is a cache miss.\n */\nfunction segment(value: string): string {\n  const cleaned = value.replace(/[^A-Za-z0-9._-]+/g, '-').replace(/^[-.]+|[-.]+$/g, '');\n  return cleaned === '' ? 'unnamed' : cleaned;\n}\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@variance-authority/core",
-  "version": "0.1.1",
+  "version": "0.3.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",
@@ -11,7 +11,7 @@
   ],
   "license": "MIT",
   "author": "Machine Garden",
-  "homepage": "https://variance-authority.dev#packages",
+  "homepage": "https://variance-authority.dev/reference/packages/core",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/Variance-Authority/variance-authority.git",
@@ -31,6 +31,14 @@
       "types": "./dist/format/index.d.ts",
       "default": "./dist/format/index.js"
     },
+    "./share": {
+      "types": "./dist/share/index.d.ts",
+      "default": "./dist/share/index.js"
+    },
+    "./segment": {
+      "types": "./dist/segment/index.d.ts",
+      "default": "./dist/segment/index.js"
+    },
     "./rules": {
       "types": "./dist/rules/index.d.ts",
       "default": "./dist/rules/index.js"