@storyshelf/affected 0.5.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Siddhant Gupta
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,29 @@
+# @storyshelf/affected
+
+Affected capture for StoryShelf: traces the dependency graph of a change to select only the stories it impacts.
+
+## Install
+
+```sh
+nub add @storyshelf/affected
+```
+
+or
+
+```sh
+npm install @storyshelf/affected
+```
+
+## Usage
+
+```ts
+import { computeAffected } from "@storyshelf/affected";
+
+const result = await computeAffected({ cwd, buildDir, baseSha, headSha });
+```
+
+See the [StoryShelf documentation](https://github.com/GuptaSiddhant/StoryShelf#readme) for configuration details.
+
+## License
+
+MIT

package/dist/git.d.mts

@@ -0,0 +1,47 @@
+import __tsdown_shims_path from 'node:path';
+import __tsdown_shims_url from 'node:url';
+//#region src/git.d.ts
+/** Upper bound on changed files before falling back to a full render. */
+declare const MAX_CHANGED_FILES = 10000;
+/** Prefix marking CLI-synthesized identities for checkouts without git. */
+declare const LOCAL_SHA_PREFIX = "local-";
+/** Default branch for synthesized identities (isolates local experiments). */
+declare const LOCAL_BRANCH = "local";
+/** Repository git status relevant to affected capture. */
+type GitRepoStatus = "ok" | "shallow" | "no-git";
+/**
+ * Probe whether the checkout can support diffing: a full repo (`ok`), a
+ * shallow clone (`shallow`), or missing git / not a repository (`no-git`).
+ */
+declare function gitRepoStatus(cwd: string): GitRepoStatus;
+/**
+ * True when the checkout cannot support diffing (shallow clone, missing git,
+ * or not a repository). Callers treat this as "render everything".
+ *
+ * @param cwd - Repository root to probe.
+ */
+declare function isShallowRepo(cwd: string): boolean;
+/**
+ * Repo-relative files changed between `base` and `head`, including staged
+ * and untracked working-tree files. Throws when git cannot diff.
+ *
+ * @param cwd - Repository root.
+ * @param base - Ancestor commit (baseline).
+ * @param head - Current commit.
+ */
+declare function changedFiles(cwd: string, base: string, head: string): string[];
+/**
+ * Current commit of the checkout, or `null` when git is missing, `cwd` is
+ * not a repository, or HEAD is unborn.
+ */
+declare function gitHeadSha(cwd: string): string | null;
+/**
+ * Current branch of the checkout, or `null` when detached, unborn, or git
+ * is unavailable.
+ */
+declare function gitBranchName(cwd: string): string | null;
+/** Synthesize a unique local sha for checkouts without git. */
+declare function localSha(): string;
+//#endregion
+export { GitRepoStatus, LOCAL_BRANCH, LOCAL_SHA_PREFIX, MAX_CHANGED_FILES, changedFiles, gitBranchName, gitHeadSha, gitRepoStatus, isShallowRepo, localSha };
+//# sourceMappingURL=git.d.mts.map

package/dist/git.mjs

@@ -0,0 +1,121 @@
+import "node:path";
+import "node:url";
+import.meta.url;
+import { execFileSync } from "node:child_process";
+import { randomUUID } from "node:crypto";
+//#region src/git.ts
+/** Upper bound on changed files before falling back to a full render. */
+const MAX_CHANGED_FILES = 1e4;
+/** Prefix marking CLI-synthesized identities for checkouts without git. */
+const LOCAL_SHA_PREFIX = "local-";
+/** Default branch for synthesized identities (isolates local experiments). */
+const LOCAL_BRANCH = "local";
+/** Run a git subcommand, returning trimmed stdout. Throws on failure. */
+function git(cwd, args) {
+	return execFileSync("git", args, {
+		cwd,
+		encoding: "utf8"
+	}).trim();
+}
+/**
+* Probe whether the checkout can support diffing: a full repo (`ok`), a
+* shallow clone (`shallow`), or missing git / not a repository (`no-git`).
+*/
+function gitRepoStatus(cwd) {
+	let shallow;
+	try {
+		shallow = git(cwd, ["rev-parse", "--is-shallow-repository"]);
+	} catch {
+		return "no-git";
+	}
+	return shallow === "true" ? "shallow" : "ok";
+}
+/**
+* True when the checkout cannot support diffing (shallow clone, missing git,
+* or not a repository). Callers treat this as "render everything".
+*
+* @param cwd - Repository root to probe.
+*/
+function isShallowRepo(cwd) {
+	return gitRepoStatus(cwd) !== "ok";
+}
+/** Split `git --name-only` output into a deduplicated file list. */
+function parseNameOnly(output) {
+	const files = /* @__PURE__ */ new Set();
+	for (const line of output.split("\n")) {
+		const trimmed = line.trim();
+		if (trimmed.length > 0) files.add(trimmed);
+	}
+	return [...files];
+}
+/** Committed changes between two revisions (two-dot range). */
+function committedChanges(cwd, base, head) {
+	return parseNameOnly(git(cwd, [
+		"diff",
+		"--name-only",
+		`${base}..${head}`
+	]));
+}
+/** Staged and unstaged changes plus untracked files (never committed). */
+function workingTreeChanges(cwd) {
+	const againstHead = parseNameOnly(git(cwd, [
+		"diff",
+		"--name-only",
+		"HEAD"
+	]));
+	const untracked = parseNameOnly(git(cwd, [
+		"ls-files",
+		"--others",
+		"--exclude-standard"
+	]));
+	return [.../* @__PURE__ */ new Set([...againstHead, ...untracked])];
+}
+/**
+* Repo-relative files changed between `base` and `head`, including staged
+* and untracked working-tree files. Throws when git cannot diff.
+*
+* @param cwd - Repository root.
+* @param base - Ancestor commit (baseline).
+* @param head - Current commit.
+*/
+function changedFiles(cwd, base, head) {
+	return [.../* @__PURE__ */ new Set([...committedChanges(cwd, base, head), ...workingTreeChanges(cwd)])].toSorted();
+}
+/** Run a git subcommand, returning trimmed stdout or `null` on any failure. */
+function tryGit(cwd, args) {
+	try {
+		const output = git(cwd, args);
+		return output.length > 0 ? output : null;
+	} catch {
+		return null;
+	}
+}
+/**
+* Current commit of the checkout, or `null` when git is missing, `cwd` is
+* not a repository, or HEAD is unborn.
+*/
+function gitHeadSha(cwd) {
+	return tryGit(cwd, ["rev-parse", "HEAD"]);
+}
+/**
+* Current branch of the checkout, or `null` when detached, unborn, or git
+* is unavailable.
+*/
+function gitBranchName(cwd) {
+	const branch = tryGit(cwd, ["branch", "--show-current"]);
+	if (branch) return branch;
+	const abbrev = tryGit(cwd, [
+		"rev-parse",
+		"--abbrev-ref",
+		"HEAD"
+	]);
+	return abbrev && abbrev !== "HEAD" ? abbrev : null;
+}
+/** Synthesize a unique local sha for checkouts without git. */
+function localSha() {
+	return `${LOCAL_SHA_PREFIX}${randomUUID().replaceAll("-", "").slice(0, 12)}`;
+}
+//#endregion
+export { LOCAL_BRANCH, LOCAL_SHA_PREFIX, MAX_CHANGED_FILES, changedFiles, gitBranchName, gitHeadSha, gitRepoStatus, isShallowRepo, localSha };
+
+//# sourceMappingURL=git.mjs.map

package/dist/git.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"git.mjs","names":[],"sources":["../src/git.ts"],"sourcesContent":["import { execFileSync } from \"node:child_process\";\nimport { randomUUID } from \"node:crypto\";\n\n/** Upper bound on changed files before falling back to a full render. */\nexport const MAX_CHANGED_FILES = 10_000;\n\n/** Prefix marking CLI-synthesized identities for checkouts without git. */\nexport const LOCAL_SHA_PREFIX = \"local-\";\n\n/** Default branch for synthesized identities (isolates local experiments). */\nexport const LOCAL_BRANCH = \"local\";\n\n/** Run a git subcommand, returning trimmed stdout. Throws on failure. */\nfunction git(cwd: string, args: string[]): string {\n  return execFileSync(\"git\", args, { cwd, encoding: \"utf8\" }).trim();\n}\n\n/** Repository git status relevant to affected capture. */\nexport type GitRepoStatus = \"ok\" | \"shallow\" | \"no-git\";\n/**\n * Probe whether the checkout can support diffing: a full repo (`ok`), a\n * shallow clone (`shallow`), or missing git / not a repository (`no-git`).\n */\nexport function gitRepoStatus(cwd: string): GitRepoStatus {\n  let shallow: string | null;\n  try {\n    shallow = git(cwd, [\"rev-parse\", \"--is-shallow-repository\"]);\n  } catch {\n    return \"no-git\";\n  }\n  return shallow === \"true\" ? \"shallow\" : \"ok\";\n}\n\n/**\n * True when the checkout cannot support diffing (shallow clone, missing git,\n * or not a repository). Callers treat this as \"render everything\".\n *\n * @param cwd - Repository root to probe.\n */\nexport function isShallowRepo(cwd: string): boolean {\n  return gitRepoStatus(cwd) !== \"ok\";\n}\n\n/** Split `git --name-only` output into a deduplicated file list. */\nfunction parseNameOnly(output: string): string[] {\n  const files = new Set<string>();\n  for (const line of output.split(\"\\n\")) {\n    const trimmed = line.trim();\n    if (trimmed.length > 0) {\n      files.add(trimmed);\n    }\n  }\n  return [...files];\n}\n\n/** Committed changes between two revisions (two-dot range). */\nfunction committedChanges(cwd: string, base: string, head: string): string[] {\n  return parseNameOnly(git(cwd, [\"diff\", \"--name-only\", `${base}..${head}`]));\n}\n\n/** Staged and unstaged changes plus untracked files (never committed). */\nfunction workingTreeChanges(cwd: string): string[] {\n  const againstHead = parseNameOnly(git(cwd, [\"diff\", \"--name-only\", \"HEAD\"]));\n  const untracked = parseNameOnly(git(cwd, [\"ls-files\", \"--others\", \"--exclude-standard\"]));\n  return [...new Set([...againstHead, ...untracked])];\n}\n\n/**\n * Repo-relative files changed between `base` and `head`, including staged\n * and untracked working-tree files. Throws when git cannot diff.\n *\n * @param cwd - Repository root.\n * @param base - Ancestor commit (baseline).\n * @param head - Current commit.\n */\nexport function changedFiles(cwd: string, base: string, head: string): string[] {\n  const files = new Set([...committedChanges(cwd, base, head), ...workingTreeChanges(cwd)]);\n  return [...files].toSorted();\n}\n\n/** Run a git subcommand, returning trimmed stdout or `null` on any failure. */\nfunction tryGit(cwd: string, args: string[]): string | null {\n  try {\n    const output = git(cwd, args);\n    return output.length > 0 ? output : null;\n  } catch {\n    return null;\n  }\n}\n\n/**\n * Current commit of the checkout, or `null` when git is missing, `cwd` is\n * not a repository, or HEAD is unborn.\n */\nexport function gitHeadSha(cwd: string): string | null {\n  return tryGit(cwd, [\"rev-parse\", \"HEAD\"]);\n}\n\n/**\n * Current branch of the checkout, or `null` when detached, unborn, or git\n * is unavailable.\n */\nexport function gitBranchName(cwd: string): string | null {\n  const branch = tryGit(cwd, [\"branch\", \"--show-current\"]);\n  if (branch) {\n    return branch;\n  }\n  const abbrev = tryGit(cwd, [\"rev-parse\", \"--abbrev-ref\", \"HEAD\"]);\n  return abbrev && abbrev !== \"HEAD\" ? abbrev : null;\n}\n\n/** Synthesize a unique local sha for checkouts without git. */\nexport function localSha(): string {\n  return `${LOCAL_SHA_PREFIX}${randomUUID().replaceAll(\"-\", \"\").slice(0, 12)}`;\n}\n"],"mappings":";;;;;;;AAIA,MAAa,oBAAoB;;AAGjC,MAAa,mBAAmB;;AAGhC,MAAa,eAAe;;AAG5B,SAAS,IAAI,KAAa,MAAwB;CAChD,OAAO,aAAa,OAAO,MAAM;EAAE;EAAK,UAAU;CAAO,CAAC,CAAC,CAAC,KAAK;AACnE;;;;;AAQA,SAAgB,cAAc,KAA4B;CACxD,IAAI;CACJ,IAAI;EACF,UAAU,IAAI,KAAK,CAAC,aAAa,yBAAyB,CAAC;CAC7D,QAAQ;EACN,OAAO;CACT;CACA,OAAO,YAAY,SAAS,YAAY;AAC1C;;;;;;;AAQA,SAAgB,cAAc,KAAsB;CAClD,OAAO,cAAc,GAAG,MAAM;AAChC;;AAGA,SAAS,cAAc,QAA0B;CAC/C,MAAM,wBAAQ,IAAI,IAAY;CAC9B,KAAK,MAAM,QAAQ,OAAO,MAAM,IAAI,GAAG;EACrC,MAAM,UAAU,KAAK,KAAK;EAC1B,IAAI,QAAQ,SAAS,GACnB,MAAM,IAAI,OAAO;CAErB;CACA,OAAO,CAAC,GAAG,KAAK;AAClB;;AAGA,SAAS,iBAAiB,KAAa,MAAc,MAAwB;CAC3E,OAAO,cAAc,IAAI,KAAK;EAAC;EAAQ;EAAe,GAAG,KAAK,IAAI;CAAM,CAAC,CAAC;AAC5E;;AAGA,SAAS,mBAAmB,KAAuB;CACjD,MAAM,cAAc,cAAc,IAAI,KAAK;EAAC;EAAQ;EAAe;CAAM,CAAC,CAAC;CAC3E,MAAM,YAAY,cAAc,IAAI,KAAK;EAAC;EAAY;EAAY;CAAoB,CAAC,CAAC;CACxF,OAAO,CAAC,mBAAG,IAAI,IAAI,CAAC,GAAG,aAAa,GAAG,SAAS,CAAC,CAAC;AACpD;;;;;;;;;AAUA,SAAgB,aAAa,KAAa,MAAc,MAAwB;CAE9E,OAAO,CAAC,mBAAG,IADO,IAAI,CAAC,GAAG,iBAAiB,KAAK,MAAM,IAAI,GAAG,GAAG,mBAAmB,GAAG,CAAC,CACxE,CAAC,CAAC,CAAC,SAAS;AAC7B;;AAGA,SAAS,OAAO,KAAa,MAA+B;CAC1D,IAAI;EACF,MAAM,SAAS,IAAI,KAAK,IAAI;EAC5B,OAAO,OAAO,SAAS,IAAI,SAAS;CACtC,QAAQ;EACN,OAAO;CACT;AACF;;;;;AAMA,SAAgB,WAAW,KAA4B;CACrD,OAAO,OAAO,KAAK,CAAC,aAAa,MAAM,CAAC;AAC1C;;;;;AAMA,SAAgB,cAAc,KAA4B;CACxD,MAAM,SAAS,OAAO,KAAK,CAAC,UAAU,gBAAgB,CAAC;CACvD,IAAI,QACF,OAAO;CAET,MAAM,SAAS,OAAO,KAAK;EAAC;EAAa;EAAgB;CAAM,CAAC;CAChE,OAAO,UAAU,WAAW,SAAS,SAAS;AAChD;;AAGA,SAAgB,WAAmB;CACjC,OAAO,GAAG,mBAAmB,WAAW,CAAC,CAAC,WAAW,KAAK,EAAE,CAAC,CAAC,MAAM,GAAG,EAAE;AAC3E"}

