npm - @pygmalionjs/pygmalion - Versions diffs - 0.2.7 → 0.2.8 - Mend

@pygmalionjs/pygmalion 0.2.7 → 0.2.8

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (11) hide show

package/dist-lib/{App-D_6vGXDa.js → App-XRuc9KYj.js} +6336 -5213
package/dist-lib/pygmalion.js +223 -172
package/dist-lib/style.css +1 -1
package/dist-lib/testing.js +1 -1
package/node/route-preview-artifact-v2.mjs +483 -0
package/node/storyboard-canonical.mjs +410 -0
package/node/storyboard-environment.mjs +1507 -0
package/node/vite.mjs +55 -2
package/package.json +4 -1
package/types.d.ts +88 -3
package/vite.d.ts +262 -0

package/node/storyboard-canonical.mjs ADDED Viewed

@@ -0,0 +1,410 @@
+import { createHash } from 'node:crypto';
+import { availableParallelism, totalmem } from 'node:os';
+export const PYGMALION_STORYBOARD_CANONICAL_CONTROL =
+  '/__pygmalion-storyboard/canonicalize';
+const MAX_SNAPSHOT_BYTES = 12 * 1024 * 1024;
+const AUTO_ID_PATTERN =
+  /(?:_r_[A-Za-z0-9_:-]+|radix-[A-Za-z0-9_:-]+|react-aria-[A-Za-z0-9_:-]+)/g;
+const TRANSIENT_ATTRIBUTE_PATTERN =
+  /\s(?:data-pygmalion-source|data-pygmalion-slot-count|data-vite-dev-id|data-reactid|data-reactroot|nonce)=(?:"[^"]*"|'[^']*')/gi;
+const FROZEN_STYLE_PATTERN =
+  /<style(?:\s[^>]*)?>\s*\*,\*::before,\*::after\{animation:none!important;transition:none!important;caret-color:transparent!important\}html,body\{pointer-events:none!important\}\s*<\/style>/gi;
+function safeSnapshot(snapshot) {
+  if (
+    typeof snapshot !== 'string' ||
+    snapshot.length === 0 ||
+    Buffer.byteLength(snapshot, 'utf8') > MAX_SNAPSHOT_BYTES
+  ) {
+    return false;
+  }
+  return !(
+    /<(?:script|iframe|object|embed)\b/i.test(snapshot) ||
+    /\son[a-z]+\s*=/i.test(snapshot) ||
+    /(?:href|src)\s*=\s*["']?\s*javascript:/i.test(snapshot)
+  );
+}
+function replaceGeneratedIds(snapshot) {
+  const replacements = new Map();
+  let index = 0;
+  return snapshot.replace(AUTO_ID_PATTERN, (value) => {
+    if (!replacements.has(value)) {
+      replacements.set(value, `__pygmalion_auto_id_${index}`);
+      index += 1;
+    }
+    return replacements.get(value);
+  });
+}
+/**
+ * Removes capture-runtime metadata while preserving authored DOM, text, state,
+ * styles, and accessibility attributes.
+ */
+export function normalizeStoryboardSnapshot(snapshot) {
+  if (!safeSnapshot(snapshot)) return null;
+  const normalized = snapshot
+    .replace(/\r\n?/g, '\n')
+    .replace(/<!doctype\s+html>/i, '<!doctype html>')
+    .replace(
+      /<meta[^>]+http-equiv=(?:"Content-Security-Policy"|'Content-Security-Policy')[^>]*>/gi,
+      '',
+    )
+    .replace(/<base(?:\s[^>]*)?>/gi, '')
+    .replace(FROZEN_STYLE_PATTERN, '')
+    .replace(TRANSIENT_ATTRIBUTE_PATTERN, '')
+    .replace(
+      /https?:\/\/(?:localhost|127\.0\.0\.1)(?::\d+)?/gi,
+      'http://__pygmalion_origin__',
+    )
+    .replace(/([?&])__pygmalion_environment=[^"'&\s>]*/gi, '$1')
+    .replace(/\?&/g, '?')
+    .replace(/[?&](?=["'\s>])/g, '')
+    .replace(/>\s+</g, '><')
+    .trim();
+  return replaceGeneratedIds(normalized);
+}
+export function fingerprintStoryboardSnapshot(snapshot) {
+  const normalized = normalizeStoryboardSnapshot(snapshot);
+  if (normalized == null) return null;
+  return createHash('sha256').update(normalized).digest('hex');
+}
+function boundedInteger(value, fallback, minimum, maximum) {
+  const candidate = Number.isFinite(value) ? Math.floor(value) : fallback;
+  return Math.max(minimum, Math.min(maximum, candidate));
+}
+export function recommendedStoryboardExecutionConcurrency(capabilities = {}) {
+  const parallelism = boundedInteger(
+    capabilities.parallelism,
+    availableParallelism(),
+    1,
+    128,
+  );
+  const totalMemoryBytes =
+    Number.isFinite(capabilities.totalMemoryBytes) &&
+    capabilities.totalMemoryBytes > 0
+      ? capabilities.totalMemoryBytes
+      : totalmem();
+  const memoryLanes = Math.max(
+    8,
+    Math.floor(totalMemoryBytes / (512 * 1024 * 1024)),
+  );
+  return Math.min(48, Math.max(8, Math.min(parallelism * 2, memoryLanes)));
+}
+/**
+ * Executes discovered candidates with bounded parallelism.
+ *
+ * The capture adapter owns browser automation. It receives the complete
+ * candidate and an AbortSignal, and returns a frozen DOM snapshot.
+ */
+export async function executeStoryboardCandidates(candidates, capture, options = {}) {
+  if (typeof capture !== 'function') {
+    throw new TypeError('Storyboard candidate execution requires a capture function.');
+  }
+  const queue = [];
+  const seen = new Set();
+  for (const candidate of Array.isArray(candidates) ? candidates : []) {
+    const normalized = normalizedCandidate(candidate);
+    if (!normalized || seen.has(normalized.id)) continue;
+    seen.add(normalized.id);
+    queue.push(candidate);
+  }
+  const concurrency = boundedInteger(
+    options.concurrency,
+    recommendedStoryboardExecutionConcurrency(),
+    1,
+    64,
+  );
+  const timeoutMs = boundedInteger(options.timeoutMs, 30_000, 100, 300_000);
+  const executions = new Array(queue.length);
+  let nextIndex = 0;
+  async function worker() {
+    while (nextIndex < queue.length) {
+      const index = nextIndex;
+      nextIndex += 1;
+      const candidate = queue[index];
+      const controller = new AbortController();
+      let timer;
+      try {
+        const snapshot = await Promise.race([
+          Promise.resolve(
+            capture(candidate, {
+              signal: controller.signal,
+              index,
+              total: queue.length,
+            }),
+          ),
+          new Promise((_, reject) => {
+            timer = setTimeout(() => {
+              controller.abort();
+              reject(
+                new Error(`Candidate capture timed out after ${timeoutMs}ms.`),
+              );
+            }, timeoutMs);
+          }),
+        ]);
+        executions[index] = {
+          candidateId: candidate.id,
+          status: 'captured',
+          snapshot,
+        };
+      } catch (error) {
+        executions[index] = {
+          candidateId: candidate.id,
+          status: 'failed',
+          error: error instanceof Error ? error.message : String(error),
+        };
+      } finally {
+        clearTimeout(timer);
+      }
+    }
+  }
+  await Promise.all(
+    Array.from(
+      { length: Math.min(concurrency, queue.length) },
+      () => worker(),
+    ),
+  );
+  return executions;
+}
+function normalizedCandidate(candidate) {
+  if (
+    !candidate ||
+    typeof candidate !== 'object' ||
+    typeof candidate.id !== 'string' ||
+    !candidate.id.trim() ||
+    typeof candidate.route !== 'string' ||
+    typeof candidate.scenarioId !== 'string'
+  ) {
+    return null;
+  }
+  return {
+    id: candidate.id.trim(),
+    route: candidate.route,
+    scenarioId: candidate.scenarioId,
+    evidenceIds: Array.isArray(candidate.evidenceIds)
+      ? [...new Set(candidate.evidenceIds.filter((id) => typeof id === 'string'))].sort()
+      : [],
+  };
+}
+function warning(code, severity, candidate, message) {
+  return {
+    code,
+    severity,
+    candidateId: candidate.id,
+    route: candidate.route,
+    scenarioId: candidate.scenarioId,
+    evidenceIds: candidate.evidenceIds,
+    message,
+  };
+}
+/**
+ * Collapses captured candidate results into canonical frames.
+ *
+ * The discovered candidate list is authoritative. Unknown execution results
+ * are reported and ignored, while every missing or failed candidate remains
+ * visible in coverage.
+ */
+export function canonicalizeStoryboardExecutions(candidates, executions) {
+  const expected = [];
+  const candidateById = new Map();
+  for (const rawCandidate of Array.isArray(candidates) ? candidates : []) {
+    const candidate = normalizedCandidate(rawCandidate);
+    if (!candidate || candidateById.has(candidate.id)) continue;
+    candidateById.set(candidate.id, candidate);
+    expected.push(candidate);
+  }
+  expected.sort((a, b) => a.id.localeCompare(b.id));
+  const executionByCandidate = new Map();
+  const warnings = [];
+  for (const execution of Array.isArray(executions) ? executions : []) {
+    const candidateId =
+      execution && typeof execution === 'object' && typeof execution.candidateId === 'string'
+        ? execution.candidateId.trim()
+        : '';
+    const candidate = candidateById.get(candidateId);
+    if (!candidate) {
+      if (candidateId) {
+        warnings.push({
+          code: 'unknown-candidate',
+          severity: 'error',
+          candidateId,
+          route: '',
+          scenarioId: '',
+          evidenceIds: [],
+          message: 'Execution result does not match a discovered candidate.',
+        });
+      }
+      continue;
+    }
+    if (executionByCandidate.has(candidateId)) {
+      warnings.push(
+        warning(
+          'duplicate-execution',
+          'error',
+          candidate,
+          'Multiple execution results were submitted for one candidate.',
+        ),
+      );
+      continue;
+    }
+    executionByCandidate.set(candidateId, execution);
+  }
+  const captured = [];
+  let failed = 0;
+  let missing = 0;
+  for (const candidate of expected) {
+    const execution = executionByCandidate.get(candidate.id);
+    if (!execution) {
+      missing += 1;
+      warnings.push(
+        warning(
+          'missing-execution',
+          'error',
+          candidate,
+          'Discovered candidate was not executed.',
+        ),
+      );
+      continue;
+    }
+    if (execution.status !== 'captured') {
+      failed += 1;
+      warnings.push(
+        warning(
+          'capture-failed',
+          'error',
+          candidate,
+          typeof execution.error === 'string' && execution.error.trim()
+            ? execution.error.trim()
+            : 'Candidate capture failed.',
+        ),
+      );
+      continue;
+    }
+    const normalizedSnapshot = normalizeStoryboardSnapshot(execution.snapshot);
+    if (normalizedSnapshot == null) {
+      failed += 1;
+      warnings.push(
+        warning(
+          'invalid-snapshot',
+          'error',
+          candidate,
+          'Candidate returned an empty, oversized, or unsafe snapshot.',
+        ),
+      );
+      continue;
+    }
+    const fingerprint = createHash('sha256')
+      .update(normalizedSnapshot)
+      .digest('hex');
+    captured.push({
+      candidate,
+      fingerprint,
+      snapshot: normalizedSnapshot,
+    });
+  }
+  const baselineByRoute = new Map();
+  for (const item of captured) {
+    if (item.candidate.scenarioId === 'environment:baseline') {
+      baselineByRoute.set(item.candidate.route, item.fingerprint);
+    }
+  }
+  let unreproduced = 0;
+  for (const item of captured) {
+    if (item.candidate.scenarioId === 'environment:baseline') continue;
+    const baseline = baselineByRoute.get(item.candidate.route);
+    if (baseline && baseline === item.fingerprint) {
+      unreproduced += 1;
+      warnings.push(
+        warning(
+          'branch-not-observed',
+          'warning',
+          item.candidate,
+          'Captured branch matched the route baseline and produced no distinct DOM state.',
+        ),
+      );
+    }
+  }
+  const framesByFingerprint = new Map();
+  const aliases = {};
+  for (const item of captured) {
+    let frame = framesByFingerprint.get(item.fingerprint);
+    if (!frame) {
+      frame = {
+        id: `frame:${item.fingerprint.slice(0, 16)}`,
+        fingerprint: item.fingerprint,
+        snapshot: item.snapshot,
+        candidateIds: [],
+        routes: new Set(),
+        scenarioIds: new Set(),
+        evidenceIds: new Set(),
+      };
+      framesByFingerprint.set(item.fingerprint, frame);
+    }
+    frame.candidateIds.push(item.candidate.id);
+    frame.routes.add(item.candidate.route);
+    frame.scenarioIds.add(item.candidate.scenarioId);
+    for (const evidenceId of item.candidate.evidenceIds) {
+      frame.evidenceIds.add(evidenceId);
+    }
+    aliases[item.candidate.id] = frame.id;
+  }
+  const frames = [...framesByFingerprint.values()]
+    .map((frame) => ({
+      id: frame.id,
+      fingerprint: frame.fingerprint,
+      snapshot: frame.snapshot,
+      candidateIds: frame.candidateIds.sort(),
+      routes: [...frame.routes].sort(),
+      scenarioIds: [...frame.scenarioIds].sort(),
+      evidenceIds: [...frame.evidenceIds].sort(),
+    }))
+    .sort((a, b) => a.id.localeCompare(b.id));
+  const sortedAliases = Object.fromEntries(
+    Object.entries(aliases).sort(([a], [b]) => a.localeCompare(b)),
+  );
+  warnings.sort((a, b) =>
+    `${a.candidateId}:${a.code}`.localeCompare(`${b.candidateId}:${b.code}`),
+  );
+  const capturedCount = captured.length;
+  const duplicates = Math.max(0, capturedCount - frames.length);
+  return {
+    version: 1,
+    frames,
+    aliases: sortedAliases,
+    warnings,
+    coverage: {
+      expected: expected.length,
+      executed: expected.length - missing,
+      captured: capturedCount,
+      canonical: frames.length,
+      duplicates,
+      failed,
+      missing,
+      unreproduced,
+      complete:
+        failed === 0 &&
+        missing === 0 &&
+        unreproduced === 0 &&
+        !warnings.some((item) => item.severity === 'error'),
+    },
+  };
+}