@pygmalionjs/pygmalion 0.4.0 → 0.5.0

package/node/route-dependency-digest.mjs

@@ -1,3 +1,7 @@
+import { createHash } from 'node:crypto';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
 function normalizedRoutePath(value) {
   if (typeof value !== 'string' || !value.trim()) return null;
   try {
@@ -60,3 +64,150 @@ export function resolvePreviewRouteDependencyDigest(route, entries) {
   );
   return candidates[0]?.digest;
 }
+
+// Observed dependencies — the source files a captured frame actually rendered.
+//
+// Freshness used to be decided by the source revision, so every commit retired
+// every frame even when a frame's own content could not have changed. A route
+// digest is not a usable replacement in a single-page application: nearly every
+// screen lives on one or two routes, so a route's dependency closure is the
+// whole application and any edit invalidates everything.
+//
+// A frozen snapshot stamps the file each element came from, so the set of files
+// a screen really rendered is recoverable from the capture itself. That set is
+// finer than a route and cannot drift from the truth, because it is an
+// observation rather than a declaration.
+
+/** Attributes the DOM importer stamps a source file onto. */
+const SOURCE_ATTRIBUTES = ['data-pygmalion-source', 'data-pygmalion-own-source'];
+
+/**
+ * Minimum stamped elements before an observed set is trusted.
+ *
+ * A frame whose stamps are missing (a host that never wired sourceComponents,
+ * or a capture that failed early) would otherwise read as "depends on nothing"
+ * and never be invalidated again. Too few stamps therefore means unknown, and
+ * unknown must fall back to the coarse key rather than claim precision.
+ */
+export const OBSERVED_DEPENDENCY_MIN_STAMPS = 8;
+
+/** Files whose content decides a screen without ever being stamped. */
+const DEFAULT_ALWAYS_INCLUDED = Object.freeze([]);
+
+function normalizedSourcePath(value) {
+  if (typeof value !== 'string') return null;
+  // A stamp is "<file>|<hash>|<tag>"; only the file participates in identity.
+  const file = value.split('|', 1)[0].trim();
+  if (!file || file.startsWith('/') || file.includes('..')) return null;
+  return file.split(path.sep).join('/');
+}
+
+/**
+ * Source files stamped into a serialized snapshot.
+ *
+ * Parsing the stored HTML rather than collecting in the page keeps the answer
+ * true to what was actually stored: a serializer that prunes or rewrites nodes
+ * cannot make the recorded set disagree with the artifact it describes. It also
+ * means one function serves every producer, since all of them publish HTML.
+ */
+export function extractObservedSourceFiles(snapshot) {
+  // A stored snapshot is `{ document, head, body }`, but callers also hold the
+  // raw body string; accept both so one function serves every producer.
+  const html =
+    typeof snapshot === 'string'
+      ? snapshot
+      : snapshot && typeof snapshot === 'object'
+        ? [snapshot.document, snapshot.head, snapshot.body]
+            .filter((part) => typeof part === 'string')
+            .join('\n')
+        : '';
+  if (!html) {
+    return { files: [], stamps: 0 };
+  }
+  const files = new Set();
+  let stamps = 0;
+  for (const attribute of SOURCE_ATTRIBUTES) {
+    const pattern = new RegExp(`${attribute}="([^"]*)"`, 'g');
+    for (const match of html.matchAll(pattern)) {
+      stamps += 1;
+      const file = normalizedSourcePath(match[1]);
+      if (file) files.add(file);
+    }
+  }
+  return { files: [...files].sort(), stamps };
+}
+
+async function fileContentHash(root, file) {
+  try {
+    const resolved = path.resolve(root, file);
+    if (!resolved.startsWith(path.resolve(root) + path.sep)) return null;
+    const source = await fs.readFile(resolved);
+    return createHash('sha256').update(source).digest('hex').slice(0, 32);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Records the observed set as `[path, contentHash]` pairs.
+ *
+ * Pairs rather than one digest: freshness is then a comparison against the
+ * files as they are now, so recording the set never changes the key the entry
+ * was written under. Storing a digest in the key instead would retire the very
+ * entry that just produced it.
+ */
+export async function recordObservedDependencies({
+  snapshot,
+  sourceRoot,
+  alwaysInclude = DEFAULT_ALWAYS_INCLUDED,
+  minStamps = OBSERVED_DEPENDENCY_MIN_STAMPS,
+}) {
+  if (typeof sourceRoot !== 'string' || !sourceRoot) return null;
+  const { files, stamps } = extractObservedSourceFiles(snapshot);
+  if (stamps < minStamps || files.length === 0) return null;
+  const wanted = [
+    ...new Set([
+      ...files,
+      ...alwaysInclude
+        .map((file) => normalizedSourcePath(file))
+        .filter((file) => file != null),
+    ]),
+  ].sort();
+  const recorded = [];
+  for (const file of wanted) {
+    const hash = await fileContentHash(sourceRoot, file);
+    // A stamped file we cannot read leaves the set unverifiable, and an
+    // unverifiable set must not be treated as fresh later.
+    if (hash == null) return null;
+    recorded.push([file, hash]);
+  }
+  return recorded;
+}
+
+/** True when every recorded file still hashes to what it did at capture time. */
+export async function observedDependenciesUnchanged({ recorded, sourceRoot }) {
+  if (!Array.isArray(recorded) || recorded.length === 0) return false;
+  if (typeof sourceRoot !== 'string' || !sourceRoot) return false;
+  for (const pair of recorded) {
+    if (!Array.isArray(pair) || pair.length !== 2) return false;
+    const [file, hash] = pair;
+    if (typeof file !== 'string' || typeof hash !== 'string') return false;
+    const current = await fileContentHash(sourceRoot, file);
+    if (current !== hash) return false;
+  }
+  return true;
+}
+
+/** Normalizes a persisted set, dropping anything malformed. */
+export function normalizeObservedDependencies(value) {
+  if (!Array.isArray(value) || value.length === 0) return null;
+  const pairs = [];
+  for (const pair of value) {
+    if (!Array.isArray(pair) || pair.length !== 2) return null;
+    const file = normalizedSourcePath(pair[0]);
+    const hash = typeof pair[1] === 'string' ? pair[1].trim() : '';
+    if (!file || !hash) return null;
+    pairs.push([file, hash]);
+  }
+  return pairs.sort((left, right) => left[0].localeCompare(right[0]));
+}

package/node/route-preview-artifact-v3.mjs

@@ -652,11 +652,16 @@ export function selectRoutePreviewArtifactFrames(bundle, wanted, options = {}) {
     }
     const fingerprint = isPlainRecord(request) ? request.fingerprint : undefined;
     const frameSourceRevision = frame.sourceRevision ?? bundle.sourceRevision;
-    if (
-      (options.sourceRevision != null &&
-        frameSourceRevision !== options.sourceRevision) ||
-      (fingerprint != null && frame.fingerprint !== fingerprint)
-    ) {
+    // A fingerprint is content identity, so it decides on its own and the
+    // revision stays provenance. Requiring both retired every frame on every
+    // commit, even when the fingerprint proved the frame could not differ.
+    // Without a fingerprint the revision is the only identity available.
+    const staleForRequest =
+      fingerprint != null
+        ? frame.fingerprint !== fingerprint
+        : options.sourceRevision != null &&
+          frameSourceRevision !== options.sourceRevision;
+    if (staleForRequest) {
       stale.push(id);
       if (options.includeStale === true) frames[id] = frame;
       continue;

package/node/source-graph.mjs

@@ -106,6 +106,95 @@ function moduleSpecifiers(source, componentFile) {
   return [...result].sort();
 }
 
+/**
+ * Symbol-level import and re-export facts for one file.
+ *
+ * The dependency graph answers "which files reference this module", which a
+ * barrel turns into "the whole app": every atom is imported by
+ * `components/ui/index.ts`, and everything imports that. Usage has to be
+ * asked about the SYMBOL to mean anything, so this records what each import
+ * actually named and what each barrel passes through.
+ */
+function moduleSymbols(source, componentFile) {
+  const sourceFile = ts.createSourceFile(
+    componentFile,
+    source,
+    ts.ScriptTarget.Latest,
+    true,
+    scriptKind(componentFile),
+  );
+  const imports = [];
+  const reExports = [];
+  const exports = new Set();
+
+  const visit = (node) => {
+    if (ts.isImportDeclaration(node) && ts.isStringLiteralLike(node.moduleSpecifier)) {
+      const clause = node.importClause;
+      const names = new Set();
+      let namespace = false;
+      if (clause?.name) names.add('default');
+      const bindings = clause?.namedBindings;
+      if (bindings && ts.isNamespaceImport(bindings)) namespace = true;
+      if (bindings && ts.isNamedImports(bindings)) {
+        for (const element of bindings.elements) {
+          if (element.isTypeOnly) continue;
+          names.add((element.propertyName ?? element.name).text);
+        }
+      }
+      // A type-only import renders nothing, so it is not usage.
+      if (!clause?.isTypeOnly) {
+        imports.push({
+          specifier: node.moduleSpecifier.text,
+          names: [...names],
+          namespace,
+        });
+      }
+    } else if (ts.isExportDeclaration(node)) {
+      if (node.moduleSpecifier && ts.isStringLiteralLike(node.moduleSpecifier)) {
+        if (node.isTypeOnly) return;
+        const clause = node.exportClause;
+        if (!clause) {
+          reExports.push({ specifier: node.moduleSpecifier.text, star: true, names: [] });
+        } else if (ts.isNamespaceExport(clause)) {
+          reExports.push({ specifier: node.moduleSpecifier.text, star: true, names: [] });
+          exports.add(clause.name.text);
+        } else {
+          const names = [];
+          for (const element of clause.elements) {
+            if (element.isTypeOnly) continue;
+            // The name importers of this barrel will write.
+            names.push(element.name.text);
+            exports.add(element.name.text);
+          }
+          reExports.push({ specifier: node.moduleSpecifier.text, star: false, names });
+        }
+      } else if (node.exportClause && ts.isNamedExports(node.exportClause)) {
+        for (const element of node.exportClause.elements) exports.add(element.name.text);
+      }
+    } else if (
+      (ts.isFunctionDeclaration(node) ||
+        ts.isClassDeclaration(node) ||
+        ts.isInterfaceDeclaration(node) ||
+        ts.isTypeAliasDeclaration(node) ||
+        ts.isEnumDeclaration(node)) &&
+      node.name &&
+      node.modifiers?.some((modifier) => modifier.kind === ts.SyntaxKind.ExportKeyword)
+    ) {
+      exports.add(node.name.text);
+    } else if (
+      ts.isVariableStatement(node) &&
+      node.modifiers?.some((modifier) => modifier.kind === ts.SyntaxKind.ExportKeyword)
+    ) {
+      for (const declaration of node.declarationList.declarations) {
+        if (ts.isIdentifier(declaration.name)) exports.add(declaration.name.text);
+      }
+    }
+    ts.forEachChild(node, visit);
+  };
+  visit(sourceFile);
+  return { imports, reExports, exports: [...exports].sort() };
+}
+
 function resolveModule(importerFile, specifier, sourceDirectory, files) {
   if (
     typeof specifier !== 'string' ||
@@ -189,6 +278,175 @@ export async function buildSourceGraph(root, { sourceDirectory = 'src' } = {}) {
   };
 }
 
+const MAX_BARREL_DEPTH = 6;
+const MAX_USAGE_FILES = 2_000;
+
+/**
+ * Scans the project once for symbol-level usage.
+ *
+ * Shares the shape of buildSourceGraph so the same result can answer both
+ * "what breaks if this changes" (transitive, over files) and "who uses this"
+ * (direct, over symbols).
+ */
+export async function buildSourceUsage(root, { sourceDirectory = 'src' } = {}) {
+  const location = await sourceLocation(root, sourceDirectory);
+  const files = await scanSourceFiles(location.rootPath, location.sourcePath);
+  const fileSet = new Set(files);
+  const symbols = {};
+  const importersByModule = new Map();
+  const reExportersByModule = new Map();
+  const reverseSets = new Map(files.map((file) => [file, new Set()]));
+
+  const parsed = [];
+  for (let offset = 0; offset < files.length; offset += READ_BATCH_SIZE) {
+    parsed.push(
+      ...(await Promise.all(
+        files.slice(offset, offset + READ_BATCH_SIZE).map(async (componentFile) => {
+          const source = await fs.readFile(path.resolve(location.rootPath, componentFile), 'utf8');
+          return [componentFile, moduleSymbols(source, componentFile)];
+        }),
+      )),
+    );
+  }
+
+  const index = (map, key, value) => {
+    const bucket = map.get(key);
+    if (bucket) bucket.push(value);
+    else map.set(key, [value]);
+  };
+
+  for (const [componentFile, facts] of parsed) {
+    const imports = [];
+    const reExports = [];
+    for (const entry of facts.imports) {
+      const module = resolveModule(
+        componentFile,
+        entry.specifier,
+        location.sourceDirectory,
+        fileSet,
+      );
+      if (!module || module === componentFile) continue;
+      const record = { file: componentFile, module, names: entry.names, namespace: entry.namespace };
+      imports.push(record);
+      index(importersByModule, module, record);
+      reverseSets.get(module).add(componentFile);
+    }
+    for (const entry of facts.reExports) {
+      const module = resolveModule(
+        componentFile,
+        entry.specifier,
+        location.sourceDirectory,
+        fileSet,
+      );
+      if (!module || module === componentFile) continue;
+      const record = { file: componentFile, module, star: entry.star, names: entry.names };
+      reExports.push(record);
+      index(reExportersByModule, module, record);
+      reverseSets.get(module).add(componentFile);
+    }
+    symbols[componentFile] = { imports, reExports, exports: facts.exports };
+  }
+
+  const reverseDependencies = {};
+  for (const componentFile of files) {
+    reverseDependencies[componentFile] = [...reverseSets.get(componentFile)].sort();
+  }
+
+  return {
+    sourceDirectory: location.sourceDirectory,
+    files,
+    symbols,
+    reverseDependencies,
+    importersByModule,
+    reExportersByModule,
+  };
+}
+
+/**
+ * Files that use a module's symbols, with barrels made transparent.
+ *
+ * A file that only re-exports is not a user — it is a pass-through, so the
+ * search continues to whoever imported the name from it. An importer counts
+ * when it names one of the symbols that reached that barrel from the target,
+ * or takes the namespace.
+ */
+export function directSourceUsers(usage, targetFile, { maxDepth = MAX_BARREL_DEPTH } = {}) {
+  if (!usage?.symbols || !usage.symbols[targetFile]) {
+    return { users: [], barrels: [] };
+  }
+  const users = new Set();
+  const barrels = new Set();
+  const seen = new Set();
+  // 'star' means every symbol of the target is in play, which is what the
+  // target itself exposes to a direct importer.
+  const queue = [{ module: targetFile, names: 'star', depth: 0 }];
+
+  while (queue.length > 0) {
+    const { module, names, depth } = queue.shift();
+    const key = `${module}::${names === 'star' ? '*' : [...names].sort().join(',')}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
+
+    for (const record of usage.importersByModule.get(module) ?? []) {
+      if (users.size >= MAX_USAGE_FILES) break;
+      const matches =
+        record.namespace ||
+        names === 'star' ||
+        record.names.some((name) => names.has(name));
+      if (matches) users.add(record.file);
+    }
+
+    if (depth >= maxDepth) continue;
+    for (const record of usage.reExportersByModule.get(module) ?? []) {
+      let exposed;
+      if (record.star) {
+        // `export *` forwards the target's own names — not everything the
+        // barrel has. Treating it as "everything" made a file that imported
+        // one atom look like a user of every atom beside it.
+        const moduleExports = usage.symbols[module]?.exports ?? [];
+        if (moduleExports.length === 0) {
+          // Nothing parsed to narrow by (a nested star chain); keep reach
+          // rather than silently dropping users.
+          exposed = names;
+        } else if (names === 'star') {
+          exposed = new Set(moduleExports);
+        } else {
+          exposed = new Set([...names].filter((name) => moduleExports.includes(name)));
+        }
+      } else {
+        exposed =
+          names === 'star'
+            ? new Set(record.names)
+            : new Set(record.names.filter((name) => names.has(name)));
+      }
+      if (exposed !== 'star' && exposed.size === 0) continue;
+      barrels.add(record.file);
+      queue.push({ module: record.file, names: exposed, depth: depth + 1 });
+    }
+  }
+
+  // A pure pass-through is not a user of what it forwards.
+  for (const barrel of barrels) users.delete(barrel);
+  return { users: [...users].sort(), barrels: [...barrels].sort() };
+}
+
+/** Direct users plus the transitive file count, per requested file. */
+export async function findSourceUsage(root, componentFiles, { sourceDirectory = 'src' } = {}) {
+  const usage = await buildSourceUsage(root, { sourceDirectory });
+  const requested = validateComponentFiles(componentFiles, usage.sourceDirectory);
+  const files = new Set(usage.files);
+  const result = {};
+  for (const componentFile of requested) {
+    if (!files.has(componentFile)) continue;
+    const { users, barrels } = directSourceUsers(usage, componentFile);
+    const transitive = collectAffectedSourceFiles(usage, [componentFile]).filter(
+      (file) => file !== componentFile,
+    );
+    result[componentFile] = { direct: users, barrels, transitive: transitive.length };
+  }
+  return result;
+}
+
 function validateComponentFilePath(value, sourceDirectory) {
   if (
     typeof value !== 'string' ||

package/node/storyboard-capture-runtime.mjs

@@ -38,6 +38,15 @@ export const STORYBOARD_CAPTURE_STATUSES = Object.freeze({
   captureError: 'capture-error',
 });
 
+/**
+ * Device pixels captured per CSS pixel. Screenshots are the zoomable canvas
+ * surface, so they are taken above 1:1 — a 1x bitmap reads as a blurry
+ * screenshot on high-density displays the moment the camera zooms in.
+ * Mirrored in the capture recipe identity (`previewBootstrap.ts`) so changing
+ * it retires every previously captured artifact.
+ */
+export const STORYBOARD_CAPTURE_SCREENSHOT_SCALE = 2;
+
 export class StoryboardCaptureStageError extends Error {
   constructor(stage, error, details = {}) {
     const message = error instanceof Error ? error.message : String(error);
@@ -1120,6 +1129,14 @@ function captureDiagnostic(error, viewport) {
   };
 }
 
+/** The context option wins so a caller's override keeps honest metadata. */
+function resolveScreenshotScale(contextOptions = {}) {
+  const scale = contextOptions.deviceScaleFactor;
+  return Number.isFinite(scale) && scale > 0
+    ? scale
+    : STORYBOARD_CAPTURE_SCREENSHOT_SCALE;
+}
+
 async function collectStableEvidence(
   page,
   viewport,
@@ -1129,6 +1146,7 @@ async function collectStableEvidence(
     previewBaseToken,
     sourceComponents = null,
     screenshotOptions,
+    screenshotScale = STORYBOARD_CAPTURE_SCREENSHOT_SCALE,
     stability = {},
   },
 ) {
@@ -1172,15 +1190,18 @@ async function collectStableEvidence(
     }
   }
   try {
+    // Screenshot metadata records the bitmap's pixel dimensions; the frame's
+    // CSS-pixel geometry stays on the capture record's `viewport`.
     evidence.screenshot = {
       mediaType: 'image/png',
-      width: viewport.width,
-      height: viewport.height,
+      width: viewport.width * screenshotScale,
+      height: viewport.height * screenshotScale,
       bytes: await page.screenshot({
         type: 'png',
         fullPage: false,
         animations: 'disabled',
         caret: 'hide',
+        scale: 'device',
         ...screenshotOptions,
       }),
     };
@@ -1291,6 +1312,7 @@ export async function captureStoryboardCase({
       context = await atCaptureStage('setup', () =>
         browser.newContext({
           viewport,
+          deviceScaleFactor: resolveScreenshotScale(contextOptions),
           colorScheme: 'light',
           reducedMotion: 'reduce',
           locale: 'en-US',
@@ -1396,6 +1418,7 @@ export async function captureStoryboardCase({
       previewBaseToken,
       sourceComponents,
       screenshotOptions,
+      screenshotScale: resolveScreenshotScale(contextOptions),
       stability,
     });
     evidence = collected.evidence;