package/dist/index.d.mts

@@ -0,0 +1,19 @@
+import __tsdown_shims_path from 'node:path';
+import __tsdown_shims_url from 'node:url';
+import { AffectedInput, AffectedResult, DepGraph, StoryLike, TraceOptions } from "./types.mjs";
+import { GitRepoStatus, LOCAL_BRANCH, LOCAL_SHA_PREFIX, MAX_CHANGED_FILES, changedFiles, gitBranchName, gitHeadSha, gitRepoStatus, isShallowRepo, localSha } from "./git.mjs";
+import { STATS_FILENAME, buildGraph, graphModulesFor, loadDepGraph, loadStoryImportPaths, normalizePath, statsPathFor } from "./stats.mjs";
+import { matchesAnyGlob, traceAffected } from "./trace.mjs";
+import { StoryPartition, selectAffectedStories } from "./select.mjs";
+//#region src/index.d.ts
+/**
+ * Compute the affected story set for an upload. Never throws: every failure
+ * degrades to a full render with a machine-readable `fullReason`, so
+ * affected capture can stay enabled by default without new failure modes.
+ *
+ * @param input - Repository root, build dir, revisions, and trace options.
+ */
+declare function computeAffected(input: AffectedInput): Promise<AffectedResult>;
+//#endregion
+export { type AffectedInput, type AffectedResult, type DepGraph, type GitRepoStatus, LOCAL_BRANCH, LOCAL_SHA_PREFIX, MAX_CHANGED_FILES, STATS_FILENAME, type StoryLike, type StoryPartition, type TraceOptions, buildGraph, changedFiles, computeAffected, gitBranchName, gitHeadSha, gitRepoStatus, graphModulesFor, isShallowRepo, loadDepGraph, loadStoryImportPaths, localSha, matchesAnyGlob, normalizePath, selectAffectedStories, statsPathFor, traceAffected };
+//# sourceMappingURL=index.d.mts.map

package/dist/index.mjs

