unbarrelify 0.0.0 → 1.0.0

package/README.md

@@ -0,0 +1,189 @@
+# unbarrelify
+
+Barrel file removal tool for JavaScript & TypeScript projects (ESM-only).
+
+## What are barrel files?
+
+Barrel files are index files that only contain re-exports from other modules:
+
+```ts
+export { formatDate } from "./date.ts";
+export { formatCurrency } from "./currency.ts";
+export { capitalize } from "./string.ts";
+```
+
+## Why avoid barrel files?
+
+Barrel files are convenient, but they often come with trade-offs including:
+
+* Performance and memory: they artificially inflate the module graph and slow down startup times, HMR, and CI pipelines.
+* Tree-shaking failures: they often confuse tree-shakers, risk entire libraries to be bundled when only a single function is needed.
+* Circular dependencies: they frequently create "import cycles", crashing bundlers or causing confusing errors.
+
+## Resources
+
+* [Speeding up the JavaScript ecosystem - The barrel file debacle][1] (Marvin Hagemeister, 2023-10-08)
+* [How we optimized package imports in Next.js][2] (Shu Ding, 2023-10-13)
+* [A practical guide against barrel files for library authors][3] (Pascal Schilp, 2024-06-01)
+* [Please Stop Using Barrel Files][4] (Dominik Dorfmeister, 2024-07-26)
+
+## Features
+
+* Automated rewiring of consumers to import directly from source
+* Preserves path aliases
+* Skips barrel files that are entry points (`package.json#exports` etc.)
+* Auto-detects or enforces file extensions to match project style
+* Optional `--organize-imports` to dedupe and clean up after rewrites
+* Granular control with `--skip`, `--only` or add `--barrel`-like files
+* Use `--check` for CI to fail if barrel files are detected
+* Go all out with `--unsafe-namespace` to namespace imports (warning: naive)
+* [Verified on non-trivial repositories][5] to not break the build/tests
+
+## Usage
+
+### Without installation
+
+```sh
+npx unbarrelify
+npx unbarrelify --help
+```
+
+It runs safe in dry-mode until you add `--write`
+
+### Installation
+
+```bash
+npm install -D unbarrelify
+```
+
+## CLI Usage
+
+```
+unbarrelify - Remove barrel files and rewire imports
+
+Usage: unbarrelify [options]
+
+Options:
+  -c, --cwd <dir>         Working directory (default: ".")
+  -o, --only <file>       Process only selected barrel file (can be repeated)
+  -s, --skip <pattern>    Barrel files to skip (glob, can be repeated)
+  -b, --barrel <pattern>  Extra files to treat as barrels (glob, can be repeated)
+  -f, --files <pattern>   Set file coverage (glob, can be repeated, default: use tsconfig.json)
+  -e, --ext <ext>         Extension for rewritten imports (default: auto-detect)
+  -w, --write             Write changes to disk (default: false/dry-run)
+      --organize-imports  Run TypeScript's "Organize Imports" after rewrites to dedupe imports
+      --check, --ci       Check mode for CI; non-zero exit if there are changes
+      --unsafe-namespace  Rewrite namespace imports; may include types (bad) and cause identifier collisions (also bad)
+  -h, --help              Show this help message
+
+Examples:
+  unbarrelify
+  unbarrelify --cwd ./src
+  unbarrelify --only ./src/utils/index.ts
+  unbarrelify --skip ./public-api.ts
+  unbarrelify --barrel looks/like/barrel.ts
+  unbarrelify --files "src/**/*.ts" --files "lib/**/*.ts"
+  unbarrelify --ext .js
+  unbarrelify --write
+  unbarrelify --check
+  unbarrelify --unsafe-namespace
+```
+
+## Programmatic API
+
+```ts
+import { unbarrelify } from "unbarrelify";
+
+const result = await unbarrelify({
+  cwd: "./src",
+  files: ["**/*.ts"],
+  skip: [],
+  ext: ".ts",
+  write: false,
+});
+
+console.log(`Modified ${result.modified.length} files`);
+console.log(`Deleted ${result.deleted.length} barrel files`);
+```
+
+### API Reference
+
+#### `unbarrelify(options: Options): Promise<Result>`
+
+The main function that processes files and removes barrel files.
+
+#### `Options`
+
+```ts
+interface Options {
+  cwd: string;
+  only?: string[];
+  files?: string[];
+  skip?: string[];
+  barrel?: string[];
+  ext?: string;
+  write: boolean;
+  check?: boolean;
+  unsafeNamespace?: boolean;
+  organizeImports?: boolean;
+  progress?: (event: ProgressEvent) => void;
+}
+```
+
+#### `Result`
+
+```ts
+interface Result {
+  modified: string[];
+  deleted: string[];
+  preserved: PreservedBarrel[];
+}
+
+ interface PreservedBarrel {
+  path: string;
+  reason: "skip" | "namespace-import" | "non-ts-import" | "dynamic-import";
+  consumers: string[];
+}
+```
+
+## How does it work?
+
+1. Identify barrel files (files containing only re-export statements)
+2. Build import/export maps to track dependencies
+3. Rewire imports in consuming files to point directly to exporting source files
+4. Remove barrel files
+
+### Before
+
+```ts
+// utils/index.ts
+export { formatDate } from "./date.ts";
+export { capitalize } from "./string.ts";
+
+// module.ts
+import { formatDate, capitalize } from "./utils/index.ts";
+```
+
+### After
+
+```ts
+// utils/index.ts - DELETED
+
+// module.ts
+import { formatDate } from "./utils/date.ts";
+import { capitalize } from "./utils/string.ts";
+```
+
+## License
+
+ISC
+
+[1]: https://marvinh.dev/blog/speeding-up-javascript-ecosystem-part-7/
+
+[2]: https://vercel.com/blog/how-we-optimized-package-imports-in-next-js
+
+[3]: https://dev.to/thepassle/a-practical-guide-against-barrel-files-for-library-authors-118c
+
+[4]: https://tkdodo.eu/blog/please-stop-using-barrel-files
+
+[5]: https://github.com/webpro/unbarrelify/blob/main/.github/workflows/integration.yml

