@percy/cli-command 1.32.0-beta.5 → 1.32.0-beta.7

package/dist/graphTrace.js

@@ -0,0 +1,157 @@
+import fs from 'fs';
+import path from 'path';
+import url from 'url';
+
+// Template resolution mirrors core/utils.js's secretPatterns.yml lookup:
+// resolves relative to this file's URL so it works under src/ (dev) and
+// dist/ (installed) without bundler help. The .html file is copied alongside
+// by babel's copyFiles when cli-command is built.
+const TEMPLATE_PATH = path.resolve(url.fileURLToPath(import.meta.url), '../graphTraceTemplate.html');
+
+// Maps a (raw kind, changed) pair to the kind value the template expects:
+// 'package' | 'component' | 'story' | 'is_relevant'. `changed: true` wins
+// over the underlying kind so any node touched in the diff renders purple.
+function templateKindOf(v) {
+  if (v.changed) return 'is_relevant';
+  switch (v.kind) {
+    case 'dependency':
+      return 'package';
+    case 'component':
+      return 'component';
+    case 'story':
+      return 'story';
+    default:
+      return 'component';
+  }
+}
+
+// Sort order within a column: packages left, components middle, stories right.
+// `is_relevant` shares rank with components so a changed node doesn't jump
+// out of its own group — it just recolors.
+const KIND_RANK = {
+  package: 0,
+  component: 1,
+  is_relevant: 1,
+  story: 2
+};
+
+// Layout algorithm (ported from the original Ruby renderer):
+//   1. col = longest-path depth reaching the vertex (read from the
+//      transitive-closure triples the API sends), with dependencies pinned
+//      to col 0.
+//   2. Propagate over edges so col[target] > col[source]. Bounded loop
+//      guards against degenerate inputs.
+//   3. Stories pushed past the rightmost non-story column.
+//   4. Within each column, sort by (kind-rank, name) and assign row.
+function computeLayout(rawVertices, edges, transitiveClosure) {
+  const n = rawVertices.length;
+  const vertices = rawVertices.map((v, i) => ({
+    index: i,
+    name: v.file_path,
+    kind: v.kind,
+    changed: !!v.changed,
+    row: 0,
+    col: 0
+  }));
+
+  // 1. Seed col from incoming transitive-closure lengths.
+  const incomingMax = new Array(n).fill(0);
+  for (const triple of transitiveClosure) {
+    const [u, v, val] = triple;
+    if (u === v || val <= 0) continue;
+    if (v < 0 || v >= n) continue;
+    if (val > incomingMax[v]) incomingMax[v] = val;
+  }
+  for (let i = 0; i < n; i++) {
+    vertices[i].col = vertices[i].kind === 'dependency' ? 0 : incomingMax[i] + 1;
+  }
+
+  // 2. Propagate edge constraint. n+2 iterations is enough for any DAG
+  // and bounds the work on accidentally-cyclic input.
+  const iterations = n + 2;
+  for (let iter = 0; iter < iterations; iter++) {
+    let changed = false;
+    for (const [s, t] of edges) {
+      if (s < 0 || s >= n || t < 0 || t >= n) continue;
+      if (vertices[s].col < vertices[t].col) continue;
+      vertices[t].col = vertices[s].col + 1;
+      changed = true;
+    }
+    if (!changed) break;
+  }
+
+  // 3. Stories rightmost. Two passes: max across non-stories first, then
+  // push every story past that boundary. Folding into one loop would let
+  // stories visited before the last non-story keep a stale max.
+  let furthestNonStory = 0;
+  for (const v of vertices) {
+    if (v.kind === 'story') continue;
+    if (v.col > furthestNonStory) furthestNonStory = v.col;
+  }
+  for (const v of vertices) {
+    if (v.kind !== 'story') continue;
+    if (v.col < furthestNonStory + 1) v.col = furthestNonStory + 1;
+  }
+
+  // 4. Group by column, sort by (kind-rank, name), assign row.
+  const groups = new Map();
+  for (const v of vertices) {
+    let list = groups.get(v.col);
+    if (!list) groups.set(v.col, list = []);
+    list.push(v);
+  }
+  const rankOf = v => {
+    const r = KIND_RANK[templateKindOf(v)];
+    /* istanbul ignore next: templateKindOf always returns a kind present in
+       KIND_RANK, so the `=== undefined` fallback is defensive */
+    return r === undefined ? 99 : r;
+  };
+  for (const list of groups.values()) {
+    list.sort((a, b) => {
+      const ra = rankOf(a);
+      const rb = rankOf(b);
+      if (ra !== rb) return ra - rb;
+      // Byte-wise compare on name to match Ruby's String#<=> behaviour.
+      if (a.name < b.name) return -1;
+      if (a.name > b.name) return 1;
+      return 0;
+    });
+    list.forEach((v, row) => {
+      v.row = row;
+    });
+  }
+
+  // 5. Final shape the template consumes: drop `changed`, fold it into kind.
+  return vertices.map(v => ({
+    index: v.index,
+    name: v.name,
+    row: v.row,
+    col: v.col,
+    kind: templateKindOf(v)
+  }));
+}
+
+// Escapes characters that have meaning inside a <script> block so user-derived
+// strings (e.g. a vertex file_path) can't break out of the surrounding tag.
+// `</` covers `</script>`; `<!--`/`-->` cover HTML comment confusion; U+2028
+// and U+2029 are valid JSON but illegal in JS string literals pre-ES2019 and
+// have historically been XSS sinks.
+const LS = String.fromCharCode(0x2028);
+const PS = String.fromCharCode(0x2029);
+function safeJson(obj) {
+  return JSON.stringify(obj).replace(/<\//g, '<\\/').replace(/<!--/g, '<\\!--').replace(/--(!?)>/g, '--$1\\>').split(LS).join('\\u2028').split(PS).join('\\u2029');
+}
+
+// Populates the trace template with the three JSON payloads the page needs.
+// Input shape matches the API's graph data: `vertices` carries `kind`,
+// `file_path`, `changed`; `edges` and `transitive_closure_matrix_sparse`
+// are arrays of integer tuples.
+export function renderGraphTraceHtml({
+  vertices,
+  edges,
+  transitiveClosureMatrixSparse
+}) {
+  const laidOutVertices = computeLayout(vertices || [], edges || [], transitiveClosureMatrixSparse || []);
+  const template = fs.readFileSync(TEMPLATE_PATH, 'utf8');
+  return template.replace('__VERTICES_JSON__', safeJson(laidOutVertices)).replace('__EDGES_JSON__', safeJson(edges || [])).replace('__TRANSITIVE_CLOSURE_JSON__', safeJson(transitiveClosureMatrixSparse || []));
+}

package/dist/graphTraceTemplate.html

@@ -0,0 +1,349 @@
+<!DOCTYPE html>
+<html>
+<head>
+    <meta charset="utf-8">
+    <title>Smartsnap Graph</title>
+    <link
+        rel="stylesheet"
+        href="https://cdn.jsdelivr.net/npm/drawflow@0.0.60/dist/drawflow.min.css"
+        integrity="sha384-IFh+Q6zh+LRcTjqVmAKetdGY59dT485vtvWT5DAKQy8iv5+fYWHXisHP7mFKcFqV"
+        crossorigin="anonymous">
+    <script
+        src="https://cdn.jsdelivr.net/npm/drawflow@0.0.60/dist/drawflow.min.js"
+        integrity="sha384-JsnM4f1X8b5e9VbQCj6Bt6840HQNDYVKohzbXJnqOetMno8i6cmKNLVkyK3snqSw"
+        crossorigin="anonymous"></script>
+    <style>
+        html, body {
+            margin: 0; padding: 0;
+            font-family: sans-serif; background: #fafafa;
+            width: 100%; height: 100%; overflow: hidden;
+        }
+        #drawflow {
+            position: fixed;
+            top: 0; left: 0; right: 0; bottom: 0;
+            background: #fafafa;
+        }
+        #legend {
+            position: fixed; top: 8px; right: 8px;
+            background: rgba(255,255,255,0.95);
+            padding: 8px 12px; border: 1px solid #999;
+            font-size: 12px; z-index: 100;
+        }
+        #legend span {
+            display: inline-block; width: 12px; height: 12px;
+            vertical-align: middle; margin-right: 4px; border: 1px solid #333;
+        }
+        #controls {
+            position: fixed; top: 8px; left: 8px;
+            background: rgba(255,255,255,0.95);
+            border: 1px solid #999; z-index: 100;
+            display: flex; gap: 2px;
+        }
+        #controls button {
+            border: 0; background: transparent;
+            padding: 6px 10px; cursor: pointer;
+            font-size: 14px; font-family: inherit;
+        }
+        #controls button:hover { background: #eee; }
+
+        .drawflow .drawflow-node {
+            width: max-content;
+            min-width: 0; max-width: none;
+            height: auto; min-height: 0;
+            padding: 8px 14px;
+            white-space: nowrap;
+            font-size: 12px;
+            font-family: ui-monospace, SFMono-Regular, Menlo, monospace;
+            background: #fff;
+            border: 2px solid #333;
+            border-radius: 4px;
+            cursor: pointer;
+            transition: opacity 150ms;
+        }
+        .drawflow .drawflow-node .drawflow_content_node {
+            width: max-content;
+            white-space: nowrap;
+        }
+        .drawflow .drawflow-node.package    { background: #d4e5f7; border-color: #2a6db5; }
+        .drawflow .drawflow-node.component  { background: #daf0c1; border-color: #4a8e1f; }
+        .drawflow .drawflow-node.story      { background: #fce4b6; border-color: #b07310; }
+        .drawflow .drawflow-node.is-relevant { background: #d9b3ff; border-color: #6f30b0; }
+
+        .drawflow .drawflow-node .input,
+        .drawflow .drawflow-node .output {
+            width: 10px !important;
+            height: 10px !important;
+            border-width: 1px !important;
+        }
+
+        .drawflow .connection,
+        .drawflow .connection *,
+        .drawflow svg.connection,
+        .drawflow svg.connection * { pointer-events: none !important; }
+
+        .drawflow .drawflow-node.is-dim { opacity: 0.25; }
+        .drawflow .connection.is-dim { visibility: hidden; }
+
+        .drawflow .drawflow-node.is-selected {
+            box-shadow: 0 0 0 3px #2a6db5, 0 2px 8px rgba(0,0,0,0.2);
+        }
+
+        .measure-node {
+            position: absolute;
+            top: -9999px; left: -9999px;
+            opacity: 0;
+            pointer-events: none;
+            white-space: nowrap;
+            padding: 8px 14px;
+            font-size: 12px;
+            font-family: ui-monospace, SFMono-Regular, Menlo, monospace;
+            border: 2px solid transparent;
+        }
+    </style>
+</head>
+<body>
+<div id="controls">
+    <button id="zoom-in" title="Zoom in">+</button>
+    <button id="zoom-out" title="Zoom out">-</button>
+    <button id="zoom-reset" title="Reset">reset</button>
+</div>
+<div id="legend">
+    <div><span style="background:#d4e5f7"></span>Package Dependency</div>
+    <div><span style="background:#daf0c1"></span>Component</div>
+    <div><span style="background:#fce4b6"></span>Story</div>
+    <div><span style="background:#d9b3ff"></span>Changed file</div>
+</div>
+<div id="drawflow"></div>
+<script type="module">
+// ---------------------------------------------------------------------------
+// Payload populated by the CLI before this template is written to disk.
+// Tokens are replaced by graphTrace.js via plain string substitution.
+//   vertices:                         [{ index, name, row, col, kind }, ...]
+//   edges:                            [[srcIndex, tgtIndex], ...]
+//   transitive_closure_matrix_sparse: [[srcIndex, tgtIndex, length], ...]
+// `kind` is one of: 'package' | 'component' | 'story' | 'is_relevant'.
+// ---------------------------------------------------------------------------
+const vertices = __VERTICES_JSON__;
+const edges = __EDGES_JSON__;
+const transitive_closure_matrix_sparse = __TRANSITIVE_CLOSURE_JSON__;
+const n = vertices.length;
+
+// ---------------------------------------------------------------------------
+// Width measurement: each node grows to fit its file path. We need the
+// rendered width (DOM-dependent) to lay out columns without overlap.
+// ---------------------------------------------------------------------------
+function measureWidth(text) {
+    const el = document.createElement('div');
+    el.className = 'measure-node';
+    el.textContent = text;
+    document.body.appendChild(el);
+    const w = el.offsetWidth;
+    el.remove();
+    return w;
+}
+
+// Drawflow adds port circles on each side (~25px) + border; pad generously.
+const PORT_PAD = 60;
+const nodeWidth = vertices.map(v => measureWidth(v.name) + PORT_PAD);
+
+// ---------------------------------------------------------------------------
+// Column X positions (cumulative by max width per column).
+// ---------------------------------------------------------------------------
+const PAD_X = 60, PAD_Y = 60, COL_GAP = 140, ROW_HEIGHT = 70;
+
+const colMaxWidth = {};
+for (let i = 0; i < n; i++) {
+    const c = vertices[i].col;
+    if (!colMaxWidth[c] || nodeWidth[i] > colMaxWidth[c]) colMaxWidth[c] = nodeWidth[i];
+}
+const sortedCols = Object.keys(colMaxWidth).map(Number).sort((a, b) => a - b);
+const colX = {};
+let cursor = PAD_X;
+for (const c of sortedCols) {
+    colX[c] = cursor;
+    cursor += colMaxWidth[c] + COL_GAP;
+}
+
+// ---------------------------------------------------------------------------
+// Boot Drawflow.
+// ---------------------------------------------------------------------------
+const container = document.getElementById('drawflow');
+const editor = new Drawflow(container);
+editor.reroute = false;
+editor.start();
+
+function escapeHtml(s) {
+    return String(s)
+        .replace(/&/g, '&amp;')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;')
+        .replace(/'/g, '&#39;');
+}
+
+// CSS classes per kind. `is_relevant` becomes `is-relevant` so it matches
+// the stylesheet rule.
+function cssClassFor(kind) {
+    if (kind === 'is_relevant') return 'is-relevant';
+    return kind;
+}
+
+// ---------------------------------------------------------------------------
+// Add nodes. row/col come from the server; pixel positions are computed
+// here using the measured widths so columns never overlap.
+// ---------------------------------------------------------------------------
+const nodeIds = new Array(n);
+for (let i = 0; i < n; i++) {
+    const v = vertices[i];
+    const id = editor.addNode(
+        'node',
+        1, 1,
+        colX[v.col],
+        PAD_Y + v.row * ROW_HEIGHT,
+        cssClassFor(v.kind),
+        { index: v.index, kind: v.kind, name: v.name },
+        escapeHtml(v.name),
+    );
+    nodeIds[i] = id;
+}
+
+// ---------------------------------------------------------------------------
+// Connections.
+// ---------------------------------------------------------------------------
+for (const e of edges) {
+    editor.addConnection(nodeIds[e[0]], nodeIds[e[1]], 'output_1', 'input_1');
+}
+
+editor.editor_mode = 'fixed';
+
+// ---------------------------------------------------------------------------
+// Arrowheads on connection paths.
+// ---------------------------------------------------------------------------
+const SVG_NS = 'http://www.w3.org/2000/svg';
+function addArrowhead(svg) {
+    if (svg.querySelector('marker')) return;
+    let defs = svg.querySelector('defs');
+    if (!defs) {
+        defs = document.createElementNS(SVG_NS, 'defs');
+        svg.insertBefore(defs, svg.firstChild);
+    }
+    const marker = document.createElementNS(SVG_NS, 'marker');
+    marker.setAttribute('id', 'arrowhead');
+    marker.setAttribute('viewBox', '0 0 10 10');
+    marker.setAttribute('refX', '9');
+    marker.setAttribute('refY', '5');
+    marker.setAttribute('markerWidth', '5');
+    marker.setAttribute('markerHeight', '5');
+    marker.setAttribute('orient', 'auto');
+    const tip = document.createElementNS(SVG_NS, 'path');
+    tip.setAttribute('d', 'M 0 0 L 10 5 L 0 10 z');
+    tip.setAttribute('fill', '#4ea9ff');
+    marker.appendChild(tip);
+    defs.appendChild(marker);
+    const path = svg.querySelector('path.main-path') || svg.querySelector('path');
+    if (path) path.setAttribute('marker-end', 'url(#arrowhead)');
+}
+container.querySelectorAll('svg.connection').forEach(addArrowhead);
+
+new MutationObserver((muts) => {
+    for (const m of muts) {
+        for (const node of m.addedNodes) {
+            if (node.nodeType !== 1) continue;
+            if (node.matches && node.matches('svg.connection')) addArrowhead(node);
+            if (node.querySelectorAll) {
+                node.querySelectorAll('svg.connection').forEach(addArrowhead);
+            }
+        }
+    }
+}).observe(container, { subtree: true, childList: true });
+
+// ---------------------------------------------------------------------------
+// Click-to-select with bidirectional reachability highlight.
+//
+// Reachability comes straight from transitive_closure_matrix_sparse: for a click
+// on vertex `start`, anything appearing as the target of a triple
+// (start, j, _) is reachable from `start`, and anything appearing as the
+// source of a triple (i, start, _) can reach `start`. No adjacency list —
+// we just iterate the triples each time. With small click counts and a
+// sparse matrix this is fast enough and avoids carrying redundant graph
+// state in the page.
+// ---------------------------------------------------------------------------
+const idxByDfId = new Map();
+for (let i = 0; i < n; i++) {
+    if (nodeIds[i] !== undefined) idxByDfId.set(nodeIds[i], i);
+}
+
+function connectedTo(start) {
+    const seen = new Set([start]);
+    for (const transitive_edge of transitive_closure_matrix_sparse) {
+        if (transitive_edge[0] === start) seen.add(transitive_edge[1]);
+        else if (transitive_edge[1] === start) seen.add(transitive_edge[0]);
+    }
+    return seen;
+}
+
+function parseEndpointIds(svg) {
+    let outId = null, inId = null;
+    for (const cls of svg.classList) {
+        if (cls.startsWith('node_out_node-')) outId = parseInt(cls.slice('node_out_node-'.length), 10);
+        else if (cls.startsWith('node_in_node-')) inId = parseInt(cls.slice('node_in_node-'.length), 10);
+    }
+    return { outId, inId };
+}
+
+let currentSelected = null;
+
+function clearSelection() {
+    container.querySelectorAll('.drawflow-node.is-dim, .drawflow-node.is-selected')
+        .forEach(el => el.classList.remove('is-dim', 'is-selected'));
+    container.querySelectorAll('svg.connection.is-dim')
+        .forEach(el => el.classList.remove('is-dim'));
+}
+
+function applySelection(startIdx) {
+    const connected = connectedTo(startIdx);
+
+    for (let i = 0; i < n; i++) {
+        const el = document.getElementById('node-' + nodeIds[i]);
+        if (!el) continue;
+        el.classList.toggle('is-dim', !connected.has(i));
+        el.classList.toggle('is-selected', i === startIdx);
+    }
+
+    container.querySelectorAll('svg.connection').forEach((svg) => {
+        const { outId, inId } = parseEndpointIds(svg);
+        const s = idxByDfId.get(outId);
+        const t = idxByDfId.get(inId);
+        const keep = (s !== undefined && t !== undefined
+                      && connected.has(s) && connected.has(t));
+        svg.classList.toggle('is-dim', !keep);
+    });
+}
+
+container.addEventListener('click', (evt) => {
+    const nodeEl = evt.target.closest('.drawflow-node');
+    if (!nodeEl) return;
+    const m = nodeEl.id.match(/^node-(\d+)$/);
+    if (!m) return;
+    const dfId = parseInt(m[1], 10);
+    const idx = idxByDfId.get(dfId);
+    if (idx === undefined) return;
+
+    if (currentSelected === idx) {
+        currentSelected = null;
+        clearSelection();
+    } else {
+        currentSelected = idx;
+        applySelection(idx);
+    }
+});
+
+// ---------------------------------------------------------------------------
+// Toolbar.
+// ---------------------------------------------------------------------------
+document.getElementById('zoom-in').onclick    = () => editor.zoom_in();
+document.getElementById('zoom-out').onclick   = () => editor.zoom_out();
+document.getElementById('zoom-reset').onclick = () => { editor.zoom_reset(); currentSelected = null; clearSelection(); };
+</script>
+</body>
+</html>

package/dist/index.js

@@ -1,5 +1,6 @@
 export { default, command, _resetShutdownForTest } from './command.js';
 export { legacyCommand, legacyFlags as flags } from './legacy.js';
+export { applySmartSnap, SmartSnapBailError } from './smartsnap.js';
 // export common packages to avoid dependency resolution issues
 export { default as PercyConfig } from '@percy/config';
 export { default as logger } from '@percy/logger';

package/dist/lockfileDiff.js

@@ -0,0 +1,184 @@
+import { createRequire } from 'module';
+import logger from '@percy/logger';
+
+// snyk-nodejs-lockfile-parser is a CommonJS optionalDependency. It requires
+// Node >=18 while the CLI supports Node >=14, so we defer the require to call
+// time — that way importing this module never throws on older Node versions
+// (or when the optional install was skipped for any other reason). Cached on
+// first successful load so the require only resolves once per process.
+const require = createRequire(import.meta.url);
+let _snykModule;
+/* istanbul ignore next: snyk-backed path — the parser requires Node >=18 while
+   CI runs the suite on Node 14, so these lines can't execute there; they're
+   exercised by the describeSnyk tests on Node >=18 */
+function loadSnyk() {
+  if (_snykModule) return _snykModule;
+  try {
+    _snykModule = require('snyk-nodejs-lockfile-parser');
+    return _snykModule;
+  } catch (e) {
+    // Surface the underlying require failure so callers can distinguish
+    // "not installed" (engine mismatch / optional skip) from genuine parse
+    // failures that happen later inside buildDepTree.
+    const err = new Error(`snyk-nodejs-lockfile-parser is not available (requires Node >=18, or the optional install was skipped): ${e.message}`);
+    err.code = 'SNYK_LOCKFILE_PARSER_UNAVAILABLE';
+    throw err;
+  }
+}
+
+// Map the on-disk filename to snyk's LockfileType enum key. We can't resolve
+// the enum value at module-eval time because the snyk import is deferred, so
+// we look up the value inside diffLockfileDeps after loadSnyk() runs.
+const TYPE_KEY_BY_FILENAME = {
+  'package-lock.json': 'npm',
+  'yarn.lock': 'yarn',
+  'pnpm-lock.yaml': 'pnpm'
+};
+
+// Walk snyk's PkgTree (a recursive `{ name, version, dependencies: { ... } }`
+// structure) into a flat `Map<name, version>` of every resolved package.
+// We dedupe by name on first sight — multiple versions of the same package
+// in the tree get collapsed to the first one encountered, which is fine for
+// the diff because we only care about whether *something* about the package
+// changed between old and new.
+/* istanbul ignore next: snyk-backed path — only reachable on Node >=18 (see loadSnyk) */
+function flattenPkgTree(tree) {
+  const out = new Map();
+  const walk = node => {
+    if (!(node !== null && node !== void 0 && node.dependencies)) return;
+    for (const [name, child] of Object.entries(node.dependencies)) {
+      if (!out.has(name)) out.set(name, child.version);
+      walk(child);
+    }
+  };
+  walk(tree);
+  return out;
+}
+
+// Pull `{ name -> rangeString }` from a raw package.json's `dependencies`
+// and `peerDependencies` blocks. devDeps and optionalDeps are intentionally
+// excluded — only runtime-relevant top-level packages count. Returns {} on
+// parse failure so the diff falls through to lockfile-only signal.
+/* istanbul ignore next: snyk-backed path — only reachable on Node >=18 (see loadSnyk) */
+function topLevelDeps(packageJsonContents) {
+  try {
+    const pkg = JSON.parse(packageJsonContents);
+    return {
+      ...(pkg.dependencies || {}),
+      ...(pkg.peerDependencies || {})
+    };
+  } catch {
+    return {};
+  }
+}
+
+// Given the project's package.json plus the old and new lockfile contents,
+// return the set of package names that were added, removed, or version-bumped.
+// Results are restricted to packages declared at the top level (dependencies
+// or peerDependencies) of either old or new package.json — transitives ride
+// along on direct-dep bumps and the BE module graph already resolves them
+// from stats `imports[]`, so surfacing them here would just be noise.
+//
+// Two complementary diffs run, both gated by top-level names:
+//   1. Resolved-version diff over the snyk PkgTree — catches lockfile entries
+//      whose version actually changed.
+//   2. Range-string diff over package.json — catches the case where a user
+//      bumped `^5.8.3` to `^5.18.0` but the lockfile already resolved to
+//      5.18.0 under the old range, so the resolved tree looks identical.
+export async function diffLockfileDeps({
+  packageJson,
+  oldPackageJson,
+  oldLockfile,
+  newLockfile,
+  lockfileType
+}) {
+  const log = logger('storybook:smartsnap:lockfile');
+
+  // Validate the filename maps to a supported lockfile type BEFORE loading the
+  // optional snyk parser. The parser requires Node >=18, so on older runtimes
+  // (or when the optional install was skipped) an unsupported type must still
+  // fail with this clear error rather than the parser-unavailable error from
+  // loadSnyk(). This filename check needs no parser to run.
+  const typeKey = TYPE_KEY_BY_FILENAME[lockfileType];
+  /* istanbul ignore else: on the Node-14 CI only the unsupported-type path is
+     exercised; the supported-type branch runs in describeSnyk on Node >=18 */
+  if (!typeKey) {
+    throw new Error(`Unsupported lockfile type: ${lockfileType}`);
+  }
+
+  /* istanbul ignore next: supported-type path — only reachable on Node >=18 (see loadSnyk) */
+  return resolveAffectedDeps({
+    packageJson,
+    oldPackageJson,
+    oldLockfile,
+    newLockfile,
+    typeKey,
+    log
+  });
+}
+
+// The snyk-backed resolution, split into its own function so a single
+// coverage-ignore covers the whole path: the parser requires Node >=18 while CI
+// runs the suite on Node 14, so none of this executes there. The describeSnyk
+// tests exercise it on Node >=18. `typeKey` is already validated against
+// TYPE_KEY_BY_FILENAME by the caller, so it always resolves to a LockfileType.
+/* istanbul ignore next: snyk-backed path — only reachable on Node >=18 (see loadSnyk) */
+async function resolveAffectedDeps({
+  packageJson,
+  oldPackageJson,
+  oldLockfile,
+  newLockfile,
+  typeKey,
+  log
+}) {
+  const {
+    buildDepTree,
+    LockfileType
+  } = loadSnyk();
+  const type = LockfileType[typeKey];
+
+  // The two buildDepTree calls are kept sequential (not Promise.all'd) so that
+  // when one of them throws the log message identifies *which* side failed —
+  // old vs. new lockfile parsing behave differently when the user's lockfile
+  // is in an unexpected state.
+  let oldTree;
+  try {
+    log.debug('buildDepTree: parsing OLD lockfile...');
+    oldTree = await buildDepTree(oldPackageJson, oldLockfile, true, type);
+    log.debug('buildDepTree: OLD lockfile parsed successfully');
+  } catch (e) {
+    log.warn(`buildDepTree: OLD lockfile failed to parse: ${e.message}`);
+    throw e;
+  }
+  let newTree;
+  try {
+    log.debug('buildDepTree: parsing NEW lockfile...');
+    newTree = await buildDepTree(packageJson, newLockfile, true, type);
+    log.debug('buildDepTree: NEW lockfile parsed successfully');
+  } catch (e) {
+    log.warn(`buildDepTree: NEW lockfile failed to parse: ${e.message}`);
+    throw e;
+  }
+  const oldPkgs = flattenPkgTree(oldTree);
+  const newPkgs = flattenPkgTree(newTree);
+  const oldTopLevel = topLevelDeps(oldPackageJson);
+  const newTopLevel = topLevelDeps(packageJson);
+  const topLevelNames = new Set([...Object.keys(oldTopLevel), ...Object.keys(newTopLevel)]);
+  const affected = new Set();
+  for (const [name, version] of newPkgs) {
+    if (!topLevelNames.has(name)) continue;
+    if (!oldPkgs.has(name) || oldPkgs.get(name) !== version) affected.add(name);
+  }
+  for (const [name] of oldPkgs) {
+    if (!topLevelNames.has(name)) continue;
+    if (!newPkgs.has(name)) affected.add(name);
+  }
+
+  // Range-string diff is inherently top-level since it iterates package.json
+  // directly. `!==` between the strings (or undefined) covers added, removed,
+  // and changed in a single comparison.
+  for (const name of topLevelNames) {
+    if (oldTopLevel[name] !== newTopLevel[name]) affected.add(name);
+  }
+  return [...affected];
+}

package/dist/smartsnap.js

@@ -0,0 +1,632 @@
+import fs from 'fs';
+import path from 'path';
+import { spawnSync } from 'child_process';
+import { createRequire } from 'module';
+import globToRegExp from 'glob-to-regexp';
+import logger from '@percy/logger';
+import { diffLockfileDeps } from './lockfileDiff.js';
+import { renderGraphTraceHtml } from './graphTrace.js';
+
+// stream-json is CommonJS — load via createRequire to avoid named-import interop issues.
+const require = createRequire(import.meta.url);
+const {
+  parser
+} = require('stream-json');
+const {
+  pick
+} = require('stream-json/filters/Pick');
+const {
+  streamArray
+} = require('stream-json/streamers/StreamArray');
+const {
+  streamValues
+} = require('stream-json/streamers/StreamValues');
+
+// Webpack/Vite stats prefix loader-resolved virtual modules with a NUL byte
+// (e.g. "\u0000/path/to/file?commonjs-es-import"). Strip it so the path lines
+// up with the absolute paths in our file index. Built via String.fromCharCode
+// to avoid embedding a control char in source / tripping no-control-regex.
+const NULL_CHAR = String.fromCharCode(0);
+// split/join instead of String.prototype.replaceAll: replaceAll is Node 15+
+// and cli-command supports Node >=14.
+/* istanbul ignore next: the non-string branch is defensive — resolveAndIndex
+   only ever passes stats string values, and a non-string would throw at the
+   path.isAbsolute call below anyway */
+const stripNull = s => typeof s === 'string' ? s.split(NULL_CHAR).join('') : s;
+
+// Status poll cadence: 12 attempts × 5s = 1 minute total.
+const POLL_INTERVAL_MS = 5000;
+const POLL_ATTEMPTS = 12;
+const GLOB_CHARS = /[*?]/;
+const MAX_PATTERN_LENGTH = 500;
+function patternToRegex(pattern) {
+  /* istanbul ignore next: callers (matchesPattern) only ever pass a string, so
+     the typeof guard is defensive; the length guard is exercised at runtime by
+     the over-long-glob test via the matchesPattern catch below */
+  if (typeof pattern !== 'string' || pattern.length > MAX_PATTERN_LENGTH) {
+    throw new Error('Invalid pattern: must be a string with max length of 500 characters');
+  }
+  return globToRegExp(pattern, {
+    extended: true,
+    globstar: true
+  });
+}
+function matchesPattern(str, pattern) {
+  if (GLOB_CHARS.test(pattern)) {
+    try {
+      return patternToRegex(pattern).test(str);
+    } catch {
+      return false;
+    }
+  }
+  return str === pattern;
+}
+
+// Thrown from any pipeline step that wants to fall back to the full snapshot
+// set. The caller in snapshots.js downgrades these to log.info — they're
+// expected, user-visible bail conditions, not crashes.
+export class SmartSnapBailError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'SmartSnapBailError';
+  }
+}
+
+// Any git failure is treated as a recoverable bail (full snapshot fallback),
+// per this module's contract. A common trigger is CI shallow clones where the
+// predicted base commit isn't fetched locally, so `git diff <sha> HEAD` fails —
+// we must downgrade that to a full snapshot, not crash the build. Callers that
+// want a more specific bail message (e.g. lockfile lookup) catch and re-throw.
+function git(args) {
+  let res;
+  try {
+    res = spawnSync('git', args, {
+      encoding: 'utf8'
+    });
+  } catch (e) {
+    /* istanbul ignore next: spawnSync only throws on an exec-level failure (e.g.
+       git binary missing / ENOMEM), which the test environment can't induce —
+       the non-zero-exit bail below is the path real git failures take */
+    throw new SmartSnapBailError(`SmartSnap: git ${args.join(' ')} failed to spawn: ${e.message}; running full snapshot set`);
+  }
+  if (res.status !== 0) {
+    /* istanbul ignore next: the stderr||stdout||exit-code fallbacks in the
+       message are defensive — git failures in tests always carry stderr */
+    throw new SmartSnapBailError(`SmartSnap: git ${args.join(' ')} failed: ${res.stderr || res.stdout || `exit ${res.status}`}; running full snapshot set`);
+  }
+  return res.stdout;
+}
+
+// baseRef flows into `git` argv from either user config (`baseline`) or the
+// API. Reject anything that could be parsed as an option (leading `-`) or
+// contains chars outside the safe ref alphabet — git also accepts `--` as an
+// end-of-options separator in `git diff`, but not before the rev in
+// `git show <rev>:<path>`, so validation is the only universal guard.
+function assertSafeRef(ref) {
+  if (typeof ref !== 'string' || !/^[A-Za-z0-9_./][A-Za-z0-9_./-]*$/.test(ref)) {
+    throw new SmartSnapBailError(`SmartSnap: unsafe baseline ref "${ref}"; running full snapshot set`);
+  }
+}
+function gitDiffNames(ref) {
+  assertSafeRef(ref);
+  return git(['diff', '--name-only', ref, 'HEAD', '--']).split('\n').filter(Boolean);
+}
+function gitProjectRoot() {
+  return git(['rev-parse', '--show-toplevel']).trim();
+}
+
+// Paths under these directories are dependencies / framework wiring rather
+// than first-party source, so we don't track them in the file index.
+const EXCLUDED_DIRS = new Set(['node_modules', '.storybook']);
+const isExcluded = relPath => relPath.split(/[/\\]/).some(seg => EXCLUDED_DIRS.has(seg));
+
+// Resolve+index used for `id` and `resolvedFrom` only. Converts absolute paths
+// to projectRoot-relative form, then either returns the existing index for that
+// path or assigns the next one (= current map size). Paths inside node_modules
+// or .storybook are returned as the relative string and *not* indexed; modules
+// whose id falls into that bucket are dropped downstream by the
+// "id is string → drop" contract in transformModule.
+function resolveAndIndex(value, fileIndex, projectRoot) {
+  const clean = stripNull(value);
+  if (!path.isAbsolute(clean)) return clean;
+  const rel = path.relative(projectRoot, clean);
+  if (isExcluded(rel)) return rel;
+  let idx = fileIndex.get(rel);
+  if (idx === undefined) {
+    idx = fileIndex.size;
+    fileIndex.set(rel, idx);
+  }
+  return idx;
+}
+
+// Transform a stats `modules[]` entry into the indexed shape the SmartSnap graph expects.
+// Returns null when the module's id is a string — those entries are dropped (per BE contract).
+// Each `imports[i]` / `passThroughExports[i]` carries `{ type, source }` from the
+// bundler-plugin: for `type === 'src'` we translate the absolute file path to its
+// project-file index when possible; for `type === 'module'` the source is already
+// the bare package name, so we leave it alone.
+function transformModule(m, fileIndex, projectRoot) {
+  const out = {};
+  if (m.id != null) out.id = resolveAndIndex(m.id, fileIndex, projectRoot);
+  if (typeof out.id === 'string') return null;
+  const mapEntry = e => {
+    const copy = {
+      ...e
+    };
+    if (copy.type === 'src' && typeof copy.source === 'string') {
+      copy.source = resolveAndIndex(copy.source, fileIndex, projectRoot);
+    }
+    return copy;
+  };
+  if (Array.isArray(m.imports)) out.imports = m.imports.map(mapEntry);
+  if (Array.isArray(m.passThroughExports)) out.passThroughExports = m.passThroughExports.map(mapEntry);
+  if (Array.isArray(m.nonPassThroughExports)) out.nonPassThroughExports = m.nonPassThroughExports;
+  return out;
+}
+function streamModules(filePath, onModule) {
+  return new Promise((resolve, reject) => {
+    fs.createReadStream(filePath).pipe(parser()).pipe(pick({
+      filter: 'modules'
+    })).pipe(streamArray()).on('data', ({
+      value
+    }) => onModule(value)).on('end', resolve).on('error', reject);
+  });
+}
+function readTopLevelKey(filePath, key) {
+  return new Promise((resolve, reject) => {
+    let value;
+    fs.createReadStream(filePath).pipe(parser()).pipe(pick({
+      filter: key
+    })).pipe(streamValues()).on('data', ({
+      value: v
+    }) => {
+      value = v;
+    }).on('end', () => resolve(value)).on('error', reject);
+  });
+}
+async function readStats(statsFile, projectRoot) {
+  const fileIndex = new Map();
+  const modules = [];
+  await streamModules(statsFile, m => {
+    const t = transformModule(m, fileIndex, projectRoot);
+    if (t) modules.push(t);
+  });
+
+  // Emit `files` ordered by encounter-time index so files[N] corresponds to
+  // every module/source ref that was assigned index N during streaming.
+  const files = [...fileIndex.entries()].sort((a, b) => a[1] - b[1]).map(([p]) => p);
+
+  // The bundler-plugin-smartsnap emits a unique buildId per storybook build
+  // so concurrent runs against the same project don't share Redis state.
+  const buildId = await readTopLevelKey(statsFile, 'buildId');
+  return {
+    files,
+    modules,
+    buildId
+  };
+}
+
+// Polls `job_status?sync=true&type=smartsnap_graph&id=<buildId>` — the sync
+// response blocks server-side until the job moves off `in_progress`, but the
+// API enforces a shorter timeout than the job can take, so we retry up to
+// POLL_ATTEMPTS times. On `done` the response also carries the graph payload
+// (affected stories + vertices/edges/transitive closure for trace
+// rendering), so the caller reads it directly without a second fetch.
+//
+// Response shape is the unwrapped `{ status, data }` — the smartsnap_graph
+// status response no longer keys the result by buildId.
+async function pollGraphStatus(percy, buildId, log) {
+  for (let i = 0; i < POLL_ATTEMPTS; i++) {
+    const res = await percy.client.getStatus('smartsnap_graph', [buildId]);
+    const status = res === null || res === void 0 ? void 0 : res.status;
+    log.debug(`SmartSnap: graph status (attempt ${i + 1}) = ${status}`);
+    if (status === 'done' || status === 'failure') return {
+      status,
+      data: res === null || res === void 0 ? void 0 : res.data
+    };
+    if (i < POLL_ATTEMPTS - 1) await new Promise(r => setTimeout(r, POLL_INTERVAL_MS));
+  }
+  return {
+    status: null
+  };
+}
+
+// First component: resolve + validate the statsFile path, stream-read it, and
+// assert it carries a usable buildId. Returns { files, modules, buildId }; any
+// problem throws a SmartSnapBailError so the caller falls back to a full set.
+export async function validateAndReadStats(buildDir, statsFile, projectRoot, log) {
+  // Treat statsFile as a flat filename anchored inside the build directory.
+  // path.basename() strips any traversal segments so the resolved path can't
+  // escape buildDir even if the config is hostile.
+  const statsName = path.basename(statsFile || 'enriched-stats.json');
+  if (!/^[\w.-]+\.json$/i.test(statsName)) {
+    throw new SmartSnapBailError(`SmartSnap: invalid statsFile "${statsName}" — must be a .json filename; running full snapshot set`);
+  }
+  // statsName is path.basename'd and regex-validated above; buildDir is operator-supplied config (reviewed, approved by security)
+  const resolvedStatsPath = path.join(path.resolve(buildDir), statsName); // nosemgrep
+  let statsStat;
+  try {
+    statsStat = fs.statSync(resolvedStatsPath);
+  } catch {
+    throw new SmartSnapBailError(`SmartSnap: stats file "${statsName}" not found in build directory ${buildDir}; running full snapshot set`);
+  }
+  if (!statsStat.isFile()) {
+    throw new SmartSnapBailError(`SmartSnap: stats file "${statsName}" in ${buildDir} is not a regular file; running full snapshot set`);
+  }
+  log.debug(`SmartSnap: parsing stats file ${resolvedStatsPath}`);
+  const {
+    files,
+    modules,
+    buildId
+  } = await readStats(resolvedStatsPath, projectRoot);
+  if (typeof buildId !== 'string' || !buildId) {
+    throw new SmartSnapBailError(`SmartSnap: stats file at ${resolvedStatsPath} is missing a top-level "buildId" — running full snapshot set`);
+  }
+  return {
+    files,
+    modules,
+    buildId
+  };
+}
+
+// Resolve the diff base ref + the list of changed files. With an explicit
+// `baseline` we diff against it directly and skip the API base-build lookup
+// entirely (its snapshot map is only consulted on the no-baseline path), so
+// `baselineSnapshots` comes back null in that case.
+export async function getBaselineAndAffectedNodes(percy, baseline, log) {
+  let baseRef;
+  let baselineSnapshots;
+  if (baseline) {
+    log.debug(`SmartSnap: diffing against explicit baseline "${baseline}"`);
+    baseRef = baseline;
+    baselineSnapshots = null;
+  } else {
+    // New API shape: `{ base_build_commit_sha, snapshots: { <name>: <review_state> } }`.
+    // The single base-build commit replaces the previous per-snapshot commit map —
+    // baseline prediction now happens server-side via `Percy::BaseBuildService`,
+    // so we just diff against whatever commit it picked. The set of snapshot
+    // names is no longer sent; the API resolves baselines from the project +
+    // git/PR context alone.
+    const baseLookup = await percy.client.getSmartsnapSnapshotNameToCommit();
+    log.debug(`SmartSnap: base lookup ${JSON.stringify(baseLookup)}`);
+    if (!(baseLookup !== null && baseLookup !== void 0 && baseLookup.base_build_commit_sha)) {
+      throw new SmartSnapBailError('SmartSnap: API could not predict a base build commit and no explicit baseline was set; running full snapshot set');
+    }
+    log.debug(`SmartSnap: diffing against predicted base build commit "${baseLookup.base_build_commit_sha}"`);
+    baseRef = baseLookup.base_build_commit_sha;
+    baselineSnapshots = baseLookup.snapshots || {};
+  }
+  assertSafeRef(baseRef);
+  const affectedNodes = gitDiffNames(baseRef);
+  return {
+    baseRef,
+    affectedNodes,
+    baselineSnapshots
+  };
+}
+
+// A change to anything under `.storybook/` (preview config, addons, manager
+// wiring) can affect every story's render, so the dep graph isn't enough.
+export function assertNoDotStorybookChange(affectedNodes) {
+  const dotStorybookHit = affectedNodes.find(p => p.split(/[/\\]/).includes('.storybook'));
+  if (dotStorybookHit) {
+    throw new SmartSnapBailError(`SmartSnap: change to "${dotStorybookHit}" inside .storybook affects all stories; running full snapshot set`);
+  }
+}
+
+// Bail to a full snapshot set if any changed file matches a user-supplied
+// bailOnChanges glob.
+export function assertNoBailOnChanges(affectedNodes, bailOnChanges) {
+  if (bailOnChanges !== null && bailOnChanges !== void 0 && bailOnChanges.length) {
+    const bailed = affectedNodes.find(p => bailOnChanges.some(g => matchesPattern(p, g)));
+    if (bailed) {
+      throw new SmartSnapBailError(`SmartSnap: change to "${bailed}" matched bailOnChanges; running full snapshot set`);
+    }
+  }
+}
+
+// Drop changed files that match a user-supplied `untraced` glob so they don't
+// drive snapshot selection. Returns the filtered list (unchanged when no
+// untraced patterns are configured).
+export function enforceUntraced(affectedNodes, untraced) {
+  if (untraced !== null && untraced !== void 0 && untraced.length) {
+    return affectedNodes.filter(p => !untraced.some(g => matchesPattern(p, g)));
+  }
+  return affectedNodes;
+}
+
+// Manifest/lockfile changes can shift the dependency tree, so resolve the
+// diff at the package level via snyk-nodejs-lockfile-parser and return the
+// changed package names to feed back into the graph. Returns [] when there's
+// nothing to resolve; short-circuits below fall back to a full snapshot
+// (via SmartSnapBailError) whenever we can't reason about the change.
+export async function getAffectedPackages(affectedNodes, baseRef, projectRoot, log) {
+  const MANIFEST_PATHS = new Set(['package.json', 'package-lock.json', 'yarn.lock', 'pnpm-lock.yaml']);
+  const manifestHits = affectedNodes.filter(p => MANIFEST_PATHS.has(path.basename(p)));
+  if (manifestHits.length === 0) return [];
+
+  // Locate the changed manifest's directory from affectedNodes (NOT the git
+  // root) — monorepos keep package.json + lockfile inside a workspace dir.
+  // If two changes land in different dirs, we'd need per-workspace resolution
+  // we don't try to do yet, so bail.
+  const uniqueDirs = [...new Set(manifestHits.map(p => path.dirname(p)))];
+  if (uniqueDirs.length > 1) {
+    throw new SmartSnapBailError(`SmartSnap: manifest changes span multiple directories (${uniqueDirs.join(', ')}); running full snapshot set`);
+  }
+  const manifestDir = uniqueDirs[0]; // repo-relative; '.' for root
+  // manifestDir is derived from git-tracked paths under projectRoot (reviewed, approved by security)
+  const absManifestDir = path.resolve(projectRoot, manifestDir); // nosemgrep
+
+  // Pick the lockfile that lives next to the changed manifest. If two
+  // coexist (e.g. a stray package-lock.json next to yarn.lock) we can't
+  // pick a canonical source, so bail.
+  const LOCKFILE_NAMES = ['package-lock.json', 'yarn.lock', 'pnpm-lock.yaml'];
+  // n is from the hardcoded LOCKFILE_NAMES allowlist (reviewed, approved by security)
+  const presentLockfiles = LOCKFILE_NAMES.filter(n => fs.existsSync(path.join(absManifestDir, n))); // nosemgrep
+  if (presentLockfiles.length === 0) {
+    throw new SmartSnapBailError(`SmartSnap: manifest changed in "${manifestDir}" but no lockfile present there; running full snapshot set`);
+  }
+  if (presentLockfiles.length > 1) {
+    throw new SmartSnapBailError(`SmartSnap: multiple lockfiles in "${manifestDir}" (${presentLockfiles.join(', ')}); cannot pick canonical; running full snapshot set`);
+  }
+  const lockfileName = presentLockfiles[0];
+  // git always uses forward slashes for its <rev>:<path> spec; build it by
+  // hand instead of path.join (which would use backslashes on Windows).
+  const lockfileRepoPath = manifestDir === '.' ? lockfileName : `${manifestDir}/${lockfileName}`;
+
+  // Resolve the lockfile at the base commit. If it wasn't tracked there
+  // (first SmartSnap run, lockfile renamed, etc.) we can't diff, so bail.
+  let oldLockfile;
+  try {
+    oldLockfile = git(['show', `${baseRef}:${lockfileRepoPath}`]);
+  } catch {
+    throw new SmartSnapBailError(`SmartSnap: lockfile "${lockfileRepoPath}" not present at base ref ${baseRef}; running full snapshot set`);
+  }
+
+  // lockfileName is one of the hardcoded LOCKFILE_NAMES allowlist (reviewed, approved by security)
+  const newLockfile = fs.readFileSync(path.join(absManifestDir, lockfileName), 'utf8'); // nosemgrep
+
+  // Byte-identical lockfile means only package.json's non-dep fields changed —
+  // nothing shifted in the dependency tree, so there are no affected packages.
+  if (oldLockfile === newLockfile) return [];
+
+  // joined with the literal 'package.json' under the resolved absManifestDir (reviewed, approved by security)
+  const packageJson = fs.readFileSync(path.join(absManifestDir, 'package.json'), 'utf8'); // nosemgrep
+  const packageJsonRepoPath = manifestDir === '.' ? 'package.json' : `${manifestDir}/package.json`;
+  const oldPackageJson = git(['show', `${baseRef}:${packageJsonRepoPath}`]);
+  try {
+    const packageAffected = await diffLockfileDeps({
+      packageJson,
+      oldLockfile,
+      newLockfile,
+      lockfileType: lockfileName,
+      oldPackageJson
+    });
+    // The two statements below run only on Node >=18 where the snyk parser
+    // loads; the CI matrix runs the suite on Node 14, where the await above
+    // throws SNYK_LOCKFILE_PARSER_UNAVAILABLE and we take the catch instead.
+    /* istanbul ignore next */
+    log.debug(`SmartSnap: lockfile diff produced ${packageAffected.length} affected packages: ${packageAffected.join(', ')}`);
+    /* istanbul ignore next */
+    return packageAffected;
+  } catch (e) {
+    // snyk-nodejs-lockfile-parser is an optionalDependency (requires Node >=18).
+    // When it's missing we can't reason about the manifest change, so we
+    // conservatively bail to a full snapshot rather than under-snapshotting.
+    /* istanbul ignore else: a non-snyk diff error can only surface on Node >=18 */
+    if (e.code === 'SNYK_LOCKFILE_PARSER_UNAVAILABLE') {
+      throw new SmartSnapBailError(`SmartSnap: ${e.message}; running full snapshot set`);
+    }
+    /* istanbul ignore next: non-snyk diff errors only surface on Node >=18 */
+    throw e;
+  }
+}
+
+// Project each snapshot's importPath into the project-root frame and return
+// the unique set. Logs how many snapshots carried an importPath and warns
+// (with a sample) when none do, which usually means broken story extraction.
+export function extractStorybookPaths(snapshots, normalizeImportPath, log) {
+  const storybookPaths = [...new Set(snapshots.map(s => normalizeImportPath(s.importPath)).filter(Boolean))];
+  const snapshotsWithImportPath = snapshots.filter(s => s.importPath).length;
+  log.debug(`SmartSnap: ${snapshotsWithImportPath}/${snapshots.length} snapshots have importPath; ${storybookPaths.length} unique storybookPaths`);
+  if (storybookPaths.length === 0) {
+    var _snapshots$, _snapshots$2, _snapshots$3;
+    log.warn(`SmartSnap: no snapshots have importPath set — check Storybook story extraction. Sample snapshot: ${JSON.stringify({
+      id: (_snapshots$ = snapshots[0]) === null || _snapshots$ === void 0 ? void 0 : _snapshots$.id,
+      name: (_snapshots$2 = snapshots[0]) === null || _snapshots$2 === void 0 ? void 0 : _snapshots$2.name,
+      importPath: (_snapshots$3 = snapshots[0]) === null || _snapshots$3 === void 0 ? void 0 : _snapshots$3.importPath,
+      keys: snapshots[0] ? Object.keys(snapshots[0]) : []
+    })}`);
+  } else {
+    log.debug(`SmartSnap: storybookPaths sample: ${storybookPaths.slice(0, 3).join(', ')}`);
+  }
+  return storybookPaths;
+}
+
+// Kick off the graph generation job and poll it to completion, returning the
+// graph payload. The sync status response carries the graph payload directly
+// on completion, so there's no second fetch — the returned `data` is the same
+// response body that used to come from `getSmartsnapGraphData`. Bails to a
+// full snapshot set if the job doesn't reach `done`.
+export async function runGraphGeneration(percy, buildId, payload, log) {
+  const {
+    files,
+    modules,
+    storybookPaths,
+    affectedNodes
+  } = payload;
+  log.debug(`SmartSnap: starting graph generation job ${JSON.stringify({
+    buildId,
+    files,
+    modules,
+    storybookPaths,
+    affectedNodes
+  })}`);
+  await percy.client.generateSmartsnapGraph(buildId, {
+    files,
+    modules,
+    storybookPaths,
+    affectedNodes
+  });
+  const {
+    status,
+    data
+  } = await pollGraphStatus(percy, buildId, log);
+  if (status !== 'done') {
+    throw new SmartSnapBailError(`SmartSnap: graph generation did not complete (status: ${status ?? 'timed out'}); running full snapshot set`);
+  }
+  log.debug(`SmartSnap: affected stories result ${JSON.stringify(data === null || data === void 0 ? void 0 : data.affected_stories)}`);
+  return data;
+}
+
+// Trace rendering moved client-side: the API now returns the raw graph
+// (vertices, edges, transitive-closure triples) and we populate the bundled
+// HTML template here. Only runs when `trace` is enabled and the payload is
+// complete — anything missing means the BE couldn't produce a graph, so we
+// skip silently rather than write a broken page.
+export function maybeWriteTrace(trace, data, log) {
+  if (trace && data !== null && data !== void 0 && data.vertices && data !== null && data !== void 0 && data.edges && data !== null && data !== void 0 && data.transitive_closure_matrix_sparse) {
+    const tracePath = path.resolve(process.cwd(), 'trace.html');
+    try {
+      const html = renderGraphTraceHtml({
+        vertices: data.vertices,
+        edges: data.edges,
+        transitiveClosureMatrixSparse: data.transitive_closure_matrix_sparse
+      });
+      fs.writeFileSync(tracePath, html);
+      log.info(`SmartSnap: trace written to ${tracePath}`);
+    } catch (e) {
+      log.warn(`SmartSnap: failed to write trace.html: ${e.message}`);
+    }
+  }
+}
+
+// Filter the snapshots down to those the affected-graph reports plus any that
+// need a forced re-snapshot, log the summary, and return the kept list.
+//
+// Snapshots whose baseline review_state is `failed` or `rejected` have no
+// usable baseline image to diff against, and snapshots that don't appear in
+// the base build at all are brand-new (no baseline exists yet). In both cases
+// SmartSnap can't legitimately skip them — re-snapshot unconditionally
+// regardless of what the affected-graph reports. `baselineSnapshots` is null
+// when an explicit baseline is set, but `needsBaselineRefresh` short-circuits
+// on `baseline` before reading it.
+export function selectAffectedSnapshots(snapshots, data, baseline, baselineSnapshots, normalizeImportPath, log) {
+  const affected = new Set((data === null || data === void 0 ? void 0 : data.affected_stories) || []);
+  const FORCE_RESNAPSHOT_STATES = new Set(['failed', 'rejected']);
+  const needsBaselineRefresh = name => {
+    if (baseline) return false;
+    const state = baselineSnapshots[name];
+    return state === undefined || FORCE_RESNAPSHOT_STATES.has(state);
+  };
+
+  // Use the same normalization on lookup so a snapshot's `./src/...` matches
+  // an affected-stories `src/...` from the API.
+  let forced = 0;
+  let affectedKept = 0;
+  const filtered = snapshots.filter(s => {
+    if (needsBaselineRefresh(s.name)) {
+      forced += 1;
+      return true;
+    }
+    const p = normalizeImportPath(s.importPath);
+    if (p && affected.has(p)) {
+      affectedKept += 1;
+      return true;
+    }
+    return false;
+  });
+  log.info(`SmartSnap: ${filtered.length} of ${snapshots.length} snapshots kept (${affectedKept} via affected-graph, ${forced} via missing/failed/rejected baseline)`);
+  return filtered;
+}
+
+// Given the mapped snapshots and storybook.smartSnap config, returns the subset of snapshots
+// that the SmartSnap graph reports as affected. On any recoverable failure, returns the input
+// list unchanged so the build runs as a full snapshot pass.
+export async function applySmartSnap(percy, snapshots, smartSnapConfig, buildDir) {
+  const log = logger('storybook:smartsnap');
+  const {
+    baseline,
+    untraced,
+    trace,
+    bailOnChanges,
+    statsFile
+  } = smartSnapConfig || {};
+  if (!buildDir) {
+    throw new SmartSnapBailError('SmartSnap requires the Storybook build directory (e.g. `percy storybook ./storybook-static`); URL and `start` modes are not supported. Running full snapshot set');
+  }
+  const projectRoot = gitProjectRoot();
+  const {
+    files,
+    modules,
+    buildId
+  } = await validateAndReadStats(buildDir, statsFile, projectRoot, log);
+  let {
+    baseRef,
+    affectedNodes,
+    baselineSnapshots
+  } = await getBaselineAndAffectedNodes(percy, baseline, log);
+  assertNoDotStorybookChange(affectedNodes);
+  assertNoBailOnChanges(affectedNodes, bailOnChanges);
+  affectedNodes = enforceUntraced(affectedNodes, untraced);
+  const packageAffectedNodes = await getAffectedPackages(affectedNodes, baseRef, projectRoot, log);
+
+  // With no traced files and no package-level changes there's nothing for the
+  // graph to reason about — bail to a full snapshot set rather than send an
+  // empty diff.
+  if (!affectedNodes.length && !packageAffectedNodes.length) {
+    throw new SmartSnapBailError('SmartSnap: no affected files or packages detected after filtering; running full snapshot set');
+  }
+
+  // Storybook's `entries[id].importPath` (and v6 `parameters.fileName`)
+  // is resolved relative to the directory percy was invoked from — for a
+  // monorepo storybook that's typically the package dir (e.g.
+  // `frontend/packages/design-stack`), not the git root. Example:
+  // `./modules/AgentCard/AgentCard.stories.tsx`.
+  //
+  // `affectedNodes` from `git diff --name-only` and the `files` array
+  // built by the stats compactor are both project-root-relative
+  // (e.g. `packages/design-stack/modules/AgentCard/AgentCard.stories.tsx`).
+  // Project them into the same frame so the BE matches importPath against
+  // affectedNodes without a cross-frame translation.
+  const dotPosix = './';
+  const dotPlatform = `.${path.sep}`;
+  const invocationDir = process.cwd();
+  const normalizeImportPath = p => {
+    if (typeof p !== 'string' || !p) return p;
+    let rel = p;
+    /* istanbul ignore next: on POSIX CI dotPlatform === dotPosix ('./'), so the
+       dotPosix else-if (a Windows-only '.\\' case) is unreachable there; ignore
+       the whole prefix-strip chain rather than a single dead else-if branch */
+    if (rel.startsWith(dotPlatform)) rel = rel.slice(dotPlatform.length);else if (rel.startsWith(dotPosix)) rel = rel.slice(dotPosix.length);
+    // If the importPath happens to be absolute (older Storybook configs),
+    // path.resolve treats it as the target directly; otherwise it's joined
+    // against `invocationDir`. Then re-base against the git project root.
+    // rel comes from build stats file paths, re-based against projectRoot on the next line (reviewed, approved by security)
+    const abs = path.resolve(invocationDir, rel); // nosemgrep
+    const projRel = path.relative(projectRoot, abs);
+    // path.relative('','') → '' and `path.relative` produces backslashes
+    // on Windows; the stats `files` array uses the same — leave platform
+    // sep alone so the two stay byte-identical for the BE match.
+    /* istanbul ignore next: the `|| rel` fallback only triggers when an importPath
+       resolves exactly to projectRoot (projRel === ''), an edge that's unstable to
+       reproduce across OS symlink/tmpdir differences */
+    return projRel || rel;
+  };
+  const storybookPaths = extractStorybookPaths(snapshots, normalizeImportPath, log);
+
+  /* istanbul ignore next: packageAffectedNodes is only non-empty on Node >=18
+     (the snyk lockfile diff); on the Node-14 CI getAffectedPackages either
+     returns [] or bails before yielding packages, so this never runs there */
+  if (packageAffectedNodes.length) {
+    affectedNodes = [...affectedNodes, ...packageAffectedNodes];
+  }
+  const data = await runGraphGeneration(percy, buildId, {
+    files,
+    modules,
+    storybookPaths,
+    affectedNodes
+  }, log);
+  maybeWriteTrace(trace, data, log);
+  return selectAffectedSnapshots(snapshots, data, baseline, baselineSnapshots, normalizeImportPath, log);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@percy/cli-command",
-  "version": "1.32.0-beta.5",
+  "version": "1.32.0-beta.7",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -27,6 +27,7 @@
     ".": "./dist/index.js",
     "./flags": "./dist/flags.js",
     "./utils": "./dist/utils.js",
+    "./smartsnap": "./dist/smartsnap.js",
     "./test/helpers": "./test/helpers.js"
   },
   "scripts": {
@@ -36,9 +37,14 @@
     "test:coverage": "yarn test --coverage"
   },
   "dependencies": {
-    "@percy/config": "1.32.0-beta.5",
-    "@percy/core": "1.32.0-beta.5",
-    "@percy/logger": "1.32.0-beta.5"
+    "@percy/config": "1.32.0-beta.7",
+    "@percy/core": "1.32.0-beta.7",
+    "@percy/logger": "1.32.0-beta.7",
+    "glob-to-regexp": "^0.4.1",
+    "stream-json": "^1.8.0"
   },
-  "gitHead": "d93415f2cc83533c9c037579e440c6e2a5119920"
+  "optionalDependencies": {
+    "snyk-nodejs-lockfile-parser": "2.7.1"
+  },
+  "gitHead": "9f25a93344237c69c9b0d104de0208857d4c8981"
 }