@@ -0,0 +1,75 @@
+import "node:path";
+import "node:url";
+import.meta.url;
+import { LOCAL_BRANCH, LOCAL_SHA_PREFIX, MAX_CHANGED_FILES, changedFiles, gitBranchName, gitHeadSha, gitRepoStatus, isShallowRepo, localSha } from "./git.mjs";
+import { STATS_FILENAME, buildGraph, graphModulesFor, loadDepGraph, loadStoryImportPaths, normalizePath, statsPathFor } from "./stats.mjs";
+import { matchesAnyGlob, traceAffected } from "./trace.mjs";
+import { selectAffectedStories } from "./select.mjs";
+//#region src/index.ts
+/**
+* Compute the affected story set for an upload. Never throws: every failure
+* degrades to a full render with a machine-readable `fullReason`, so
+* affected capture can stay enabled by default without new failure modes.
+*
+* @param input - Repository root, build dir, revisions, and trace options.
+*/
+async function computeAffected(input) {
+	try {
+		return await computeSelective(input);
+	} catch {
+		return fullResult([], input.baseSha, "affected-computation-failed");
+	}
+}
+/** Full-render result with a reason. */
+function fullResult(changed, baselineSha, reason) {
+	return {
+		affectedImportPaths: null,
+		changedFiles: changed,
+		baselineSha,
+		fullReason: reason
+	};
+}
+/** Selective result for an affected import-path set. */
+function selectiveResult(changed, baselineSha, paths) {
+	return {
+		affectedImportPaths: paths,
+		changedFiles: changed,
+		baselineSha,
+		fullReason: null
+	};
+}
+/** Guarded changed-file list, throwing a full-render reason when unusable. */
+function guardedChanged(input) {
+	const repo = gitRepoStatus(input.cwd);
+	if (repo !== "ok") throw new Error(repo === "shallow" ? "shallow-clone" : "not-a-git-repo");
+	const changed = changedFiles(input.cwd, input.baseSha, input.headSha);
+	if (changed.length > 1e4) throw new Error("too-many-changed-files");
+	return changed;
+}
+/** Trace the affected set once inputs are validated. Throws reason strings. */
+async function traceSelective(input, changed) {
+	if (changed.length === 0) return selectiveResult(changed, input.baseSha, []);
+	const stories = await loadStoryImportPaths(input.cwd, input.buildDir).catch(() => {
+		throw new Error("story-index-unreadable");
+	});
+	const graph = await loadDepGraph(statsPathFor(input.cwd, input.buildDir, input.statsFile));
+	if (!graph) throw new Error("dependency-graph-unavailable");
+	const affected = traceAffected(graph, changed, stories, { untraced: input.untraced });
+	if (affected === null) throw new Error("global-file-changed");
+	return selectiveResult(changed, input.baseSha, affected);
+}
+/** Selective computation with reason-string failures mapped to full renders. */
+async function computeSelective(input) {
+	let changed = [];
+	try {
+		changed = guardedChanged(input);
+		return await traceSelective(input, changed);
+	} catch (error) {
+		const reason = error instanceof Error ? error.message : "affected-computation-failed";
+		return fullResult(changed, input.baseSha, reason);
+	}
+}
+//#endregion
+export { LOCAL_BRANCH, LOCAL_SHA_PREFIX, MAX_CHANGED_FILES, STATS_FILENAME, buildGraph, changedFiles, computeAffected, gitBranchName, gitHeadSha, gitRepoStatus, graphModulesFor, isShallowRepo, loadDepGraph, loadStoryImportPaths, localSha, matchesAnyGlob, normalizePath, selectAffectedStories, statsPathFor, traceAffected };
+
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.mjs","names":[],"sources":["../src/index.ts"],"sourcesContent":["import { changedFiles, gitRepoStatus, MAX_CHANGED_FILES } from \"./git.ts\";\nimport { loadDepGraph, loadStoryImportPaths, statsPathFor } from \"./stats.ts\";\nimport { traceAffected } from \"./trace.ts\";\nimport type { AffectedInput, AffectedResult } from \"./types.ts\";\n\n/**\n * Compute the affected story set for an upload. Never throws: every failure\n * degrades to a full render with a machine-readable `fullReason`, so\n * affected capture can stay enabled by default without new failure modes.\n *\n * @param input - Repository root, build dir, revisions, and trace options.\n */\nexport async function computeAffected(input: AffectedInput): Promise<AffectedResult> {\n  try {\n    return await computeSelective(input);\n  } catch {\n    return fullResult([], input.baseSha, \"affected-computation-failed\");\n  }\n}\n\n/** Full-render result with a reason. */\nfunction fullResult(changed: string[], baselineSha: string | null, reason: string): AffectedResult {\n  return { affectedImportPaths: null, changedFiles: changed, baselineSha, fullReason: reason };\n}\n\n/** Selective result for an affected import-path set. */\nfunction selectiveResult(changed: string[], baselineSha: string, paths: string[]): AffectedResult {\n  return { affectedImportPaths: paths, changedFiles: changed, baselineSha, fullReason: null };\n}\n\n/** Guarded changed-file list, throwing a full-render reason when unusable. */\nfunction guardedChanged(input: AffectedInput): string[] {\n  const repo = gitRepoStatus(input.cwd);\n  if (repo !== \"ok\") {\n    throw new Error(repo === \"shallow\" ? \"shallow-clone\" : \"not-a-git-repo\");\n  }\n  const changed = changedFiles(input.cwd, input.baseSha, input.headSha);\n  if (changed.length > MAX_CHANGED_FILES) {\n    throw new Error(\"too-many-changed-files\");\n  }\n  return changed;\n}\n\n/** Trace the affected set once inputs are validated. Throws reason strings. */\nasync function traceSelective(input: AffectedInput, changed: string[]): Promise<AffectedResult> {\n  if (changed.length === 0) {\n    return selectiveResult(changed, input.baseSha, []);\n  }\n  const stories = await loadStoryImportPaths(input.cwd, input.buildDir).catch(() => {\n    throw new Error(\"story-index-unreadable\");\n  });\n  const graph = await loadDepGraph(statsPathFor(input.cwd, input.buildDir, input.statsFile));\n  if (!graph) {\n    throw new Error(\"dependency-graph-unavailable\");\n  }\n  const affected = traceAffected(graph, changed, stories, { untraced: input.untraced });\n  if (affected === null) {\n    throw new Error(\"global-file-changed\");\n  }\n  return selectiveResult(changed, input.baseSha, affected);\n}\n\n/** Selective computation with reason-string failures mapped to full renders. */\nasync function computeSelective(input: AffectedInput): Promise<AffectedResult> {\n  let changed: string[] = [];\n  try {\n    changed = guardedChanged(input);\n    return await traceSelective(input, changed);\n  } catch (error) {\n    const reason = error instanceof Error ? error.message : \"affected-computation-failed\";\n    return fullResult(changed, input.baseSha, reason);\n  }\n}\n\nexport type { AffectedInput, AffectedResult, DepGraph, StoryLike, TraceOptions } from \"./types.ts\";\nexport {\n  changedFiles,\n  gitBranchName,\n  gitHeadSha,\n  gitRepoStatus,\n  isShallowRepo,\n  LOCAL_BRANCH,\n  LOCAL_SHA_PREFIX,\n  localSha,\n  MAX_CHANGED_FILES,\n} from \"./git.ts\";\nexport type { GitRepoStatus } from \"./git.ts\";\nexport {\n  buildGraph,\n  graphModulesFor,\n  loadDepGraph,\n  loadStoryImportPaths,\n  normalizePath,\n  STATS_FILENAME,\n  statsPathFor,\n} from \"./stats.ts\";\nexport { matchesAnyGlob, traceAffected } from \"./trace.ts\";\nexport { selectAffectedStories, type StoryPartition } from \"./select.ts\";\n"],"mappings":";;;;;;;;;;;;;;;AAYA,eAAsB,gBAAgB,OAA+C;CACnF,IAAI;EACF,OAAO,MAAM,iBAAiB,KAAK;CACrC,QAAQ;EACN,OAAO,WAAW,CAAC,GAAG,MAAM,SAAS,6BAA6B;CACpE;AACF;;AAGA,SAAS,WAAW,SAAmB,aAA4B,QAAgC;CACjG,OAAO;EAAE,qBAAqB;EAAM,cAAc;EAAS;EAAa,YAAY;CAAO;AAC7F;;AAGA,SAAS,gBAAgB,SAAmB,aAAqB,OAAiC;CAChG,OAAO;EAAE,qBAAqB;EAAO,cAAc;EAAS;EAAa,YAAY;CAAK;AAC5F;;AAGA,SAAS,eAAe,OAAgC;CACtD,MAAM,OAAO,cAAc,MAAM,GAAG;CACpC,IAAI,SAAS,MACX,MAAM,IAAI,MAAM,SAAS,YAAY,kBAAkB,gBAAgB;CAEzE,MAAM,UAAU,aAAa,MAAM,KAAK,MAAM,SAAS,MAAM,OAAO;CACpE,IAAI,QAAQ,SAAA,KACV,MAAM,IAAI,MAAM,wBAAwB;CAE1C,OAAO;AACT;;AAGA,eAAe,eAAe,OAAsB,SAA4C;CAC9F,IAAI,QAAQ,WAAW,GACrB,OAAO,gBAAgB,SAAS,MAAM,SAAS,CAAC,CAAC;CAEnD,MAAM,UAAU,MAAM,qBAAqB,MAAM,KAAK,MAAM,QAAQ,CAAC,CAAC,YAAY;EAChF,MAAM,IAAI,MAAM,wBAAwB;CAC1C,CAAC;CACD,MAAM,QAAQ,MAAM,aAAa,aAAa,MAAM,KAAK,MAAM,UAAU,MAAM,SAAS,CAAC;CACzF,IAAI,CAAC,OACH,MAAM,IAAI,MAAM,8BAA8B;CAEhD,MAAM,WAAW,cAAc,OAAO,SAAS,SAAS,EAAE,UAAU,MAAM,SAAS,CAAC;CACpF,IAAI,aAAa,MACf,MAAM,IAAI,MAAM,qBAAqB;CAEvC,OAAO,gBAAgB,SAAS,MAAM,SAAS,QAAQ;AACzD;;AAGA,eAAe,iBAAiB,OAA+C;CAC7E,IAAI,UAAoB,CAAC;CACzB,IAAI;EACF,UAAU,eAAe,KAAK;EAC9B,OAAO,MAAM,eAAe,OAAO,OAAO;CAC5C,SAAS,OAAO;EACd,MAAM,SAAS,iBAAiB,QAAQ,MAAM,UAAU;EACxD,OAAO,WAAW,SAAS,MAAM,SAAS,MAAM;CAClD;AACF"}

