@tractiontactics/tt-fidelity 0.2.1

package/src/styles.mjs

@@ -0,0 +1,356 @@
+import { ALL_PROPS, BUCKET_OF, CHROME_ROLES, DEFAULT_ROLES } from './constants.mjs';
+import { readFileSync } from 'node:fs';
+
+export function loadRoles(path) {
+	if (!path) return DEFAULT_ROLES;
+	let parsed;
+	try {
+		parsed = JSON.parse(readFileSync(path, 'utf8'));
+	} catch (err) {
+		throw new Error(`could not read --roles file "${path}": ${err.message}`);
+	}
+	if (!Array.isArray(parsed) || !parsed.length) {
+		throw new Error('--roles file must be a non-empty JSON array of [role, selectors[], max]');
+	}
+	for (const entry of parsed) {
+		if (!Array.isArray(entry) || typeof entry[0] !== 'string' || !Array.isArray(entry[1])) {
+			throw new Error('each --roles entry must be [role: string, selectors: string[], max?: number]');
+		}
+	}
+	return parsed.map(([role, sels, max]) => [role, sels, Number(max) > 0 ? Number(max) : 1]);
+}
+
+export function filterRolesByScope(roles, scope) {
+	const s = String(scope || 'full').toLowerCase();
+	if ('full' === s) return roles;
+	if ('chrome' === s) {
+		return roles.filter(([role]) => CHROME_ROLES.has(role));
+	}
+	if ('content' === s) {
+		return roles.filter(([role]) => !CHROME_ROLES.has(role));
+	}
+	throw new Error(`unknown --scope "${scope}" (use full, chrome, or content)`);
+}
+
+/* eslint-disable no-undef */
+export function inPageCapture({ props, roles }) {
+	const pick = (sels) => {
+		for (const s of sels) {
+			let n;
+			try {
+				n = document.querySelectorAll(s);
+			} catch (e) {
+				continue;
+			}
+			if (n.length) return [...n];
+		}
+		return [];
+	};
+	const visible = (el) => {
+		if (!el) return false;
+		const cs = getComputedStyle(el);
+		if (cs.visibility === 'hidden' || cs.display === 'none') return false;
+		if (el.offsetParent === null && cs.position !== 'fixed') return false;
+		const r = el.getBoundingClientRect();
+		return r.width > 0 || r.height > 0;
+	};
+	const sel = (el) => {
+		if (!el || el === document.body) return 'body';
+		if (el.id) return `#${el.id}`;
+		const parts = [];
+		let c = el;
+		let i = 0;
+		while (c && c.nodeType === 1 && i < 4) {
+			let n = c.tagName.toLowerCase();
+			if (c.classList && c.classList.length) n += `.${[...c.classList].slice(0, 2).join('.')}`;
+			parts.unshift(n);
+			c = c.parentElement;
+			i += 1;
+		}
+		return parts.join(' > ');
+	};
+	const label = (el) => (el.textContent || '').replace(/\s+/g, ' ').trim().slice(0, 48);
+	const read = (el) => {
+		const cs = getComputedStyle(el);
+		const r = el.getBoundingClientRect();
+		const o = {};
+		for (const p of props) {
+			const v = cs.getPropertyValue(p);
+			if (v) o[p] = String(v).trim();
+		}
+		o._w = `${Math.round(r.width)}px`;
+		o._h = `${Math.round(r.height)}px`;
+		o._x = `${Math.round(r.left)}px`;
+		return o;
+	};
+
+	const nodes = [];
+	const counts = {};
+	for (const [role, sels, max] of roles) {
+		const got = pick(sels).filter(visible);
+		counts[role] = got.length;
+		got.slice(0, max).forEach((el, i) => {
+			nodes.push({
+				key: max > 1 ? `${role}:${i + 1}` : role,
+				role,
+				selector: sel(el),
+				label: label(el),
+				styles: read(el)
+			});
+		});
+	}
+	return { url: location.href, title: document.title, viewport: document.documentElement.clientWidth, counts, nodes };
+}
+/* eslint-enable no-undef */
+
+export { ALL_PROPS };
+
+const pxOf = (v) => {
+	const m = /^(-?[\d.]+)px$/.exec(String(v ?? '').trim());
+	return m ? parseFloat(m[1]) : null;
+};
+
+function normColour(v) {
+	const s = String(v ?? '').trim().toLowerCase();
+	if (!s) return '';
+	if (s === 'transparent' || /^rgba\(\s*0,\s*0,\s*0,\s*0\s*\)$/.test(s.replace(/\s+/g, ' '))) return 'transparent';
+	const hex = /^#([0-9a-f]{3}|[0-9a-f]{6})$/.exec(s);
+	if (hex) {
+		let h = hex[1];
+		if (h.length === 3) h = h[0] + h[0] + h[1] + h[1] + h[2] + h[2];
+		return `rgb(${parseInt(h.slice(0, 2), 16)}, ${parseInt(h.slice(2, 4), 16)}, ${parseInt(h.slice(4, 6), 16)})`;
+	}
+	const m = /^rgba\(([^)]+),\s*1\)$/.exec(s.replace(/\s+/g, ' '));
+	if (m) return `rgb(${m[1].trim()})`;
+	return s.replace(/\s+/g, ' ');
+}
+
+function norm(prop, raw) {
+	const v = String(raw ?? '').trim();
+	if (!v) return '';
+	if (prop === 'color' || /color$/.test(prop)) return normColour(v);
+	if (prop === 'font-family') return v.split(',')[0].replace(/["']/g, '').trim().toLowerCase();
+	if (prop === 'transition-property' || prop === 'animation-name') return v.toLowerCase().replace(/\s+/g, '');
+	return v.replace(/\s+/g, ' ');
+}
+
+function matches(prop, a, b, tol) {
+	const na = norm(prop, a);
+	const nb = norm(prop, b);
+	if (na === nb) return true;
+	const pa = pxOf(na);
+	const pb = pxOf(nb);
+	if (pa !== null && pb !== null) return Math.abs(pa - pb) <= tol;
+	if (prop === 'opacity') {
+		const fa = parseFloat(na);
+		const fb = parseFloat(nb);
+		if (!Number.isNaN(fa) && !Number.isNaN(fb)) return Math.abs(fa - fb) <= 0.01;
+	}
+	if (prop === 'line-height' && (na === 'normal' || nb === 'normal')) return true;
+	return false;
+}
+
+function mergeGapRows(rows) {
+	const r = rows.filter((x) => x.prop === 'row-gap');
+	const c = rows.filter((x) => x.prop === 'column-gap');
+	if (r.length !== 1 || c.length !== 1) return rows;
+	if (r[0].proto !== c[0].proto || r[0].draft !== c[0].draft) return rows;
+	return [
+		{ ...r[0], prop: 'gap' },
+		...rows.filter((x) => x.prop !== 'row-gap' && x.prop !== 'column-gap')
+	];
+}
+
+function collapseGlobalRows(elements, minShared) {
+	const tally = new Map();
+	for (const el of elements) {
+		for (const row of el.rows) {
+			if (row.geometry) continue;
+			const k = `${row.prop}\u0000${row.proto}\u0000${row.draft}`;
+			if (!tally.has(k)) tally.set(k, { row, keys: [] });
+			tally.get(k).keys.push(el.key);
+		}
+	}
+
+	const global = [];
+	const lifted = new Set();
+	for (const [k, { row, keys }] of tally) {
+		if (keys.length < minShared) continue;
+		lifted.add(k);
+		global.push({
+			prop: row.prop,
+			proto: row.proto,
+			draft: row.draft,
+			bucket: row.bucket,
+			count: keys.length,
+			examples: keys.slice(0, 5)
+		});
+	}
+
+	if (!lifted.size) return { elements, global };
+
+	const trimmed = [];
+	for (const el of elements) {
+		const rows = el.rows.filter(
+			(row) => row.geometry || !lifted.has(`${row.prop}\u0000${row.proto}\u0000${row.draft}`)
+		);
+		if (rows.length) trimmed.push({ ...el, rows });
+	}
+	return { elements: trimmed, global };
+}
+
+export function diffStyles(proto, draft, tol, only) {
+	const keep = (bucket) => !only || only.includes(bucket);
+	const idx = (l) => Object.fromEntries(l.map((n) => [n.key, n]));
+	const A = idx(proto.nodes);
+	const B = idx(draft.nodes);
+	const elements = [];
+	const structural = [];
+	const leftEdgeSeen = new Set();
+
+	for (const [key, a] of Object.entries(A)) {
+		const b = B[key];
+		if (!b) {
+			structural.push({
+				kind: 'unmatched',
+				role: a.role,
+				text: `${key}${a.label ? ` ("${a.label}")` : ''} matched on the prototype but not on the draft — either genuinely absent, or the selectors need extending for this build (prototype: ${a.selector})`
+			});
+			continue;
+		}
+		const rows = [];
+		for (const [prop, av] of Object.entries(a.styles)) {
+			if (prop.startsWith('_')) continue;
+			const bv = b.styles[prop];
+			if (bv === undefined) continue;
+			if (matches(prop, av, bv, tol)) continue;
+			const bucket = CHROME_ROLES.has(a.role) ? 'menus' : BUCKET_OF[prop] || 'flow';
+			if (!keep(bucket)) continue;
+			rows.push({ prop, proto: norm(prop, av), draft: norm(prop, bv), bucket });
+		}
+		for (const [g, name] of [['_w', 'rendered width'], ['_h', 'rendered height'], ['_x', 'left edge']]) {
+			const av = a.styles[g];
+			const bv = b.styles[g];
+			if (av === undefined || bv === undefined) continue;
+			if (matches('width', av, bv, Math.max(tol, 2))) continue;
+			if (g === '_x') {
+				if (leftEdgeSeen.has(a.role)) continue;
+				leftEdgeSeen.add(a.role);
+			}
+			const bucket = g === '_x' ? 'alignment' : 'widths';
+			if (!keep(CHROME_ROLES.has(a.role) ? 'menus' : bucket)) continue;
+			rows.push({ prop: name, proto: av, draft: bv, bucket, geometry: true });
+		}
+		if (rows.length) {
+			elements.push({
+				key,
+				role: a.role,
+				label: a.label,
+				protoSelector: a.selector,
+				draftSelector: b.selector,
+				rows: mergeGapRows(rows)
+			});
+		}
+	}
+
+	for (const [key, b] of Object.entries(B)) {
+		if (A[key]) continue;
+		structural.push({
+			kind: 'extra',
+			role: b.role,
+			text: `${key}${b.label ? ` ("${b.label}")` : ''} matched on the draft but not on the prototype — either an addition the prototype lacks, or a selector mismatch (draft: ${b.selector})`
+		});
+	}
+
+	for (const [role, ca] of Object.entries(proto.counts)) {
+		const cb = draft.counts[role];
+		if (typeof cb !== 'number' || ca === cb) continue;
+		structural.push({
+			kind: 'count',
+			role,
+			text: `${role}: prototype has ${ca}, draft has ${cb}${cb < ca ? ` (draft is missing ${ca - cb})` : ` (draft has ${cb - ca} extra)`}`
+		});
+	}
+
+	const { elements: trimmed, global } = collapseGlobalRows(elements, 3);
+	const total = global.length + trimmed.reduce((n, el) => n + el.rows.length, 0);
+
+	return { elements: trimmed, global, structural, total };
+}
+
+export function assessCoverage(proto, draft, roles) {
+	const matched = [];
+	const onlyProto = [];
+	const onlyDraft = [];
+	const absentBoth = [];
+
+	for (const [role] of roles) {
+		const a = (proto.counts[role] || 0) > 0;
+		const b = (draft.counts[role] || 0) > 0;
+		if (a && b) matched.push(role);
+		else if (a) onlyProto.push(role);
+		else if (b) onlyDraft.push(role);
+		else absentBoth.push(role);
+	}
+
+	const comparable = matched.length + onlyProto.length + onlyDraft.length;
+	const ratio = comparable ? matched.length / comparable : 0;
+
+	return {
+		matched,
+		onlyProto,
+		onlyDraft,
+		absentBoth,
+		ratio,
+		unreliable: ratio < 0.5 && onlyProto.length + onlyDraft.length >= 3
+	};
+}
+
+export function renderCoverage(cov) {
+	const pct = Math.round(cov.ratio * 100);
+	const out = [
+		`COVERAGE: ${cov.matched.length}/${cov.matched.length + cov.onlyProto.length + cov.onlyDraft.length} roles matched on both pages (${pct}%).`
+	];
+	if (cov.onlyProto.length) out.push(`  matched on the prototype only: ${cov.onlyProto.join(', ')}`);
+	if (cov.onlyDraft.length) out.push(`  matched on the draft only:     ${cov.onlyDraft.join(', ')}`);
+	if (cov.absentBoth.length) out.push(`  absent from both (not applicable): ${cov.absentBoth.join(', ')}`);
+	return out;
+}
+
+export function renderCoverageFailure(cov, rolesPath) {
+	return [
+		'CANNOT MEASURE RELIABLY — ABORTING RATHER THAN GUESSING',
+		'',
+		...renderCoverage(cov),
+		'',
+		'Most roles matched on only one side. That almost always means the selector',
+		'list does not fit one of these builds — not that the elements are missing.',
+		'Reporting them as "missing" would produce a work plan telling you to rebuild',
+		'parts of a page that are already there, so no plan has been produced.',
+		'',
+		'Fix by supplying a role map for this project:',
+		'',
+		'  1. Inspect the unmatched side and find the real selectors.',
+		'  2. Write a JSON file, e.g. roles.json:',
+		'',
+		'     [',
+		'       ["header",   [".Hdr_a1b2", "header"], 1],',
+		'       ["nav",      [".Nav_c3d4"], 1],',
+		'       ["nav-item", [".Nav_c3d4 a"], 8],',
+		'       ["main",     [".Wrap_g7h8"], 1],',
+		'       ["h1",       [".Ttl_i9j0"], 1],',
+		'       ["button",   [".Cta_k1l2"], 6],',
+		'       ["section",  [".Blk_m3n4"], 8],',
+		'       ["card",     [".Itm_q7r8"], 6],',
+		'       ["footer",   [".Ftr_s9t0"], 1]',
+		'     ]',
+		'',
+		`  3. Re-run with --roles ${rolesPath || 'roles.json'}`,
+		'',
+		'Selectors are tried in order and the first that matches anything wins, so',
+		'you can list the prototype selector and the build selector together in one',
+		'entry and the same role will resolve on both pages.'
+	];
+}
+
+export { pxOf, norm, matches };

package/src/tt-map.mjs

@@ -0,0 +1,17 @@
+/**
+ * Helpers for reading TT layout IDs from captured section metadata.
+ */
+
+export function formatTtTarget(section) {
+	if (!section) return null;
+	const row = section.ttRowId;
+	const blocks = section.ttBlockIds || [];
+	if (!row && !blocks.length) return null;
+	return {
+		row: row || null,
+		blocks,
+		hint: row
+			? `PUT /pages/{id}/layout — target ${row}${blocks.length ? ` / ${blocks.join(', ')}` : ''}`
+			: `blocks: ${blocks.join(', ')}`
+	};
+}