@snolla/data 0.0.0-stage → 1.0.7

package/dist/test/support/render-parity.js

@@ -0,0 +1,262 @@
+// The render-parity harness (task:3824, plan:50 Q7, requirements:66 п.7): the
+// plumbing that decides whether the same engine renders the same bytes from a
+// different DSN.
+//
+// Not a test file and not a runner: capture / normalize / diff / report are pure
+// enough to be unit-tested, and the same functions are what the cutover runbook
+// (task:3828) will wrap in a CLI. Nothing here boots an engine or opens a
+// database — an engine reaches the harness as an origin (a base URL), which is
+// what keeps "run it against any target DSN" true.
+//
+//   const pages = await loadPageSet();
+//   const from = await captureSite({ origin: baseline, pages });
+//   const to = await captureSite({ origin: target, pages });
+//   const diffs = diffSnapshots(from, to);
+//   if (diffs.length) throw new Error(formatReport({ baseline, target, diffs }));
+import { readFile } from 'node:fs/promises';
+/** The fixed capture kinds (plan:50 Q7.1); a page set must match this exactly. */
+export const PAGE_KINDS = [
+    'home',
+    'catalog',
+    'catalog-pagination',
+    'product',
+    'post',
+    'page',
+    'sitemap',
+    'robots',
+    'redirect',
+    'redirect',
+];
+const DEFAULT_PAGE_SET = new URL('../fixtures/render-parity/pages.json', import.meta.url);
+/**
+ * Loads a page set — the shipped fixture by default, or an explicit file (a site
+ * passes its own real URLs, e.g. «Стайер»'s catalog paths, via TEST_RENDER_PAGES).
+ * The set is a fixed denominator: it must match PAGE_KINDS exactly and may not
+ * repeat a name or a path, so a silently shrinking set can never silently weaken
+ * the check.
+ */
+export const loadPageSet = async (source = undefined) => {
+    const raw = source === undefined
+        ? JSON.parse(await readFile(DEFAULT_PAGE_SET, 'utf8'))
+        : typeof source === 'string' || source instanceof URL
+            ? JSON.parse(await readFile(source, 'utf8'))
+            : source;
+    const pages = Array.isArray(raw) ? raw : raw.pages;
+    if (!Array.isArray(pages) || !pages.length)
+        throw new Error('page set: no pages');
+    for (const page of pages) {
+        if (!page || typeof page.name !== 'string' || typeof page.path !== 'string' || typeof page.kind !== 'string') {
+            throw new Error('page set: every page needs { name, kind, path }');
+        }
+        if (!PAGE_KINDS.includes(page.kind))
+            throw new Error(`page set: unknown kind "${page.kind}"`);
+        if (!page.path.startsWith('/') || page.path.startsWith('//') || page.path.includes('..')) {
+            throw new Error(`page set: "${page.name}" path must be an origin-relative path`);
+        }
+    }
+    if (new Set(pages.map((page) => page.name)).size !== pages.length)
+        throw new Error('page set: duplicated name');
+    if (new Set(pages.map((page) => page.path)).size !== pages.length)
+        throw new Error('page set: duplicated path');
+    if (pages.length !== PAGE_KINDS.length || pages.filter((page) => page.kind === 'redirect').length !== 2) {
+        throw new Error(`page set: kinds must be exactly the ${PAGE_KINDS.length} Q7 captures (redirect ×2)`);
+    }
+    for (const kind of PAGE_KINDS) {
+        if (!pages.some((page) => page.kind === kind))
+            throw new Error(`page set: kind "${kind}" is not captured`);
+    }
+    return pages;
+};
+// Cache-busting suffixes the two engines add differently (`?v=`, `?ver=`, `?cb=`,
+// `?t=`, `?_=`) — noise for parity, never content. Matched only as whole query
+// parameter names so `?width=` or `?video=` survive.
+const CACHE_BUST = /([?&])(?:v|ver|cb|t|_)=[^"'&<>#\s]*/g;
+/** Query-string leftovers once the cache-busting parameters are gone (`/a.css?` → `/a.css`). */
+const tidyQuery = (text) => text
+    .replace(/\?&/g, '?')
+    .replace(/&&+/g, '&')
+    .replace(/[?&](?=["'<>\s]|#|$)/g, '');
+/** Drops cache-busting parameters from one URL. */
+export const stripCacheBust = (url) => tidyQuery(url.replace(CACHE_BUST, '$1'));
+const escapeRegExp = (text) => text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+/**
+ * The served origin is noise; a foreign one is content. Boundary-aware, so an
+ * origin that merely prefixes another (`:3000` vs `:30001`) is left alone. An
+ * origin embedded inside a *foreign* URL's query is still relativized — accepted:
+ * it costs a diff excerpt, not a silent pass (the pair of engines is the same
+ * codebase, so a foreign-URL-embedding query is not where parity breaks).
+ */
+const relativizeOrigin = (text, origin) => text.replace(new RegExp(`${escapeRegExp(origin)}(?=[/?#"'<>\s]|$)`, 'g'), '');
+/** HTML tags whose attributes are order-noise; comments, doctype and closing tags are left alone. */
+const TAG = /<(\/?)([a-zA-Z][^\s/>]*)((?:"[^"]*"|'[^']*'|[^>"'])*)>/g;
+const ATTRIBUTE = /([^\s=/>]+)(?:\s*=\s*("[^"]*"|'[^']*'|[^\s>]+))?/g;
+/** Codepoint order, not `localeCompare`: attribute order must not depend on the machine's locale. */
+const byCodepoint = (left, right) => (left < right ? -1 : left > right ? 1 : 0);
+const orderAttributes = (body) => body.replace(TAG, (match, close, tag, attrs) => {
+    if (!attrs.trim())
+        return `<${close}${tag}>`;
+    const selfClosing = /\/\s*$/.test(attrs);
+    const pairs = [];
+    for (const found of attrs.matchAll(ATTRIBUTE))
+        pairs.push(found[2] ? `${found[1]}=${found[2]}` : found[1]);
+    pairs.sort(byCodepoint);
+    return `<${close}${tag} ${pairs.join(' ')}${selfClosing ? '/' : ''}>`;
+});
+const collapseWhitespace = (text) => text
+    .split('\n')
+    .map((line) => line.replace(/[^\S\n]+/g, ' ').trim())
+    .filter((line) => line.length > 0)
+    .join('\n');
+/** Markup segment: URL noise and cache-busting go, whitespace collapses, attributes order (HTML only). */
+const normalizeSegment = (text, { origin, order }) => {
+    let out = origin ? relativizeOrigin(text, origin) : text;
+    out = tidyQuery(out.replace(CACHE_BUST, '$1'));
+    out = collapseWhitespace(out);
+    return order ? orderAttributes(out) : out;
+};
+// Raw-text elements: attribute reordering inside a script body would corrupt code,
+// and whitespace inside pre/textarea is content. Only script/style bodies get the
+// whitespace collapse (the two engines render the same templates, so a difference
+// in inline JS string whitespace is not what parity is about).
+const RAW_ELEMENT = /<(script|style|pre|textarea)\b[^>]*>[\s\S]*?<\/\1\s*>/gi;
+const VERBATIM = new Set(['pre', 'textarea']);
+const normalizeRawElement = (match, tag, { origin, order }) => match.replace(new RegExp(`(<${tag}\\b[^>]*>)([\\s\\S]*)(</${tag}\\s*>)`, 'i'), (whole, open, body, close) => `${normalizeSegment(open, { origin, order })}\n${collapseWhitespace(body)}\n${close}`);
+/**
+ * Normalizes one rendered body for the diff (plan:50 Q7.2): absolute URLs of the
+ * served origin become relative, cache-busting suffixes go, attributes are
+ * ordered, whitespace is collapsed line-wise with blank lines dropped.
+ *
+ * Only markup (HTML/XML) is URL-normalized: robots.txt is content, and a
+ * `Disallow: /a?t=1` line must survive verbatim. XML keeps attribute order —
+ * `xmlns` is not noise.
+ */
+export const normalizeText = (text, { origin, contentType = '' } = {}) => {
+    const base = origin ? origin.replace(/\/+$/, '') : '';
+    const type = String(contentType);
+    const markup = type === '' || /(html|xml)/i.test(type);
+    const order = /html/i.test(type);
+    let out = String(text).replace(/^\uFEFF/, '').replace(/\r\n?/g, '\n');
+    if (!markup)
+        return collapseWhitespace(out);
+    const pieces = [];
+    let cursor = 0;
+    out.replace(RAW_ELEMENT, (match, tag, offset) => {
+        pieces.push(normalizeSegment(out.slice(cursor, offset), { origin: base, order }));
+        pieces.push(VERBATIM.has(tag.toLowerCase())
+            ? match
+            : normalizeRawElement(match, tag, { origin: base, order }));
+        cursor = offset + match.length;
+        return match;
+    });
+    pieces.push(normalizeSegment(out.slice(cursor), { origin: base, order }));
+    return pieces.filter((piece) => piece !== '').join('\n');
+};
+/** `normalizeText` for markup — the common case. */
+export const normalizeHtml = (html, { origin } = {}) => normalizeText(html, { origin, contentType: 'text/html' });
+/** A redirect target is content, but its origin is not: same-origin → relative. */
+const normalizeLocation = (location, origin) => {
+    if (!location)
+        return null;
+    const base = origin.replace(/\/+$/, '');
+    return location.startsWith(base) ? location.slice(base.length) || '/' : location;
+};
+/**
+ * Snapshots a fixed page set from a running engine. Redirects are recorded, not
+ * followed (`redirect: 'manual'`): a 301 whose target drifts is exactly the kind
+ * of regression this harness exists to see. A page that does not answer at all is
+ * recorded with `status: null` and its error — a failed capture must reach the
+ * report, never abort the run without a page name.
+ */
+export const captureSite = async ({ origin, pages = undefined, fetchImpl = fetch, timeoutMs = 30000 }) => {
+    const base = origin.replace(/\/+$/, '');
+    const set = pages ?? (await loadPageSet());
+    const captured = [];
+    for (const page of set) {
+        try {
+            const response = await fetchImpl(`${base}${page.path}`, {
+                redirect: 'manual',
+                signal: AbortSignal.timeout(timeoutMs),
+            });
+            const contentType = response.headers.get('content-type') ?? '';
+            const location = response.headers.get('location');
+            captured.push({
+                name: page.name,
+                kind: page.kind,
+                path: page.path,
+                status: response.status,
+                location: normalizeLocation(location, base),
+                error: null,
+                body: normalizeText(await response.text(), { origin: base, contentType }),
+            });
+        }
+        catch (error) {
+            captured.push({
+                name: page.name,
+                kind: page.kind,
+                path: page.path,
+                status: null,
+                location: null,
+                error: String(error?.message ?? error),
+                body: '',
+            });
+        }
+    }
+    return { origin: base, pages: captured };
+};
+const splitLines = (body) => (body === '' ? [] : body.split('\n'));
+/** First differing lines, capped — the evidence a human reads, not a full dump. */
+const bodyDiff = (baselineBody, targetBody, { max = 3 } = {}) => {
+    const from = splitLines(baselineBody);
+    const to = splitLines(targetBody);
+    const lines = [];
+    const length = Math.max(from.length, to.length);
+    for (let index = 0; index < length && lines.length < max; index++) {
+        if (from[index] === to[index])
+            continue;
+        lines.push(`line ${index + 1}:`, `  - ${from[index] ?? '<missing>'}`, `  + ${to[index] ?? '<missing>'}`);
+    }
+    return lines;
+};
+/**
+ * Compares two captures by page name. Returns mismatches only: `[]` means the
+ * render is identical. Kinds are `diff` (status, redirect target, failure or body
+ * moved), `missing` (baseline page the target did not serve) or `extra`.
+ */
+export const diffSnapshots = (baseline, target) => {
+    const byName = (snapshot) => new Map(snapshot.pages.map((page) => [page.name, page]));
+    const from = byName(baseline);
+    const to = byName(target);
+    const diffs = [];
+    for (const [name, left] of from) {
+        const right = to.get(name);
+        if (!right) {
+            diffs.push({ name, kind: 'missing', path: left.path, lines: [`${left.path}: not served by the target`] });
+            continue;
+        }
+        const lines = [];
+        if (left.status !== right.status)
+            lines.push(`status: ${left.status ?? 'failed'} → ${right.status ?? 'failed'}`);
+        if ((left.error ?? null) !== (right.error ?? null))
+            lines.push(`error: ${left.error ?? '-'} → ${right.error ?? '-'}`);
+        if (left.location !== right.location)
+            lines.push(`location: ${left.location ?? '-'} → ${right.location ?? '-'}`);
+        if (left.body !== right.body)
+            lines.push(...bodyDiff(left.body, right.body));
+        if (lines.length)
+            diffs.push({ name, kind: 'diff', path: left.path, lines });
+    }
+    for (const [name, right] of to) {
+        if (from.has(name))
+            continue;
+        diffs.push({ name, kind: 'extra', path: right.path, lines: [`${right.path}: served only by the target`] });
+    }
+    return diffs;
+};
+/** The report a cutover (task:3828) attaches to its window: pass or the evidence. */
+export const formatReport = ({ baseline, target, diffs }) => {
+    const head = [`render-parity: ${baseline} → ${target}`];
+    if (!diffs.length)
+        return [...head, 'IDENTICAL: every captured page matches after normalization.'].join('\n');
+    const body = diffs.map((diff) => [`### ${diff.name} (${diff.path}) — ${diff.kind}`, ...diff.lines.map((line) => `    ${line}`)]);
+    return [...head, `${diffs.length} page(s) differ from the baseline:`, ...body.flat()].join('\n');
+};

package/package.json

@@ -1,6 +1,51 @@
 {
-  "name": "@snolla/data",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+    "name": "@snolla/data",
+    "type": "module",
+    "version": "1.0.7",
+    "license": "MIT",
+    "dependencies": {
+        "config": "^3.3.3",
+        "kysely": "^0.29"
+    },
+    "gitHead": "5124dc5293ec47420def6a96f80976e1ed3f998a",
+    "scripts": {
+        "build": "tsc -p tsconfig.build.json",
+        "prepare": "yarn build",
+        "test": "node --test test/*.test.js",
+        "owners:audit": "node scripts/owners-audit.mjs",
+        "owners:audit:mssql": "node scripts/owners-audit.mjs --source=mssql --compare",
+        "owners:spec": "node scripts/owner-spec-check.mjs",
+        "canon:audit": "node scripts/canon-audit.mjs"
+    },
+    "exports": {
+        "./audit.ts": "./dist/audit.js",
+        "./dataProvider.js": "./dist/dataProvider.js",
+        "./dataSource.js": "./dist/dataSource.js",
+        "./dbProvider.js": "./dist/dbProvider.js",
+        "./freeze.ts": "./dist/freeze.js",
+        "./guard.ts": "./dist/guard.js",
+        "./insert.ts": "./dist/insert.js",
+        "./singleMode.ts": "./dist/singleMode.js",
+        "./sqliteDialect.js": "./dist/sqliteDialect.js",
+        "./templateDefs.js": "./dist/templateDefs.js",
+        "./schema/index.ts": "./dist/schema/index.js",
+        "./schema/generate.mjs": "./dist/schema/generate.mjs",
+        "./schema/provision.mjs": "./dist/schema/provision.mjs",
+        "./schema/generated/kysely-types": "./dist/schema/generated/kysely-types.js",
+        "./test/support/dialect-stand.js": "./dist/test/support/dialect-stand.js",
+        "./package.json": "./package.json"
+    },
+    "files": [
+        "dist",
+        "!dist/**/*.map"
+    ],
+    "devDependencies": {
+        "typescript": "^5.9.3"
+    },
+    "optionalDependencies": {
+        "mysql2": "^3.24.6",
+        "pg": "^8.23.1",
+        "tarn": "^3.1.2",
+        "tedious": "^9.2.1"
+    }
+}

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.