Skip to content

Build your personal knowledge base with Trilium Notes

fix(skills): match packages by path segment in the bundle analyzer

Elian Dorand49ec6d4d355
diff --git a/.claude/skills/analyzing-backend-bundle/SKILL.md b/.claude/skills/analyzing-backend-bundle/SKILL.md
index 56d38ffff3..752ff5fea0 100644
--- a/.claude/skills/analyzing-backend-bundle/SKILL.md
+++ b/.claude/skills/analyzing-backend-bundle/SKILL.md
@@ -41,9 +41,12 @@ env $ENV node .claude/skills/analyzing-backend-bundle/analyze-bundle.mjs record
node .claude/skills/analyzing-backend-bundle/analyze-bundle.mjs startup \
--meta <meta.json> --loaded /tmp/loaded.txt
-# 3. Explain WHY a package is eager (shortest static import chain from the entry):
+# 3. Explain WHY a package is eager (shortest static import chain from the entry;
+# --from <input> traces from a module that is itself dynamically imported):
node .claude/skills/analyzing-backend-bundle/analyze-bundle.mjs why \
--meta <meta.json> iconv-lite undici
+node .claude/skills/analyzing-backend-bundle/analyze-bundle.mjs why \
+ --meta <meta.json> --from apps/server/src/www.ts highlight.js
# 4. Whole-bundle composition, no boot needed:
node .claude/skills/analyzing-backend-bundle/analyze-bundle.mjs packages --meta <meta.json>
@@ -79,10 +82,18 @@ restoring. (Making buildBackend write per-entry metafiles is the real fix if thi
reasoning that consults `entryPoint`, or assumes "chunk = lazy", overcounts. Conversely the
static-reachability closure *undercounts*: a dynamic import executed during boot loads its
chunk anyway.
-- **"NOT statically reachable" + present in the startup set** is that second pattern and is
- the best kind of finding: the seam already exists, boot-time code defeats it. Find the
- dynamic import that runs at startup and defer it to first use (example: the `/mcp` route
- registering the MCP SDK at boot instead of on first request).
+- **"NOT statically reachable" + present in the startup set** has two causes, and they call
+ for opposite fixes. Either a dynamic import runs during startup — the seam exists and
+ boot-time code defeats it, so defer that call (example: the `/mcp` route registering the
+ MCP SDK at boot instead of on first request) — or the package is reached by an ordinary
+ static chain from a module that is *itself* dynamically imported at boot, such as
+ `apps/server/src/www.ts`. `why --from apps/server/src/www.ts <pkg>` shows the second kind;
+ the fix there is a seam somewhere along the chain it prints.
+- **`why` takes a package name, not a substring.** A bare needle matches at
+ `node_modules/<name>/` or a whole path segment, because plain substring matching silently
+ confuses a package with any file whose name merely ends the same way — "highlight.js" also
+ appears in postcss's `terminal-highlight.js`, which reads as a plausible but entirely
+ fictitious dependency edge.
- **Chunks load as units.** A package can be "lazy" in source but ride in a chunk shared
with eager code; `startup`'s biggest-chunks table shows each chunk's dominant input so
this is visible.
diff --git a/.claude/skills/analyzing-backend-bundle/analyze-bundle.mjs b/.claude/skills/analyzing-backend-bundle/analyze-bundle.mjs
index a14800450c..18c17f39b5 100644
--- a/.claude/skills/analyzing-backend-bundle/analyze-bundle.mjs
+++ b/.claude/skills/analyzing-backend-bundle/analyze-bundle.mjs
@@ -188,8 +188,11 @@ function findEntryInput(meta) {
}
/** BFS over static edges only — a dynamic-import edge is a lazy boundary. */
-function staticReachability(meta) {
- const entry = findEntryInput(meta);
+function staticReachability(meta, from) {
+ const entry = from ?? findEntryInput(meta);
+ if (!meta.inputs[entry]) {
+ throw new Error(`no such input: ${entry}`);
+ }
const prev = new Map([[entry, null]]);
const queue = [entry];
while (queue.length) {
@@ -208,26 +211,50 @@ function staticReachability(meta) {
/** Explains why packages are eager: the shortest static import chain from the entry. */
async function why() {
const meta = JSON.parse(fs.readFileSync(flag("--meta"), "utf8"));
- const prev = staticReachability(meta);
- const needles = args.filter((a) => !a.startsWith("--") && a !== flag("--meta") && a !== flag("--entry"));
+ const from = flag("--from");
+ const prev = staticReachability(meta, from);
+ const needles = args.filter((a) => !a.startsWith("--")
+ && a !== flag("--meta") && a !== flag("--entry") && a !== from);
for (const needle of needles) {
- const target = [...prev.keys()].find((k) => k.includes(needle));
+ const target = findInput([...prev.keys()], needle);
if (!target) {
- console.log(`\n${needle}: NOT statically reachable.`);
- console.log(" If it still loads at boot (per a recording), a dynamic import runs during startup — find and defer that call.");
+ console.log(`\n${needle}: NOT statically reachable from ${from ?? "the entry"}.`);
+ console.log(" Two things still put it in the startup set, both visible only in a recording:");
+ console.log(" - a dynamic import that runs during startup (defer that call), or");
+ console.log(" - a static path from a module that is itself dynamically imported at boot");
+ console.log(` (e.g. www.ts). Re-run with --from <that input> to see the chain.`);
continue;
}
const chain = [];
for (let n = target; n; n = prev.get(n)) {
chain.unshift(n);
}
- console.log(`\n${needle}: eager via`);
+ console.log(`\n${needle} (matched ${target}): eager via`);
for (const p of chain) {
console.log(" " + p);
}
}
}
+/**
+ * Resolves a needle to one input path. A bare package name is matched at its
+ * `node_modules/<name>/` boundary first: plain substring matching confuses a
+ * package with any file whose name ends the same way ("highlight.js" also
+ * matches postcss's `terminal-highlight.js`).
+ */
+function findInput(keys, needle) {
+ if (needle.includes("/")) {
+ return keys.find((k) => k.includes(needle));
+ }
+ const atBoundary = keys.find((k) => k.includes(`node_modules/${needle}/`));
+ if (atBoundary) {
+ return atBoundary;
+ }
+ // Path-segment match only, so a needle never matches the tail of a longer
+ // file name.
+ return keys.find((k) => k.includes(`/${needle}/`) || k.endsWith(`/${needle}`));
+}
+
/** Whole-bundle composition, no recording needed. */
async function packages() {
const meta = JSON.parse(fs.readFileSync(flag("--meta"), "utf8"));