package/dist/select.d.mts

@@ -0,0 +1,24 @@
+import __tsdown_shims_path from 'node:path';
+import __tsdown_shims_url from 'node:url';
+import { StoryLike } from "./types.mjs";
+//#region src/select.d.ts
+/** Stories split into render-now versus inherit-from-baseline sets. */
+interface StoryPartition<T> {
+  /** Stories to capture in this build. */
+  render: T[];
+  /** Stories to inherit unchanged from their baseline. */
+  inherit: T[];
+}
+/**
+ * Partition stories into render versus inherit sets.
+ *
+ * Stories without an import path always render (they cannot be matched).
+ * A `null` affected set renders everything (full capture).
+ *
+ * @param stories - Discovered stories for the build.
+ * @param affectedImportPaths - Affected import paths, or `null` for full.
+ */
+declare function selectAffectedStories<T extends StoryLike>(stories: readonly T[], affectedImportPaths: readonly string[] | null): StoryPartition<T>;
+//#endregion
+export { StoryPartition, selectAffectedStories };
+//# sourceMappingURL=select.d.mts.map

package/dist/select.mjs

@@ -0,0 +1,44 @@
+import "node:path";
+import "node:url";
+import.meta.url;
+import { normalizePath } from "./stats.mjs";
+//#region src/select.ts
+/** Sort stories into render versus inherit buckets for an affected set. */
+function partitionByPath(stories, affected, render, inherit) {
+	for (const story of stories) {
+		const path = storyPath(story);
+		if (path === null || affected.has(path)) render.push(story);
+		else inherit.push(story);
+	}
+}
+/** Import path of a story record, normalized for affected comparison. */
+function storyPath(story) {
+	if (typeof story.importPath !== "string" || story.importPath.length === 0) return null;
+	return normalizePath(story.importPath);
+}
+/**
+* Partition stories into render versus inherit sets.
+*
+* Stories without an import path always render (they cannot be matched).
+* A `null` affected set renders everything (full capture).
+*
+* @param stories - Discovered stories for the build.
+* @param affectedImportPaths - Affected import paths, or `null` for full.
+*/
+function selectAffectedStories(stories, affectedImportPaths) {
+	const render = [];
+	const inherit = [];
+	if (affectedImportPaths === null) return {
+		render: [...stories],
+		inherit
+	};
+	partitionByPath(stories, new Set(affectedImportPaths.map((path) => normalizePath(path))), render, inherit);
+	return {
+		render,
+		inherit
+	};
+}
+//#endregion
+export { selectAffectedStories };
+
+//# sourceMappingURL=select.mjs.map

package/dist/select.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"select.mjs","names":[],"sources":["../src/select.ts"],"sourcesContent":["import { normalizePath } from \"./stats.ts\";\nimport type { StoryLike } from \"./types.ts\";\n\n/** Stories split into render-now versus inherit-from-baseline sets. */\nexport interface StoryPartition<T> {\n  /** Stories to capture in this build. */\n  render: T[];\n  /** Stories to inherit unchanged from their baseline. */\n  inherit: T[];\n}\n\n/** Sort stories into render versus inherit buckets for an affected set. */\nfunction partitionByPath<T extends StoryLike>(\n  stories: readonly T[],\n  affected: ReadonlySet<string>,\n  render: T[],\n  inherit: T[],\n): void {\n  for (const story of stories) {\n    const path = storyPath(story);\n    if (path === null || affected.has(path)) {\n      render.push(story);\n    } else {\n      inherit.push(story);\n    }\n  }\n}\n\n/** Import path of a story record, normalized for affected comparison. */\nfunction storyPath(story: StoryLike): string | null {\n  if (typeof story.importPath !== \"string\" || story.importPath.length === 0) {\n    return null;\n  }\n  return normalizePath(story.importPath);\n}\n\n/**\n * Partition stories into render versus inherit sets.\n *\n * Stories without an import path always render (they cannot be matched).\n * A `null` affected set renders everything (full capture).\n *\n * @param stories - Discovered stories for the build.\n * @param affectedImportPaths - Affected import paths, or `null` for full.\n */\nexport function selectAffectedStories<T extends StoryLike>(\n  stories: readonly T[],\n  affectedImportPaths: readonly string[] | null,\n): StoryPartition<T> {\n  const render: T[] = [];\n  const inherit: T[] = [];\n  if (affectedImportPaths === null) {\n    return { render: [...stories], inherit };\n  }\n  partitionByPath(\n    stories,\n    new Set(affectedImportPaths.map((path) => normalizePath(path))),\n    render,\n    inherit,\n  );\n  return { render, inherit };\n}\n"],"mappings":";;;;;;AAYA,SAAS,gBACP,SACA,UACA,QACA,SACM;CACN,KAAK,MAAM,SAAS,SAAS;EAC3B,MAAM,OAAO,UAAU,KAAK;EAC5B,IAAI,SAAS,QAAQ,SAAS,IAAI,IAAI,GACpC,OAAO,KAAK,KAAK;OAEjB,QAAQ,KAAK,KAAK;CAEtB;AACF;;AAGA,SAAS,UAAU,OAAiC;CAClD,IAAI,OAAO,MAAM,eAAe,YAAY,MAAM,WAAW,WAAW,GACtE,OAAO;CAET,OAAO,cAAc,MAAM,UAAU;AACvC;;;;;;;;;;AAWA,SAAgB,sBACd,SACA,qBACmB;CACnB,MAAM,SAAc,CAAC;CACrB,MAAM,UAAe,CAAC;CACtB,IAAI,wBAAwB,MAC1B,OAAO;EAAE,QAAQ,CAAC,GAAG,OAAO;EAAG;CAAQ;CAEzC,gBACE,SACA,IAAI,IAAI,oBAAoB,KAAK,SAAS,cAAc,IAAI,CAAC,CAAC,GAC9D,QACA,OACF;CACA,OAAO;EAAE;EAAQ;CAAQ;AAC3B"}

package/dist/stats.d.mts

@@ -0,0 +1,47 @@
+import __tsdown_shims_path from 'node:path';
+import __tsdown_shims_url from 'node:url';
+import { DepGraph } from "./types.mjs";
+//#region src/stats.d.ts
+/** Basename of the Vite stats file emitted next to a built Storybook. */
+declare const STATS_FILENAME = "preview-stats.json";
+/** A single module entry in a stats file (Vite or Webpack shape). */
+interface StatsModule {
+  id?: unknown;
+  name?: unknown;
+  identifier?: unknown;
+  imported?: unknown;
+  importedIds?: unknown;
+  dependencies?: unknown;
+  reasons?: unknown;
+}
+/** Normalize a stats path to a repo-relative posix form for comparison. */
+declare function normalizePath(value: string): string;
+/**
+ * Build a bidirectional dependency graph from parsed stats modules.
+ *
+ * @param entries - Module entries from a Vite or Webpack stats document.
+ * @returns Bidirectional graph, or `null` when no usable edges exist.
+ */
+declare function buildGraph(entries: StatsModule[]): DepGraph | null;
+/**
+ * Load and parse a stats file into a dependency graph.
+ *
+ * @param statsPath - Absolute or cwd-relative path to the stats JSON file.
+ * @returns Graph, or `null` when the file is missing or unrecognized.
+ */
+declare function loadDepGraph(statsPath: string): Promise<DepGraph | null>;
+/** Resolve the stats file path for a built Storybook directory. */
+declare function statsPathFor(cwd: string, buildDir: string, override?: string): string;
+/**
+ * Load the deduplicated story import paths from a built Storybook's index.
+ *
+ * @param cwd - Repository root.
+ * @param buildDir - Built Storybook directory.
+ * @returns Normalized import paths; throws when no index is readable.
+ */
+declare function loadStoryImportPaths(cwd: string, buildDir: string): Promise<string[]>;
+/** Find graph modules referring to repo-relative file `target`. */
+declare function graphModulesFor(graph: DepGraph, target: string): string[];
+//#endregion
+export { STATS_FILENAME, buildGraph, graphModulesFor, loadDepGraph, loadStoryImportPaths, normalizePath, statsPathFor };
+//# sourceMappingURL=stats.d.mts.map

