@wolfcola/eslint-plugin-treeshake 0.0.0

package/README.md

@@ -0,0 +1,158 @@
+# @wolfcola/eslint-plugin-treeshake
+
+An ESLint plugin that flags code patterns known to break tree-shaking. Catches problems at authoring time so they don't reach production bundles.
+
+Optionally integrates with [@wolfcola/treeshake-check](https://www.npmjs.com/package/@wolfcola/treeshake-check) for full Rollup-based bundle analysis mapped back to source locations.
+
+## Installation
+
+```bash
+pnpm add -D @wolfcola/eslint-plugin-treeshake
+```
+
+For bundle-check mode (optional):
+
+```bash
+pnpm add -D @wolfcola/treeshake-check
+```
+
+## Setup
+
+### Flat config (ESLint 9+)
+
+```js
+// eslint.config.mjs
+import treeshake from '@wolfcola/eslint-plugin-treeshake';
+
+export default [
+  // Use the recommended preset (all static checks, warn severity)
+  treeshake.configs.recommended,
+
+  // Or configure manually:
+  {
+    plugins: { wolfcola: treeshake },
+    rules: {
+      'wolfcola/no-treeshake-hazard': [
+        'warn',
+        {
+          checkEnums: true,
+          checkUnannotatedCalls: true,
+          checkPrototypeMutation: true,
+          checkGlobalAssignment: true,
+          checkCjsPatterns: true,
+          checkSideEffectsField: true,
+          additionalPureFunctions: [],
+          bundleCheck: false,
+        },
+      ],
+    },
+  },
+];
+```
+
+### Strict preset
+
+Enables all static checks at `error` severity and turns on bundle-check mode:
+
+```js
+import treeshake from '@wolfcola/eslint-plugin-treeshake';
+
+export default [treeshake.configs.strict];
+```
+
+## Rule: `wolfcola/no-treeshake-hazard`
+
+A single rule covering all tree-shaking hazard categories.
+
+### What it detects
+
+| Hazard                    | What it flags                                                 | Autofix                       |
+| ------------------------- | ------------------------------------------------------------- | ----------------------------- |
+| `EnumPattern`             | TypeScript `enum` declarations at module scope                | Suggestion: `as const` object |
+| `UnannotatedCall`         | Top-level function calls without `/*#__PURE__*/`              | Fix: inserts `/*#__PURE__*/`  |
+| `PrototypeMutation`       | `Object.defineProperty`, `.prototype.x = ...` at module scope | None                          |
+| `GlobalAssignment`        | `window.x = ...`, `globalThis.x = ...` at module scope        | None                          |
+| `CjsPatterns`             | `require()`, `module.exports` in ESM files                    | None                          |
+| `MissingSideEffectsField` | Missing `"sideEffects"` field in the nearest `package.json`   | None                          |
+
+### Options
+
+| Option                    | Type       | Default | Description                                      |
+| ------------------------- | ---------- | ------- | ------------------------------------------------ |
+| `checkEnums`              | `boolean`  | `true`  | Flag TypeScript enums                            |
+| `checkUnannotatedCalls`   | `boolean`  | `true`  | Flag top-level calls without `/*#__PURE__*/`     |
+| `checkPrototypeMutation`  | `boolean`  | `true`  | Flag prototype/property mutations                |
+| `checkGlobalAssignment`   | `boolean`  | `true`  | Flag global object assignments                   |
+| `checkCjsPatterns`        | `boolean`  | `true`  | Flag CommonJS patterns in ESM                    |
+| `checkSideEffectsField`   | `boolean`  | `true`  | Warn if nearest package.json lacks `sideEffects` |
+| `additionalPureFunctions` | `string[]` | `[]`    | Function names to treat as side-effect-free      |
+| `bundleCheck`             | `boolean`  | `false` | Run full Rollup-based analysis (slow)            |
+| `bundleCheckCwd`          | `string`   | auto    | Working directory for bundle check               |
+
+### Known-pure functions (not flagged)
+
+The following top-level calls are recognized as side-effect-free and not flagged by `checkUnannotatedCalls`:
+
+`Object.freeze`, `Object.create`, `Object.keys`, `Object.values`, `Object.entries`, `Object.fromEntries`, `Symbol`, `Symbol.for`, `Array.from`, `Array.of`, `Array.isArray`, `Map`, `Set`, `WeakMap`, `WeakSet`, `Number.isNaN`, `Number.isFinite`, `Number.parseInt`, `Number.parseFloat`, `String.fromCharCode`, `String.fromCodePoint`, `JSON.parse`, `JSON.stringify`, `Math.max`, `Math.min`, `Math.floor`, `Math.ceil`, `Math.round`, `Math.abs`, `Promise.resolve`, `Promise.reject`
+
+Extend with `additionalPureFunctions`.
+
+### Bundle check mode
+
+When `bundleCheck: true`, the rule runs a full Rollup build via `@wolfcola/treeshake-check` and maps results back to source locations. This is slow but catches issues that static analysis misses (transitive side effects, bundler-specific behavior).
+
+Bundle-check findings are deduplicated against static findings — if both detect the same hazard category in the same file, only the static finding is reported.
+
+Requires `@wolfcola/treeshake-check` as a dev dependency.
+
+### Relationship to @wolfcola/treeshake-check
+
+|                 | eslint-plugin-treeshake          | treeshake-check          |
+| --------------- | -------------------------------- | ------------------------ |
+| **When**        | Authoring time                   | Post-build / CI          |
+| **Speed**       | Fast (per-file AST)              | Slow (full Rollup build) |
+| **Accuracy**    | Heuristic                        | Ground truth             |
+| **Integration** | Editor squiggles, `eslint --fix` | CLI, exit codes          |
+
+Use both: the ESLint plugin for fast feedback during development, `treeshake-check` as a CI quality gate.
+
+## Examples
+
+### Before (flagged)
+
+```ts
+// Enum - breaks tree-shaking
+export enum Direction {
+  Up,
+  Down,
+  Left,
+  Right,
+}
+
+// Unannotated call - bundler assumes side effects
+const registry = createRegistry();
+
+// Global assignment - observable side effect
+window.MY_APP = { version: '1.0' };
+```
+
+### After (clean)
+
+```ts
+// as const object - fully shakeable
+export const Direction = {
+  Up: 'Up',
+  Down: 'Down',
+  Left: 'Left',
+  Right: 'Right',
+} as const;
+export type Direction = (typeof Direction)[keyof typeof Direction];
+
+// PURE annotation - bundler can safely drop if unused
+const registry = /*#__PURE__*/ createRegistry();
+
+// Moved into an explicit init function
+export function initApp() {
+  window.MY_APP = { version: '1.0' };
+}
+```

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+import { noTreeshakeHazard } from './lib/no-treeshake-hazard.js';
+declare const plugin: any;
+export default plugin;
+export { noTreeshakeHazard };
+//# 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":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,8BAA8B,CAAC;AAGjE,QAAA,MAAM,MAAM,EAAE,GASb,CAAC;AAoBF,eAAe,MAAM,CAAC;AACtB,OAAO,EAAE,iBAAiB,EAAE,CAAC"}

package/dist/index.js

@@ -0,0 +1,29 @@
+import { noTreeshakeHazard } from './lib/no-treeshake-hazard.js';
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+const plugin = {
+    meta: {
+        name: '@wolfcola/eslint-plugin-treeshake',
+        version: '0.0.0',
+    },
+    rules: {
+        'no-treeshake-hazard': noTreeshakeHazard,
+    },
+    configs: {},
+};
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+const recommended = {
+    plugins: { wolfcola: plugin },
+    rules: {
+        'wolfcola/no-treeshake-hazard': 'warn',
+    },
+};
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+const strict = {
+    plugins: { wolfcola: plugin },
+    rules: {
+        'wolfcola/no-treeshake-hazard': ['error', { bundleCheck: true }],
+    },
+};
+plugin.configs = { recommended, strict };
+export default plugin;
+export { noTreeshakeHazard };

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

@@ -0,0 +1,12 @@
+import type { HazardCategory } from './explanations.js';
+export interface BundleFileReport {
+    readonly filePath: string;
+    readonly causes: ReadonlyArray<HazardCategory>;
+    readonly survivingCode: string | null;
+    readonly line: number;
+    readonly column: number;
+}
+export declare const loadTreeshakeCheck: () => Promise<any>;
+export declare const mapResultToFileReports: (result: any, sourceContents?: Map<string, string>) => BundleFileReport[];
+export declare const deduplicateReports: (bundleReports: BundleFileReport[], staticFindings: Map<string, Set<HazardCategory>>) => BundleFileReport[];
+//# sourceMappingURL=bundle-check.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"bundle-check.d.ts","sourceRoot":"","sources":["../../src/lib/bundle-check.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAGxD,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC,cAAc,CAAC,CAAC;IAC/C,QAAQ,CAAC,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IACtC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAsBD,eAAO,MAAM,kBAAkB,QAAa,OAAO,CAAC,GAAG,CAWtD,CAAC;AAEF,eAAO,MAAM,sBAAsB,GAEjC,QAAQ,GAAG,EACX,iBAAiB,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,KACnC,gBAAgB,EAyBlB,CAAC;AAEF,eAAO,MAAM,kBAAkB,GAC7B,eAAe,gBAAgB,EAAE,EACjC,gBAAgB,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,cAAc,CAAC,CAAC,KAC/C,gBAAgB,EAWkC,CAAC"}

package/dist/lib/bundle-check.js

@@ -0,0 +1,68 @@
+import { findSnippetLocation } from './snippet-match.js';
+const mapCause = (cause) => {
+    switch (cause) {
+        case 'EnumPattern':
+            return 'EnumPattern';
+        case 'CommonJsContamination':
+            return 'CjsPatterns';
+        case 'PrototypeMutation':
+            return 'PrototypeMutation';
+        case 'GlobalAssignment':
+            return 'GlobalAssignment';
+        case 'UnannotatedCall':
+            return 'UnannotatedCall';
+        case 'TopLevelSideEffect':
+            return 'TopLevelSideEffect';
+        default:
+            return 'Unknown';
+    }
+};
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export const loadTreeshakeCheck = async () => {
+    // Use a variable to prevent TypeScript from resolving the optional dep at compile time
+    const pkg = '@wolfcola/treeshake-check';
+    try {
+        return await import(pkg);
+    }
+    catch {
+        throw new Error('bundleCheck requires @wolfcola/treeshake-check to be installed. ' +
+            'Run: pnpm add -D @wolfcola/treeshake-check');
+    }
+};
+export const mapResultToFileReports = (
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+result, sourceContents) => {
+    if (result._tag === 'FullyTreeshakeable')
+        return [];
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    return result.modules.map((mod) => {
+        const causes = mod.suspectedCauses.map(mapCause);
+        let line = 1;
+        let column = 0;
+        if (mod.survivingCode && sourceContents?.has(mod.id)) {
+            const loc = findSnippetLocation(sourceContents.get(mod.id), mod.survivingCode);
+            if (loc) {
+                line = loc.line;
+                column = loc.column;
+            }
+        }
+        return {
+            filePath: mod.id,
+            causes,
+            survivingCode: mod.survivingCode ?? null,
+            line,
+            column,
+        };
+    });
+};
+export const deduplicateReports = (bundleReports, staticFindings) => bundleReports
+    .map((report) => {
+    const staticCauses = staticFindings.get(report.filePath);
+    if (!staticCauses)
+        return report;
+    const remaining = report.causes.filter((c) => !staticCauses.has(c));
+    if (remaining.length === 0)
+        return null;
+    return { ...report, causes: remaining };
+})
+    .filter((r) => r !== null);

package/dist/lib/explanations.d.ts

@@ -0,0 +1,9 @@
+export type HazardCategory = 'EnumPattern' | 'UnannotatedCall' | 'PrototypeMutation' | 'GlobalAssignment' | 'CjsPatterns' | 'TopLevelSideEffect' | 'MissingSideEffectsField' | 'Unknown';
+export interface HazardExplanation {
+    readonly messageId: string;
+    readonly summary: string;
+    readonly why: string;
+    readonly fix: string;
+}
+export declare const EXPLANATIONS: Record<HazardCategory, HazardExplanation>;
+//# 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,MAAM,MAAM,cAAc,GACtB,aAAa,GACb,iBAAiB,GACjB,mBAAmB,GACnB,kBAAkB,GAClB,aAAa,GACb,oBAAoB,GACpB,yBAAyB,GACzB,SAAS,CAAC;AAEd,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;CACtB;AAED,eAAO,MAAM,YAAY,EAAE,MAAM,CAAC,cAAc,EAAE,iBAAiB,CAiDlE,CAAC"}

package/dist/lib/explanations.js

@@ -0,0 +1,50 @@
+export const EXPLANATIONS = {
+    EnumPattern: {
+        messageId: 'enumPattern',
+        summary: 'TypeScript enum breaks tree-shaking.',
+        why: 'TypeScript compiles `enum` to an IIFE that mutates a module-scoped variable. Bundlers keep the entire module.',
+        fix: 'Replace with an `as const` object and a derived type alias.',
+    },
+    UnannotatedCall: {
+        messageId: 'unannotatedCall',
+        summary: 'Top-level function call without /*#__PURE__*/ annotation.',
+        why: 'Bundlers treat bare function calls at module scope as side-effectful and cannot eliminate them.',
+        fix: 'Add /*#__PURE__*/ before the call if it has no side effects, or move it inside an exported function.',
+    },
+    PrototypeMutation: {
+        messageId: 'prototypeMutation',
+        summary: 'Prototype or property mutation at module scope breaks tree-shaking.',
+        why: 'Object.defineProperty, Object.assign, or .prototype assignments at the top level are observable side effects.',
+        fix: 'Move the mutation inside a function, or annotate with /*#__PURE__*/ if genuinely side-effect-free.',
+    },
+    GlobalAssignment: {
+        messageId: 'globalAssignment',
+        summary: 'Assignment to a global object at module scope breaks tree-shaking.',
+        why: 'Assignments to window/globalThis/self/global are observable side effects that bundlers can never eliminate.',
+        fix: 'Move the assignment into an explicitly-invoked function or a separate entry point.',
+    },
+    CjsPatterns: {
+        messageId: 'cjsPatterns',
+        summary: 'CommonJS pattern in an ESM file prevents tree-shaking.',
+        why: 'require(), module.exports, and __esModule markers indicate CommonJS, which bundlers cannot statically analyze.',
+        fix: 'Use ESM import/export syntax. Ensure your build emits ESM output.',
+    },
+    TopLevelSideEffect: {
+        messageId: 'topLevelSideEffect',
+        summary: 'Top-level statement with side effects prevents tree-shaking.',
+        why: 'This statement runs when the module is imported and the bundler cannot prove it is safe to remove.',
+        fix: 'Move side-effecting code into an exported function, or annotate pure expressions with /*#__PURE__*/.',
+    },
+    MissingSideEffectsField: {
+        messageId: 'missingSideEffectsField',
+        summary: 'package.json is missing the "sideEffects" field.',
+        why: 'Without "sideEffects": false, bundlers conservatively assume every module may have side effects, blocking aggressive tree-shaking.',
+        fix: 'Add "sideEffects": false to package.json. If some files do have side effects, use an array: "sideEffects": ["./src/polyfill.ts"].',
+    },
+    Unknown: {
+        messageId: 'unknown',
+        summary: 'Unknown tree-shaking hazard detected by bundle analysis.',
+        why: 'The bundler kept this code but no specific pattern was matched.',
+        fix: 'Inspect the surviving code manually. Common causes: getters, decorators, destructuring with defaults, class field initializers.',
+    },
+};

package/dist/lib/known-pure.d.ts

@@ -0,0 +1,3 @@
+export declare const KNOWN_PURE_CALLS: ReadonlySet<string>;
+export declare const isKnownPure: (calleeName: string, additionalPureFunctions?: ReadonlyArray<string>) => boolean;
+//# sourceMappingURL=known-pure.d.ts.map

package/dist/lib/known-pure.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"known-pure.d.ts","sourceRoot":"","sources":["../../src/lib/known-pure.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,gBAAgB,EAAE,WAAW,CAAC,MAAM,CAyC/C,CAAC;AAEH,eAAO,MAAM,WAAW,GACtB,YAAY,MAAM,EAClB,0BAAyB,aAAa,CAAC,MAAM,CAAM,KAClD,OAA2F,CAAC"}

package/dist/lib/known-pure.js

@@ -0,0 +1,43 @@
+export const KNOWN_PURE_CALLS = new Set([
+    // Object
+    'Object.freeze',
+    'Object.create',
+    'Object.keys',
+    'Object.values',
+    'Object.entries',
+    'Object.fromEntries',
+    // Symbol
+    'Symbol',
+    'Symbol.for',
+    // Array
+    'Array.from',
+    'Array.of',
+    'Array.isArray',
+    // Collections
+    'Map',
+    'Set',
+    'WeakMap',
+    'WeakSet',
+    // Number
+    'Number.isNaN',
+    'Number.isFinite',
+    'Number.parseInt',
+    'Number.parseFloat',
+    // String
+    'String.fromCharCode',
+    'String.fromCodePoint',
+    // JSON
+    'JSON.parse',
+    'JSON.stringify',
+    // Math
+    'Math.max',
+    'Math.min',
+    'Math.floor',
+    'Math.ceil',
+    'Math.round',
+    'Math.abs',
+    // Promise
+    'Promise.resolve',
+    'Promise.reject',
+]);
+export const isKnownPure = (calleeName, additionalPureFunctions = []) => KNOWN_PURE_CALLS.has(calleeName) || additionalPureFunctions.includes(calleeName);

package/dist/lib/no-treeshake-hazard.d.ts

@@ -0,0 +1,20 @@
+import { ESLintUtils } from '@typescript-eslint/utils';
+type RuleOptions = [
+    {
+        checkEnums?: boolean;
+        checkUnannotatedCalls?: boolean;
+        checkPrototypeMutation?: boolean;
+        checkGlobalAssignment?: boolean;
+        checkCjsPatterns?: boolean;
+        checkSideEffectsField?: boolean;
+        additionalPureFunctions?: string[];
+        bundleCheck?: boolean;
+        bundleCheckCwd?: string;
+    }
+];
+type MessageIds = 'enumPattern' | 'unannotatedCall' | 'prototypeMutation' | 'globalAssignment' | 'cjsPatterns' | 'topLevelSideEffect' | 'missingSideEffectsField' | 'unknown' | 'enumSuggestion';
+export declare const noTreeshakeHazard: ESLintUtils.RuleModule<MessageIds, RuleOptions, unknown, ESLintUtils.RuleListener> & {
+    name: string;
+};
+export {};
+//# sourceMappingURL=no-treeshake-hazard.d.ts.map

package/dist/lib/no-treeshake-hazard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"no-treeshake-hazard.d.ts","sourceRoot":"","sources":["../../src/lib/no-treeshake-hazard.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,WAAW,EAAiB,MAAM,0BAA0B,CAAC;AAmBtE,KAAK,WAAW,GAAG;IACjB;QACE,UAAU,CAAC,EAAE,OAAO,CAAC;QACrB,qBAAqB,CAAC,EAAE,OAAO,CAAC;QAChC,sBAAsB,CAAC,EAAE,OAAO,CAAC;QACjC,qBAAqB,CAAC,EAAE,OAAO,CAAC;QAChC,gBAAgB,CAAC,EAAE,OAAO,CAAC;QAC3B,qBAAqB,CAAC,EAAE,OAAO,CAAC;QAChC,uBAAuB,CAAC,EAAE,MAAM,EAAE,CAAC;QACnC,WAAW,CAAC,EAAE,OAAO,CAAC;QACtB,cAAc,CAAC,EAAE,MAAM,CAAC;KACzB;CACF,CAAC;AAEF,KAAK,UAAU,GACX,aAAa,GACb,iBAAiB,GACjB,mBAAmB,GACnB,kBAAkB,GAClB,aAAa,GACb,oBAAoB,GACpB,yBAAyB,GACzB,SAAS,GACT,gBAAgB,CAAC;AAOrB,eAAO,MAAM,iBAAiB;;CAqT5B,CAAC"}

package/dist/lib/no-treeshake-hazard.js

@@ -0,0 +1,302 @@
+import { execFileSync } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { ESLintUtils } from '@typescript-eslint/utils';
+import { EXPLANATIONS } from './explanations.js';
+import { isKnownPure } from './known-pure.js';
+import { isModuleScope, getCalleeName, hasPureAnnotation } from './scope-utils.js';
+import { mapResultToFileReports, deduplicateReports } from './bundle-check.js';
+const MUTATION_METHODS = new Set([
+    'Object.defineProperty',
+    'Object.defineProperties',
+    'Object.setPrototypeOf',
+]);
+const GLOBAL_OBJECTS = new Set(['window', 'globalThis', 'self', 'global']);
+const createRule = ESLintUtils.RuleCreator((name) => `https://github.com/ryanbas21/devtools/blob/main/packages/eslint-plugin-treeshake/docs/rules/${name}.md`);
+const buildMessage = (category) => {
+    const e = EXPLANATIONS[category];
+    return `${e.summary} ${e.why} ${e.fix}`;
+};
+export const noTreeshakeHazard = createRule({
+    name: 'no-treeshake-hazard',
+    meta: {
+        type: 'problem',
+        docs: {
+            description: 'Flags code patterns known to break tree-shaking.',
+        },
+        fixable: 'code',
+        hasSuggestions: true,
+        schema: [
+            {
+                type: 'object',
+                properties: {
+                    checkEnums: { type: 'boolean' },
+                    checkUnannotatedCalls: { type: 'boolean' },
+                    checkPrototypeMutation: { type: 'boolean' },
+                    checkGlobalAssignment: { type: 'boolean' },
+                    checkCjsPatterns: { type: 'boolean' },
+                    checkSideEffectsField: { type: 'boolean' },
+                    additionalPureFunctions: {
+                        type: 'array',
+                        items: { type: 'string' },
+                    },
+                    bundleCheck: { type: 'boolean' },
+                    bundleCheckCwd: { type: 'string' },
+                },
+                additionalProperties: false,
+            },
+        ],
+        messages: {
+            enumPattern: buildMessage('EnumPattern'),
+            unannotatedCall: buildMessage('UnannotatedCall'),
+            prototypeMutation: buildMessage('PrototypeMutation'),
+            globalAssignment: buildMessage('GlobalAssignment'),
+            cjsPatterns: buildMessage('CjsPatterns'),
+            topLevelSideEffect: buildMessage('TopLevelSideEffect'),
+            missingSideEffectsField: buildMessage('MissingSideEffectsField'),
+            unknown: buildMessage('Unknown'),
+            enumSuggestion: 'Replace enum with an as const object and type alias.',
+        },
+    },
+    defaultOptions: [
+        {
+            checkEnums: true,
+            checkUnannotatedCalls: true,
+            checkPrototypeMutation: true,
+            checkGlobalAssignment: true,
+            checkCjsPatterns: true,
+            checkSideEffectsField: true,
+            additionalPureFunctions: [],
+            bundleCheck: false,
+            bundleCheckCwd: undefined,
+        },
+    ],
+    create(context, [options]) {
+        const { checkEnums = true, checkUnannotatedCalls = true, checkPrototypeMutation = true, checkGlobalAssignment = true, checkCjsPatterns = true, checkSideEffectsField = true, additionalPureFunctions = [], } = options;
+        const sourceCode = context.sourceCode;
+        // Track static findings for dedup with bundle check
+        const staticFindings = new Map();
+        const recordStatic = (category) => {
+            const file = context.filename;
+            if (!staticFindings.has(file))
+                staticFindings.set(file, new Set());
+            staticFindings.get(file).add(category);
+        };
+        /**
+         * Build the replacement text for an enum → as const object suggestion.
+         */
+        function buildEnumReplacement(node, isExported) {
+            const name = node.id.name;
+            const members = (node.body?.members ?? node.members)
+                .map((m) => {
+                const key = m.id.type === 'Identifier' ? m.id.name : sourceCode.getText(m.id);
+                const value = m.initializer ? sourceCode.getText(m.initializer) : `"${key}"`;
+                return `  ${key}: ${value}`;
+            })
+                .join(',\n');
+            const exportPrefix = isExported ? 'export ' : '';
+            const obj = `${exportPrefix}const ${name} = {\n${members},\n} as const;`;
+            const type = `${exportPrefix}type ${name} = (typeof ${name})[keyof typeof ${name}];`;
+            return `${obj}\n${type}`;
+        }
+        return {
+            // 1. TSEnumDeclaration
+            TSEnumDeclaration(node) {
+                if (!checkEnums || !isModuleScope(node))
+                    return;
+                const isExported = node.parent?.type === 'ExportNamedDeclaration';
+                const reportNode = isExported ? node.parent : node;
+                recordStatic('EnumPattern');
+                context.report({
+                    node,
+                    messageId: 'enumPattern',
+                    suggest: [
+                        {
+                            messageId: 'enumSuggestion',
+                            fix(fixer) {
+                                return fixer.replaceText(reportNode, buildEnumReplacement(node, isExported));
+                            },
+                        },
+                    ],
+                });
+            },
+            // 2. CallExpression — unannotated top-level calls
+            CallExpression(node) {
+                if (!checkUnannotatedCalls || !isModuleScope(node))
+                    return;
+                const calleeName = getCalleeName(node.callee);
+                if (calleeName && isKnownPure(calleeName, additionalPureFunctions))
+                    return;
+                if (calleeName && MUTATION_METHODS.has(calleeName))
+                    return;
+                if (hasPureAnnotation(sourceCode, node))
+                    return;
+                // Skip require() calls — handled by CJS check
+                if (node.callee.type === 'Identifier' && node.callee.name === 'require')
+                    return;
+                recordStatic('UnannotatedCall');
+                context.report({
+                    node,
+                    messageId: 'unannotatedCall',
+                    fix(fixer) {
+                        return fixer.insertTextBefore(node, '/*#__PURE__*/ ');
+                    },
+                });
+            },
+            // 3. Prototype mutation — method calls (Object.defineProperty, etc.)
+            'ExpressionStatement > CallExpression'(node) {
+                if (!checkPrototypeMutation || !isModuleScope(node))
+                    return;
+                const calleeName = getCalleeName(node.callee);
+                if (calleeName && MUTATION_METHODS.has(calleeName)) {
+                    recordStatic('PrototypeMutation');
+                    context.report({
+                        node,
+                        messageId: 'prototypeMutation',
+                    });
+                }
+            },
+            // 4. Prototype mutation — assignment (X.prototype.y = ...)
+            'ExpressionStatement > AssignmentExpression'(node) {
+                if (!checkPrototypeMutation || !isModuleScope(node))
+                    return;
+                if (node.left.type === 'MemberExpression' &&
+                    node.left.object.type === 'MemberExpression' &&
+                    !node.left.object.computed &&
+                    node.left.object.property.type === 'Identifier' &&
+                    node.left.object.property.name === 'prototype') {
+                    recordStatic('PrototypeMutation');
+                    context.report({
+                        node,
+                        messageId: 'prototypeMutation',
+                    });
+                }
+            },
+            // 5. Global assignment
+            AssignmentExpression(node) {
+                if (!checkGlobalAssignment || !isModuleScope(node))
+                    return;
+                if (node.left.type === 'MemberExpression' &&
+                    node.left.object.type === 'Identifier' &&
+                    GLOBAL_OBJECTS.has(node.left.object.name)) {
+                    recordStatic('GlobalAssignment');
+                    context.report({
+                        node,
+                        messageId: 'globalAssignment',
+                    });
+                }
+            },
+            // 6. CJS — require()
+            'CallExpression[callee.name="require"]'(node) {
+                if (!checkCjsPatterns || !isModuleScope(node))
+                    return;
+                context.report({
+                    node,
+                    messageId: 'cjsPatterns',
+                });
+            },
+            // 7. CJS — module.exports
+            'MemberExpression[object.name="module"][property.name="exports"]'(node) {
+                if (!checkCjsPatterns || !isModuleScope(node))
+                    return;
+                context.report({
+                    node,
+                    messageId: 'cjsPatterns',
+                });
+            },
+            // 8. CJS — exports.x (skip if parent is module.exports)
+            'MemberExpression[object.name="exports"]'(node) {
+                if (!checkCjsPatterns || !isModuleScope(node))
+                    return;
+                // Skip if this is module.exports (avoid double report)
+                if (node.parent?.type === 'MemberExpression' && node.parent.object === node) {
+                    return;
+                }
+                context.report({
+                    node,
+                    messageId: 'cjsPatterns',
+                });
+            },
+            // 9. Check nearest package.json for missing sideEffects field
+            Program(node) {
+                if (!checkSideEffectsField)
+                    return;
+                let dir = dirname(context.filename);
+                for (let i = 0; i < 20; i++) {
+                    const candidate = join(dir, 'package.json');
+                    if (existsSync(candidate)) {
+                        try {
+                            const pkg = JSON.parse(readFileSync(candidate, 'utf-8'));
+                            if (pkg.sideEffects === undefined) {
+                                context.report({
+                                    node,
+                                    loc: { line: 1, column: 0 },
+                                    messageId: 'missingSideEffectsField',
+                                });
+                            }
+                        }
+                        catch {
+                            // Ignore parse errors in package.json
+                        }
+                        break;
+                    }
+                    const parent = dirname(dir);
+                    if (parent === dir)
+                        break;
+                    dir = parent;
+                }
+            },
+            // 10. Bundle check (opt-in, synchronous via execFileSync)
+            'Program:exit'(node) {
+                if (!options.bundleCheck)
+                    return;
+                const cwd = options.bundleCheckCwd ?? process.cwd();
+                let jsonOutput;
+                try {
+                    jsonOutput = execFileSync('npx', ['treeshake-check', '--json'], {
+                        cwd,
+                        encoding: 'utf-8',
+                        timeout: 60_000,
+                        stdio: ['pipe', 'pipe', 'pipe'],
+                    });
+                }
+                catch (err) {
+                    // treeshake-check exits 1 when not shakeable — stdout still has JSON
+                    const execErr = err;
+                    if (execErr.stdout) {
+                        jsonOutput = execErr.stdout;
+                    }
+                    else {
+                        context.report({
+                            node,
+                            loc: { line: 1, column: 0 },
+                            messageId: 'unknown',
+                        });
+                        return;
+                    }
+                }
+                let result;
+                try {
+                    result = JSON.parse(jsonOutput);
+                }
+                catch {
+                    return;
+                }
+                const reports = mapResultToFileReports(result);
+                const deduplicated = deduplicateReports(reports, staticFindings);
+                for (const report of deduplicated) {
+                    if (report.filePath !== context.filename)
+                        continue;
+                    for (const cause of report.causes) {
+                        const explanation = EXPLANATIONS[cause];
+                        context.report({
+                            node,
+                            loc: { line: report.line, column: report.column },
+                            messageId: explanation.messageId,
+                        });
+                    }
+                }
+            },
+        };
+    },
+});

package/dist/lib/scope-utils.d.ts

@@ -0,0 +1,20 @@
+import type { TSESTree } from '@typescript-eslint/utils';
+/**
+ * Check whether a node is at the top level of a module (direct child of Program.body).
+ * Walk up the parent chain; if we hit Program without crossing a function/class boundary,
+ * the node is at module scope.
+ */
+export declare const isModuleScope: (node: TSESTree.Node) => boolean;
+/**
+ * Extract a human-readable callee name from a CallExpression's callee node.
+ * Returns "Object.freeze" for `Object.freeze(...)`, "foo" for `foo(...)`,
+ * or null for computed/complex expressions.
+ */
+export declare const getCalleeName: (callee: TSESTree.Expression) => string | null;
+/**
+ * Check whether a node has a leading /*#__PURE__*\/ comment.
+ */
+export declare const hasPureAnnotation: (sourceCode: {
+    getCommentsBefore(node: TSESTree.Node): TSESTree.Comment[];
+}, node: TSESTree.Node) => boolean;
+//# sourceMappingURL=scope-utils.d.ts.map

package/dist/lib/scope-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scope-utils.d.ts","sourceRoot":"","sources":["../../src/lib/scope-utils.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,0BAA0B,CAAC;AAEzD;;;;GAIG;AACH,eAAO,MAAM,aAAa,GAAI,MAAM,QAAQ,CAAC,IAAI,KAAG,OAgBnD,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,aAAa,GAAI,QAAQ,QAAQ,CAAC,UAAU,KAAG,MAAM,GAAG,IAapE,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,iBAAiB,GAC5B,YAAY;IAAE,iBAAiB,CAAC,IAAI,EAAE,QAAQ,CAAC,IAAI,GAAG,QAAQ,CAAC,OAAO,EAAE,CAAA;CAAE,EAC1E,MAAM,QAAQ,CAAC,IAAI,KAClB,OAGF,CAAC"}

package/dist/lib/scope-utils.js

@@ -0,0 +1,46 @@
+/**
+ * Check whether a node is at the top level of a module (direct child of Program.body).
+ * Walk up the parent chain; if we hit Program without crossing a function/class boundary,
+ * the node is at module scope.
+ */
+export const isModuleScope = (node) => {
+    let current = node.parent;
+    while (current) {
+        switch (current.type) {
+            case 'Program':
+                return true;
+            case 'FunctionDeclaration':
+            case 'FunctionExpression':
+            case 'ArrowFunctionExpression':
+            case 'ClassBody':
+            case 'StaticBlock':
+                return false;
+        }
+        current = current.parent;
+    }
+    return false;
+};
+/**
+ * Extract a human-readable callee name from a CallExpression's callee node.
+ * Returns "Object.freeze" for `Object.freeze(...)`, "foo" for `foo(...)`,
+ * or null for computed/complex expressions.
+ */
+export const getCalleeName = (callee) => {
+    if (callee.type === 'Identifier') {
+        return callee.name;
+    }
+    if (callee.type === 'MemberExpression' &&
+        !callee.computed &&
+        callee.object.type === 'Identifier' &&
+        callee.property.type === 'Identifier') {
+        return `${callee.object.name}.${callee.property.name}`;
+    }
+    return null;
+};
+/**
+ * Check whether a node has a leading /*#__PURE__*\/ comment.
+ */
+export const hasPureAnnotation = (sourceCode, node) => {
+    const comments = sourceCode.getCommentsBefore(node);
+    return comments.some((c) => c.type === 'Block' && c.value.trim() === '#__PURE__');
+};

package/dist/lib/snippet-match.d.ts

@@ -0,0 +1,13 @@
+export interface SourceLocation {
+    /** 1-based line number */
+    readonly line: number;
+    /** 0-based column offset */
+    readonly column: number;
+}
+/**
+ * Find where a code snippet appears in a source string.
+ * For multi-line snippets, matches the first non-empty line of the snippet.
+ * Returns null if not found or snippet is empty/whitespace.
+ */
+export declare const findSnippetLocation: (source: string, snippet: string) => SourceLocation | null;
+//# sourceMappingURL=snippet-match.d.ts.map

package/dist/lib/snippet-match.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"snippet-match.d.ts","sourceRoot":"","sources":["../../src/lib/snippet-match.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,cAAc;IAC7B,0BAA0B;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,4BAA4B;IAC5B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED;;;;GAIG;AACH,eAAO,MAAM,mBAAmB,GAAI,QAAQ,MAAM,EAAE,SAAS,MAAM,KAAG,cAAc,GAAG,IAiBtF,CAAC"}

package/dist/lib/snippet-match.js

@@ -0,0 +1,22 @@
+/**
+ * Find where a code snippet appears in a source string.
+ * For multi-line snippets, matches the first non-empty line of the snippet.
+ * Returns null if not found or snippet is empty/whitespace.
+ */
+export const findSnippetLocation = (source, snippet) => {
+    const trimmed = snippet.trim();
+    if (trimmed.length === 0)
+        return null;
+    const firstLine = trimmed.split('\n').find((l) => l.trim().length > 0);
+    if (!firstLine)
+        return null;
+    const searchTarget = firstLine.trim();
+    const index = source.indexOf(searchTarget);
+    if (index === -1)
+        return null;
+    const before = source.slice(0, index);
+    const line = before.split('\n').length;
+    const lastNewline = before.lastIndexOf('\n');
+    const column = lastNewline === -1 ? index : index - lastNewline - 1;
+    return { line, column };
+};

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@wolfcola/eslint-plugin-treeshake",
+  "version": "0.0.0",
+  "description": "ESLint plugin that flags code patterns known to break tree-shaking",
+  "license": "MIT",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ryanbas21/devtools.git",
+    "directory": "packages/eslint-plugin-treeshake"
+  },
+  "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",
+  "files": [
+    "dist",
+    "!dist/*.tsbuildinfo"
+  ],
+  "dependencies": {
+    "@typescript-eslint/utils": "8.59.2"
+  },
+  "peerDependencies": {
+    "eslint": ">=9.0.0",
+    "@typescript-eslint/parser": ">=8.0.0"
+  },
+  "optionalDependencies": {
+    "@wolfcola/treeshake-check": "0.0.0"
+  },
+  "devDependencies": {
+    "@typescript-eslint/rule-tester": "8.59.2",
+    "vitest": "^3.2.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.lib.json",
+    "lint": "eslint .",
+    "test": "vitest run"
+  }
+}