@rollipop/rolldown-debug 1.0.8 → 1.0.10

package/README.md

@@ -0,0 +1,101 @@
+# @rolldown/debug
+
+Utilities and generated TypeScript types for reading Rolldown devtools output.
+
+When `devtools` is enabled, Rolldown writes JSON-lines files to:
+
+```text
+node_modules/.rolldown/<session_id>/
+  meta.json
+  logs.json
+```
+
+`logs.json` is complete after `await bundle.close()` resolves.
+
+## Parse Events
+
+```ts
+import fs from 'node:fs';
+import { parseToEvents, type Event, type StringRef } from '@rolldown/debug';
+
+const data = fs.readFileSync('node_modules/.rolldown/<session_id>/logs.json', 'utf8');
+const events = parseToEvents(data.trim());
+
+type ActionEvent = Exclude<Event, StringRef> & { build_id: string };
+const actionEvents = events.filter((event): event is ActionEvent => 'build_id' in event);
+```
+
+Action events include `session_id`, `build_id`, `timestamp`, and an `action` discriminator. `StringRef` events contain deduplicated large string content and do not belong to a specific build.
+
+## Consume Package Data
+
+Use `PackageGraphReady` to build a package table. In watch/rebuild sessions, `logs.json` is append-only, so select the events for the `build_id` being displayed.
+
+```ts
+import fs from 'node:fs';
+import { parseToEvents, type Event, type StringRef } from '@rolldown/debug';
+
+type ActionEvent = Exclude<Event, StringRef> & { build_id: string };
+
+function isActionEvent(event: Event): event is ActionEvent {
+  return 'build_id' in event;
+}
+
+const data = fs.readFileSync('node_modules/.rolldown/<session_id>/logs.json', 'utf8');
+const actionEvents = parseToEvents(data.trim()).filter(isActionEvent);
+const buildId = actionEvents.at(-1)?.build_id;
+
+function latest<T extends ActionEvent['action']>(
+  action: T,
+): Extract<ActionEvent, { action: T }> | undefined {
+  for (let i = actionEvents.length - 1; i >= 0; i--) {
+    const event = actionEvents[i];
+    if (event.build_id === buildId && event.action === action) {
+      return event as Extract<ActionEvent, { action: T }>;
+    }
+  }
+}
+
+const packageGraph = latest('PackageGraphReady');
+const chunkGraph = latest('ChunkGraphReady');
+const moduleGraph = latest('ModuleGraphReady');
+
+const chunksById = new Map(chunkGraph?.chunks.map((chunk) => [chunk.chunk_id, chunk]) ?? []);
+const modulesById = new Map(moduleGraph?.modules.map((module) => [module.id, module]) ?? []);
+
+const packageRows = packageGraph?.packages.map((pkg) => ({
+  id: pkg.package_id,
+  label: pkg.name ?? pkg.package_root,
+  version: pkg.version ?? 'unknown',
+  dependencyType: pkg.dependency_type,
+  renderedSize: pkg.size,
+  isUsed: pkg.is_used,
+  chunks: pkg.chunk_ids.flatMap((chunkId) => {
+    const chunk = chunksById.get(chunkId);
+    return chunk ? [chunk] : [];
+  }),
+  modules: pkg.modules.map(
+    (moduleId) =>
+      modulesById.get(moduleId) ?? {
+        id: moduleId,
+      },
+  ),
+}));
+```
+
+## Package Fields
+
+| Field              | Consumer meaning                                                                                                                                                                                                     |
+| ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `package_id`       | Stable row key for one emitted package record. Prefer this, or `package_root`, over `name@version`.                                                                                                                  |
+| `name` / `version` | Metadata from the resolved package manifest. Either can be `null`; fall back to `package_root` or an unknown version label in UI.                                                                                    |
+| `package_root`     | Package directory. Useful for display, duplicate detection, and row identity.                                                                                                                                        |
+| `is_used`          | `true` when at least one module from the package appears in a generated chunk. `false` means the package was resolved but tree-shaken away.                                                                          |
+| `dependency_type`  | `direct` when any package module is imported by a source module under the build `cwd` and outside `node_modules`; otherwise `transitive`. Rolldown does not inspect `package.json` dependency fields for this value. |
+| `size`             | Sum of rendered package module bytes after tree-shaking/codegen and before `renderChunk`, minification, banners, and final asset emission. This is package attribution data, not final asset size.                   |
+| `modules`          | Generated chunk module IDs for the package. Join with `ModuleGraphReady.modules[].id` when the module graph is needed. Empty for unused packages.                                                                    |
+| `chunk_ids`        | IDs of chunks containing modules from the package. Join with `ChunkGraphReady.chunks[].chunk_id`. Empty for unused packages.                                                                                         |
+
+To detect duplicate packages, group records by non-null `name`, then mark groups that contain more than one version or package root.
+
+See `meta/design/devtools.md` in the Rolldown repository for implementation details and event lifecycle notes.