package/dist/stats.mjs

@@ -0,0 +1,161 @@
+import "node:path";
+import "node:url";
+import.meta.url;
+import { readFile } from "node:fs/promises";
+import { join, resolve } from "node:path";
+//#region src/stats.ts
+/** Basename of the Vite stats file emitted next to a built Storybook. */
+const STATS_FILENAME = "preview-stats.json";
+/** Candidate index files listing a built Storybook's stories. */
+const INDEX_CANDIDATES = ["stories.json", "index.json"];
+/** Normalize a stats path to a repo-relative posix form for comparison. */
+function normalizePath(value) {
+	return value.replaceAll("\\", "/").replaceAll(/^\.\//gu, "").replaceAll(/^\//gu, "");
+}
+/** True when stats module `candidate` refers to repo-relative file `target`. */
+function matchesFile(candidate, target) {
+	if (candidate === target) return true;
+	return candidate.endsWith(`/${target}`);
+}
+/** Coerce an unknown stats value to a list of normalized paths. */
+function asPathList(value) {
+	if (!Array.isArray(value)) return [];
+	const paths = [];
+	for (const entry of value) if (typeof entry === "string" && entry.length > 0) paths.push(normalizePath(entry));
+	return paths;
+}
+/** Read a non-empty string field from a stats module entry. */
+function stringField(entry, key) {
+	const value = entry[key];
+	return typeof value === "string" && value.length > 0 ? value : null;
+}
+/** Read the file a stats module entry refers to, if any. */
+function moduleFile(entry) {
+	const raw = stringField(entry, "id") ?? stringField(entry, "name") ?? stringField(entry, "identifier");
+	return raw === null ? null : normalizePath(raw);
+}
+/** Forward imports declared by a stats module entry, if any. */
+function moduleImports(entry) {
+	return asPathList(entry.imported ?? entry.importedIds ?? entry.dependencies);
+}
+/** Dependent names declared via Webpack-style `reasons`, if any. */
+function moduleReasonNames(entry) {
+	if (!Array.isArray(entry.reasons)) return [];
+	const names = [];
+	for (const reason of entry.reasons) if (typeof reason === "object" && reason !== null) {
+		const record = reason;
+		const name = record["moduleName"] ?? record["module"];
+		if (typeof name === "string" && name.length > 0) names.push(normalizePath(name));
+	}
+	return names;
+}
+/** Attach a record-shaped module entry to its name. */
+function entryWithName(name, value) {
+	if (typeof value === "object" && value !== null) return {
+		name,
+		...value
+	};
+	return { name };
+}
+/** Extract module entries from a parsed stats document of unknown shape. */
+function moduleEntries(document) {
+	if (typeof document !== "object" || document === null) return [];
+	const raw = document["modules"];
+	if (Array.isArray(raw)) return raw.filter((entry) => typeof entry === "object");
+	if (typeof raw === "object" && raw !== null) return Object.entries(raw).map(([name, value]) => entryWithName(name, value));
+	return [];
+}
+/** Record one directed edge in the graph under construction. */
+function addEdge(imports, importedBy, from, to) {
+	if (from === to) return;
+	const forward = imports.get(from) ?? /* @__PURE__ */ new Set();
+	forward.add(to);
+	imports.set(from, forward);
+	const reverse = importedBy.get(to) ?? /* @__PURE__ */ new Set();
+	reverse.add(from);
+	importedBy.set(to, reverse);
+}
+/** Add one stats entry's edges to the graph under construction. */
+function addEntryEdges(imports, importedBy, entry) {
+	const file = moduleFile(entry);
+	if (!file) return;
+	for (const imported of moduleImports(entry)) addEdge(imports, importedBy, file, imported);
+	for (const dependent of moduleReasonNames(entry)) addEdge(imports, importedBy, dependent, file);
+}
+function toGraph(imports, importedBy) {
+	return {
+		imports: Object.fromEntries([...imports].map(([file, set]) => [file, [...set].toSorted()])),
+		importedBy: Object.fromEntries([...importedBy].map(([file, set]) => [file, [...set].toSorted()]))
+	};
+}
+/**
+* Build a bidirectional dependency graph from parsed stats modules.
+*
+* @param entries - Module entries from a Vite or Webpack stats document.
+* @returns Bidirectional graph, or `null` when no usable edges exist.
+*/
+function buildGraph(entries) {
+	const imports = /* @__PURE__ */ new Map();
+	const importedBy = /* @__PURE__ */ new Map();
+	for (const entry of entries) addEntryEdges(imports, importedBy, entry);
+	if (imports.size === 0) return null;
+	return toGraph(imports, importedBy);
+}
+/**
+* Load and parse a stats file into a dependency graph.
+*
+* @param statsPath - Absolute or cwd-relative path to the stats JSON file.
+* @returns Graph, or `null` when the file is missing or unrecognized.
+*/
+async function loadDepGraph(statsPath) {
+	let raw;
+	try {
+		raw = await readFile(statsPath, "utf8");
+	} catch {
+		return null;
+	}
+	let document;
+	try {
+		document = JSON.parse(raw);
+	} catch {
+		return null;
+	}
+	return buildGraph(moduleEntries(document));
+}
+/** Resolve the stats file path for a built Storybook directory. */
+function statsPathFor(cwd, buildDir, override) {
+	if (override) return resolve(cwd, override);
+	return join(resolve(cwd, buildDir), STATS_FILENAME);
+}
+/**
+* Load the deduplicated story import paths from a built Storybook's index.
+*
+* @param cwd - Repository root.
+* @param buildDir - Built Storybook directory.
+* @returns Normalized import paths; throws when no index is readable.
+*/
+async function loadStoryImportPaths(cwd, buildDir) {
+	const root = resolve(cwd, buildDir);
+	const found = (await Promise.all(INDEX_CANDIDATES.map(async (name) => {
+		try {
+			return JSON.parse(await readFile(join(root, name), "utf8"));
+		} catch {
+			return null;
+		}
+	}))).find((document) => document !== null);
+	if (!found?.entries) throw new Error(`No Storybook index found in ${root}`);
+	const paths = /* @__PURE__ */ new Set();
+	for (const entry of Object.values(found.entries)) if (typeof entry.importPath === "string" && entry.importPath.length > 0) paths.add(normalizePath(entry.importPath));
+	return [...paths].toSorted();
+}
+/** Find graph modules referring to repo-relative file `target`. */
+function graphModulesFor(graph, target) {
+	const matched = [];
+	for (const file of Object.keys(graph.imports)) if (matchesFile(file, target)) matched.push(file);
+	for (const file of Object.keys(graph.importedBy)) if (matchesFile(file, target) && !matched.includes(file)) matched.push(file);
+	return matched;
+}
+//#endregion
+export { STATS_FILENAME, buildGraph, graphModulesFor, loadDepGraph, loadStoryImportPaths, normalizePath, statsPathFor };
+
+//# sourceMappingURL=stats.mjs.map

package/dist/stats.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"stats.mjs","names":["record"],"sources":["../src/stats.ts"],"sourcesContent":["import { readFile } from \"node:fs/promises\";\nimport { join, resolve } from \"node:path\";\nimport type { DepGraph } from \"./types.ts\";\n\n/** Basename of the Vite stats file emitted next to a built Storybook. */\nexport const STATS_FILENAME = \"preview-stats.json\";\n\n/** Candidate index files listing a built Storybook's stories. */\nconst INDEX_CANDIDATES = [\"stories.json\", \"index.json\"];\n\n/** A single module entry in a stats file (Vite or Webpack shape). */\ninterface StatsModule {\n  id?: unknown;\n  name?: unknown;\n  identifier?: unknown;\n  imported?: unknown;\n  importedIds?: unknown;\n  dependencies?: unknown;\n  reasons?: unknown;\n}\n\ninterface StoryIndex {\n  entries?: Record<string, { importPath?: unknown }>;\n}\n\n/** Normalize a stats path to a repo-relative posix form for comparison. */\nexport function normalizePath(value: string): string {\n  return value.replaceAll(\"\\\\\", \"/\").replaceAll(/^\\.\\//gu, \"\").replaceAll(/^\\//gu, \"\");\n}\n\n/** True when stats module `candidate` refers to repo-relative file `target`. */\nfunction matchesFile(candidate: string, target: string): boolean {\n  if (candidate === target) {\n    return true;\n  }\n  return candidate.endsWith(`/${target}`);\n}\n\n/** Coerce an unknown stats value to a list of normalized paths. */\nfunction asPathList(value: unknown): string[] {\n  if (!Array.isArray(value)) {\n    return [];\n  }\n  const paths: string[] = [];\n  for (const entry of value) {\n    if (typeof entry === \"string\" && entry.length > 0) {\n      paths.push(normalizePath(entry));\n    }\n  }\n  return paths;\n}\n\n/** Read a non-empty string field from a stats module entry. */\nfunction stringField(entry: StatsModule, key: \"id\" | \"name\" | \"identifier\"): string | null {\n  const value = entry[key];\n  return typeof value === \"string\" && value.length > 0 ? value : null;\n}\n\n/** Read the file a stats module entry refers to, if any. */\nfunction moduleFile(entry: StatsModule): string | null {\n  const raw =\n    stringField(entry, \"id\") ?? stringField(entry, \"name\") ?? stringField(entry, \"identifier\");\n  return raw === null ? null : normalizePath(raw);\n}\n\n/** Forward imports declared by a stats module entry, if any. */\nfunction moduleImports(entry: StatsModule): string[] {\n  return asPathList(entry.imported ?? entry.importedIds ?? entry.dependencies);\n}\n\n/** Dependent names declared via Webpack-style `reasons`, if any. */\nfunction moduleReasonNames(entry: StatsModule): string[] {\n  if (!Array.isArray(entry.reasons)) {\n    return [];\n  }\n  const names: string[] = [];\n  for (const reason of entry.reasons) {\n    if (typeof reason === \"object\" && reason !== null) {\n      const record = reason as Record<string, unknown>;\n      const name = record[\"moduleName\"] ?? record[\"module\"];\n      if (typeof name === \"string\" && name.length > 0) {\n        names.push(normalizePath(name));\n      }\n    }\n  }\n  return names;\n}\n\n/** Attach a record-shaped module entry to its name. */\nfunction entryWithName(name: string, value: unknown): StatsModule {\n  if (typeof value === \"object\" && value !== null) {\n    return { name, ...(value as StatsModule) };\n  }\n  return { name };\n}\n\n/** Extract module entries from a parsed stats document of unknown shape. */\nfunction moduleEntries(document: unknown): StatsModule[] {\n  if (typeof document !== \"object\" || document === null) {\n    return [];\n  }\n  const record = document as Record<string, unknown>;\n  const raw = record[\"modules\"];\n  if (Array.isArray(raw)) {\n    return raw.filter((entry): entry is StatsModule => typeof entry === \"object\");\n  }\n  if (typeof raw === \"object\" && raw !== null) {\n    return Object.entries(raw as Record<string, unknown>).map(([name, value]) =>\n      entryWithName(name, value),\n    );\n  }\n  return [];\n}\n\n/** Record one directed edge in the graph under construction. */\nfunction addEdge(\n  imports: Map<string, Set<string>>,\n  importedBy: Map<string, Set<string>>,\n  from: string,\n  to: string,\n): void {\n  if (from === to) {\n    return;\n  }\n  const forward = imports.get(from) ?? new Set<string>();\n  forward.add(to);\n  imports.set(from, forward);\n  const reverse = importedBy.get(to) ?? new Set<string>();\n  reverse.add(from);\n  importedBy.set(to, reverse);\n}\n\n/** Add one stats entry's edges to the graph under construction. */\nfunction addEntryEdges(\n  imports: Map<string, Set<string>>,\n  importedBy: Map<string, Set<string>>,\n  entry: StatsModule,\n): void {\n  const file = moduleFile(entry);\n  if (!file) {\n    return;\n  }\n  for (const imported of moduleImports(entry)) {\n    addEdge(imports, importedBy, file, imported);\n  }\n  for (const dependent of moduleReasonNames(entry)) {\n    addEdge(imports, importedBy, dependent, file);\n  }\n}\nfunction toGraph(\n  imports: Map<string, Set<string>>,\n  importedBy: Map<string, Set<string>>,\n): DepGraph {\n  return {\n    imports: Object.fromEntries([...imports].map(([file, set]) => [file, [...set].toSorted()])),\n    importedBy: Object.fromEntries(\n      [...importedBy].map(([file, set]) => [file, [...set].toSorted()]),\n    ),\n  };\n}\n\n/**\n * Build a bidirectional dependency graph from parsed stats modules.\n *\n * @param entries - Module entries from a Vite or Webpack stats document.\n * @returns Bidirectional graph, or `null` when no usable edges exist.\n */\nexport function buildGraph(entries: StatsModule[]): DepGraph | null {\n  const imports = new Map<string, Set<string>>();\n  const importedBy = new Map<string, Set<string>>();\n  for (const entry of entries) {\n    addEntryEdges(imports, importedBy, entry);\n  }\n  if (imports.size === 0) {\n    return null;\n  }\n  return toGraph(imports, importedBy);\n}\n\n/**\n * Load and parse a stats file into a dependency graph.\n *\n * @param statsPath - Absolute or cwd-relative path to the stats JSON file.\n * @returns Graph, or `null` when the file is missing or unrecognized.\n */\nexport async function loadDepGraph(statsPath: string): Promise<DepGraph | null> {\n  let raw: string;\n  try {\n    raw = await readFile(statsPath, \"utf8\");\n  } catch {\n    return null;\n  }\n  let document: unknown;\n  try {\n    document = JSON.parse(raw) as unknown;\n  } catch {\n    return null;\n  }\n  return buildGraph(moduleEntries(document));\n}\n\n/** Resolve the stats file path for a built Storybook directory. */\nexport function statsPathFor(cwd: string, buildDir: string, override?: string): string {\n  if (override) {\n    return resolve(cwd, override);\n  }\n  return join(resolve(cwd, buildDir), STATS_FILENAME);\n}\n\n/**\n * Load the deduplicated story import paths from a built Storybook's index.\n *\n * @param cwd - Repository root.\n * @param buildDir - Built Storybook directory.\n * @returns Normalized import paths; throws when no index is readable.\n */\nexport async function loadStoryImportPaths(cwd: string, buildDir: string): Promise<string[]> {\n  const root = resolve(cwd, buildDir);\n  const documents = await Promise.all(\n    INDEX_CANDIDATES.map(async (name) => {\n      try {\n        return JSON.parse(await readFile(join(root, name), \"utf8\")) as StoryIndex;\n      } catch {\n        return null;\n      }\n    }),\n  );\n  const found = documents.find((document) => document !== null);\n  if (!found?.entries) {\n    throw new Error(`No Storybook index found in ${root}`);\n  }\n  const paths = new Set<string>();\n  for (const entry of Object.values(found.entries)) {\n    if (typeof entry.importPath === \"string\" && entry.importPath.length > 0) {\n      paths.add(normalizePath(entry.importPath));\n    }\n  }\n  return [...paths].toSorted();\n}\n\n/** Find graph modules referring to repo-relative file `target`. */\nexport function graphModulesFor(graph: DepGraph, target: string): string[] {\n  const matched: string[] = [];\n  for (const file of Object.keys(graph.imports)) {\n    if (matchesFile(file, target)) {\n      matched.push(file);\n    }\n  }\n  for (const file of Object.keys(graph.importedBy)) {\n    if (matchesFile(file, target) && !matched.includes(file)) {\n      matched.push(file);\n    }\n  }\n  return matched;\n}\n"],"mappings":"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"}

