@wolfcola/treeshake-check 0.0.0-snapshot-20260512024645

package/README.md

@@ -0,0 +1,159 @@
+# @wolfcola/treeshake-check
+
+A tree-shakeability analyzer for npm packages. Tells you whether your package can be fully tree-shaken by Rollup, and when it can't, points at the specific files, exports, and likely causes preventing it.
+
+Built on [Effect](https://effect.website), [@effect/cli](https://www.npmjs.com/package/@effect/cli), and [Rollup](https://rollupjs.org).
+
+## Why this exists
+
+When you publish a library, consumers' bundlers (webpack, Rollup, Vite, esbuild) try to eliminate unused exports from your package — that's tree-shaking. If your package isn't shakeable, every consumer who imports a single function pulls in your entire library, inflating their bundle size.
+
+Tree-shakeability isn't visible from the outside. You can ship what looks like a clean ESM library and still have it be unshakeable due to a single `Object.defineProperty` call at module scope, a missing `"sideEffects": false` in `package.json`, or a transitive CJS dependency. This tool surfaces those problems.
+
+The technique is the same one used by Rich Harris's [agadoo](https://www.npmjs.com/package/agadoo): bundle your package as a side-effect-only import (`import "your-package"` with no bindings used) and see what Rollup couldn't eliminate. Anything that survives is what's preventing tree-shaking.
+
+## Installation
+
+```bash
+pnpm add -D @wolfcola/treeshake-check
+```
+
+## Usage
+
+### Quickstart
+
+From any package directory:
+
+```bash
+pnpm treeshake-check
+```
+
+You'll get one of two outcomes:
+
+- **Fully tree-shakeable** — ASCII tree celebration plus any recommendations for `package.json` improvements.
+- **Has side effects** — a per-module breakdown of what survived, with diagnostic info for each file.
+
+### Flags
+
+| Flag             | Alias | Description                                                                     |
+| ---------------- | ----- | ------------------------------------------------------------------------------- |
+| `--cwd <path>`   | `-C`  | Directory containing `package.json`. Defaults to the current working directory. |
+| `--entry <path>` | `-e`  | Analyze a specific entry file directly, skipping `package.json` resolution.     |
+| `--json`         |       | Emit machine-readable JSON instead of human output.                             |
+| `--quiet`        | `-q`  | Suppress all output; rely on the exit code only.                                |
+| `--top <n>`      |       | Show only the N modules with the largest surviving byte count.                  |
+
+Plus the standard `--help`, `--version`, `--wizard`, and `--completions <shell>` flags from `@effect/cli`.
+
+### Examples
+
+Check the current package:
+
+```bash
+pnpm treeshake-check
+```
+
+Check a different package in the workspace:
+
+```bash
+pnpm treeshake-check --cwd packages/my-sdk
+```
+
+Check a specific built file directly:
+
+```bash
+pnpm treeshake-check --entry dist/index.js
+```
+
+Show only the worst 5 offenders:
+
+```bash
+pnpm treeshake-check --top 5
+```
+
+JSON output for CI tooling:
+
+```bash
+pnpm treeshake-check --json | jq '.modules[] | {id, renderedLength, suspectedCauses}'
+```
+
+## Detected causes
+
+The analyzer uses AST-based heuristics to classify surviving code:
+
+| Cause                   | Description                                               |
+| ----------------------- | --------------------------------------------------------- |
+| `EnumPattern`           | TypeScript enum compiled to IIFE                          |
+| `CommonJsContamination` | `require()`, `module.exports`, `__esModule` markers       |
+| `PrototypeMutation`     | `Object.defineProperty`, `.prototype.x = ...`             |
+| `GlobalAssignment`      | Assignment to `window`, `globalThis`, `self`, or `global` |
+| `UnannotatedCall`       | Top-level function call without `/*#__PURE__*/`           |
+| `TopLevelSideEffect`    | Top-level statement with observable effects               |
+| `Unknown`               | None of the above patterns matched                        |
+
+Labels are heuristic — a starting point for investigation, not a verdict.
+
+## Programmatic usage
+
+```typescript
+import { Effect } from 'effect';
+import { NodeContext } from '@effect/platform-node';
+import { checkPackage } from '@wolfcola/treeshake-check';
+
+const program = Effect.gen(function* () {
+  const result = yield* checkPackage('./packages/sdk');
+
+  if (result._tag === 'FullyTreeshakeable') {
+    return true;
+  }
+
+  for (const m of result.modules) {
+    console.log(`${m.id}: ${m.renderedLength}/${m.originalLength} bytes`);
+    console.log(`  causes: ${m.suspectedCauses.join(', ')}`);
+  }
+  return false;
+});
+
+const isShakeable = await Effect.runPromise(program.pipe(Effect.provide(NodeContext.layer)));
+```
+
+## CI integration
+
+`treeshake-check` exits with code 1 when a package isn't fully shakeable, so it composes naturally as a quality gate.
+
+### GitHub Actions
+
+```yaml
+- name: Tree-shake check
+  run: pnpm -r --filter "./packages/*" exec treeshake-check --top 5
+```
+
+### As a pre-publish hook
+
+```json
+{
+  "scripts": {
+    "prepublishOnly": "treeshake-check --quiet"
+  }
+}
+```
+
+### Across a monorepo
+
+```bash
+pnpm -r --parallel exec treeshake-check --top 3
+```
+
+## How it works
+
+1. Reads `package.json` from the target directory and resolves the entry point (`exports` → `module` → `main`).
+2. Constructs a synthetic Rollup entry that imports the target as a side-effect-only import: `import "/absolute/path/to/entry.js"`.
+3. Runs Rollup with default tree-shaking enabled.
+4. Inspects `chunk.modules` for per-module `renderedLength`, `renderedExports`, and `removedExports`.
+5. Classifies surviving code by AST analysis (with regex fallback for unparseable output).
+6. Reports per-module statistics, surviving code, and `package.json` recommendations.
+
+## Prior art
+
+- [agadoo](https://www.npmjs.com/package/agadoo) by Rich Harris — same technique, the original implementation. This package adds richer diagnostics, structured output, and Effect-based composition.
+- [bundlephobia](https://bundlephobia.com) — measures the post-shake size from a consumer's perspective rather than analyzing why shaking succeeds or fails.

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":""}

package/dist/index.js

@@ -0,0 +1,159 @@
+#!/usr/bin/env node
+// src/index.ts
+import { Command, Options } from '@effect/cli';
+import { NodeContext, NodeRuntime } from '@effect/platform-node';
+import { Console, Effect, Option, Schema, pipe } from 'effect';
+import { analyzeTreeshakeability, checkPackage } from './lib/treeshake-check.js';
+import { EXPLANATIONS, primaryCause } from './lib/explanations.js';
+import { TreeshakeResult } from './lib/schemas.js';
+const tree = `
+      \\\\///  /Thanks
+        \\\\//////
+         |||||
+         |||||
+         |||||
+   .....//||||\\\\....
+Awesome! Your code is 100% tree-shakeable!
+`;
+// ─── Options ─────────────────────────────────────────────────────────────────
+const cwd = Options.directory('cwd', { exists: 'yes' }).pipe(Options.withAlias('C'), Options.withDescription('Directory containing the package.json to analyze. Defaults to the current working directory.'), Options.optional);
+const entry = Options.file('entry', { exists: 'yes' }).pipe(Options.withAlias('e'), Options.withDescription('Analyze a specific entry file directly, skipping package.json resolution.'), Options.optional);
+const json = Options.boolean('json').pipe(Options.withDescription('Emit machine-readable JSON instead of human-readable output.'));
+const quiet = Options.boolean('quiet').pipe(Options.withAlias('q'), Options.withDescription('Suppress all output; rely on exit code only.'));
+const top = Options.integer('top').pipe(Options.withDescription('Show only the N modules with the largest surviving byte count.'), Options.optional);
+// ─── Rendering helpers ───────────────────────────────────────────────────────
+const indent = (text, prefix = '    ') => text
+    .split('\n')
+    .map((line) => prefix + line)
+    .join('\n');
+const SEPARATOR = '  ───────────────────────────────────────────────';
+// ─── Renderers ───────────────────────────────────────────────────────────────
+const renderJson = (result) => pipe(Schema.encode(TreeshakeResult)(result), Effect.flatMap((encoded) => Console.log(JSON.stringify(encoded, null, 2))));
+const renderHuman = (result, topN) => Effect.gen(function* () {
+    if (result._tag === 'FullyTreeshakeable') {
+        yield* Console.info(tree);
+        if (result.hints.recommendations.length > 0) {
+            yield* Console.info('\nRecommendations:');
+            for (const rec of result.hints.recommendations) {
+                yield* Console.info(`  • ${rec}`);
+            }
+        }
+        return;
+    }
+    // ─── Headline verdict ──────────────────────────────────────────────────
+    const survivedPct = (result.totalRenderedBytes / result.totalOriginalBytes) * 100;
+    const moduleCount = result.modules.length;
+    yield* Console.info('\n  This package is not tree-shakeable.\n');
+    yield* Console.info(`  When a consumer imports anything from this package, ${survivedPct.toFixed(0)}% ` +
+        `of its code (${result.totalRenderedBytes} of ${result.totalOriginalBytes} bytes) ` +
+        `gets pulled into their bundle, even if they only use a single export.\n`);
+    yield* Console.info(`  ${moduleCount} ${moduleCount === 1 ? 'file is' : 'files are'} preventing ` +
+        `tree-shaking. Details below.\n`);
+    // ─── Per-module diagnosis ──────────────────────────────────────────────
+    const sorted = [...result.modules].sort((a, b) => b.renderedLength - a.renderedLength);
+    const shown = Option.match(topN, {
+        onNone: () => sorted,
+        onSome: (n) => sorted.slice(0, n),
+    });
+    yield* Console.info(`${SEPARATOR}\n`);
+    for (const [i, m] of shown.entries()) {
+        const cause = primaryCause(m.suspectedCauses);
+        const explanation = EXPLANATIONS[cause];
+        const filePct = (m.renderedLength / m.originalLength) * 100;
+        yield* Console.info(`  [${i + 1}] ${m.id}\n`);
+        yield* Console.info(`      Problem: ${explanation.summary}\n`);
+        yield* Console.info(`      Impact:  ${m.renderedLength} of ${m.originalLength} bytes ` +
+            `(${filePct.toFixed(0)}%) end up in consumer bundles\n`);
+        if (m.renderedExports.length > 0) {
+            yield* Console.info(`      Exports affected: ${m.renderedExports.join(', ')}\n`);
+        }
+        yield* Console.info('      Why this happens:');
+        yield* Console.info(indent(explanation.why, '        '));
+        yield* Console.info('');
+        yield* Console.info('      How to fix:');
+        for (const f of explanation.fix) {
+            yield* Console.info(`        • ${f}`);
+        }
+        if (explanation.example) {
+            yield* Console.info('\n      Example:');
+            yield* Console.info('        Before:');
+            yield* Console.info(indent(explanation.example.before, '          '));
+            yield* Console.info('\n        After:');
+            yield* Console.info(indent(explanation.example.after, '          '));
+        }
+        // Show a snippet of the actual surviving code as evidence
+        if (m.survivingCode && m.survivingCode.trim().length > 0) {
+            const snippet = m.survivingCode.length > 400
+                ? m.survivingCode.slice(0, 400) + '\n... (truncated)'
+                : m.survivingCode;
+            yield* Console.info('\n      Surviving code:');
+            yield* Console.info(indent(snippet, '        '));
+        }
+        yield* Console.info(`\n${SEPARATOR}\n`);
+    }
+    // ─── Truncation notice ─────────────────────────────────────────────────
+    if (Option.isSome(topN) && sorted.length > Option.getOrThrow(topN)) {
+        yield* Console.info(`  (Showing top ${shown.length} of ${sorted.length}. ` +
+            `Run without --top to see all, or with --json for machine-readable output.)\n`);
+    }
+    // ─── Aggregate summary when all modules share a cause ──────────────────
+    const uniqueCauses = new Set(result.modules.map((m) => primaryCause(m.suspectedCauses)));
+    if (uniqueCauses.size === 1 && result.modules.length > 1) {
+        const [onlyCause] = Array.from(uniqueCauses);
+        yield* Console.info(`  Summary: All ${result.modules.length} files have the same root cause ` +
+            `(${EXPLANATIONS[onlyCause].summary}). Applying the fix above resolves all of them.\n`);
+    }
+    // ─── Rollup warnings, if any ───────────────────────────────────────────
+    if (result.warnings.length > 0) {
+        yield* Console.info('  Rollup warnings encountered during analysis:');
+        for (const w of result.warnings) {
+            const loc = w.loc ? ` (${w.loc.file ?? '?'}:${w.loc.line}:${w.loc.column})` : '';
+            yield* Console.info(`    [${w.code ?? 'WARN'}] ${w.message}${loc}`);
+        }
+        yield* Console.info('');
+    }
+    // ─── Package-level recommendations ─────────────────────────────────────
+    if (result.hints.recommendations.length > 0) {
+        yield* Console.info('  Package-level recommendations:');
+        for (const rec of result.hints.recommendations) {
+            yield* Console.info(`    • ${rec}`);
+        }
+        yield* Console.info('');
+    }
+});
+// ─── Command ─────────────────────────────────────────────────────────────────
+const command = Command.make('treeshake-check', { cwd, entry, json, quiet, top }, ({ cwd, entry, json, quiet, top }) => Effect.gen(function* () {
+    const result = yield* Option.match(entry, {
+        onNone: () => checkPackage(Option.getOrUndefined(cwd)),
+        onSome: (entryPath) => analyzeTreeshakeability(entryPath),
+    });
+    if (!quiet) {
+        yield* json ? renderJson(result) : renderHuman(result, top);
+    }
+    // Non-zero exit when shaking failed, so this composes as a CI gate.
+    // Use process.exitCode (not process.exit) so any in-flight stdout
+    // writes flush before Node exits.
+    if (result._tag === 'HasSideEffects') {
+        yield* Effect.sync(() => {
+            process.exitCode = 1;
+        });
+    }
+})).pipe(Command.withDescription('Check whether a package can be fully tree-shaken by Rollup.'));
+const cli = Command.run(command, {
+    name: 'Treeshake Check',
+    version: '1.0.0',
+});
+cli(process.argv).pipe(Effect.catchTags({
+    PackageJsonNotFound: (e) => Console.error(`error: package.json not found at ${e.path}`).pipe(Effect.zipRight(Effect.sync(() => {
+        process.exitCode = 1;
+    }))),
+    MissingEntryPoint: (e) => Console.error(`error: package.json at ${e.path} has no "module" or "main" entry`).pipe(Effect.zipRight(Effect.sync(() => {
+        process.exitCode = 1;
+    }))),
+    BundleFailed: (e) => Console.error(`error: bundling failed — ${String(e.cause)}`).pipe(Effect.zipRight(Effect.sync(() => {
+        process.exitCode = 1;
+    }))),
+    ParseError: (e) => Console.error(`error: invalid package.json — ${e.message}`).pipe(Effect.zipRight(Effect.sync(() => {
+        process.exitCode = 1;
+    }))),
+}), Effect.provide(NodeContext.layer), NodeRuntime.runMain);

package/dist/lib/analysis.d.ts

@@ -0,0 +1,33 @@
+import type { ModuleAnalysis, PackageJson, PackageJsonHints, SuspectedCause } from './schemas.js';
+/**
+ * Resolve the ESM entry point from a package.json.
+ *
+ * Priority: exports["." | flat] → module → main
+ * Within the exports conditions, priority is: import → module → default
+ * Returns undefined when no usable ESM entry can be found (e.g. require-only).
+ */
+export declare const resolveEntry: (pkg: PackageJson) => string | undefined;
+export declare const detectCauses: (code: string) => ReadonlyArray<SuspectedCause>;
+/**
+ * Build a single ModuleAnalysis from rollup's per-module rendered info.
+ */
+export declare const buildModuleAnalysis: (id: string, m: {
+    originalLength: number;
+    renderedLength: number;
+    renderedExports: ReadonlyArray<string>;
+    removedExports: ReadonlyArray<string>;
+    code: string | null;
+}) => ModuleAnalysis;
+/**
+ * Inspect a parsed package.json and produce hints + recommendations.
+ *
+ * The single highest-leverage fix for most real-world libraries is
+ * declaring `"sideEffects": false`, so that recommendation comes first.
+ */
+export declare const analyzePackageJsonHints: (pkg: PackageJson) => PackageJsonHints;
+/**
+ * Default hints for cases where we analyze a raw entry path without a
+ * package.json (e.g., when the user passes --entry directly).
+ */
+export declare const defaultHints: () => PackageJsonHints;
+//# sourceMappingURL=analysis.d.ts.map

package/dist/lib/analysis.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"analysis.d.ts","sourceRoot":"","sources":["../../src/lib/analysis.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,cAAc,EAAE,WAAW,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AA4BlG;;;;;;GAMG;AACH,eAAO,MAAM,YAAY,GAAI,KAAK,WAAW,KAAG,MAAM,GAAG,SAwBxD,CAAC;AAEF,eAAO,MAAM,YAAY,GAAI,MAAM,MAAM,KAAG,aAAa,CAAC,cAAc,CAsCvE,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,mBAAmB,GAC9B,IAAI,MAAM,EACV,GAAG;IACD,cAAc,EAAE,MAAM,CAAC;IACvB,cAAc,EAAE,MAAM,CAAC;IACvB,eAAe,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IACvC,cAAc,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IACtC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;CACrB,KACA,cASD,CAAC;AAEH;;;;;GAKG;AACH,eAAO,MAAM,uBAAuB,GAAI,KAAK,WAAW,KAAG,gBAqC1D,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,YAAY,QAAO,gBAK9B,CAAC"}

package/dist/lib/analysis.js

@@ -0,0 +1,144 @@
+// src/lib/analysis.ts
+import * as acorn from 'acorn';
+// Walk the AST to find top-level ExpressionStatement → CallExpression nodes
+// that are not preceded by a /*#__PURE__*/ annotation. Falls back to a regex
+// heuristic when acorn cannot parse the code (e.g. unparseable rollup output).
+const detectTopLevelCall = (code) => {
+    let ast;
+    try {
+        ast = acorn.parse(code, { ecmaVersion: 'latest', sourceType: 'module' });
+    }
+    catch {
+        const topLevelCall = /^(?!.*\/\*#__PURE__\*\/)\s*[a-zA-Z_$][\w$]*\s*\(/m;
+        return topLevelCall.test(code);
+    }
+    return ast.body.some((node) => {
+        if (node.type !== 'ExpressionStatement')
+            return false;
+        const expr = node.expression;
+        if (expr.type !== 'CallExpression')
+            return false;
+        // Check for a /*#__PURE__*/ annotation immediately before this node
+        const preceding = code.slice(0, node.start);
+        const annotationIdx = preceding.lastIndexOf('/*#__PURE__*/');
+        if (annotationIdx === -1)
+            return true;
+        const between = preceding.slice(annotationIdx + '/*#__PURE__*/'.length);
+        return !/^\s*$/.test(between);
+    });
+};
+/**
+ * Resolve the ESM entry point from a package.json.
+ *
+ * Priority: exports["." | flat] → module → main
+ * Within the exports conditions, priority is: import → module → default
+ * Returns undefined when no usable ESM entry can be found (e.g. require-only).
+ */
+export const resolveEntry = (pkg) => {
+    const { exports } = pkg;
+    if (exports !== undefined) {
+        if (typeof exports === 'string')
+            return exports;
+        // exports is a record — determine whether it's a subpath map or flat conditions
+        const dotEntry = exports['.'];
+        const conditions = dotEntry !== undefined ? dotEntry : exports;
+        if (typeof conditions === 'string')
+            return conditions;
+        if (conditions !== null && typeof conditions === 'object') {
+            const c = conditions;
+            const candidate = c['import'] ?? c['module'] ?? c['default'];
+            if (typeof candidate === 'string')
+                return candidate;
+        }
+        // No usable ESM condition found in exports — don't fall through to module/main.
+        // Falling through would return a CJS path dressed as ESM.
+        return undefined;
+    }
+    return pkg.module ?? pkg.main;
+};
+export const detectCauses = (code) => {
+    const causes = new Set();
+    // TypeScript enum IIFE: `(function (X) { ... })(X || (X = {}));`
+    if (/\(function\s*\([A-Z_$][\w$]*\)\s*\{[\s\S]*?\}\)\s*\(\s*[A-Z_$][\w$]*\s*\|\|\s*\(\s*[A-Z_$][\w$]*\s*=\s*\{\s*\}\s*\)\s*\)/.test(code)) {
+        causes.add('EnumPattern');
+    }
+    // CJS contamination
+    if (/\b(require\s*\(|module\.exports|exports\.[a-zA-Z_$]|__esModule)/.test(code)) {
+        causes.add('CommonJsContamination');
+    }
+    // Prototype mutations / Object.defineProperty
+    if (/Object\.(defineProperty|defineProperties|assign|setPrototypeOf|freeze)\s*\(/.test(code)) {
+        causes.add('PrototypeMutation');
+    }
+    if (/\.prototype\.[a-zA-Z_$]+\s*=/.test(code)) {
+        causes.add('PrototypeMutation');
+    }
+    // Global assignment
+    if (/^\s*(window|globalThis|self|global)\.[a-zA-Z_$]/m.test(code)) {
+        causes.add('GlobalAssignment');
+    }
+    // Bare top-level call without /*#__PURE__*/ — AST-based, regex fallback
+    if (!causes.has('EnumPattern') && detectTopLevelCall(code)) {
+        causes.add('UnannotatedCall');
+        causes.add('TopLevelSideEffect');
+    }
+    if (causes.size === 0)
+        causes.add('Unknown');
+    return Array.from(causes);
+};
+/**
+ * Build a single ModuleAnalysis from rollup's per-module rendered info.
+ */
+export const buildModuleAnalysis = (id, m) => ({
+    id,
+    originalLength: m.originalLength,
+    renderedLength: m.renderedLength,
+    shakingRatio: m.originalLength === 0 ? 0 : m.renderedLength / m.originalLength,
+    renderedExports: [...m.renderedExports],
+    removedExports: [...m.removedExports],
+    survivingCode: m.code,
+    suspectedCauses: m.code ? detectCauses(m.code) : ['Unknown'],
+});
+/**
+ * Inspect a parsed package.json and produce hints + recommendations.
+ *
+ * The single highest-leverage fix for most real-world libraries is
+ * declaring `"sideEffects": false`, so that recommendation comes first.
+ */
+export const analyzePackageJsonHints = (pkg) => {
+    const hasSideEffectsField = pkg.sideEffects !== undefined;
+    const hasModuleField = pkg.module !== undefined;
+    const hasTypeModule = pkg.type === 'module';
+    const recommendations = [];
+    if (!hasSideEffectsField) {
+        recommendations.push('Add "sideEffects": false to package.json. Without it, bundlers ' +
+            'conservatively assume every module may have side effects, which ' +
+            'blocks aggressive tree-shaking by consumers.');
+    }
+    if (!hasModuleField && pkg.main !== undefined) {
+        recommendations.push('Add a "module" field pointing to an ESM build. The "main" field ' +
+            'traditionally points to CommonJS, which cannot be statically ' +
+            'analyzed for tree-shaking.');
+    }
+    if (!hasTypeModule && !hasModuleField) {
+        recommendations.push('Add "type": "module" to package.json, or provide a separate ' +
+            '"module" entry for ESM consumers.');
+    }
+    return {
+        hasSideEffectsField,
+        sideEffectsValue: pkg.sideEffects,
+        hasModuleField,
+        hasTypeModule,
+        recommendations,
+    };
+};
+/**
+ * Default hints for cases where we analyze a raw entry path without a
+ * package.json (e.g., when the user passes --entry directly).
+ */
+export const defaultHints = () => ({
+    hasSideEffectsField: false,
+    hasModuleField: false,
+    hasTypeModule: false,
+    recommendations: [],
+});

package/dist/lib/explanations.d.ts

@@ -0,0 +1,22 @@
+import type { SuspectedCause } from './schemas.js';
+export interface CauseExplanation {
+    /** One-line description of what was detected. */
+    readonly summary: string;
+    /** Why this prevents tree-shaking. */
+    readonly why: string;
+    /** Concrete steps the user can take. */
+    readonly fix: ReadonlyArray<string>;
+    /** Optional code example showing the fix. */
+    readonly example?: {
+        before: string;
+        after: string;
+    };
+}
+export declare const EXPLANATIONS: Record<SuspectedCause, CauseExplanation>;
+/**
+ * Pick the most informative cause when a module has multiple labels.
+ * EnumPattern wins over UnannotatedCall, etc., so users get the most
+ * specific explanation rather than a generic one.
+ */
+export declare const primaryCause: (causes: ReadonlyArray<SuspectedCause>) => SuspectedCause;
+//# sourceMappingURL=explanations.d.ts.map

package/dist/lib/explanations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"explanations.d.ts","sourceRoot":"","sources":["../../src/lib/explanations.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAEnD,MAAM,WAAW,gBAAgB;IAC/B,iDAAiD;IACjD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,sCAAsC;IACtC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,wCAAwC;IACxC,QAAQ,CAAC,GAAG,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IACpC,6CAA6C;IAC7C,QAAQ,CAAC,OAAO,CAAC,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;CACtD;AAED,eAAO,MAAM,YAAY,EAAE,MAAM,CAAC,cAAc,EAAE,gBAAgB,CA6GjE,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,YAAY,GAAI,QAAQ,aAAa,CAAC,cAAc,CAAC,KAAG,cAcpE,CAAC"}

package/dist/lib/explanations.js

@@ -0,0 +1,117 @@
+export const EXPLANATIONS = {
+    EnumPattern: {
+        summary: 'TypeScript enum',
+        why: 'TypeScript compiles `enum` declarations into an IIFE that mutates a ' +
+            'module-scoped variable. Rollup sees the mutation and conservatively ' +
+            'assumes the module has observable side effects, even when no one is ' +
+            'using the enum.',
+        fix: [
+            'Replace `enum` with an `as const` object plus a derived type. This ' +
+                'compiles to a plain object literal that Rollup can statically analyze.',
+            'For published packages, also add `"sideEffects": false` to ' +
+                'package.json so consumers benefit from the change.',
+        ],
+        example: {
+            before: 'export enum StepType {\n' + '  LOGIN = "LOGIN",\n' + '  LOGOUT = "LOGOUT",\n' + '}',
+            after: 'export const StepType = {\n' +
+                '  LOGIN: "LOGIN",\n' +
+                '  LOGOUT: "LOGOUT",\n' +
+                '} as const;\n' +
+                'export type StepType = typeof StepType[keyof typeof StepType];',
+        },
+    },
+    PrototypeMutation: {
+        summary: 'prototype or property mutation at module scope',
+        why: 'Calls like `Object.defineProperty`, `Object.assign`, or assignments ' +
+            'to `.prototype` at the top level run when the module is imported, so ' +
+            'Rollup keeps them in the bundle.',
+        fix: [
+            'Move the mutation inside a function that callers explicitly invoke.',
+            'If the call is genuinely pure (e.g., defining a property on a ' +
+                'module-local object), wrap it in a `/*#__PURE__*/` annotation.',
+            'For library code that legitimately needs side effects on import ' +
+                "(polyfills, registrations), declare the file in `package.json`'s " +
+                "`sideEffects` array so it's explicitly opted in.",
+        ],
+    },
+    GlobalAssignment: {
+        summary: 'assignment to a global object',
+        why: 'Assignments to `window`, `globalThis`, `self`, or `global` at module ' +
+            'scope are observable side effects — they affect state outside the ' +
+            'module — and can never be tree-shaken.',
+        fix: [
+            'If this is a polyfill or registration, declare the file in ' +
+                "`package.json`'s `sideEffects` array so consumers know it has to run.",
+            'If the global assignment is opportunistic (e.g., exposing a debug API), ' +
+                'consider moving it to a separately-imported entry point so the main ' +
+                'entry stays shakeable.',
+        ],
+    },
+    CommonJsContamination: {
+        summary: 'CommonJS code in the bundle',
+        why: '`require()`, `module.exports`, and `__esModule` markers indicate ' +
+            "CommonJS code, which Rollup can't statically analyze for tree-shaking. " +
+            'This usually means a transitive dependency ships only CJS, or your ' +
+            'build is producing CJS output.',
+        fix: [
+            'Verify your build emits ESM. Check `package.json` for a `"module"` ' +
+                'field or `"type": "module"`.',
+            'If a dependency is the source, look for an ESM-only alternative or ' +
+                'check whether the dep has an `exports` field with an `import` condition.',
+            'For unavoidable CJS deps, mark them as external in your build so they ' +
+                "don't get bundled into your output.",
+        ],
+    },
+    UnannotatedCall: {
+        summary: 'top-level function call',
+        why: 'A bare function call at module scope is treated as side-effectful by ' +
+            "default — Rollup doesn't know whether the call mutates state, prints " +
+            'to console, or registers something globally.',
+        fix: [
+            'If you know the call is pure, prefix it with `/*#__PURE__*/`:\n' +
+                '    const result = /*#__PURE__*/ computeOnce();',
+            'If the call genuinely has side effects, move it inside a function ' +
+                'that consumers explicitly invoke.',
+        ],
+    },
+    TopLevelSideEffect: {
+        summary: 'top-level statement with side effects',
+        why: 'Some statement at the top of the module runs when imported and ' +
+            "Rollup can't prove it's safe to eliminate.",
+        fix: [
+            'Move side-effecting code into an exported function.',
+            'For pure expressions, wrap them in `/*#__PURE__*/`.',
+        ],
+    },
+    Unknown: {
+        summary: 'unknown side effect',
+        why: "The heuristic patterns didn't match this code, but Rollup decided to " +
+            'keep it. Look at the surviving code below to identify the cause manually.',
+        fix: [
+            'Read the surviving code in the breakdown above to identify the side effect.',
+            'Common causes the heuristic might miss: getters, decorators, ' +
+                'destructuring with defaults, or class field initializers.',
+        ],
+    },
+};
+/**
+ * Pick the most informative cause when a module has multiple labels.
+ * EnumPattern wins over UnannotatedCall, etc., so users get the most
+ * specific explanation rather than a generic one.
+ */
+export const primaryCause = (causes) => {
+    const priority = [
+        'EnumPattern',
+        'CommonJsContamination',
+        'GlobalAssignment',
+        'PrototypeMutation',
+        'UnannotatedCall',
+        'TopLevelSideEffect',
+        'Unknown',
+    ];
+    for (const p of priority) {
+        if (causes.includes(p))
+            return p;
+    }
+    return 'Unknown';
+};

package/dist/lib/schemas.d.ts

@@ -0,0 +1,103 @@
+import { Schema } from 'effect';
+export declare const SideEffectsValue: Schema.Union<[typeof Schema.Boolean, Schema.Array$<typeof Schema.String>]>;
+export declare const ExportsConditions: Schema.Record$<typeof Schema.String, Schema.Union<[typeof Schema.String, typeof Schema.Unknown]>>;
+export declare const ExportsField: Schema.Union<[typeof Schema.String, Schema.Record$<typeof Schema.String, Schema.Union<[typeof Schema.String, typeof Schema.Unknown]>>]>;
+export declare const PackageJson: Schema.Struct<{
+    name: Schema.optional<typeof Schema.String>;
+    module: Schema.optional<typeof Schema.String>;
+    main: Schema.optional<typeof Schema.String>;
+    exports: Schema.optional<Schema.Union<[typeof Schema.String, Schema.Record$<typeof Schema.String, Schema.Union<[typeof Schema.String, typeof Schema.Unknown]>>]>>;
+    type: Schema.optional<Schema.Literal<["module", "commonjs"]>>;
+    sideEffects: Schema.optional<Schema.Union<[typeof Schema.Boolean, Schema.Array$<typeof Schema.String>]>>;
+    dependencies: Schema.optional<typeof Schema.Unknown>;
+    peerDependencies: Schema.optional<typeof Schema.Unknown>;
+    devDependencies: Schema.optional<typeof Schema.Unknown>;
+}>;
+export type PackageJson = typeof PackageJson.Type;
+export declare const PackageJsonFromString: Schema.transform<Schema.SchemaClass<unknown, string, never>, Schema.Struct<{
+    name: Schema.optional<typeof Schema.String>;
+    module: Schema.optional<typeof Schema.String>;
+    main: Schema.optional<typeof Schema.String>;
+    exports: Schema.optional<Schema.Union<[typeof Schema.String, Schema.Record$<typeof Schema.String, Schema.Union<[typeof Schema.String, typeof Schema.Unknown]>>]>>;
+    type: Schema.optional<Schema.Literal<["module", "commonjs"]>>;
+    sideEffects: Schema.optional<Schema.Union<[typeof Schema.Boolean, Schema.Array$<typeof Schema.String>]>>;
+    dependencies: Schema.optional<typeof Schema.Unknown>;
+    peerDependencies: Schema.optional<typeof Schema.Unknown>;
+    devDependencies: Schema.optional<typeof Schema.Unknown>;
+}>>;
+export declare const SuspectedCause: Schema.Literal<["TopLevelSideEffect", "PrototypeMutation", "GlobalAssignment", "CommonJsContamination", "UnannotatedCall", "EnumPattern", "Unknown"]>;
+export type SuspectedCause = typeof SuspectedCause.Type;
+export declare const ModuleAnalysis: Schema.Struct<{
+    id: typeof Schema.String;
+    originalLength: typeof Schema.Number;
+    renderedLength: typeof Schema.Number;
+    shakingRatio: typeof Schema.Number;
+    renderedExports: Schema.Array$<typeof Schema.String>;
+    removedExports: Schema.Array$<typeof Schema.String>;
+    survivingCode: Schema.NullOr<typeof Schema.String>;
+    suspectedCauses: Schema.Array$<Schema.Literal<["TopLevelSideEffect", "PrototypeMutation", "GlobalAssignment", "CommonJsContamination", "UnannotatedCall", "EnumPattern", "Unknown"]>>;
+}>;
+export type ModuleAnalysis = typeof ModuleAnalysis.Type;
+export declare const RollupWarning: Schema.Struct<{
+    code: Schema.optional<typeof Schema.String>;
+    message: typeof Schema.String;
+    id: Schema.optional<typeof Schema.String>;
+    loc: Schema.optional<Schema.Struct<{
+        file: Schema.optional<typeof Schema.String>;
+        line: typeof Schema.Number;
+        column: typeof Schema.Number;
+    }>>;
+}>;
+export type RollupWarning = typeof RollupWarning.Type;
+export declare const PackageJsonHints: Schema.Struct<{
+    hasSideEffectsField: typeof Schema.Boolean;
+    sideEffectsValue: Schema.optional<Schema.Union<[typeof Schema.Boolean, Schema.Array$<typeof Schema.String>]>>;
+    hasModuleField: typeof Schema.Boolean;
+    hasTypeModule: typeof Schema.Boolean;
+    recommendations: Schema.Array$<typeof Schema.String>;
+}>;
+export type PackageJsonHints = typeof PackageJsonHints.Type;
+export declare const TreeshakeResult: Schema.Union<[Schema.Struct<{
+    _tag: Schema.Literal<["FullyTreeshakeable"]>;
+    hints: Schema.Struct<{
+        hasSideEffectsField: typeof Schema.Boolean;
+        sideEffectsValue: Schema.optional<Schema.Union<[typeof Schema.Boolean, Schema.Array$<typeof Schema.String>]>>;
+        hasModuleField: typeof Schema.Boolean;
+        hasTypeModule: typeof Schema.Boolean;
+        recommendations: Schema.Array$<typeof Schema.String>;
+    }>;
+}>, Schema.Struct<{
+    _tag: Schema.Literal<["HasSideEffects"]>;
+    totalOriginalBytes: typeof Schema.Number;
+    totalRenderedBytes: typeof Schema.Number;
+    modules: Schema.Array$<Schema.Struct<{
+        id: typeof Schema.String;
+        originalLength: typeof Schema.Number;
+        renderedLength: typeof Schema.Number;
+        shakingRatio: typeof Schema.Number;
+        renderedExports: Schema.Array$<typeof Schema.String>;
+        removedExports: Schema.Array$<typeof Schema.String>;
+        survivingCode: Schema.NullOr<typeof Schema.String>;
+        suspectedCauses: Schema.Array$<Schema.Literal<["TopLevelSideEffect", "PrototypeMutation", "GlobalAssignment", "CommonJsContamination", "UnannotatedCall", "EnumPattern", "Unknown"]>>;
+    }>>;
+    warnings: Schema.Array$<Schema.Struct<{
+        code: Schema.optional<typeof Schema.String>;
+        message: typeof Schema.String;
+        id: Schema.optional<typeof Schema.String>;
+        loc: Schema.optional<Schema.Struct<{
+            file: Schema.optional<typeof Schema.String>;
+            line: typeof Schema.Number;
+            column: typeof Schema.Number;
+        }>>;
+    }>>;
+    hints: Schema.Struct<{
+        hasSideEffectsField: typeof Schema.Boolean;
+        sideEffectsValue: Schema.optional<Schema.Union<[typeof Schema.Boolean, Schema.Array$<typeof Schema.String>]>>;
+        hasModuleField: typeof Schema.Boolean;
+        hasTypeModule: typeof Schema.Boolean;
+        recommendations: Schema.Array$<typeof Schema.String>;
+    }>;
+    unshakenCode: typeof Schema.String;
+}>]>;
+export type TreeshakeResult = typeof TreeshakeResult.Type;
+//# sourceMappingURL=schemas.d.ts.map

package/dist/lib/schemas.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schemas.d.ts","sourceRoot":"","sources":["../../src/lib/schemas.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAIhC,eAAO,MAAM,gBAAgB,4EAA4D,CAAC;AAG1F,eAAO,MAAM,iBAAiB,mGAG5B,CAAC;AAGH,eAAO,MAAM,YAAY,yIAAiD,CAAC;AAE3E,eAAO,MAAM,WAAW;;;;;;;;;;EAUtB,CAAC;AACH,MAAM,MAAM,WAAW,GAAG,OAAO,WAAW,CAAC,IAAI,CAAC;AAGlD,eAAO,MAAM,qBAAqB;;;;;;;;;;GAAgC,CAAC;AAInE,eAAO,MAAM,cAAc,uJAQ1B,CAAC;AACF,MAAM,MAAM,cAAc,GAAG,OAAO,cAAc,CAAC,IAAI,CAAC;AAExD,eAAO,MAAM,cAAc;;;;;;;;;EAUzB,CAAC;AACH,MAAM,MAAM,cAAc,GAAG,OAAO,cAAc,CAAC,IAAI,CAAC;AAIxD,eAAO,MAAM,aAAa;;;;;;;;;EAWxB,CAAC;AACH,MAAM,MAAM,aAAa,GAAG,OAAO,aAAa,CAAC,IAAI,CAAC;AAItD,eAAO,MAAM,gBAAgB;;;;;;EAM3B,CAAC;AACH,MAAM,MAAM,gBAAgB,GAAG,OAAO,gBAAgB,CAAC,IAAI,CAAC;AAI5D,eAAO,MAAM,eAAe;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IAc3B,CAAC;AACF,MAAM,MAAM,eAAe,GAAG,OAAO,eAAe,CAAC,IAAI,CAAC"}

package/dist/lib/schemas.js

@@ -0,0 +1,69 @@
+// src/lib/schemas.ts
+import { Schema } from 'effect';
+// ─── package.json (the bits we care about) ───────────────────────────────────
+export const SideEffectsValue = Schema.Union(Schema.Boolean, Schema.Array(Schema.String));
+// Conditions object: { import?: string, module?: string, require?: string, default?: string, ... }
+export const ExportsConditions = Schema.Record({
+    key: Schema.String,
+    value: Schema.Union(Schema.String, Schema.Unknown),
+});
+// exports field: string | conditions | { ".": conditions | string }
+export const ExportsField = Schema.Union(Schema.String, ExportsConditions);
+export const PackageJson = Schema.Struct({
+    name: Schema.optional(Schema.String),
+    module: Schema.optional(Schema.String),
+    main: Schema.optional(Schema.String),
+    exports: Schema.optional(ExportsField),
+    type: Schema.optional(Schema.Literal('module', 'commonjs')),
+    sideEffects: Schema.optional(SideEffectsValue),
+    dependencies: Schema.optional(Schema.Unknown),
+    peerDependencies: Schema.optional(Schema.Unknown),
+    devDependencies: Schema.optional(Schema.Unknown),
+});
+// JSON-string → validated PackageJson in one shot
+export const PackageJsonFromString = Schema.parseJson(PackageJson);
+// ─── Per-module analysis ─────────────────────────────────────────────────────
+export const SuspectedCause = Schema.Literal('TopLevelSideEffect', 'PrototypeMutation', 'GlobalAssignment', 'CommonJsContamination', 'UnannotatedCall', 'EnumPattern', 'Unknown');
+export const ModuleAnalysis = Schema.Struct({
+    id: Schema.String,
+    originalLength: Schema.Number,
+    renderedLength: Schema.Number,
+    // 0 = fully shaken, 1 = nothing shaken
+    shakingRatio: Schema.Number,
+    renderedExports: Schema.Array(Schema.String),
+    removedExports: Schema.Array(Schema.String),
+    survivingCode: Schema.NullOr(Schema.String),
+    suspectedCauses: Schema.Array(SuspectedCause),
+});
+// ─── Rollup warnings (captured during build) ─────────────────────────────────
+export const RollupWarning = Schema.Struct({
+    code: Schema.optional(Schema.String),
+    message: Schema.String,
+    id: Schema.optional(Schema.String),
+    loc: Schema.optional(Schema.Struct({
+        file: Schema.optional(Schema.String),
+        line: Schema.Number,
+        column: Schema.Number,
+    })),
+});
+// ─── package.json hints ──────────────────────────────────────────────────────
+export const PackageJsonHints = Schema.Struct({
+    hasSideEffectsField: Schema.Boolean,
+    sideEffectsValue: Schema.optional(SideEffectsValue),
+    hasModuleField: Schema.Boolean,
+    hasTypeModule: Schema.Boolean,
+    recommendations: Schema.Array(Schema.String),
+});
+// ─── Top-level result ────────────────────────────────────────────────────────
+export const TreeshakeResult = Schema.Union(Schema.Struct({
+    _tag: Schema.Literal('FullyTreeshakeable'),
+    hints: PackageJsonHints,
+}), Schema.Struct({
+    _tag: Schema.Literal('HasSideEffects'),
+    totalOriginalBytes: Schema.Number,
+    totalRenderedBytes: Schema.Number,
+    modules: Schema.Array(ModuleAnalysis),
+    warnings: Schema.Array(RollupWarning),
+    hints: PackageJsonHints,
+    unshakenCode: Schema.String,
+}));

package/dist/lib/treeshake-check.d.ts

@@ -0,0 +1,95 @@
+import { FileSystem, Path } from '@effect/platform';
+import { Effect } from 'effect';
+import { type PackageJson, type TreeshakeResult } from './schemas.js';
+declare const PackageJsonNotFound_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "PackageJsonNotFound";
+} & Readonly<A>;
+export declare class PackageJsonNotFound extends PackageJsonNotFound_base<{
+    readonly path: string;
+}> {
+}
+declare const MissingEntryPoint_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "MissingEntryPoint";
+} & Readonly<A>;
+export declare class MissingEntryPoint extends MissingEntryPoint_base<{
+    readonly path: string;
+}> {
+}
+declare const BundleFailed_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "BundleFailed";
+} & Readonly<A>;
+export declare class BundleFailed extends BundleFailed_base<{
+    readonly cause: unknown;
+}> {
+}
+export declare const getEntryFromPackageJson: (cwd?: string) => Effect.Effect<{
+    readonly entry: string;
+    readonly pkg: {
+        readonly name?: string | undefined;
+        readonly module?: string | undefined;
+        readonly main?: string | undefined;
+        readonly exports?: string | {
+            readonly [x: string]: unknown;
+        } | undefined;
+        readonly type?: "module" | "commonjs" | undefined;
+        readonly sideEffects?: boolean | readonly string[] | undefined;
+        readonly dependencies?: unknown;
+        readonly peerDependencies?: unknown;
+        readonly devDependencies?: unknown;
+    };
+}, PackageJsonNotFound | MissingEntryPoint | import("effect/ParseResult").ParseError | import("@effect/platform/Error").PlatformError, Path.Path | FileSystem.FileSystem>;
+/**
+ * Bundle the entry as the *only* import in a synthetic virtual module.
+ * If rollup can statically determine the entry has no observable side
+ * effects, every real module renders to zero bytes — that's our "fully
+ * shakeable" signal. Anything that survives is what's preventing
+ * tree-shaking.
+ */
+export declare const analyzeTreeshakeability: (entry: string, pkg?: PackageJson) => Effect.Effect<TreeshakeResult, BundleFailed, Path.Path>;
+/**
+ * Full check: read package.json from `cwd`, resolve its entry, then analyze.
+ */
+export declare const checkPackage: (cwd?: string) => Effect.Effect<{
+    readonly _tag: "FullyTreeshakeable";
+    readonly hints: {
+        readonly hasSideEffectsField: boolean;
+        readonly sideEffectsValue?: boolean | readonly string[] | undefined;
+        readonly hasModuleField: boolean;
+        readonly hasTypeModule: boolean;
+        readonly recommendations: readonly string[];
+    };
+} | {
+    readonly _tag: "HasSideEffects";
+    readonly hints: {
+        readonly hasSideEffectsField: boolean;
+        readonly sideEffectsValue?: boolean | readonly string[] | undefined;
+        readonly hasModuleField: boolean;
+        readonly hasTypeModule: boolean;
+        readonly recommendations: readonly string[];
+    };
+    readonly totalOriginalBytes: number;
+    readonly totalRenderedBytes: number;
+    readonly modules: readonly {
+        readonly id: string;
+        readonly originalLength: number;
+        readonly renderedLength: number;
+        readonly shakingRatio: number;
+        readonly renderedExports: readonly string[];
+        readonly removedExports: readonly string[];
+        readonly survivingCode: string | null;
+        readonly suspectedCauses: readonly ("TopLevelSideEffect" | "PrototypeMutation" | "GlobalAssignment" | "CommonJsContamination" | "UnannotatedCall" | "EnumPattern" | "Unknown")[];
+    }[];
+    readonly warnings: readonly {
+        readonly id?: string | undefined;
+        readonly code?: string | undefined;
+        readonly message: string;
+        readonly loc?: {
+            readonly file?: string | undefined;
+            readonly line: number;
+            readonly column: number;
+        } | undefined;
+    }[];
+    readonly unshakenCode: string;
+}, PackageJsonNotFound | MissingEntryPoint | BundleFailed | import("effect/ParseResult").ParseError | import("@effect/platform/Error").PlatformError, Path.Path | FileSystem.FileSystem>;
+export {};
+//# sourceMappingURL=treeshake-check.d.ts.map

package/dist/lib/treeshake-check.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"treeshake-check.d.ts","sourceRoot":"","sources":["../../src/lib/treeshake-check.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AACpD,OAAO,EAAQ,MAAM,EAAgB,MAAM,QAAQ,CAAC;AASpD,OAAO,EAEL,KAAK,WAAW,EAEhB,KAAK,eAAe,EACrB,MAAM,cAAc,CAAC;;;;AAOtB,qBAAa,mBAAoB,SAAQ,yBAAwC;IAC/E,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB,CAAC;CAAG;;;;AAEL,qBAAa,iBAAkB,SAAQ,uBAAsC;IAC3E,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB,CAAC;CAAG;;;;AAEL,qBAAa,YAAa,SAAQ,kBAAiC;IACjE,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;CACzB,CAAC;CAAG;AAqBL,eAAO,MAAM,uBAAuB,GAAI,MAAM,MAAM;;;;;;;;;;;;;;;yKASjD,CAAC;AA2BJ;;;;;;GAMG;AACH,eAAO,MAAM,uBAAuB,GAClC,OAAO,MAAM,EACb,MAAM,WAAW,KAChB,MAAM,CAAC,MAAM,CAAC,eAAe,EAAE,YAAY,EAAE,IAAI,CAAC,IAAI,CAmEjC,CAAC;AAIzB;;GAEG;AACH,eAAO,MAAM,YAAY,GAAI,MAAM,MAAM;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;wLAItC,CAAC"}

package/dist/lib/treeshake-check.js

@@ -0,0 +1,115 @@
+// src/lib/treeshake-check.ts
+import { FileSystem, Path } from '@effect/platform';
+import { Data, Effect, Schema, pipe } from 'effect';
+import virtualPlugin from '@rollup/plugin-virtual';
+import { rollup } from 'rollup';
+import { analyzePackageJsonHints, buildModuleAnalysis, defaultHints, resolveEntry, } from './analysis.js';
+import { PackageJsonFromString, } from './schemas.js';
+// eslint-disable-next-line @typescript-eslint/no-explicit-any -- interop default export
+const virtual = virtualPlugin;
+// ─── Errors ──────────────────────────────────────────────────────────────────
+export class PackageJsonNotFound extends Data.TaggedError('PackageJsonNotFound') {
+}
+export class MissingEntryPoint extends Data.TaggedError('MissingEntryPoint') {
+}
+export class BundleFailed extends Data.TaggedError('BundleFailed') {
+}
+// ─── Read & validate package.json ────────────────────────────────────────────
+const readPackageJson = (cwd) => Effect.gen(function* () {
+    const fs = yield* FileSystem.FileSystem;
+    const path = yield* Path.Path;
+    const pkgPath = path.join(cwd, 'package.json');
+    const exists = yield* fs.exists(pkgPath);
+    if (!exists) {
+        return yield* new PackageJsonNotFound({ path: pkgPath });
+    }
+    const contents = yield* fs.readFileString(pkgPath, 'utf-8');
+    const pkg = yield* Schema.decodeUnknown(PackageJsonFromString)(contents);
+    return { pkg, pkgPath };
+});
+export const getEntryFromPackageJson = (cwd) => pipe(readPackageJson(cwd ?? process.cwd()), Effect.flatMap(({ pkg, pkgPath }) => {
+    const entry = resolveEntry(pkg);
+    return entry !== undefined
+        ? Effect.succeed({ entry, pkg })
+        : new MissingEntryPoint({ path: pkgPath });
+}));
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+const closeBundle = (bundle) => Effect.tryPromise(() => bundle.close()).pipe(Effect.catchAll((cause) => Effect.logWarning('Failed to close rollup bundle').pipe(Effect.annotateLogs('cause', String(cause)))));
+/**
+ * Drop the synthetic virtual entry — `@rollup/plugin-virtual` prefixes its
+ * module IDs with `\0virtual:`. The leading null byte is sometimes stripped
+ * before the ID surfaces in `chunk.modules`, sometimes not, so we check the
+ * realistic forms plus a permissive `:treeshake` suffix as a catch-all.
+ */
+const isSyntheticEntry = (id) => id === 'treeshake' ||
+    id === 'virtual:treeshake' ||
+    id === '\0virtual:treeshake' ||
+    id.endsWith(':treeshake');
+// ─── Rollup bundling ─────────────────────────────────────────────────────────
+/**
+ * Bundle the entry as the *only* import in a synthetic virtual module.
+ * If rollup can statically determine the entry has no observable side
+ * effects, every real module renders to zero bytes — that's our "fully
+ * shakeable" signal. Anything that survives is what's preventing
+ * tree-shaking.
+ */
+export const analyzeTreeshakeability = (entry, pkg) => Effect.gen(function* () {
+    const path = yield* Path.Path;
+    const resolvedEntry = path.resolve(entry);
+    const warnings = [];
+    const bundle = yield* Effect.acquireRelease(Effect.tryPromise({
+        try: () => rollup({
+            input: 'treeshake',
+            plugins: [
+                virtual({
+                    treeshake: `import ${JSON.stringify(resolvedEntry)}`,
+                }),
+            ],
+            onwarn: (warning) => {
+                if (warning.code === 'EMPTY_BUNDLE')
+                    return;
+                warnings.push({
+                    code: warning.code,
+                    message: warning.message,
+                    id: warning.id,
+                    loc: warning.loc,
+                });
+            },
+        }),
+        catch: (cause) => new BundleFailed({ cause }),
+    }), closeBundle);
+    const output = yield* Effect.tryPromise({
+        try: () => bundle.generate({ format: 'esm' }),
+        catch: (cause) => new BundleFailed({ cause }),
+    });
+    const chunk = output.output[0];
+    const hints = pkg ? analyzePackageJsonHints(pkg) : defaultHints();
+    // Build per-module analyses, skipping the synthetic virtual entry.
+    const modules = Object.entries(chunk.modules)
+        .filter(([id]) => !isSyntheticEntry(id))
+        .map(([id, m]) => buildModuleAnalysis(id, m));
+    const totalOriginalBytes = modules.reduce((s, m) => s + m.originalLength, 0);
+    const totalRenderedBytes = modules.reduce((s, m) => s + m.renderedLength, 0);
+    // The package is fully shakeable when none of the real modules have
+    // surviving code. The bundle's `chunk.code` may still contain a tiny
+    // bit of rollup glue, but that's not the user's code.
+    const isFullyShakeable = modules.length === 0 || totalRenderedBytes === 0;
+    if (isFullyShakeable) {
+        return { _tag: 'FullyTreeshakeable', hints };
+    }
+    const offenders = modules.filter((m) => m.renderedLength > 0);
+    return {
+        _tag: 'HasSideEffects',
+        totalOriginalBytes,
+        totalRenderedBytes,
+        modules: modules.filter((m) => m.renderedLength > 0), // only show actual offenders
+        warnings,
+        hints,
+        unshakenCode: offenders.map((m) => `// ${m.id}\n${m.survivingCode ?? ''}`).join('\n\n'),
+    };
+}).pipe(Effect.scoped);
+// ─── Composed pipeline ───────────────────────────────────────────────────────
+/**
+ * Full check: read package.json from `cwd`, resolve its entry, then analyze.
+ */
+export const checkPackage = (cwd) => pipe(getEntryFromPackageJson(cwd), Effect.flatMap(({ entry, pkg }) => analyzeTreeshakeability(entry, pkg)));

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@wolfcola/treeshake-check",
+  "version": "0.0.0-snapshot-20260512024645",
+  "description": "Check whether a package can be fully tree-shaken by Rollup",
+  "license": "MIT",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ryanbas21/devtools.git",
+    "directory": "packages/treeshake-check"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "treeshake-check": "./dist/index.js"
+  },
+  "files": [
+    "dist",
+    "!dist/test-setup.*",
+    "!dist/*.tsbuildinfo"
+  ],
+  "dependencies": {
+    "@effect/cli": "^0.75.1",
+    "@effect/platform": "^0.96.0",
+    "@effect/platform-node": "^0.106.0",
+    "@rollup/plugin-virtual": "^3.0.2",
+    "acorn": "^8.16.0",
+    "effect": "^3.21.1",
+    "rollup": "^4.59.0"
+  },
+  "devDependencies": {
+    "@effect/vitest": "^0.29.0",
+    "vitest": "^3.2.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.lib.json",
+    "lint": "eslint .",
+    "test": "vitest run"
+  }
+}