package/dist/generated/Meta.d.ts

@@ -11,5 +11,6 @@ import type { HookResolveIdCallStart } from "./HookResolveIdCallStart";
 import type { HookTransformCallEnd } from "./HookTransformCallEnd";
 import type { HookTransformCallStart } from "./HookTransformCallStart";
 import type { ModuleGraphReady } from "./ModuleGraphReady";
+import type { PackageGraphReady } from "./PackageGraphReady";
 import type { SessionMeta } from "./SessionMeta";
-export type Meta = HookTransformCallStart | HookTransformCallEnd | HookLoadCallStart | HookLoadCallEnd | BuildStart | BuildEnd | HookResolveIdCallStart | HookResolveIdCallEnd | ModuleGraphReady | SessionMeta | ChunkGraphReady | HookRenderChunkStart | HookRenderChunkEnd | AssetsReady;
+export type Meta = HookTransformCallStart | HookTransformCallEnd | HookLoadCallStart | HookLoadCallEnd | BuildStart | BuildEnd | HookResolveIdCallStart | HookResolveIdCallEnd | ModuleGraphReady | SessionMeta | ChunkGraphReady | PackageGraphReady | HookRenderChunkStart | HookRenderChunkEnd | AssetsReady;

package/dist/generated/PackageGraphReady.d.ts

@@ -0,0 +1,5 @@
+import type { PackageInfo } from "./PackageInfo";
+export type PackageGraphReady = {
+    action: 'PackageGraphReady';
+    packages: Array<PackageInfo>;
+};

package/dist/generated/PackageGraphReady.js

@@ -0,0 +1 @@
+export {};

package/dist/generated/PackageInfo.d.ts

@@ -0,0 +1,12 @@
+export type PackageInfo = {
+    package_id: string;
+    name: string | null;
+    version: string | null;
+    package_json_path: string;
+    package_root: string;
+    is_used: boolean;
+    dependency_type: 'direct' | 'transitive';
+    size: number;
+    modules: Array<string>;
+    chunk_ids: Array<number>;
+};

package/dist/generated/PackageInfo.js

@@ -0,0 +1,2 @@
+// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+export {};

package/dist/generated/index.d.ts

@@ -18,5 +18,7 @@ export * from './Meta.js';
 export * from './Module.js';
 export * from './ModuleGraphReady.js';
 export * from './ModuleImport.js';
+export * from './PackageGraphReady.js';
+export * from './PackageInfo.js';
 export * from './PluginItem.js';
 export * from './SessionMeta.js';

package/dist/generated/index.js

@@ -18,5 +18,7 @@ export * from './Meta.js';
 export * from './Module.js';
 export * from './ModuleGraphReady.js';
 export * from './ModuleImport.js';
+export * from './PackageGraphReady.js';
+export * from './PackageInfo.js';
 export * from './PluginItem.js';
 export * from './SessionMeta.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rollipop/rolldown-debug",
-  "version": "1.0.8",
+  "version": "1.0.10",
   "homepage": "https://rolldown.rs/",
   "license": "MIT",
   "repository": {