package/dist/trace.d.mts

@@ -0,0 +1,19 @@
+import __tsdown_shims_path from 'node:path';
+import __tsdown_shims_url from 'node:url';
+import { DepGraph, TraceOptions } from "./types.mjs";
+//#region src/trace.d.ts
+/** True when `path` matches any of the given glob patterns. */
+declare function matchesAnyGlob(path: string, patterns: readonly string[]): boolean;
+/**
+ * Trace changed files through the dependency graph to story files.
+ *
+ * @param graph - Bidirectional module graph of the built Storybook.
+ * @param changedFiles - Repo-relative changed files.
+ * @param storyFiles - Normalized story import paths from the story index.
+ * @param options - Untraced globs excluded from tracing.
+ * @returns Affected story files, or `null` when everything must render.
+ */
+declare function traceAffected(graph: DepGraph, changedFiles: string[], storyFiles: readonly string[], options?: TraceOptions): string[] | null;
+//#endregion
+export { matchesAnyGlob, traceAffected };
+//# sourceMappingURL=trace.d.mts.map

package/dist/trace.mjs

@@ -0,0 +1,166 @@
+import "node:path";
+import "node:url";
+import.meta.url;
+import { graphModulesFor } from "./stats.mjs";
+//#region src/trace.ts
+/** Basenames whose change invalidates every story (global render setup). */
+const GLOBAL_BASENAMES = /* @__PURE__ */ new Set([
+	"preview.js",
+	"preview.jsx",
+	"preview.ts",
+	"preview.tsx",
+	"preview.mjs",
+	"preview.cjs",
+	"preview.mts",
+	"preview.cts",
+	"manager.js",
+	"manager.jsx",
+	"manager.ts",
+	"manager.tsx"
+]);
+/** Config basenames whose change may add, remove, or re-glob stories. */
+const CONFIG_BASENAMES = /* @__PURE__ */ new Set([
+	"main.js",
+	"main.ts",
+	"main.mjs",
+	"main.cjs",
+	"main.mts"
+]);
+/** Lockfiles whose change means dependency versions cannot be resolved. */
+const LOCKFILE_BASENAMES = /* @__PURE__ */ new Set([
+	"package.json",
+	"package-lock.json",
+	"pnpm-lock.yaml",
+	"yarn.lock",
+	"bun.lock",
+	"bun.lockb",
+	"deno.lock"
+]);
+/** Basename of a repo-relative path. */
+function basename(path) {
+	const index = path.lastIndexOf("/");
+	return index === -1 ? path : path.slice(index + 1);
+}
+/** True when a changed file forces a full render of every story. */
+function isGlobalFile(path) {
+	const base = basename(path);
+	if (GLOBAL_BASENAMES.has(base) || CONFIG_BASENAMES.has(base) || LOCKFILE_BASENAMES.has(base)) return true;
+	return path.includes(".storybook/") && (CONFIG_BASENAMES.has(base) || GLOBAL_BASENAMES.has(base));
+}
+/** Regex-special chars escaped when translating globs (kept discrete: no `${`). */
+const REGEX_SPECIALS = /* @__PURE__ */ new Set([
+	"+",
+	"^",
+	"$",
+	"{",
+	"}",
+	"(",
+	")",
+	"|",
+	"[",
+	"]",
+	"\\",
+	"."
+]);
+/** Translate one glob token at `index` into regex text and advance width. */
+function translateGlobToken(pattern, index) {
+	const char = pattern[index];
+	if (char === "*") return pattern[index + 1] === "*" ? {
+		text: ".*",
+		advance: 2
+	} : {
+		text: "[^/]*",
+		advance: 1
+	};
+	if (char === "?") return {
+		text: "[^/]",
+		advance: 1
+	};
+	if (char !== void 0 && REGEX_SPECIALS.has(char)) return {
+		text: `\\${char}`,
+		advance: 1
+	};
+	return {
+		text: char ?? "",
+		advance: 1
+	};
+}
+/** Escape regex syntax while translating `*`, `**`, and `?` globs. */
+function globToRegExp(pattern) {
+	const parts = [];
+	let index = 0;
+	while (index < pattern.length) {
+		const token = translateGlobToken(pattern, index);
+		parts.push(token.text);
+		index += token.advance;
+	}
+	return new RegExp(`^${parts.join("")}$`, "u");
+}
+/** True when `path` matches any of the given glob patterns. */
+function matchesAnyGlob(path, patterns) {
+	return patterns.some((pattern) => globToRegExp(pattern).test(path));
+}
+/** Queue reverse-edge dependents not yet visited. */
+function pushUnseen(seen, pending, dependents) {
+	for (const dependent of dependents) if (!seen.has(dependent)) {
+		seen.add(dependent);
+		pending.push(dependent);
+	}
+}
+/** Fold one graph node into the affected set and queue its dependents. */
+function processNode(graph, storyOf, seen, pending, affected, current) {
+	const story = storyOf.get(current);
+	if (story !== void 0) affected.add(story);
+	pushUnseen(seen, pending, graph.importedBy[current] ?? []);
+}
+/** Collect every story file reachable from `roots` via reverse edges. */
+function reachableStories(graph, roots, storyOf) {
+	const seen = new Set(roots);
+	const pending = [...roots];
+	const affected = /* @__PURE__ */ new Set();
+	while (pending.length > 0) {
+		const current = pending.pop();
+		if (current === void 0) break;
+		processNode(graph, storyOf, seen, pending, affected, current);
+	}
+	return affected;
+}
+/** Map every graph node to its story file (suffix match for absolute stats). */
+function storyNodeMap(graph, storyFiles) {
+	const nodes = /* @__PURE__ */ new Set([...Object.keys(graph.imports), ...Object.keys(graph.importedBy)]);
+	const map = /* @__PURE__ */ new Map();
+	for (const story of storyFiles) for (const node of nodes) if ((node === story || node.endsWith(`/${story}`)) && !map.has(node)) map.set(node, story);
+	return map;
+}
+/** Root modules for tracing: changed modules plus directly changed stories. */
+function traceRoots(graph, relevant, storyOf) {
+	const roots = changedModules(graph, relevant);
+	for (const file of relevant) if (storyOf.has(file)) roots.push(file);
+	return [...new Set(roots)];
+}
+/** Map changed files to graph modules, dropping files outside the graph. */
+function changedModules(graph, changed) {
+	const modules = /* @__PURE__ */ new Set();
+	for (const file of changed) for (const module of graphModulesFor(graph, file)) modules.add(module);
+	return [...modules];
+}
+/**
+* Trace changed files through the dependency graph to story files.
+*
+* @param graph - Bidirectional module graph of the built Storybook.
+* @param changedFiles - Repo-relative changed files.
+* @param storyFiles - Normalized story import paths from the story index.
+* @param options - Untraced globs excluded from tracing.
+* @returns Affected story files, or `null` when everything must render.
+*/
+function traceAffected(graph, changedFiles, storyFiles, options = {}) {
+	const untraced = options.untraced ?? [];
+	const relevant = changedFiles.filter((file) => !matchesAnyGlob(file, untraced));
+	if (relevant.find((file) => isGlobalFile(file)) !== void 0) return null;
+	const storyOf = storyNodeMap(graph, storyFiles);
+	return [...reachableStories(graph, traceRoots(graph, relevant, storyOf), storyOf)].toSorted();
+}
+//#endregion
+export { matchesAnyGlob, traceAffected };
+
+//# sourceMappingURL=trace.mjs.map

