@pygmalionjs/pygmalion 0.2.44 → 0.5.0

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);
@@ -811,11 +820,35 @@ export async function waitForStableStoryboardDocument(
 /**
  * Serializes the current document into an inert, standalone DOM preview.
  *
- * This function is self-contained because Playwright serializes it into the page.
+ * Accepts either the base href string (the legacy form, byte-identical output)
+ * or `{ baseHref, sourceComponents }`. When `sourceComponents` — a map of
+ * component display name to `{ sourceId }` — is provided, elements that are
+ * the first host DOM of a matching component fiber are stamped with
+ * `data-pygmalion-source-*` attributes and the body receives the
+ * `data-pygmalion-source-stamped="1"` marker (see docs/perf-contracts.md).
+ *
+ * This function is self-contained because Playwright serializes it into the
+ * page: it must reference nothing from module scope. The fiber walk below is
+ * therefore a minimal copy of src/editor/fiberMap.ts rather than an import,
+ * and component matching is by display name because registry function
+ * references never cross into the captured realm.
  */
 export function serializeStoryboardPreviewDocument(
-  baseHref = '__PYGMALION_PREVIEW_BASE__',
+  baseHrefOrOptions = '__PYGMALION_PREVIEW_BASE__',
 ) {
+  const options =
+    typeof baseHrefOrOptions === 'string'
+      ? { baseHref: baseHrefOrOptions }
+      : (baseHrefOrOptions ?? {});
+  const baseHref =
+    typeof options.baseHref === 'string'
+      ? options.baseHref
+      : '__PYGMALION_PREVIEW_BASE__';
+  const sourceComponents =
+    options.sourceComponents && typeof options.sourceComponents === 'object'
+      ? options.sourceComponents
+      : null;
+
   const clone = document.documentElement.cloneNode(true);
   if (!(clone instanceof HTMLElement)) return null;
 
@@ -850,6 +883,162 @@ export function serializeStoryboardPreviewDocument(
     });
   });
 
