@badisi/agadoo 4.0.0

package/LICENSE

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

package/README.md

@@ -0,0 +1,175 @@
+<h1 align="center">
+    @badisi/agadoo
+</h1>
+
+<p align="center">
+    🍃 <i>Check whether a package is tree-shakeable.</i><br/>
+</p>
+
+<p align="center">
+    <a href="https://www.npmjs.com/package/@badisi/agadoo">
+        <img src="https://img.shields.io/npm/v/@badisi/agadoo.svg?color=blue&logo=npm" alt="npm version" /></a>
+    <a href="https://npmcharts.com/compare/@badisi/agadoo?minimal=true">
+        <img src="https://img.shields.io/npm/dw/@badisi/agadoo.svg?color=7986CB&logo=npm" alt="npm donwloads" /></a>
+    <a href="https://github.com/Badisi/agadoo/blob/main/LICENSE">
+        <img src="https://img.shields.io/npm/l/@badisi/agadoo.svg?color=ff69b4" alt="license" /></a>
+</p>
+
+<p align="center">
+    <a href="https://github.com/Badisi/agadoo/actions/workflows/ci_tests.yml">
+        <img src="https://img.shields.io/github/actions/workflow/status/badisi/agadoo/ci_tests.yml?logo=github" alt="build status" /></a>
+    <a href="https://github.com/Badisi/agadoo/blob/main/CONTRIBUTING.md#-submitting-a-pull-request-pr">
+        <img src="https://img.shields.io/badge/PRs-welcome-brightgreen.svg" alt="PRs welcome" /></a>
+</p>
+
+<hr/>
+
+#### Tree-shaking
+
+> It is a form of `dead-code elimination` that optimizes your production bundle size by removing unused code.
+>
+> With the advent of JavaScript modules (import and export), it is now possible to build libraries that are `tree-shakeable`. This means that a user of your library can import just the bits they need, without burdening their users with all the code they are *not* using. Modern bundlers use static analysis to track your export dependency graph, automatically pruning the "dead leaves" (unused exports) so that only active code ships to the browser.
+
+<hr/>
+
+
+## Getting started
+
+This tool checks whether your JavaScript library is `tree-shakeable` by analyzing it with [Rollup](https://rollupjs.org).
+
+> [!NOTE]
+> This project is a revamp of the original [agadoo](https://github.com/Rich-Harris/agadoo) by [Rich Harris](https://github.com/Rich-Harris).
+
+
+## Installation
+
+```sh
+npm install -g @badisi/agadoo
+```
+
+```sh
+yarn add @badisi/agadoo
+```
+
+
+## Usage
+
+```sh
+bagadoo [path] [options]
+
+# or without installation, using `npx` directly:
+npx @badisi/agadoo [path] [options]
+```
+
+
+#### Arguments
+
+| Argument | Description |
+| :--- | :--- |
+| `path` | Path to an entry file or package directory.</br>*Defaults to reading the `module` or `main` field from `package.json` in the current directory*. |
+
+
+#### Options
+
+| Option | Description |
+| :--- | :--- |
+| `-c, --config <file>` | Path to a Rollup config file for custom plugins, externals, etc. |
+| `-v, --version` | Print version. |
+| `-h, --help` | Show help message. |
+
+
+#### Examples
+
+* **Check the package in the current directory:**
+
+```sh
+bagadoo
+```
+
+* **Check a specific file:**
+
+```sh
+bagadoo dist/my-library.js
+```
+
+* **Check a package directory:**
+
+```sh
+bagadoo packages/my-lib
+```
+
+* **Use a custom Rollup config file to handle plugins or mark external dependencies:**
+
+```sh
+bagadoo --config rollup.config.js
+```
+
+* **Add it to your `prepublishOnly` script to prevent publishing if tree-shaking fails:**
+
+```json
+{
+  "scripts": {
+    "prepublishOnly": "bagadoo"
+  }
+}
+```
+
+
+## API
+
+You can also use agadoo programmatically:
+
+```ts
+import { check } from '@badisi/agadoo';
+
+const result = await check('./dist/my-library.js');
+console.log(result.isShaken); // true or false
+```
+
+Pass custom Rollup options:
+
+```ts
+import { check } from '@badisi/agadoo';
+
+const result = await check('./dist/my-library.js', {
+  external: ['some-external-dep'],
+  plugins: [myPlugin()]
+});
+```
+
+
+## Help! my library isn't tree-shakeable
+
+If tree-shaking fails, it means `Rollup` found side-effects in your code.
+
+Here are common guidelines:
+
+* Avoid transpilers like `Babel` and `Bublé` (if you're using TypeScript, target a modern JS version)
+* Export plain functions — don't create instances of things on initial evaluation
+* The output will show the code that remains after tree-shaking to help you diagnose the issue
+
+If your library needs custom Rollup plugins (e.g., to handle non-standard file types), use the `--config` option.
+
+
+## Development
+
+See the [developer docs][developer].
+
+
+## Contributing
+
+#### > Want to Help ?
+
+Want to file a bug, contribute some code or improve documentation ? Excellent!
+
+But please read up first on the guidelines for [contributing][contributing], and learn about submission process, coding rules and more.
+
+#### > Code of Conduct
+
+Please read and follow the [Code of Conduct][codeofconduct] and help us keep this project open and inclusive.
+
+
+
+[developer]: https://github.com/Badisi/agadoo/blob/main/DEVELOPER.md
+[contributing]: https://github.com/Badisi/agadoo/blob/main/CONTRIBUTING.md
+[codeofconduct]: https://github.com/Badisi/agadoo/blob/main/CODE_OF_CONDUCT.md

package/bin/bagadoo

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+
+import '../cli.mjs';

package/cli.mjs

@@ -0,0 +1,145 @@
+import { access, readFile, stat } from "node:fs/promises";
+import { relative, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import { styleText } from "node:util";
+import { rollup } from "rollup";
+import virtual from "@rollup/plugin-virtual";
+//#region package.json
+var version = "4.0.0";
+//#endregion
+//#region src/index.ts
+const check = async (path, rollupOptions) => {
+	const { plugins, onwarn, ...restOptions } = rollupOptions ?? {};
+	const warnings = [];
+	const { output } = await (await rollup({
+		...restOptions,
+		input: "__badisi_agadoo__",
+		plugins: [virtual({ __badisi_agadoo__: `import * as __agadoo__ from ${JSON.stringify(path)}` }), ...Array.isArray(plugins) ? plugins : plugins ? [plugins] : []],
+		onwarn: (warning, handle) => {
+			if (onwarn) onwarn(warning, handle);
+			else if (warning.code !== "EMPTY_BUNDLE") warnings.push(warning.message);
+		}
+	})).generate({ format: "esm" });
+	const code = output[0].code.trim();
+	return {
+		isShaken: !code.split("\n").some((line) => {
+			const t = line.trim();
+			return t && !t.startsWith("import ") && !t.startsWith("//") && !t.startsWith("/*") && !t.startsWith("*") && !t.startsWith("*/");
+		}),
+		code,
+		warnings
+	};
+};
+//#endregion
+//#region src/cli.ts
+const exitWithError = (message) => {
+	console.error(message);
+	process.exit(1);
+};
+const ifExists = async (path) => {
+	try {
+		await access(path);
+		return path;
+	} catch {
+		return null;
+	}
+};
+const isDirectory = async (path) => {
+	try {
+		return (await stat(path)).isDirectory();
+	} catch {
+		return false;
+	}
+};
+const resolveEntry = async (value) => {
+	if (await isDirectory(value)) return await ifExists(`${value}/index.mjs`) ?? await ifExists(`${value}/index.js`);
+	return await ifExists(value) ?? await ifExists(`${value}.mjs`) ?? await ifExists(`${value}.js`);
+};
+const getInput = async () => {
+	let pkgJson;
+	try {
+		pkgJson = JSON.parse(await readFile("package.json", "utf-8"));
+	} catch {
+		exitWithError(`Could not find or parse 'package.json'`);
+	}
+	const name = pkgJson.module ?? pkgJson.main ?? "index";
+	const entryPath = await resolveEntry(name);
+	if (!entryPath) exitWithError(`Could not resolve entry point '${name}' from package.json`);
+	return entryPath;
+};
+const displayHelp = () => {
+	console.log([
+		`🍃 ${styleText(["bgGreen", "black"], " bagadoo ")}`,
+		"",
+		styleText("bold", "VERSION:"),
+		`    ${styleText("green", version)}`,
+		"",
+		styleText("bold", "DESCRIPTION:"),
+		"    Check whether a package is tree-shakeable.",
+		"",
+		styleText("bold", "USAGE:"),
+		"    $ bagadoo [path] [options]",
+		"",
+		styleText("bold", "ARGUMENTS:"),
+		`    ${styleText("cyan", "[path]")}             Path to an entry file or package directory`,
+		`    ${styleText(["gray", "italic"], "                   (default: read module or main from package.json)")}`,
+		"",
+		styleText("bold", "OPTIONS:"),
+		`    ${styleText("cyan", "-c, --config <file>")}  Path to a Rollup config file`,
+		`    ${styleText("cyan", "-v, --version")}        Print version`,
+		`    ${styleText("cyan", "-h, --help")}           Show this help message`
+	].join("\n"));
+};
+const getOptions = async () => {
+	const args = process.argv.slice(2);
+	let configPath;
+	const configIndex = args.findIndex((a) => a.startsWith("--config=") || a.startsWith("-c="));
+	if (configIndex !== -1) {
+		const match = args[configIndex];
+		configPath = match.slice(match.indexOf("=") + 1);
+		args.splice(configIndex, 1);
+	}
+	for (const flag of ["--config", "-c"]) {
+		const idx = args.indexOf(flag);
+		if (idx !== -1) {
+			configPath = args[idx + 1];
+			args.splice(idx, 2);
+			break;
+		}
+	}
+	let rollupOptions;
+	if (configPath) {
+		const configModule = await import(pathToFileURL(resolve(process.cwd(), configPath)).href);
+		const config = configModule.default ?? configModule;
+		rollupOptions = config?.rollup ?? config;
+	}
+	const input = args[0];
+	const absolutePath = input ? await resolveEntry(resolve(process.cwd(), input)) ?? resolve(process.cwd(), input) : resolve(process.cwd(), await getInput());
+	const relativePath = relative(process.cwd(), absolutePath);
+	return {
+		rollupOptions,
+		absolutePath,
+		relativePath
+	};
+};
+(async () => {
+	if (process.argv.includes("--version") || process.argv.includes("-v")) {
+		console.log(version);
+		process.exit();
+	} else if (process.argv.includes("--help") || process.argv.includes("-h")) {
+		displayHelp();
+		process.exit();
+	} else {
+		const options = await getOptions();
+		const result = await check(options.absolutePath, options.rollupOptions);
+		result.warnings.forEach((w) => console.error(styleText("yellow", w)));
+		result.code.split("\n").forEach((line) => {
+			const t = line.trim();
+			console.error(t.startsWith("//#region") || t.startsWith("//#endregion") ? styleText("gray", line) : line);
+		});
+		if (result.isShaken) console.log(`\n${styleText("green", "✓ Success:")} ${styleText("cyan", options.relativePath)} ${styleText("green", "is fully tree-shakeable.")}`);
+		else exitWithError(`\n${styleText("red", "✗ Failed:")} ${styleText("cyan", options.relativePath)} ${styleText("red", "is not fully tree-shakeable.")}`);
+	}
+})();
+//#endregion
+export {};

package/index.d.mts

@@ -0,0 +1,10 @@
+import { RollupOptions } from "rollup";
+//#region src/index.d.ts
+interface CheckResult {
+  isShaken: boolean;
+  code: string;
+  warnings: string[];
+}
+declare const check: (path: string, rollupOptions?: Partial<RollupOptions>) => Promise<CheckResult>;
+//#endregion
+export { CheckResult, check };

package/index.mjs

@@ -0,0 +1,27 @@
+import { rollup } from "rollup";
+import virtual from "@rollup/plugin-virtual";
+//#region src/index.ts
+const check = async (path, rollupOptions) => {
+	const { plugins, onwarn, ...restOptions } = rollupOptions ?? {};
+	const warnings = [];
+	const { output } = await (await rollup({
+		...restOptions,
+		input: "__badisi_agadoo__",
+		plugins: [virtual({ __badisi_agadoo__: `import * as __agadoo__ from ${JSON.stringify(path)}` }), ...Array.isArray(plugins) ? plugins : plugins ? [plugins] : []],
+		onwarn: (warning, handle) => {
+			if (onwarn) onwarn(warning, handle);
+			else if (warning.code !== "EMPTY_BUNDLE") warnings.push(warning.message);
+		}
+	})).generate({ format: "esm" });
+	const code = output[0].code.trim();
+	return {
+		isShaken: !code.split("\n").some((line) => {
+			const t = line.trim();
+			return t && !t.startsWith("import ") && !t.startsWith("//") && !t.startsWith("/*") && !t.startsWith("*") && !t.startsWith("*/");
+		}),
+		code,
+		warnings
+	};
+};
+//#endregion
+export { check };

package/package.json

@@ -0,0 +1,48 @@
+{
+    "name": "@badisi/agadoo",
+    "version": "4.0.0",
+    "description": "Check whether a package is tree-shakeable.",
+    "homepage": "https://github.com/Badisi/agadoo",
+    "license": "MIT",
+    "author": {
+        "name": "Badisi"
+    },
+    "sideEffects": false,
+    "type": "module",
+    "main": "./index.mjs",
+    "module": "./index.mjs",
+    "exports": {
+        ".": {
+            "types": "./index.d.mts",
+            "default": "./index.mjs"
+        },
+        "./package.json": "./package.json"
+    },
+    "bin": {
+        "bagadoo": "bin/bagadoo"
+    },
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/Badisi/agadoo.git"
+    },
+    "keywords": [
+        "agadoo",
+        "rollup",
+        "analyzer",
+        "checker",
+        "tree-shaking",
+        "tree-shakeable",
+        "esm"
+    ],
+    "engines": {
+        "node": ">= 20.12.0"
+    },
+    "dependencies": {
+        "@rollup/plugin-virtual": "^3.0.2",
+        "rollup": "^4.62.2"
+    },
+    "allowScripts": {
+        "esbuild": true,
+        "fsevents": true
+    }
+}