package/dist/trace.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"trace.mjs","names":[],"sources":["../src/trace.ts"],"sourcesContent":["import { graphModulesFor } from \"./stats.ts\";\nimport type { DepGraph, TraceOptions } from \"./types.ts\";\n\n/** Basenames whose change invalidates every story (global render setup). */\nconst GLOBAL_BASENAMES = new Set([\n  \"preview.js\",\n  \"preview.jsx\",\n  \"preview.ts\",\n  \"preview.tsx\",\n  \"preview.mjs\",\n  \"preview.cjs\",\n  \"preview.mts\",\n  \"preview.cts\",\n  \"manager.js\",\n  \"manager.jsx\",\n  \"manager.ts\",\n  \"manager.tsx\",\n]);\n\n/** Config basenames whose change may add, remove, or re-glob stories. */\nconst CONFIG_BASENAMES = new Set([\"main.js\", \"main.ts\", \"main.mjs\", \"main.cjs\", \"main.mts\"]);\n\n/** Lockfiles whose change means dependency versions cannot be resolved. */\nconst LOCKFILE_BASENAMES = new Set([\n  \"package.json\",\n  \"package-lock.json\",\n  \"pnpm-lock.yaml\",\n  \"yarn.lock\",\n  \"bun.lock\",\n  \"bun.lockb\",\n  \"deno.lock\",\n]);\n\n/** Basename of a repo-relative path. */\nfunction basename(path: string): string {\n  const index = path.lastIndexOf(\"/\");\n  return index === -1 ? path : path.slice(index + 1);\n}\n\n/** True when a changed file forces a full render of every story. */\nfunction isGlobalFile(path: string): boolean {\n  const base = basename(path);\n  if (GLOBAL_BASENAMES.has(base) || CONFIG_BASENAMES.has(base) || LOCKFILE_BASENAMES.has(base)) {\n    return true;\n  }\n  return path.includes(\".storybook/\") && (CONFIG_BASENAMES.has(base) || GLOBAL_BASENAMES.has(base));\n}\n\n/** Regex-special chars escaped when translating globs (kept discrete: no `${`). */\nconst REGEX_SPECIALS = new Set([\"+\", \"^\", \"$\", \"{\", \"}\", \"(\", \")\", \"|\", \"[\", \"]\", \"\\\\\", \".\"]);\n\n/** Translate one glob token at `index` into regex text and advance width. */\nfunction translateGlobToken(pattern: string, index: number): { text: string; advance: number } {\n  const char = pattern[index];\n  if (char === \"*\") {\n    return pattern[index + 1] === \"*\" ? { text: \".*\", advance: 2 } : { text: \"[^/]*\", advance: 1 };\n  }\n  if (char === \"?\") {\n    return { text: \"[^/]\", advance: 1 };\n  }\n  if (char !== undefined && REGEX_SPECIALS.has(char)) {\n    return { text: `\\\\${char}`, advance: 1 };\n  }\n  return { text: char ?? \"\", advance: 1 };\n}\n\n/** Escape regex syntax while translating `*`, `**`, and `?` globs. */\nfunction globToRegExp(pattern: string): RegExp {\n  const parts: string[] = [];\n  let index = 0;\n  while (index < pattern.length) {\n    const token = translateGlobToken(pattern, index);\n    parts.push(token.text);\n    index += token.advance;\n  }\n  return new RegExp(`^${parts.join(\"\")}$`, \"u\");\n}\n\n/** True when `path` matches any of the given glob patterns. */\nexport function matchesAnyGlob(path: string, patterns: readonly string[]): boolean {\n  return patterns.some((pattern) => globToRegExp(pattern).test(path));\n}\n\n/** Queue reverse-edge dependents not yet visited. */\nfunction pushUnseen(seen: Set<string>, pending: string[], dependents: readonly string[]): void {\n  for (const dependent of dependents) {\n    if (!seen.has(dependent)) {\n      seen.add(dependent);\n      pending.push(dependent);\n    }\n  }\n}\n\n/** Fold one graph node into the affected set and queue its dependents. */\nfunction processNode(\n  graph: DepGraph,\n  storyOf: ReadonlyMap<string, string>,\n  seen: Set<string>,\n  pending: string[],\n  affected: Set<string>,\n  current: string,\n): void {\n  const story = storyOf.get(current);\n  if (story !== undefined) {\n    affected.add(story);\n  }\n  pushUnseen(seen, pending, graph.importedBy[current] ?? []);\n}\n\n/** Collect every story file reachable from `roots` via reverse edges. */\nfunction reachableStories(\n  graph: DepGraph,\n  roots: string[],\n  storyOf: ReadonlyMap<string, string>,\n): Set<string> {\n  const seen = new Set<string>(roots);\n  const pending = [...roots];\n  const affected = new Set<string>();\n  while (pending.length > 0) {\n    const current = pending.pop();\n    if (current === undefined) {\n      break;\n    }\n    processNode(graph, storyOf, seen, pending, affected, current);\n  }\n  return affected;\n}\n\n/** Map every graph node to its story file (suffix match for absolute stats). */\nfunction storyNodeMap(graph: DepGraph, storyFiles: readonly string[]): Map<string, string> {\n  const nodes = new Set([...Object.keys(graph.imports), ...Object.keys(graph.importedBy)]);\n  const map = new Map<string, string>();\n  for (const story of storyFiles) {\n    for (const node of nodes) {\n      if ((node === story || node.endsWith(`/${story}`)) && !map.has(node)) {\n        map.set(node, story);\n      }\n    }\n  }\n  return map;\n}\n/** Root modules for tracing: changed modules plus directly changed stories. */\nfunction traceRoots(\n  graph: DepGraph,\n  relevant: string[],\n  storyOf: ReadonlyMap<string, string>,\n): string[] {\n  const roots = changedModules(graph, relevant);\n  for (const file of relevant) {\n    if (storyOf.has(file)) {\n      roots.push(file);\n    }\n  }\n  return [...new Set(roots)];\n}\n/** Map changed files to graph modules, dropping files outside the graph. */\nfunction changedModules(graph: DepGraph, changed: string[]): string[] {\n  const modules = new Set<string>();\n  for (const file of changed) {\n    for (const module of graphModulesFor(graph, file)) {\n      modules.add(module);\n    }\n  }\n  return [...modules];\n}\n\n/**\n * Trace changed files through the dependency graph to story files.\n *\n * @param graph - Bidirectional module graph of the built Storybook.\n * @param changedFiles - Repo-relative changed files.\n * @param storyFiles - Normalized story import paths from the story index.\n * @param options - Untraced globs excluded from tracing.\n * @returns Affected story files, or `null` when everything must render.\n */\nexport function traceAffected(\n  graph: DepGraph,\n  changedFiles: string[],\n  storyFiles: readonly string[],\n  options: TraceOptions = {},\n): string[] | null {\n  const untraced = options.untraced ?? [];\n  const relevant = changedFiles.filter((file) => !matchesAnyGlob(file, untraced));\n  const forcing = relevant.find((file) => isGlobalFile(file));\n  if (forcing !== undefined) {\n    return null;\n  }\n  const storyOf = storyNodeMap(graph, storyFiles);\n  const roots = traceRoots(graph, relevant, storyOf);\n  return [...reachableStories(graph, roots, storyOf)].toSorted();\n}\n"],"mappings":"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"}