+  if (sourceComponents) {
+    // Source metadata stamping. This must run before canvas replacement and
+    // script stripping mutate the clone: both element lists are read from the
+    // same still-parallel tree, so index N in the source maps to index N in
+    // the clone (the copyFormState pattern above relies on the same fact).
+    // Stamping is best-effort — a failure must never cost the snapshot.
+    try {
+      const findFiber = (el) => {
+        for (const key in el) {
+          if (key.startsWith('__reactFiber$')) return el[key];
+        }
+        return null;
+      };
+      // Strip React.memo (.type) and forwardRef (.render) wrappers, exactly
+      // as src/editor/fiberMap.ts unwrapType does.
+      const unwrapFiberType = (type) => {
+        let current = type;
+        while (current && typeof current === 'object') {
+          const next = current.type ?? current.render;
+          if (next == null) break;
+          current = next;
+        }
+        return current;
+      };
+      // First host DOM of a component fiber — the instance-root criterion
+      // (firstHostElement in src/editor/fiberMap.ts).
+      const firstHostElement = (from) => {
+        let fiber = from.child;
+        while (fiber) {
+          const stateNode = fiber.stateNode;
+          if (stateNode && stateNode.nodeType === 1) return stateNode;
+          if (fiber.child) {
+            fiber = fiber.child;
+            continue;
+          }
+          let node = fiber;
+          while (node && node !== from && !node.sibling) node = node.return;
+          fiber = node && node !== from ? node.sibling : null;
+        }
+        return null;
+      };
+      const resolveInstance = (el) => {
+        let hit = null;
+        let hitName = '';
+        for (let fiber = findFiber(el); fiber; fiber = fiber.return) {
+          const type = fiber.type;
+          if (type == null || typeof type === 'string') continue;
+          const unwrapped = unwrapFiberType(type);
+          if (typeof unwrapped !== 'function') continue;
+          const name = unwrapped.displayName ?? unwrapped.name;
+          if (!name || !sourceComponents[name]) continue;
+          // Walk the full return chain so the outermost registered boundary
+          // wins when nested matches share a root DOM.
+          if (firstHostElement(fiber) === el) {
+            hit = fiber;
+            hitName = name;
+          }
+        }
+        if (!hit) return null;
+        const props = {};
+        let childrenText = '';
+        for (const [key, value] of Object.entries(hit.memoizedProps ?? {})) {
+          if (key === 'children') {
+            if (typeof value === 'string') childrenText = value;
+            continue;
+          }
+          if (
+            typeof value === 'string' ||
+            typeof value === 'number' ||
+            typeof value === 'boolean'
+          ) {
+            props[key] = value;
+          }
+        }
+        return {
+          name: hitName,
+          sourceId: sourceComponents[hitName].sourceId ?? hitName,
+          props,
+          childrenText,
+        };
+      };
+      // CSS-module source map of the captured realm, injected by the inspect
+      // plugin (mirrors sourceTargetOf in src/editor/inspect.ts).
+      const styleByScopedClass = new Map();
+      for (const registration of window.__PYG_CSS_MODULES__ ?? []) {
+        for (const [localName, scoped] of Object.entries(
+          registration.classes ?? {},
+        )) {
+          if (typeof scoped === 'string' && !styleByScopedClass.has(scoped)) {
+            styleByScopedClass.set(
+              scoped,
+              `${registration.file}#${localName}`,
+            );
+          }
+        }
+      }
+      const resolveStyle = (el) => {
+        for (const cls of el.classList) {
+          const styleSource = styleByScopedClass.get(cls);
+          if (styleSource) return styleSource;
+        }
+        return null;
+      };
+      const sourceElements = document.documentElement.querySelectorAll('*');
+      const cloneElements = clone.querySelectorAll('*');
+      const total = Math.min(sourceElements.length, cloneElements.length);
+      for (let index = 0; index < total; index += 1) {
+        // One element failing to resolve must never break serialization.
+        try {
+          const sourceElement = sourceElements[index];
+          const cloneElement = cloneElements[index];
+          const hit = resolveInstance(sourceElement);
+          if (hit) {
+            cloneElement.setAttribute(
+              'data-pygmalion-source-component',
+              hit.sourceId,
+            );
+            cloneElement.setAttribute(
+              'data-pygmalion-source-component-name',
+              hit.name,
+            );
+            const propsJson = JSON.stringify(hit.props);
+            // Values above a cap are omitted, never truncated mid-JSON.
+            if (propsJson.length <= 8 * 1024) {
+              cloneElement.setAttribute(
+                'data-pygmalion-source-props',
+                propsJson,
+              );
+            }
+            if (hit.childrenText && hit.childrenText.length <= 2 * 1024) {
+              cloneElement.setAttribute(
+                'data-pygmalion-source-children',
+                hit.childrenText,
+              );
+            }
+          }
+          const styleSource = resolveStyle(sourceElement);
+          if (styleSource) {
+            cloneElement.setAttribute(
+              'data-pygmalion-source-style',
+              styleSource,
+            );
+          }
+        } catch {
+          // Skip the element; stamping is additive metadata.
+        }
+      }
+      const cloneBody = clone.querySelector('body');
+      if (cloneBody) {
+        cloneBody.setAttribute('data-pygmalion-source-stamped', '1');
+      }
+    } catch {
+      // An unstamped snapshot is still a valid snapshot.
+    }
+  }
+
   const sourceCanvases = [...document.querySelectorAll('canvas')];
   const cloneCanvases = [...clone.querySelectorAll('canvas')];
   sourceCanvases.forEach((source, index) => {
@@ -940,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,
@@ -947,7 +1144,9 @@ async function collectStableEvidence(
     includeDomTree,
     includePreviewSnapshot,
     previewBaseToken,
+    sourceComponents = null,
     screenshotOptions,
+    screenshotScale = STORYBOARD_CAPTURE_SCREENSHOT_SCALE,
     stability = {},
   },
 ) {
@@ -975,7 +1174,9 @@ async function collectStableEvidence(
     try {
       const snapshot = await page.evaluate(
         serializeStoryboardPreviewDocument,
-        previewBaseToken,
+        sourceComponents
+          ? { baseHref: previewBaseToken, sourceComponents }
+          : previewBaseToken,
       );
       if (
         typeof snapshot !== 'string' ||
@@ -989,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,
       }),
     };
@@ -1061,6 +1265,7 @@ export async function captureStoryboardCase({
   includeDomTree = true,
   includePreviewSnapshot = true,
   previewBaseToken = '__PYGMALION_PREVIEW_BASE__',
+  sourceComponents = null,
   contextOptions = {},
   navigationOptions = {},
   screenshotOptions = {},
@@ -1107,6 +1312,7 @@ export async function captureStoryboardCase({
       context = await atCaptureStage('setup', () =>
         browser.newContext({
           viewport,
+          deviceScaleFactor: resolveScreenshotScale(contextOptions),
           colorScheme: 'light',
           reducedMotion: 'reduce',
           locale: 'en-US',
@@ -1210,7 +1416,9 @@ export async function captureStoryboardCase({
       includeDomTree,
       includePreviewSnapshot,
       previewBaseToken,
+      sourceComponents,
       screenshotOptions,
+      screenshotScale: resolveScreenshotScale(contextOptions),
       stability,
     });
     evidence = collected.evidence;