@mostra/verify 0.0.0-placeholder → 0.1.0

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -1,3 +1,7 @@
 # @mostra/verify
 
-A placeholder: the first Mostra release replaces it. https://github.com/mostra-dev/mostra
+The verify runner of [Mostra](https://github.com/mostra-dev/mostra). It is the child process that renders an artifact's pages in a warm headless Chromium and reports what it saw: errors, console and network findings, accessibility, an ARIA snapshot, screenshots at DPR 1 and a smoke test. It also compares screenshots with those of the artifact's last passing version.
+
+It ships in the Mostra runtime bundle and runs only as a child of a Mostra supervisor, which starts it on the first `mostra verify` and owns the verdict.
+
+Apache-2.0. It drives Chromium through `playwright-core` (Apache-2.0) and injects `axe-core` (MPL-2.0), unmodified, into the pages it checks.

package/dist/index.d.ts

@@ -0,0 +1,89 @@
+import { CompareRequest, CompareResult, Diagnostic, RenderRequest, RenderResult, ariaSummary } from "@mostra/protocol";
+import "playwright-core";
+//#region src/recorder.d.ts
+/**
+ * The recorder every frame of a verify render starts with (Playwright's init script): it keeps the
+ * page's own console errors and warnings, uncaught errors and unhandled rejections, each with the
+ * diagnostic codes along its `cause` chain, so the runner can tell the artifact's faults from those
+ * verify's synthetic refusal caused (D138 item 2). An unhandled rejection whose reason is that
+ * refusal is dropped, as the browser would never meet it for a viewer.
+ *
+ * It runs in the page, so it is one self-contained function: nothing from this module's scope.
+ */
+/** One thing the page reported. */
+interface RecordedEntry {
+  /** Its place in the page's order of entries, from 0. */
+  readonly seq: number;
+  /**
+   * `error` and `warn` (the console), `uncaught` (an error event), `rejection`, or `caught`
+   * (an error a React error boundary caught, reported by the page's root).
+   */
+  readonly kind: "error" | "warn" | "uncaught" | "rejection" | "caught";
+  /** The message, or the error's name and message, as the page gave it. */
+  readonly text: string;
+  /** The `code`s of the value and its `cause` chain: `MostraError`s carry one. */
+  readonly codes: readonly string[];
+  /** Set on a rejection the recorder kept from the browser: verify's own refusal. */
+  readonly dropped?: true;
+}
+/** The recorder, as Playwright installs it in every frame before the page's scripts run. */
+export declare function recorder(): void;
+//#endregion
+//#region src/observe.d.ts
+/** Folds identical findings into one with a count. */
+export declare function dedupe(findings: readonly Diagnostic[]): Diagnostic[];
+/** Where a finding happened, for its message. */
+type Moment = {
+  readonly kind: "load";
+} | {
+  readonly kind: "interaction";
+  readonly control: string;
+};
+/**
+ * Judges what the page reported in one moment (D138 items 2 and 3): its own faults are errors,
+ * console warnings hints; a fault whose `cause` chain is verify's refusal, and any console error
+ * in a moment when verify refused an action, is a hint naming the action; a missing secret is
+ * the environment's, a warning.
+ */
+export declare function judge(entries: readonly RecordedEntry[], moment: Moment, skipped: readonly string[], viewport: string): Diagnostic[];
+//#endregion
+//#region src/runner.d.ts
+/** How long the runner keeps its browser without work (ROUND-3 §9): 10 minutes. */
+export declare const RUNNER_IDLE_MS: number;
+/** Options for {@link createRunner}. */
+interface RunnerOptions {
+  /** Called when the runner has been idle for `idleMs`: the process exits then. */
+  readonly onIdle?: () => void;
+  /** How long without work counts as idle; {@link RUNNER_IDLE_MS} by default. */
+  readonly idleMs?: number;
+}
+/** The runner of one process. */
+interface Runner {
+  /** Renders one capability link in a fresh browser context and reports what the page did. */
+  render(request: RenderRequest): Promise<RenderResult>;
+  /** Compares two screenshots and writes the difference. */
+  compare(request: CompareRequest): Promise<CompareResult>;
+  /** Closes the browser. */
+  close(): Promise<void>;
+}
+/** Creates the runner; its browser starts on the first render. */
+export declare function createRunner(options?: RunnerOptions): Runner;
+/** Whether a PNG is one uniform color. */
+export declare function uniform(png: Buffer): boolean;
+/**
+ * Waits for `work`, and gives up on it `graceMs` past `deadline`: `abandon()` is called (for a
+ * render, closing its context, which ends a page whose code blocks its main thread) and `late` is
+ * the answer, also when `work` then fails because of the abandon. A failure before that is
+ * `work`'s own and is thrown (Opus review finding 5).
+ */
+export declare function bounded<T>(work: Promise<T>, options: {
+  readonly deadline: number;
+  readonly late: T;
+  readonly abandon: () => Promise<unknown> | undefined;
+  readonly graceMs?: number;
+}): Promise<T>;
+/** Compares two screenshots with pixelmatch's perceptual threshold and writes the difference. */
+export declare function compareImages(request: CompareRequest): Promise<CompareResult>;
+//#endregion
+export { type Moment, type RecordedEntry, type Runner, type RunnerOptions, ariaSummary };
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","names":[],"sources":["../src/recorder.ts","../src/observe.ts","../src/runner.ts"],"mappings":";;;;;;;;;;;;;UAYiB;;WAEN;;;;;WAKA;;WAEA;;WAEA;;WAEA;;;wBAOK;;;;wBC4BA,OAAO,mBAAmB,eAAe;;KA2B7C;WACG;;WACA;WAA8B;;;;;;;;wBAW7B,MACd,kBAAkB,iBAClB,QAAQ,QACR,4BACA,mBACC;;;;qBClEU;;UAaI;;WAEN;;WAEA;;;UAIM;;EAEf,OAAO,SAAS,gBAAgB,QAAQ;;EAExC,QAAQ,SAAS,iBAAiB,QAAQ;;EAE1C,SAAS;;;wBAWK,aAAa,UAAS,gBAAqB;;wBA0F3C,QAAQ,KAAK;;;;;;;wBAqBP,QAAQ,GAC5B,MAAM,QAAQ,IACd;WACW;WACA,MAAM;WACN,eAAe;WACf;IAEV,QAAQ;;wBA4PW,cAAc,SAAS,iBAAiB,QAAQ"}

package/dist/index.js

@@ -0,0 +1,3 @@
+import { a as uniform, c as recorder, i as createRunner, n as bounded, o as dedupe, r as compareImages, s as judge, t as RUNNER_IDLE_MS } from "./runner-DCmzgY2w.js";
+import { ariaSummary } from "@mostra/protocol";
+export { RUNNER_IDLE_MS, ariaSummary, bounded, compareImages, createRunner, dedupe, judge, recorder, uniform };

package/dist/main.d.ts

@@ -0,0 +1 @@
+export {}

package/dist/main.js

@@ -0,0 +1,48 @@
+#!/usr/bin/env node
+import { i as createRunner } from "./runner-DCmzgY2w.js";
+import { RpcError, RpcPeer, VERIFY_RUNNER_METHODS, createDiagnostic } from "@mostra/protocol";
+//#region src/main.ts
+/**
+* The verify runner child's entry (`mostra-verify`, ARCHITECTURE §1): the supervisor's process
+* manager starts it, in its own process group, with a JSON-RPC channel over Node IPC. It serves
+* `verify/render` and `verify/compare`, keeps one warm Chromium for them, and exits after 10 idle
+* minutes or when its supervisor goes away, taking the browser with it (FAILURE_MODEL §2).
+*/
+const send = process.send?.bind(process);
+if (!send) {
+	process.stderr.write("mostra-verify runs only as a child of a Mostra supervisor.\n");
+	process.exit(2);
+}
+/** Ends this child and its process group (the browser with it). */
+function exitWithGroup(code) {
+	try {
+		process.kill(-process.pid, "SIGTERM");
+	} catch {}
+	process.exit(code);
+}
+const idle = Number(process.env["MOSTRA_TEST_VERIFY_IDLE_MS"]);
+const runner = createRunner({
+	...idle > 0 ? { idleMs: idle } : {},
+	onIdle: () => {
+		runner.close().finally(() => exitWithGroup(0));
+	}
+});
+const peer = new RpcPeer({
+	send: (message) => {
+		send(message);
+	},
+	onRequest: async (method, params) => {
+		if (method === VERIFY_RUNNER_METHODS.render) return runner.render(params);
+		if (method === VERIFY_RUNNER_METHODS.compare) return runner.compare(params);
+		throw new RpcError(createDiagnostic("MOSTRA_HOST_METHOD_UNKNOWN", { message: `The verify runner serves no method ${method}.` }));
+	}
+});
+process.on("message", (message) => peer.receive(message));
+process.on("disconnect", () => {
+	peer.close();
+	runner.close().finally(() => exitWithGroup(0));
+});
+//#endregion
+export {};
+
+//# sourceMappingURL=main.js.map

package/dist/main.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"main.js","names":[],"sources":["../src/main.ts"],"sourcesContent":["#!/usr/bin/env node\n/**\n * The verify runner child's entry (`mostra-verify`, ARCHITECTURE §1): the supervisor's process\n * manager starts it, in its own process group, with a JSON-RPC channel over Node IPC. It serves\n * `verify/render` and `verify/compare`, keeps one warm Chromium for them, and exits after 10 idle\n * minutes or when its supervisor goes away, taking the browser with it (FAILURE_MODEL §2).\n */\nimport {\n  type CompareRequest,\n  createDiagnostic,\n  type RenderRequest,\n  RpcError,\n  RpcPeer,\n  VERIFY_RUNNER_METHODS,\n} from \"@mostra/protocol\";\nimport { createRunner } from \"./runner.ts\";\n\nconst send = process.send?.bind(process);\nif (!send) {\n  process.stderr.write(\"mostra-verify runs only as a child of a Mostra supervisor.\\n\");\n  process.exit(2);\n}\n\n/** Ends this child and its process group (the browser with it). */\nfunction exitWithGroup(code: number): never {\n  try {\n    process.kill(-process.pid, \"SIGTERM\");\n  } catch {\n    // The group is already gone.\n  }\n  process.exit(code);\n}\n\nconst idle = Number(process.env[\"MOSTRA_TEST_VERIFY_IDLE_MS\"]);\nconst runner = createRunner({\n  ...(idle > 0 ? { idleMs: idle } : {}),\n  onIdle: () => {\n    void runner.close().finally(() => exitWithGroup(0));\n  },\n});\n\nconst peer = new RpcPeer({\n  send: (message) => {\n    send(message);\n  },\n  onRequest: async (method, params) => {\n    if (method === VERIFY_RUNNER_METHODS.render) {\n      return runner.render(params as unknown as RenderRequest);\n    }\n    if (method === VERIFY_RUNNER_METHODS.compare) {\n      return runner.compare(params as unknown as CompareRequest);\n    }\n    throw new RpcError(\n      createDiagnostic(\"MOSTRA_HOST_METHOD_UNKNOWN\", {\n        message: `The verify runner serves no method ${method}.`,\n      }),\n    );\n  },\n});\nprocess.on(\"message\", (message) => peer.receive(message));\nprocess.on(\"disconnect\", () => {\n  peer.close();\n  void runner.close().finally(() => exitWithGroup(0));\n});\n"],"mappings":";;;;;;;;;;AAiBA,MAAM,OAAO,QAAQ,MAAM,KAAK,OAAO;AACvC,IAAI,CAAC,MAAM;CACT,QAAQ,OAAO,MAAM,8DAA8D;CACnF,QAAQ,KAAK,CAAC;AAChB;;AAGA,SAAS,cAAc,MAAqB;CAC1C,IAAI;EACF,QAAQ,KAAK,CAAC,QAAQ,KAAK,SAAS;CACtC,QAAQ,CAER;CACA,QAAQ,KAAK,IAAI;AACnB;AAEA,MAAM,OAAO,OAAO,QAAQ,IAAI,6BAA6B;AAC7D,MAAM,SAAS,aAAa;CAC1B,GAAI,OAAO,IAAI,EAAE,QAAQ,KAAK,IAAI,CAAC;CACnC,cAAc;EACZ,OAAY,MAAM,CAAC,CAAC,cAAc,cAAc,CAAC,CAAC;CACpD;AACF,CAAC;AAED,MAAM,OAAO,IAAI,QAAQ;CACvB,OAAO,YAAY;EACjB,KAAK,OAAO;CACd;CACA,WAAW,OAAO,QAAQ,WAAW;EACnC,IAAI,WAAW,sBAAsB,QACnC,OAAO,OAAO,OAAO,MAAkC;EAEzD,IAAI,WAAW,sBAAsB,SACnC,OAAO,OAAO,QAAQ,MAAmC;EAE3D,MAAM,IAAI,SACR,iBAAiB,8BAA8B,EAC7C,SAAS,sCAAsC,OAAO,GACxD,CAAC,CACH;CACF;AACF,CAAC;AACD,QAAQ,GAAG,YAAY,YAAY,KAAK,QAAQ,OAAO,CAAC;AACxD,QAAQ,GAAG,oBAAoB;CAC7B,KAAK,MAAM;CACX,OAAY,MAAM,CAAC,CAAC,cAAc,cAAc,CAAC,CAAC;AACpD,CAAC"}