package/dist/types.d.mts

@@ -0,0 +1,57 @@
+import __tsdown_shims_path from 'node:path';
+import __tsdown_shims_url from 'node:url';
+//#region src/types.d.ts
+/**
+ * Shared types for affected capture: dependency graphs, trace inputs, and
+ * the affected-set result. Zero runtime dependencies by design — both the
+ * server (`@storyshelf/core`) and the CI client (`storyshelf`) consume this
+ * package without inheriting each other's dependency trees.
+ */
+/** A module dependency graph with edges in both directions. */
+interface DepGraph {
+  /** Forward edges: file path → files it directly imports. */
+  imports: Record<string, string[]>;
+  /** Reverse edges: file path → files that directly import it. */
+  importedBy: Record<string, string[]>;
+}
+/** Options tuning how changed files trace to stories. */
+interface TraceOptions {
+  /** Glob patterns (e.g. `**literal*.generated.ts`) excluded from tracing. */
+  untraced?: string[];
+}
+/** Inputs for computing the affected story set of a change. */
+interface AffectedInput {
+  /** Repository root used for `git` commands. */
+  cwd: string;
+  /** Built Storybook directory holding `index.json` and stats. */
+  buildDir: string;
+  /** Ancestor commit the current build is compared against. */
+  baseSha: string;
+  /** Current commit being uploaded. */
+  headSha: string;
+  /** Glob patterns excluded from tracing. */
+  untraced?: string[];
+  /** Explicit stats file path (defaults to `<buildDir>/preview-stats.json`). */
+  statsFile?: string;
+}
+/** The affected story set of a change. */
+interface AffectedResult {
+  /**
+   * Story import paths to render, or `null` when the whole Storybook must be
+   * rendered (missing history, global file change, unreadable graph, …).
+   */
+  affectedImportPaths: string[] | null;
+  /** Repo-relative files changed between `baseSha` and `headSha`. */
+  changedFiles: string[];
+  /** Ancestor commit the diff was computed against. */
+  baselineSha: string | null;
+  /** Machine-readable reason for a full render (`null` when selective). */
+  fullReason: string | null;
+}
+/** A story-like record carrying the file it was imported from. */
+interface StoryLike {
+  importPath?: string | null;
+}
+//#endregion
+export { AffectedInput, AffectedResult, DepGraph, StoryLike, TraceOptions };
+//# sourceMappingURL=types.d.mts.map

package/package.json

@@ -0,0 +1,74 @@
+{
+  "name": "@storyshelf/affected",
+  "version": "0.5.3",
+  "description": "Affected capture for StoryShelf: dependency-graph tracing that selects the stories impacted by a change.",
+  "keywords": [
+    "affected",
+    "dependency-graph",
+    "selective",
+    "storybook",
+    "visual-testing"
+  ],
+  "homepage": "https://github.com/GuptaSiddhant/StoryShelf#readme",
+  "bugs": {
+    "url": "https://github.com/GuptaSiddhant/StoryShelf/issues"
+  },
+  "license": "MIT",
+  "author": {
+    "name": "Siddhant Gupta",
+    "url": "https://guptasiddhant.com"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/GuptaSiddhant/StoryShelf.git",
+    "directory": "packages/affected"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "types": "./dist/index.d.mts",
+  "exports": {
+    ".": {
+      "source": "./src/index.ts",
+      "default": "./dist/index.mjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "exports": {
+      ".": "./dist/index.mjs",
+      "./package.json": "./package.json"
+    },
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "dev": "tsdown -w",
+    "fmt": "oxfmt ./src",
+    "lint": "oxlint --type-aware --type-check ./src",
+    "test": "vitest run",
+    "prepublishOnly": "nub run build"
+  },
+  "dependencies": {},
+  "devDependencies": {
+    "@types/node": "^26.0.0",
+    "@vitest/coverage-v8": "^4.0.0",
+    "oxfmt": "^0.65.0",
+    "oxlint": "^1.80.0",
+    "oxlint-tsgolint": "^7.0.2001",
+    "tsdown": "^0.22.14",
+    "typescript": "^7.0.2",
+    "vitest": "^5.0.0"
+  },
+  "jsr": {
+    "runtimeCompat": {
+      "node": true,
+      "deno": true,
+      "bun": true,
+      "workerd": false,
+      "browser": false
+    }
+  }
+}