package/dist/analyzer.d.ts

@@ -0,0 +1,14 @@
+import ts from "typescript";
+import type { Context, ExportMap, File, ImportMap, PathAliases } from "./types.ts";
+interface ParsedSpecifier {
+    prefix: string;
+    path: string;
+    suffix: string;
+}
+export declare function parseSpecifier(specifier: string): ParsedSpecifier;
+export declare function analyzeFile(filePath: string, ctx: Context): Promise<File>;
+export declare function checkIsBarrel(sourceFile: ts.SourceFile): boolean;
+export declare function getExportedNames(filePath: string): Promise<Set<string>>;
+export declare function buildExportMap(sourceFile: ts.SourceFile, aliases: PathAliases | null): Promise<ExportMap>;
+export declare function buildImportMap(sourceFile: ts.SourceFile, aliases: PathAliases | null): ImportMap;
+export {};

package/dist/analyzer.js

@@ -0,0 +1,324 @@
+import { isAbsolute } from "node:path";
+import { readFile } from "node:fs/promises";
+import ts from "typescript";
+import { resolveModule } from "./resolver.js";
+const CHAR_EXCLAMATION = 33; // '!'
+const CHAR_QUESTION = 63; // '?'
+const CHAR_HASH = 35; // '#'
+export function parseSpecifier(specifier) {
+    const len = specifier.length;
+    let lastBang = -1;
+    let suffixStart = len;
+    for (let i = 0; i < len; i++) {
+        const ch = specifier.charCodeAt(i);
+        if (ch === CHAR_EXCLAMATION) {
+            lastBang = i;
+        }
+        else if (ch === CHAR_QUESTION || ch === CHAR_HASH) {
+            suffixStart = i;
+            break;
+        }
+    }
+    const pathStart = lastBang + 1;
+    return {
+        prefix: specifier.slice(0, pathStart),
+        path: specifier.slice(pathStart, suffixStart),
+        suffix: specifier.slice(suffixStart),
+    };
+}
+export async function analyzeFile(filePath, ctx) {
+    const cached = ctx.fileCache.get(filePath);
+    if (cached)
+        return cached;
+    const content = await readFile(filePath, "utf-8");
+    const sourceFile = ts.createSourceFile(filePath, content, ts.ScriptTarget.Latest);
+    const isBarrel = checkIsBarrel(sourceFile);
+    const exports = await buildExportMap(sourceFile, ctx.aliases);
+    const imports = buildImportMap(sourceFile, ctx.aliases);
+    const dynamicImports = isBarrel ? new Set() : findDynamicImports(sourceFile, ctx.aliases);
+    const file = { isBarrel, exports, imports, sourceFile, dynamicImports };
+    ctx.fileCache.set(filePath, file);
+    return file;
+}
+export function checkIsBarrel(sourceFile) {
+    return sourceFile.statements.length > 0 && sourceFile.statements.every(ts.isExportDeclaration);
+}
+function extractExportedNames(sourceFile) {
+    const names = new Set();
+    for (const node of sourceFile.statements) {
+        if (ts.canHaveModifiers(node)) {
+            const modifiers = ts.getModifiers(node);
+            if (modifiers?.some((m) => m.kind === ts.SyntaxKind.ExportKeyword)) {
+                if (modifiers.some((m) => m.kind === ts.SyntaxKind.DefaultKeyword)) {
+                    names.add("default");
+                }
+                else {
+                    extractExportedName(node, names);
+                }
+            }
+        }
+        if (ts.isExportAssignment(node)) {
+            names.add("default");
+        }
+        if (ts.isExportDeclaration(node) && node.exportClause && ts.isNamedExports(node.exportClause)) {
+            for (const element of node.exportClause.elements) {
+                names.add(element.name.text);
+            }
+        }
+    }
+    return names;
+}
+const sourceFileCache = new Map();
+export async function getExportedNames(filePath) {
+    let sourceFile = sourceFileCache.get(filePath);
+    if (!sourceFile) {
+        const content = await readFile(filePath, "utf-8");
+        sourceFile = ts.createSourceFile(filePath, content, ts.ScriptTarget.Latest);
+        sourceFileCache.set(filePath, sourceFile);
+    }
+    return extractExportedNames(sourceFile);
+}
+function extractExportedName(node, names) {
+    if (ts.isVariableStatement(node)) {
+        for (const decl of node.declarationList.declarations) {
+            if (ts.isIdentifier(decl.name))
+                names.add(decl.name.text);
+        }
+    }
+    else if ((ts.isFunctionDeclaration(node) ||
+        ts.isClassDeclaration(node) ||
+        ts.isInterfaceDeclaration(node) ||
+        ts.isTypeAliasDeclaration(node) ||
+        ts.isEnumDeclaration(node) ||
+        ts.isModuleDeclaration(node)) &&
+        node.name &&
+        ts.isIdentifier(node.name)) {
+        names.add(node.name.text);
+    }
+}
+export async function buildExportMap(sourceFile, aliases) {
+    const exports = new Map();
+    for (const node of sourceFile.statements) {
+        if (!ts.isExportDeclaration(node) || !node.moduleSpecifier || !ts.isStringLiteral(node.moduleSpecifier)) {
+            continue;
+        }
+        const specifier = node.moduleSpecifier.text;
+        const resolvedPath = resolveModule(sourceFile.fileName, specifier, aliases);
+        if (!resolvedPath)
+            continue;
+        const pos = { start: node.getStart(sourceFile), end: node.end };
+        if (isAbsolute(resolvedPath)) {
+            await processLocalExport(exports, node, resolvedPath, specifier, pos);
+        }
+        else {
+            processExternalExport(exports, node, specifier, pos);
+        }
+    }
+    return exports;
+}
+async function processLocalExport(exports, node, resolvedPath, specifier, pos) {
+    if (node.exportClause && ts.isNamedExports(node.exportClause)) {
+        const exportedNames = new Set();
+        const aliasedDefaults = new Map();
+        let exportedAsDefault;
+        for (const element of node.exportClause.elements) {
+            exportedNames.add(element.name.text);
+            if (element.propertyName?.text === "default") {
+                aliasedDefaults.set(element.name.text, "default");
+            }
+            if (element.name.text === "default" && element.propertyName) {
+                exportedAsDefault = element.propertyName.text;
+            }
+        }
+        mergeExport(exports, resolvedPath, {
+            specifier,
+            pos,
+            exportedNames,
+            aliasedDefaults: aliasedDefaults.size > 0 ? aliasedDefaults : undefined,
+            exportedAsDefault,
+        });
+    }
+    else {
+        const namespace = node.exportClause && ts.isNamespaceExport(node.exportClause) ? node.exportClause.name.text : undefined;
+        const exportedNames = await getExportedNames(resolvedPath);
+        mergeExport(exports, resolvedPath, {
+            specifier,
+            pos,
+            exportedNames,
+            reExportedNs: namespace,
+            externalSpecifier: specifier.startsWith(".") ? undefined : specifier,
+        });
+    }
+}
+function processExternalExport(exports, node, specifier, pos) {
+    const namespace = node.exportClause && ts.isNamespaceExport(node.exportClause) ? node.exportClause.name.text : undefined;
+    const exportedNames = new Set();
+    if (node.exportClause && ts.isNamedExports(node.exportClause)) {
+        for (const element of node.exportClause.elements) {
+            exportedNames.add(element.name.text);
+        }
+    }
+    exports.set(specifier, {
+        specifier,
+        pos,
+        exportedNames,
+        reExportedNs: namespace,
+        externalSpecifier: specifier,
+    });
+}
+function mergeExport(exports, path, data) {
+    const existing = exports.get(path);
+    if (!existing) {
+        exports.set(path, data);
+        return;
+    }
+    for (const name of data.exportedNames) {
+        existing.exportedNames.add(name);
+    }
+    if (data.aliasedDefaults) {
+        existing.aliasedDefaults = existing.aliasedDefaults || new Map();
+        for (const [k, v] of data.aliasedDefaults) {
+            existing.aliasedDefaults.set(k, v);
+        }
+    }
+    if (data.exportedAsDefault && !existing.exportedAsDefault) {
+        existing.exportedAsDefault = data.exportedAsDefault;
+    }
+    if (data.reExportedNs && !existing.reExportedNs) {
+        existing.reExportedNs = data.reExportedNs;
+    }
+}
+export function buildImportMap(sourceFile, aliases) {
+    const imports = new Map();
+    for (const node of sourceFile.statements) {
+        if (ts.isImportDeclaration(node) && node.moduleSpecifier && ts.isStringLiteral(node.moduleSpecifier)) {
+            processImportDeclaration(imports, node, sourceFile, aliases);
+        }
+        else if (ts.isExportDeclaration(node) && node.moduleSpecifier && ts.isStringLiteral(node.moduleSpecifier)) {
+            processReExportDeclaration(imports, node, sourceFile, aliases);
+        }
+    }
+    return imports;
+}
+function processImportDeclaration(imports, node, sourceFile, aliases) {
+    const originalSpecifier = node.moduleSpecifier.text;
+    const { prefix, path, suffix } = parseSpecifier(originalSpecifier);
+    const resolvedPath = resolveModule(sourceFile.fileName, path, aliases);
+    if (!resolvedPath || !isAbsolute(resolvedPath))
+        return;
+    const clause = node.importClause;
+    if (!clause)
+        return;
+    const pos = { start: node.getStart(sourceFile), end: node.end };
+    const specifierPrefix = prefix || undefined;
+    const specifierSuffix = suffix || undefined;
+    if (clause.namedBindings && ts.isNamespaceImport(clause.namedBindings)) {
+        addToImportMap(imports, resolvedPath, {
+            name: clause.namedBindings.name.text,
+            type: "ns",
+            pos,
+            members: [],
+            originalSpecifier: path,
+            specifierPrefix,
+            specifierSuffix,
+        });
+    }
+    else if (clause.namedBindings && ts.isNamedImports(clause.namedBindings)) {
+        for (const element of clause.namedBindings.elements) {
+            const isType = element.isTypeOnly || clause.isTypeOnly;
+            const propertyName = element.propertyName;
+            const hasAlias = propertyName && ts.isIdentifier(propertyName);
+            addToImportMap(imports, resolvedPath, {
+                names: [
+                    {
+                        name: hasAlias ? propertyName.text : element.name.text,
+                        alias: hasAlias ? element.name.text : undefined,
+                        isType,
+                    },
+                ],
+                type: hasAlias ? "as" : "named",
+                pos,
+                originalSpecifier: path,
+                specifierPrefix,
+                specifierSuffix,
+            });
+        }
+    }
+    if (clause.name && ts.isIdentifier(clause.name)) {
+        addToImportMap(imports, resolvedPath, {
+            name: clause.name.text,
+            type: "default",
+            pos,
+            originalSpecifier: path,
+            specifierPrefix,
+            specifierSuffix,
+        });
+    }
+}
+function processReExportDeclaration(imports, node, sourceFile, aliases) {
+    const originalSpecifier = node.moduleSpecifier.text;
+    const { prefix, path, suffix } = parseSpecifier(originalSpecifier);
+    const resolvedPath = resolveModule(sourceFile.fileName, path, aliases);
+    if (!resolvedPath || !isAbsolute(resolvedPath))
+        return;
+    const pos = { start: node.getStart(sourceFile), end: node.end };
+    const specifierPrefix = prefix || undefined;
+    const specifierSuffix = suffix || undefined;
+    if (node.exportClause && ts.isNamedExports(node.exportClause)) {
+        for (const element of node.exportClause.elements) {
+            const isType = element.isTypeOnly || node.isTypeOnly;
+            const hasAlias = element.propertyName && ts.isIdentifier(element.propertyName);
+            const propertyName = hasAlias ? element.propertyName : undefined;
+            addToImportMap(imports, resolvedPath, {
+                names: [
+                    {
+                        name: propertyName ? propertyName.text : element.name.text,
+                        alias: hasAlias ? element.name.text : undefined,
+                        isType,
+                    },
+                ],
+                type: "export",
+                pos,
+                originalSpecifier: path,
+                specifierPrefix,
+                specifierSuffix,
+            });
+        }
+    }
+    else {
+        addToImportMap(imports, resolvedPath, {
+            name: "*",
+            type: "export",
+            pos,
+            originalSpecifier: path,
+            specifierPrefix,
+            specifierSuffix,
+        });
+    }
+}
+function addToImportMap(imports, filePath, item) {
+    const existing = imports.get(filePath);
+    if (existing) {
+        existing.add(item);
+    }
+    else {
+        imports.set(filePath, new Set([item]));
+    }
+}
+function findDynamicImports(sourceFile, aliases) {
+    const dynamicImports = new Set();
+    function visit(node) {
+        if (ts.isCallExpression(node) && node.expression.kind === ts.SyntaxKind.ImportKeyword) {
+            const arg = node.arguments[0];
+            if (arg && ts.isStringLiteral(arg)) {
+                const resolvedPath = resolveModule(sourceFile.fileName, arg.text, aliases);
+                if (resolvedPath && isAbsolute(resolvedPath)) {
+                    dynamicImports.add(resolvedPath);
+                }
+            }
+        }
+        ts.forEachChild(node, visit);
+    }
+    visit(sourceFile);
+    return dynamicImports;
+}

package/dist/cli.d.ts

@@ -0,0 +1,17 @@
+#!/usr/bin/env node
+export interface ParsedArgs {
+    only: string[];
+    cwd: string;
+    files?: string[];
+    skip: string[];
+    barrel: string[];
+    ext?: string;
+    write: boolean;
+    check: boolean;
+    unsafeNamespace: boolean;
+    organizeImports: boolean;
+    help: boolean;
+}
+export declare function parseCliArgs(args: string[]): ParsedArgs;
+export declare function printHelp(): void;
+export declare function main(): Promise<void>;