@luigisbox/luma 0.0.0-stage → 0.2.0

package/parity/owner.mjs

@@ -0,0 +1,170 @@
+// Who owns a difference `yarn luma parity` found: the integration's template (our
+// markup and CSS: geometry, computed styles, fonts, structure, missing parts,
+// order) or the data (the catalog, the API). Pure functions, no browser,
+// unit-tested.
+//
+// A difference is the data's when it follows from the product data or the
+// API, not from our markup or CSS:
+//   - a text that differs because the paired product's catalog value differs:
+//     ours shows the catalog's value (its title, its price), theirs shows
+//     another one that is no catalog value of the product (evidence: the
+//     field and the catalog's value);
+//   - their product missing from the catalog (unpaired: compare.mjs);
+//   - what the map declares the API cannot supply ("dataGaps", map.mjs GAPS:
+//     facet value counts, an empty state that cannot occur, autocomplete
+//     sections the channel lacks; or a component / "component.part");
+//   - on an instance whose text is the data's, its boxes and its pixels (a
+//     longer title is a wider, taller box).
+// Everything else is the template's: an agent fixes those, the client the others.
+import { GAPS } from './map.mjs';
+
+/** Scalars of a catalog record as [field, value] (lists: each value; objects: dotted fields). @param {any} hit */
+export const catalogValues = (hit) => {
+  const out = /** @type {[string, string | number][]} */ ([]);
+  const walk = (v, k, depth) => {
+    if (v == null || depth > 3) return;
+    if (typeof v === 'string' || typeof v === 'number') out.push([k, v]);
+    else if (Array.isArray(v)) for (const x of v.slice(0, 20)) walk(x, k, depth + 1);
+    else if (typeof v === 'object') for (const [kk, x] of Object.entries(v)) walk(x, `${k}.${kk}`, depth + 1);
+  };
+  if (hit && typeof hit === 'object') for (const [k, v] of Object.entries(hit)) walk(v, k, 0);
+  return out;
+};
+
+const normText = (s) => String(s ?? '').toLowerCase().replace(/\s+/g, ' ').trim();
+
+/**
+ * The numbers a text can mean, whatever its separators: `€1,199.50`,
+ * `1 199,50 €`, `1.199,-` (each grouping read both ways).
+ * @param {string} text
+ */
+export const numbersIn = (text) => {
+  const out = new Set();
+  for (const m of String(text).matchAll(/\d[\d\s.,'’]*/g)) {
+    const t = m[0].replace(/[\s'’]/g, '').replace(/[.,]+$/, '');
+    if (!t) continue;
+    const seps = [...t.matchAll(/[.,]/g)].map((x) => x.index);
+    const add = (s) => {
+      const n = Number(s);
+      if (Number.isFinite(n)) out.add(n);
+    };
+    add(t.replace(/[.,]/g, ''));
+    if (seps.length) {
+      // The last separator as the decimal point, the others as grouping.
+      const last = seps[seps.length - 1];
+      add(`${t.slice(0, last).replace(/[.,]/g, '')}.${t.slice(last + 1)}`);
+    }
+  }
+  return [...out];
+};
+
+/** A text that is a price (or a number) and little else: digits, separators and at most a currency's few letters. @param {string} text */
+const priceLike = (text) => /\d/.test(text) && String(text).replace(/[\d\s.,'’()+-]/g, '').length <= 5;
+
+/**
+ * The catalog fields a text shows as they are: a string field equal to it
+ * (case and whitespace aside), a number field when the text is a price-like
+ * number of that value.
+ * @param {string} text @param {[string, string | number][]} values
+ */
+export const fieldsShown = (text, values) => {
+  const t = normText(text);
+  if (!t) return [];
+  const nums = priceLike(text) ? numbersIn(text) : [];
+  const out = [];
+  for (const [k, v] of values) {
+    const hit = typeof v === 'number' ? nums.some((n) => Math.abs(n - v) < 0.005) : normText(v) === t || (priceLike(text) && priceLike(v) && numbersIn(v).some((x) => nums.some((n) => Math.abs(n - x) < 0.005)));
+    if (hit && !out.includes(k)) out.push(k);
+  }
+  return out;
+};
+
+/**
+ * A text difference on a paired product: the data's when ours shows a
+ * catalog value as it is and theirs shows no catalog value of the product
+ * (nor ours' value with more around it: that is their template composing).
+ * @param {string} theirs @param {string} ours @param {any} hit the paired catalog record
+ * @returns {{ owner: 'data', evidence: { field: string, catalog: string | number, theirs: string } } | { owner: 'template', why: string }}
+ */
+export const textOwner = (theirs, ours, hit) => {
+  if (!hit) return { owner: 'template', why: 'no catalog record paired' };
+  const values = catalogValues(hit);
+  const o = fieldsShown(ours, values);
+  if (!o.length) return { owner: 'template', why: 'ours shows no catalog value as it is' };
+  const t = fieldsShown(theirs, values);
+  if (t.some((f) => o.includes(f))) return { owner: 'template', why: `both show ${t.find((f) => o.includes(f))}, formatted differently` };
+  if (t.length) return { owner: 'template', why: `theirs shows ${t[0]}, ours ${o[0]}` };
+  const tt = normText(theirs);
+  if (o.some((f) => values.some(([k, v]) => k === f && typeof v === 'string' && normText(v).length >= 3 && tt.includes(normText(v))))) return { owner: 'template', why: `theirs adds to ${o[0]}` };
+  const catalog = values.find(([k]) => k === o[0])[1];
+  return { owner: 'data', evidence: { field: o[0], catalog, theirs } };
+};
+
+/** A facet value's text without its count: `Red (12)`, `Red 12`, `Red [12]`. @param {string} s */
+export const withoutCounts = (s) => normText(String(s ?? '').replace(/[([]\s*\d[\d\s.,]*[)\]]/g, ' ').replace(/(^|\s)\d[\d\s.,]*(?=\s|$)/g, ' '));
+
+const BOX = new Set(['x', 'y', 'width', 'height']);
+const FACET = /^facet/;
+
+/**
+ * Every difference of one instance with its owner (`owner`, and `evidence`
+ * or `why` for the data's).
+ * @param {any[]} diffs one instance's (compare.mjs Diff)
+ * @param {{ component?: string, role?: string | null, partRoles?: Record<string, string | null>, hit?: any, gaps?: Record<string, string>, text?: string | false }} ctx
+ */
+export const attribute = (diffs, ctx = {}) => {
+  const gaps = ctx.gaps ?? {};
+  const role = ctx.role ?? null;
+  const roleOfPart = (part) => (part === 'root' || part === 'grid' ? role : (ctx.partRoles?.[part] ?? null));
+  const dataText = new Set();
+  const out = diffs.map((d) => {
+    // A column count is the template's at any viewport, whatever the map declares: never the data's.
+    if (d.prop === 'columns') return { ...d, owner: 'template' };
+    const pr = roleOfPart(d.part);
+    const declared = gaps[`${ctx.component}.${d.part}`] ?? (d.part === 'root' || d.part === 'grid' ? gaps[`${ctx.component}.root`] : undefined) ?? (ctx.component in GAPS ? undefined : gaps[ctx.component]);
+    if (declared) return { ...d, owner: 'data', why: `dataGaps: ${declared}` };
+    if (gaps.empty && (role === 'empty' || role === 'ac-empty' || pr === 'empty' || pr === 'ac-empty')) return { ...d, owner: 'data', why: `dataGaps.empty: ${gaps.empty}` };
+    if (gaps.acSections && (['ac-section', 'ac-title'].includes(role) || ['ac-section', 'ac-title'].includes(pr) || (role === 'ac-panel' && d.part === 'root' && (d.prop === 'height' || d.prop === 'pixels'))))
+      return { ...d, owner: 'data', why: `dataGaps.acSections: ${gaps.acSections}` };
+    if (gaps.facetCounts && (FACET.test(role ?? '') || FACET.test(pr ?? ''))) {
+      if (d.prop === 'text' && withoutCounts(d.theirs) === withoutCounts(d.ours)) {
+        dataText.add(d.part);
+        return { ...d, owner: 'data', why: `dataGaps.facetCounts: ${gaps.facetCounts}` };
+      }
+      if (d.prop === 'presence' && /count/i.test(`${d.part} ${pr ?? ''}`)) return { ...d, owner: 'data', why: `dataGaps.facetCounts: ${gaps.facetCounts}` };
+    }
+    // The text of a paired product: by the catalog's evidence (shape-compared texts, counts, are not values).
+    if (d.prop === 'text' && d.delta !== 'different wording' && ctx.hit) {
+      const r = textOwner(d.theirs, d.ours, ctx.hit);
+      if (r.owner === 'data') {
+        dataText.add(d.part);
+        return { ...d, owner: 'data', evidence: r.evidence, why: `the catalog's ${r.evidence.field} is ${JSON.stringify(r.evidence.catalog)}; theirs shows another value` };
+      }
+    }
+    return { ...d, owner: 'template' };
+  });
+  if (!dataText.size) return out;
+  // What a data text moves: the boxes of this instance and its pixels.
+  const from = [...dataText].join(', ');
+  return out.map((d) => (d.owner === 'template' && (BOX.has(d.prop) || d.prop === 'pixels') ? { ...d, owner: 'data', why: `follows from the data's text in ${from}` } : d));
+};
+
+/**
+ * Recorded product decisions (the map's `excluded` with a `decision`, map.mjs
+ * `decided`): a template difference on a decided component, part or
+ * property is the decision's (`owner: 'decision'`, with it), not the
+ * template's: it counts as passed in the template score and is listed apart.
+ * Keys: `tile`, `tile.title`, `tile color`, `tile.title color`; `collateral`,
+ * `collateral.<block path>`, either with a property.
+ * @param {any[]} diffs @param {{ component?: string, decided?: Record<string, { reason: string, decision: string }> }} ctx
+ */
+export const decide = (diffs, { component = '', decided = {} } = {}) => {
+  if (!Object.keys(decided).length) return diffs;
+  return diffs.map((d) => {
+    if ((d.owner ?? 'template') !== 'template') return d;
+    const at = d.part === 'root' || d.part === 'grid' ? [component, `${component}.root`] : [component, `${component}.${d.part}`];
+    const keys = at.flatMap((w) => [`${w} ${d.prop}`, w]);
+    const k = keys.find((x) => decided[x]);
+    return k ? { ...d, owner: 'decision', decision: decided[k].decision, why: `decided (${k}): ${decided[k].reason}` } : d;
+  });
+};

package/parity/pairing.mjs

@@ -0,0 +1,110 @@
+// What `yarn luma parity` asks the API for their products with (parity/probe.mjs
+// `alignInit`, and `--init`'s check of its pairing), and when the pairing has
+// failed. Pure functions, unit-tested.
+//
+// Their products are fetched by id (`products.field` in their ids) together
+// with a query: many channels answer the search endpoint's empty query with
+// zero hits, so an id request with an empty query paired nothing and a run
+// compared structure only, silently. The queries, in order, at most
+// `MAX_QUERIES`: the map's page query (`pages.<name>.query`), our page's own
+// query (its `q`, or what the page types; not on our search page against
+// another page of theirs: our query is not their products'), their category's
+// name (their page's heading), the most frequent words of their tiles'
+// titles. Each next query asks only for the products the ones before did not
+// find. When none finds any, the pairing has failed: a CRITICAL difference,
+// never a silent fallback (`pairingFailure`).
+
+/** Queries tried at most, besides a collections surface's request (which takes none). */
+export const MAX_QUERIES = 4;
+
+/** Query-string params a search page's query is in. */
+export const QUERY_PARAMS = Object.freeze(['q', 'query', 'search', 's', 'term', 'text', 'phrase', 'keyword', 'keywords', 'searchTerm', 'search_query']);
+
+/** Words that find nothing on their own (articles, prepositions; English and the shops' usual languages). */
+const STOP = new Set(
+  'the and for with from new set pcs pack size der die das und mit fur für les des pour avec una uno con per del della pro pre ako alebo bez na za od do pod nad'.split(' '),
+);
+
+/** Words of a text, lower-cased, in order. @param {string} s */
+const wordsOf = (s) => String(s ?? '').toLowerCase().normalize('NFC').split(/[^\p{L}\p{N}]+/u).filter(Boolean);
+
+/**
+ * The words most of their titles share, most frequent first (each title
+ * counted once per word; ties by the word): `["shoe", "leather"]`. Numbers,
+ * words of fewer than 3 letters and stop words left out.
+ * @param {string[]} titles @param {number} [n]
+ */
+export const frequentWords = (titles, n = 2) => {
+  const freq = new Map();
+  for (const t of titles) {
+    const seen = new Set();
+    for (const w of wordsOf(t)) {
+      if (w.length < 3 || /\d/.test(w) || STOP.has(w) || seen.has(w)) continue;
+      seen.add(w);
+      freq.set(w, (freq.get(w) ?? 0) + 1);
+    }
+  }
+  return [...freq]
+    .filter(([, c]) => c >= 2 || titles.length < 2)
+    .sort((a, b) => b[1] - a[1] || (a[0] < b[0] ? -1 : 1))
+    .slice(0, n)
+    .map(([w]) => w);
+};
+
+/** A page path's search query (`/search?q=lamp` -> `lamp`), or ''. @param {string | null | undefined} path */
+export const queryOfPath = (path) => {
+  try {
+    const u = new URL(String(path ?? ''), 'https://x.invalid/');
+    for (const k of QUERY_PARAMS) {
+      const v = u.searchParams.get(k);
+      if (v && v.trim()) return v.trim();
+    }
+  } catch {}
+  return '';
+};
+
+/**
+ * The queries their products are asked for with, in order, each once (case
+ * aside), at most `max`; never empty: `['']` when nothing gives one.
+ * @param {{ queries?: string[], oursPath?: string | null, typed?: string | null, cross?: boolean, heading?: string | null, titles?: string[], max?: number }} o
+ */
+export const queryCandidates = ({ queries = [], oursPath = null, typed = null, cross = false, heading = null, titles = [], max = MAX_QUERIES }) => {
+  const out = [];
+  const add = (q) => {
+    const v = String(q ?? '').replace(/\s+/g, ' ').trim();
+    if (v && v.length <= 80 && !out.some((x) => x.toLowerCase() === v.toLowerCase())) out.push(v);
+  };
+  for (const q of queries) add(q);
+  // Our own query: their products' on the same page; on another page of theirs it is ours alone.
+  if (!cross) {
+    add(queryOfPath(oursPath));
+    add(typed);
+  }
+  add(heading);
+  for (const w of frequentWords(titles)) add(w);
+  return out.length ? out.slice(0, max) : [''];
+};
+
+/**
+ * Whether their products' pairing failed on a page: their page showed none
+ * (no ids), our build asked for none of their type, or every request found
+ * none of them (`aligned`: probe.mjs `window.__parity.aligned`). Null when it
+ * paired (some products unpaired are the data's: not in the catalog).
+ * @param {string[] | null} ids their ids (null: the page pairs nothing)
+ * @param {{ asked: number, found: number, endpoint: string, queries?: { endpoint: string, query: string | null, asked: number, found: number }[] }[]} aligned
+ * @param {{ selector?: string, type?: string }} [o]
+ * @returns {{ why: string, queries: { endpoint: string, query: string | null, asked: number, found: number }[] } | null}
+ */
+export const pairingFailure = (ids, aligned, o = {}) => {
+  if (ids == null) return null;
+  if (!ids.length) return { why: `no product ids on their page ("${o.selector ?? ''}"): nothing to pair`, queries: [] };
+  if (!aligned.length) return { why: `our page made no request for products of type "${o.type ?? 'product'}": nothing to pair (products.type, or the build's own request failed)`, queries: [] };
+  const best = aligned.reduce((a, b) => (b.found > a.found ? b : a));
+  if (best.found > 0) return null;
+  const queries = best.queries ?? [];
+  const tried = queries.map((q) => (q.query == null ? `${q.endpoint} (no query)` : `"${q.query}"`)).join(', ');
+  return { why: `none of their ${ids.length} products found by the API${tried ? ` (tried ${tried})` : ''}: set pages.<page>.query to a query that finds them, or products.field / products.pair`, queries };
+};
+
+/** The queries tried, as the report shows them: `"lamp" 6/6`, `collections 0/6`. @param {{ endpoint: string, query: string | null, asked: number, found: number }[]} queries */
+export const formatQueries = (queries = []) => queries.map((q) => `${q.query == null ? `${q.endpoint} (by id, no query)` : `"${q.query}"`} ${q.found}/${q.asked}`).join(', ');

package/parity/pixels.mjs

@@ -0,0 +1,33 @@
+// The pixel diff of `yarn luma parity`: a secondary signal next to the property
+// comparison (parity/compare.mjs), never a measurement of a value. Two crops
+// of one component (theirs, ours, PNG from the same DPR and viewport), padded
+// to the same size (the padding counts as differing: a component 4 px taller
+// is 4 px rows of difference), compared with pixelmatch (anti-aliasing
+// ignored), and the diff image.
+import pixelmatch from 'pixelmatch';
+import { PNG } from 'pngjs';
+
+/** Pads a decoded PNG to w x h with a colour no page paints (magenta), top-left aligned. */
+const pad = (png, w, h) => {
+  if (png.width === w && png.height === h) return png.data;
+  const out = Buffer.alloc(w * h * 4);
+  for (let i = 0; i < w * h; i++) out.set([255, 0, 255, 255], i * 4);
+  for (let y = 0; y < png.height; y++) png.data.copy(out, y * w * 4, y * png.width * 4, (y + 1) * png.width * 4);
+  return out;
+};
+
+/**
+ * @param {Buffer} theirs PNG
+ * @param {Buffer} ours PNG
+ * @param {{ threshold?: number }} [opts] pixelmatch's per-pixel colour threshold (0-1)
+ * @returns {{ ratio: number, differing: number, total: number, size: { theirs: string, ours: string }, diff: Buffer }}
+ */
+export const diffPng = (theirs, ours, opts = {}) => {
+  const a = PNG.sync.read(theirs);
+  const b = PNG.sync.read(ours);
+  const w = Math.max(a.width, b.width);
+  const h = Math.max(a.height, b.height);
+  const out = new PNG({ width: w, height: h });
+  const differing = w && h ? pixelmatch(pad(a, w, h), pad(b, w, h), out.data, w, h, { threshold: opts.threshold ?? 0.1, includeAA: false, alpha: 0.2 }) : 0;
+  return { ratio: w * h ? differing / (w * h) : 0, differing, total: w * h, size: { theirs: `${a.width}x${a.height}`, ours: `${b.width}x${b.height}` }, diff: PNG.sync.write(out) };
+};