@nextcommerce/campaigns-os 1.52.0 → 1.54.0

package/src/qc-accept.mjs

@@ -14,6 +14,7 @@ import { isNamedHuman, validateWaiverAttribution } from "./checkpoint-waiver.mjs
 import { DOCTOR_SIDECAR_SCHEMA } from "./doctor-sidecar.mjs";
 import { cmd } from "./install-invocation.mjs";
 import { canonicalJson } from "./polish-capture.mjs";
+import { QC_CHECK_REGISTRY } from "./qc-check-registry.mjs";
 import { QC_LEGS, QC_REASON, fingerprint12, qcResultRef } from "./qc-results.mjs";
 import { shellToken } from "./shell-token.mjs";
 
@@ -22,7 +23,18 @@ export const QC_ACCEPT_SCOPE = "qc_accept";
 export const QC_ACCEPT_RECORDER = "campaigns-os checkpoint accept";
 export const QC_ACCEPT_STATUSES = Object.freeze(["active", "lapsed", "orphaned", "expired", "inert"]);
 export const QC_DISPOSITION = Object.freeze({ OPEN: "open", OPERATOR_ACCEPTED: "operator_accepted" });
-export const QC_MEASURED_SOURCES = Object.freeze({ doctor: "doctor_sidecar", polish: "polish_media_weight", qa: "qa_full_verdict" });
+// The evidence an accept's measurement came from: the doctor sidecar, the
+// full QA verdict, or, on the Polish leg, the package-owned record the
+// accepted check is read from (QC_CHECK_REGISTRY `record`).
+const QC_LEG_SOURCES = Object.freeze({ doctor: "doctor_sidecar", qa: "qa_full_verdict" });
+export const QC_POLISH_RECORD_SOURCES = Object.freeze({ media_weight: "polish_media_weight", readability: "polish_readability" });
+
+// Null for a Polish check with no record, or a leg with no source.
+export function measuredSourceFor(leg, check) {
+  if (leg !== "polish") return Object.hasOwn(QC_LEG_SOURCES, leg) ? QC_LEG_SOURCES[leg] : null;
+  const entry = Object.hasOwn(QC_CHECK_REGISTRY, check) ? QC_CHECK_REGISTRY[check] : null;
+  return entry?.leg === "polish" && Object.hasOwn(QC_POLISH_RECORD_SOURCES, entry.record) ? QC_POLISH_RECORD_SOURCES[entry.record] : null;
+}
 
 // The command's closed refusal list.
 export const QC_ACCEPT_REFUSALS = Object.freeze({
@@ -100,7 +112,7 @@ export function createQcAccept(result, { measuredAt, attribution }) {
     state_fingerprint: result.state_fingerprint,
     result_at_accept: "warning",
     measured_at: measuredAt,
-    measured_source: QC_MEASURED_SOURCES[result.leg],
+    measured_source: measuredSourceFor(result.leg, result.check),
     ...attribution,
     recorded_by: QC_ACCEPT_RECORDER,
   };
@@ -119,7 +131,8 @@ function malformed(record) {
     && FINGERPRINT.test(record.state_fingerprint || "")
     && record.result_at_accept === "warning"
     && validTime(record.measured_at)
-    && record.measured_source === QC_MEASURED_SOURCES[record.leg]
+    && isNonEmptyString(record.measured_source)
+    && record.measured_source === measuredSourceFor(record.leg, record.check)
     && typeof record.reason === "string"
     && typeof record.accepted_by === "string"
     && typeof record.accepted_at === "string"
@@ -291,7 +304,29 @@ export function planQcAccepts({ refs, results, sidecarPath, now, attribution })
 const LEG_ORDER = Object.freeze({ doctor: 0, polish: 1, qa: 2 });
 const compareText = (a, b) => String(a ?? "").localeCompare(String(b ?? ""));
 
+// A readability colour pair reads as its roles, colours, ratio and
+// requirement: `<roles>: <fg8> on <bg8>, <ratio>:1, needs <required>:1
+// (<size_class> text)`, from the row's observation (the lowest ratio of the
+// rows given). Null for any other row.
+function readabilityPairSummary(rows) {
+  const pairs = rows.map((row) => (row?.check === "readability.contrast" && String(row.subject?.key ?? "").startsWith("pair:") && isPlainObject(row.observation) ? row.observation : null));
+  if (!pairs.length || pairs.some((observation) => observation === null)) return null;
+  const roles = [...new Set(pairs.flatMap((observation) => (Array.isArray(observation.roles) ? observation.roles : [])))].sort(compareText);
+  const lowest = pairs.reduce((low, observation) => (observation.ratio < low.ratio ? observation : low));
+  return `${roles.join(", ")}: ${lowest.fg8} on ${lowest.bg8}, ${lowest.display_ratio}:1, needs ${lowest.required}:1 (${lowest.size_class} text)`;
+}
+
+// The crop path of a readability review row: its first member's crop.
+// Undefined for a review row with no crop, and for any other row.
+function readabilityReviewCrop(row) {
+  if (row?.check !== "readability.contrast" || row.result !== "review") return undefined;
+  const members = Array.isArray(row.observation?.members) ? row.observation.members : [];
+  const ref = members.find((member) => isPlainObject(member?.crop_ref))?.crop_ref;
+  return typeof ref?.path === "string" ? ref.path : undefined;
+}
+
 function handoffEntry(row) {
+  const crop = readabilityReviewCrop(row);
   return {
     result_ref: qcResultRef(row),
     check: row.check,
@@ -303,7 +338,8 @@ function handoffEntry(row) {
     reason_code: row.reason_code,
     accept_eligible: row.accept_eligible === true,
     members: Array.isArray(row.members) ? row.members : [],
-    summary: `${row.check} ${row.result}${row.reason_code ? ` (${row.reason_code})` : ""} on ${row.subject?.page ?? "(no page)"}${row.subject?.key == null ? "" : `: ${row.subject.key}`}`,
+    summary: readabilityPairSummary([row]) ?? `${row.check} ${row.result}${row.reason_code ? ` (${row.reason_code})` : ""} on ${row.subject?.page ?? "(no page)"}${row.subject?.key == null ? "" : `: ${row.subject.key}`}`,
+    ...(crop === undefined ? {} : { crop }),
   };
 }
 
@@ -315,7 +351,7 @@ const byCheckKeyPage = (a, b) => compareText(a.check, b.check) || compareText(a.
 // first page's fields, `pages`, and `results`, which keeps every page's result
 // with its own ref, accept eligibility and members, so every member stays
 // visible. The entry is accept-eligible only when every result in it is.
-function groupOpenWarnings(entries) {
+function groupOpenWarnings(entries, rows = []) {
   const groups = new Map();
   for (const entry of [...entries].sort(byCheckKeyPage)) {
     const key = JSON.stringify([entry.check, entry.key]);
@@ -330,7 +366,7 @@ function groupOpenWarnings(entries) {
       pages,
       accept_eligible: results.every((entry) => entry.accept_eligible),
       summary: results.length > 1
-        ? `${lead.check} ${lead.result}${lead.reason_code ? ` (${lead.reason_code})` : ""} on ${pages.join(", ")}${lead.key == null ? "" : `: ${lead.key}`}`
+        ? readabilityPairSummary(results.map((entry) => rows.find((row) => qcResultRef(row) === entry.result_ref))) ?? `${lead.check} ${lead.result}${lead.reason_code ? ` (${lead.reason_code})` : ""} on ${pages.join(", ")}${lead.key == null ? "" : `: ${lead.key}`}`
         : lead.summary,
       results,
     };
@@ -401,7 +437,7 @@ export function buildQcHandoff({ results, coverage = [], accepts, now = new Date
   const coverageEntries = [...grouped.values(), ...coverage]
     .map((entry) => ({ ...entry, pages: [...entry.pages].sort(compareText) }))
     .sort((a, b) => (LEG_ORDER[a.leg] ?? 9) - (LEG_ORDER[b.leg] ?? 9) || compareText(a.check, b.check) || compareText(a.reason_code, b.reason_code) || compareText(a.result, b.result));
-  const openGroups = groupOpenWarnings(open);
+  const openGroups = groupOpenWarnings(open, results);
   review.sort(byCheckKeyPage);
   lapsed.sort(byCheckKeyPage);
   accepted.sort(byCheckKeyPage);
@@ -435,7 +471,7 @@ export function qcHandoffTextLines(handoff) {
   section("Open warnings", handoff.open, (entry) => (entry.results?.length > 1
     ? [entry.summary, ...entry.results.map((result) => `      ${openLine(result)}`)]
     : openLine(entry)));
-  section("Review", handoff.review, (entry) => `${entry.result_ref} ${entry.summary}${members(entry)}`);
+  section("Review", handoff.review, (entry) => `${entry.result_ref} ${entry.summary}${entry.crop ? ` crop: ${entry.crop}` : ""}${members(entry)}`);
   section("Lapsed accepts", handoff.lapsed, (entry) => `${entry.result_ref} ${entry.summary}; accepted by ${entry.accepted_by} at ${entry.accepted_at}; lapsed: ${entry.why}`);
   section("Coverage", handoff.coverage, (entry) => `${entry.leg} ${entry.check}: ${entry.result} (${entry.reason_code})${entry.count ? ` x${entry.count}` : ""}${entry.pages.length ? ` on ${entry.pages.join(", ")}` : ""}`);
   section("Accepted", handoff.accepted, (entry) => `${entry.result_ref} accepted by ${entry.accepted_by} at ${entry.accepted_at}: ${entry.reason}${members(entry)}`);

package/src/qc-check-registry.mjs

@@ -1,15 +1,19 @@
 // The one map from a QC check id to the check module that re-derives its
-// results. The QC readers
-// (src/qc-results.mjs) reach every check's rules through here, so a check
-// lands by adding its module, never by editing the readers.
+// results. The QC readers (src/qc-results.mjs) reach every check's rules
+// through here. A QA check lands by adding its module; a Polish check reads
+// one package-owned visual_review record, named by `record`, and each record
+// has its own reader in the Polish dispatch (POLISH_RECORDS), so a check for
+// a new record also adds that reader.
 //
 // Each entry names a module specifier, imported lazily and relative to this
 // file, and the export the reader calls:
 // - QA checks: `rederiveQcResult(observation)` returns a Derived result
 //   ({check, subject, result, reason_code, members, accept_eligible, coverage,
 //   state}) or null when the observation cannot be re-derived.
-// - Polish checks: `MEDIA_WEIGHT_QC_RULES` is {thresholds, vocabulary,
-//   evaluate(cell, thresholds) => Derived[]}.
+// - Polish checks: the record's rules, {thresholds, vocabulary,
+//   evaluate(cell, thresholds) => Derived[]} (MEDIA_WEIGHT_QC_RULES for
+//   media_weight; READABILITY_QC_RULES for readability, which also carries
+//   the record's fixed producer values, limits and route set).
 // - Doctor checks recompute from the built HTML on every read and are called
 //   by doctor itself; their entries name the evaluator for completeness.
 //
@@ -23,11 +27,13 @@ export const QC_CHECK_REGISTRY = Object.freeze({
   // Content params
   content_param: Object.freeze({ leg: "qa", unit: "1.2", module: "./qa-content-params.mjs", rederive: "rederiveQcResult" }),
   // Media weight and oversizing
-  "media.weight": Object.freeze({ leg: "polish", unit: "1.3", module: "./polish-media-weight.mjs", rederive: "MEDIA_WEIGHT_QC_RULES" }),
-  "media.oversize": Object.freeze({ leg: "polish", unit: "1.3", module: "./polish-media-weight.mjs", rederive: "MEDIA_WEIGHT_QC_RULES" }),
+  "media.weight": Object.freeze({ leg: "polish", unit: "1.3", module: "./polish-media-weight.mjs", rederive: "MEDIA_WEIGHT_QC_RULES", record: "media_weight" }),
+  "media.oversize": Object.freeze({ leg: "polish", unit: "1.3", module: "./polish-media-weight.mjs", rederive: "MEDIA_WEIGHT_QC_RULES", record: "media_weight" }),
   // Policy links
   "policy.presence": Object.freeze({ leg: "qa", unit: "1.4", module: "./qa-policy-links.mjs", rederive: "rederiveQcResult" }),
   "policy.availability": Object.freeze({ leg: "qa", unit: "1.4", module: "./qa-policy-links.mjs", rederive: "rederiveQcResult" }),
+  // Text readability
+  "readability.contrast": Object.freeze({ leg: "polish", unit: "2.4", module: "./polish-readability.mjs", rederive: "READABILITY_QC_RULES", record: "readability" }),
   // Cart placeholders
   cart_placeholders: Object.freeze({ leg: "doctor", unit: "1.5", module: "./cart-placeholders.mjs", rederive: "evaluateCartPlaceholders" }),
   // Built-output smoke checks
@@ -35,6 +41,8 @@ export const QC_CHECK_REGISTRY = Object.freeze({
 });
 
 export const qcChecksForLeg = (leg) => Object.keys(QC_CHECK_REGISTRY).filter((check) => QC_CHECK_REGISTRY[check].leg === leg);
+// The Polish checks read from one visual_review record.
+export const qcChecksForRecord = (record) => Object.keys(QC_CHECK_REGISTRY).filter((check) => QC_CHECK_REGISTRY[check].leg === "polish" && QC_CHECK_REGISTRY[check].record === record);
 
 // A module "does not exist yet" only when Node reports ERR_MODULE_NOT_FOUND
 // for that exact specifier. A missing transitive import names another URL,