miniread 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Łukasz Jerciński
+
+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,86 @@
+# miniread
+
+Transform minified JavaScript/TypeScript into a more readable form using deterministic AST-based transforms.
+
+## Install
+
+```bash
+npm install --global miniread
+```
+
+## Quick start
+
+```bash
+miniread --input ./minified --output ./readable
+cat bundle.min.js | miniread > bundle.js
+miniread --list-transforms
+miniread --input ./minified --output ./readable --transforms recommended
+miniread --input ./minified --output ./readable --dry-run
+miniread --input ./minified --output ./readable --workers 8
+```
+
+## Examples
+
+### Find the most common identifiers in a minified bundle
+
+```bash
+cat bundle.min.js | miniread | grep -oE '[A-Za-z_][A-Za-z0-9_]+' | sort | uniq -c | sort -rn | head -20
+```
+
+### Locate error-throwing code paths quickly
+
+```bash
+cat bundle.min.js | miniread | grep -n "throw new" | head -20
+```
+
+### Use transform metadata in scripts (TSV)
+
+```bash
+miniread --list-transforms --format tsv | tail -n +2 | cut -f1
+```
+
+## Agent Rule
+
+Add to your `CLAUDE.md` or `AGENTS.md`:
+
+```markdown
+# Rule: `miniread` Usage
+
+Run `npx -y miniread --help` to learn available options.
+
+Use `miniread` when you need readable JavaScript/TypeScript from minified input for review, diffing, or grepping; it works as a stdin/stdout filter so it composes well with Unix pipelines.
+```
+
+## Development
+
+```bash
+pnpm install
+pnpm run build
+node bin/miniread --help
+```
+
+## miniread-evaluate (developer tool)
+
+The `miniread-evaluate` CLI compares transform configurations by measuring diff reduction across version pairs under `./sources/`. It prints TSV to stdout by default (or JSON with `--format json`) and sends logs/errors to stderr.
+
+### Requirements
+
+- `diff` (override with `MINIREAD_EVALUATE_DIFF_PATH`)
+- `pnpm` + `prettier` (used unless `--no-format-code`; overrides: `MINIREAD_EVALUATE_PNPM_PATH`, `MINIREAD_EVALUATE_PRETTIER_PATH`)
+
+### Usage
+
+```bash
+pnpm run miniread-evaluate -- --help
+
+# Compare baseline none vs a transform
+pnpm run miniread-evaluate -- --compare v1.0:v1.1 --baseline none --test add-prefix
+
+# Pipeline example: sort by reduction ratio (best first)
+pnpm run miniread-evaluate -- --compare v1.0:v1.1 --compare v2.0:v2.1 --baseline none --test add-prefix \
+  | tail -n +2 | sort -k5,5nr | head -10
+```
+
+## License
+
+MIT

package/bin/miniread

@@ -0,0 +1,17 @@
+#!/usr/bin/env node
+/**
+ * CLI entry point that dynamically imports the compiled TypeScript.
+ *
+ * Uses top-level await to ensure module evaluation errors are handled
+ * properly. Without await, errors during import would surface as unhandled
+ * rejections instead of clean CLI failures with appropriate exit codes.
+ */
+try {
+  await import("../dist/cli.js");
+} catch (error) {
+  console.error(
+    "Failed to start miniread:",
+    error instanceof Error ? error.message : error,
+  );
+  process.exitCode = 1;
+}

package/bin/miniread-evaluate

@@ -0,0 +1,17 @@
+#!/usr/bin/env node
+/**
+ * CLI entry point that dynamically imports the compiled TypeScript.
+ *
+ * Uses top-level await to ensure module evaluation errors are handled
+ * properly. Without await, errors during import would surface as unhandled
+ * rejections instead of clean CLI failures with appropriate exit codes.
+ */
+try {
+  await import("../dist/scripts/evaluate.js");
+} catch (error) {
+  console.error(
+    "Failed to start miniread-evaluate:",
+    error instanceof Error ? error.message : error,
+  );
+  process.exitCode = 1;
+}

package/bin/miniread-sample

@@ -0,0 +1,17 @@
+#!/usr/bin/env node
+/**
+ * CLI entry point that dynamically imports the compiled TypeScript.
+ *
+ * Uses top-level await to ensure module evaluation errors are handled
+ * properly. Without await, errors during import would surface as unhandled
+ * rejections instead of clean CLI failures with appropriate exit codes.
+ */
+try {
+  await import("../dist/scripts/sample.js");
+} catch (error) {
+  console.error(
+    "Failed to start miniread-sample:",
+    error instanceof Error ? error.message : error,
+  );
+  process.exitCode = 1;
+}

package/dist/cli/config.d.ts

@@ -0,0 +1,17 @@
+import type { Transform } from "../core/types.js";
+type TransformSummary = {
+    id: string;
+    description: string;
+    scope: Transform["scope"];
+    parallelizable: boolean;
+};
+export declare const getTransformSummaries: () => TransformSummary[];
+type GetTransformsResult = {
+    ok: true;
+    transforms: Transform[];
+} | {
+    ok: false;
+    error: string;
+};
+export declare const getTransformsToRun: (transformList?: string) => GetTransformsResult;
+export {};

package/dist/cli/config.js

@@ -0,0 +1,85 @@
+import { transformPresets } from "../transforms/transform-presets.js";
+import { allTransformIds, transformRegistry, } from "../transforms/transform-registry.js";
+export const getTransformSummaries = () => {
+    const summaries = [];
+    for (const id of allTransformIds) {
+        const transform = transformRegistry[id];
+        if (!transform)
+            continue;
+        summaries.push({
+            id,
+            description: transform.description,
+            scope: transform.scope,
+            parallelizable: transform.parallelizable,
+        });
+    }
+    return summaries;
+};
+const getTransformsForPreset = (preset) => {
+    if (preset === "recommended" || preset === "default") {
+        return [...transformPresets.recommended];
+    }
+    if (preset === "all") {
+        return [...allTransformIds];
+    }
+    return;
+};
+export const getTransformsToRun = (transformList) => {
+    // undefined = run recommended transforms (default behavior)
+    if (transformList === undefined) {
+        const requestedIds = getTransformsForPreset("recommended");
+        if (!requestedIds || requestedIds.length === 0) {
+            return { ok: false, error: "No recommended transforms are configured." };
+        }
+        const transforms = [];
+        for (const id of requestedIds) {
+            const transform = transformRegistry[id];
+            if (!transform)
+                return { ok: false, error: `Unknown transform: ${id}` };
+            transforms.push(transform);
+        }
+        return { ok: true, transforms };
+    }
+    // Empty string = run no transforms (explicit empty list)
+    if (transformList === "" || transformList === "none") {
+        return { ok: true, transforms: [] };
+    }
+    // Parse comma-separated list
+    const requestedIds = transformList.split(",").map((id) => id.trim());
+    const expandedIds = [];
+    const unknownIds = [];
+    for (const id of requestedIds) {
+        if (!id || id === "none")
+            continue;
+        const presetTransforms = getTransformsForPreset(id);
+        if (presetTransforms) {
+            expandedIds.push(...presetTransforms);
+            continue;
+        }
+        expandedIds.push(id);
+    }
+    const uniqueIds = [];
+    const seen = new Set();
+    for (const id of expandedIds) {
+        if (seen.has(id))
+            continue;
+        seen.add(id);
+        uniqueIds.push(id);
+    }
+    const transforms = [];
+    for (const id of uniqueIds) {
+        const transform = transformRegistry[id];
+        if (!transform) {
+            unknownIds.push(id);
+            continue;
+        }
+        transforms.push(transform);
+    }
+    if (unknownIds.length > 0) {
+        return {
+            ok: false,
+            error: `Unknown transform(s): ${unknownIds.join(", ")}. Use --list-transforms to see available transforms.`,
+        };
+    }
+    return { ok: true, transforms };
+};

package/dist/cli/generate-code.d.ts

@@ -0,0 +1,2 @@
+import type { File } from "@babel/types";
+export declare const generateCode: (ast: File) => string;

package/dist/cli/generate-code.js

@@ -0,0 +1,7 @@
+import { createRequire } from "node:module";
+const require = createRequire(import.meta.url);
+// eslint-disable-next-line @typescript-eslint/no-unsafe-member-access
+const generate = require("@babel/generator").default;
+export const generateCode = (ast) => {
+    return generate(ast).code;
+};

package/dist/cli/output.d.ts

@@ -0,0 +1,7 @@
+import type PQueue from "p-queue";
+export declare const printDryRunSummary: (finalFiles: Map<string, string>, otherFilePaths: string[], inputBase: string) => void;
+type WriteOutputOptions = {
+    overwrite: boolean;
+};
+export declare const writeOutputFiles: (finalFiles: Map<string, string>, otherFilePaths: string[], inputBase: string, output: string, queue: PQueue, options: WriteOutputOptions) => Promise<void>;
+export {};

package/dist/cli/output.js

@@ -0,0 +1,119 @@
+import { randomUUID } from "node:crypto";
+import { constants as fsConstants } from "node:fs";
+import * as fs from "node:fs/promises";
+import path from "node:path";
+export const printDryRunSummary = (finalFiles, otherFilePaths, inputBase) => {
+    process.stdout.write("ACTION\tPATH\tBYTES\n");
+    for (const [filePath, content] of finalFiles) {
+        const relativePath = path.relative(inputBase, filePath);
+        process.stdout.write(`TRANSFORM\t${relativePath}\t${content.length}\n`);
+    }
+    for (const filePath of otherFilePaths) {
+        const relativePath = path.relative(inputBase, filePath);
+        process.stdout.write(`COPY\t${relativePath}\t\n`);
+    }
+};
+const isErrnoException = (error) => {
+    return error instanceof Error;
+};
+const commitTemporaryFile = async (temporaryPath, outputPath, options) => {
+    if (options.overwrite) {
+        try {
+            await fs.rename(temporaryPath, outputPath);
+            return;
+        }
+        catch (error) {
+            if (!isErrnoException(error))
+                throw error;
+            if (process.platform !== "win32")
+                throw error;
+            if (error.code !== "EEXIST" && error.code !== "EPERM")
+                throw error;
+            await fs.unlink(outputPath);
+            await fs.rename(temporaryPath, outputPath);
+            return;
+        }
+    }
+    if (process.platform === "win32") {
+        await fs.rename(temporaryPath, outputPath);
+        return;
+    }
+    await fs.link(temporaryPath, outputPath);
+    await fs.unlink(temporaryPath);
+};
+const writeTextFileAtomic = async (outputPath, content, options) => {
+    const outputDirectory = path.dirname(outputPath);
+    const temporaryPath = path.join(outputDirectory, `.miniread-tmp-${randomUUID()}`);
+    await fs.writeFile(temporaryPath, content, { encoding: "utf8", flag: "wx" });
+    try {
+        await commitTemporaryFile(temporaryPath, outputPath, options);
+    }
+    catch (error) {
+        await fs.unlink(temporaryPath).catch(() => { });
+        throw error;
+    }
+};
+const copyFileAtomic = async (sourcePath, outputPath, options) => {
+    const outputDirectory = path.dirname(outputPath);
+    const temporaryPath = path.join(outputDirectory, `.miniread-tmp-${randomUUID()}`);
+    await fs.copyFile(sourcePath, temporaryPath, fsConstants.COPYFILE_EXCL);
+    try {
+        await commitTemporaryFile(temporaryPath, outputPath, options);
+    }
+    catch (error) {
+        await fs.unlink(temporaryPath).catch(() => { });
+        throw error;
+    }
+};
+export const writeOutputFiles = async (finalFiles, otherFilePaths, inputBase, output, queue, options) => {
+    const conflicts = [];
+    if (!options.overwrite) {
+        for (const filePath of finalFiles.keys()) {
+            const relativePath = path.relative(inputBase, filePath);
+            const outputPath = path.join(output, relativePath);
+            try {
+                await fs.access(outputPath);
+                conflicts.push(relativePath);
+            }
+            catch {
+                // ok
+            }
+        }
+        for (const filePath of otherFilePaths) {
+            const relativePath = path.relative(inputBase, filePath);
+            const outputPath = path.join(output, relativePath);
+            try {
+                await fs.access(outputPath);
+                conflicts.push(relativePath);
+            }
+            catch {
+                // ok
+            }
+        }
+    }
+    if (conflicts.length > 0) {
+        const sample = conflicts.slice(0, 5).join(", ");
+        throw new Error(`Refusing to overwrite existing output file(s): ${sample}. Re-run with --overwrite to replace.`);
+    }
+    await fs.mkdir(output, { recursive: true });
+    const writePromises = [];
+    for (const [filePath, content] of finalFiles) {
+        const relativePath = path.relative(inputBase, filePath);
+        const outputPath = path.join(output, relativePath);
+        writePromises.push(queue.add(async () => {
+            const outputDirectory = path.dirname(outputPath);
+            await fs.mkdir(outputDirectory, { recursive: true });
+            await writeTextFileAtomic(outputPath, content, options);
+        }));
+    }
+    for (const filePath of otherFilePaths) {
+        const relativePath = path.relative(inputBase, filePath);
+        const outputPath = path.join(output, relativePath);
+        writePromises.push(queue.add(async () => {
+            const outputDirectory = path.dirname(outputPath);
+            await fs.mkdir(outputDirectory, { recursive: true });
+            await copyFileAtomic(filePath, outputPath, options);
+        }));
+    }
+    await Promise.all(writePromises);
+};

package/dist/cli/run-transforms.d.ts

@@ -0,0 +1,16 @@
+import type { Transform } from "../core/types.js";
+export type RunnerOptions = {
+    input: string;
+    output: string;
+    transforms: Transform[];
+    dryRun: boolean;
+    workers: number;
+    overwrite: boolean;
+    verbose: boolean;
+};
+export type RunnerResult = {
+    filesProcessed: number;
+    totalTransformations: number;
+    errors: string[];
+};
+export declare const runTransforms: (options: RunnerOptions) => Promise<RunnerResult>;

package/dist/cli/run-transforms.js

@@ -0,0 +1,145 @@
+import * as fs from "node:fs/promises";
+import path from "node:path";
+import PQueue from "p-queue";
+import { buildProjectGraph } from "../core/project-graph.js";
+import { printDryRunSummary, writeOutputFiles } from "./output.js";
+import { generateCode } from "./generate-code.js";
+const logVerbose = (verbose, message) => {
+    if (!verbose)
+        return;
+    console.error(message);
+};
+const isSourceFile = (fileName) => {
+    return (!fileName.endsWith(".d.ts") &&
+        (fileName.endsWith(".ts") ||
+            fileName.endsWith(".tsx") ||
+            fileName.endsWith(".js") ||
+            fileName.endsWith(".jsx")));
+};
+const findAllFiles = async (directory) => {
+    const sourceFiles = [];
+    const otherFiles = [];
+    const entries = await fs.readdir(directory, { withFileTypes: true });
+    for (const entry of entries) {
+        const fullPath = path.join(directory, entry.name);
+        if (entry.isDirectory()) {
+            const subResult = await findAllFiles(fullPath);
+            sourceFiles.push(...subResult.sourceFiles);
+            otherFiles.push(...subResult.otherFiles);
+        }
+        else if (entry.isFile()) {
+            if (isSourceFile(entry.name)) {
+                sourceFiles.push(fullPath);
+            }
+            else {
+                otherFiles.push(fullPath);
+            }
+        }
+    }
+    return { sourceFiles, otherFiles };
+};
+export const runTransforms = async (options) => {
+    const { input, output, transforms, dryRun, workers, overwrite, verbose } = options;
+    // Check if input exists
+    try {
+        await fs.access(input);
+    }
+    catch {
+        return {
+            filesProcessed: 0,
+            totalTransformations: 0,
+            errors: [`Input path does not exist: ${input}`],
+        };
+    }
+    // Find all files
+    const inputStat = await fs.stat(input);
+    let sourceFilePaths;
+    let otherFilePaths;
+    if (inputStat.isDirectory()) {
+        const allFiles = await findAllFiles(input);
+        sourceFilePaths = allFiles.sourceFiles;
+        otherFilePaths = allFiles.otherFiles;
+    }
+    else {
+        sourceFilePaths = isSourceFile(input) ? [input] : [];
+        otherFilePaths = isSourceFile(input) ? [] : [input];
+    }
+    if (sourceFilePaths.length === 0) {
+        return {
+            filesProcessed: 0,
+            totalTransformations: 0,
+            errors: ["No source files found in input path"],
+        };
+    }
+    logVerbose(verbose, `Found ${sourceFilePaths.length} source file(s)`);
+    if (otherFilePaths.length > 0) {
+        logVerbose(verbose, `Found ${otherFilePaths.length} other file(s) to copy`);
+    }
+    // Read all files
+    logVerbose(verbose, "Reading files...");
+    const parsedFiles = [];
+    for (const filePath of sourceFilePaths) {
+        const content = await fs.readFile(filePath, "utf8");
+        parsedFiles.push({ path: filePath, content });
+    }
+    // Build project graph (includes parsing)
+    logVerbose(verbose, "Parsing files with Babel...");
+    const projectGraph = buildProjectGraph(parsedFiles);
+    logVerbose(verbose, `Running ${transforms.length} transform(s) with ${workers} worker(s)...`);
+    // Create a queue for parallel processing
+    const queue = new PQueue({ concurrency: workers });
+    // Track results
+    let totalTransformations = 0;
+    // Run transforms sequentially - each mutates the AST in place
+    for (const transform of transforms) {
+        logVerbose(verbose, `Running transform: ${transform.id}`);
+        try {
+            const stats = await transform.transform({
+                projectGraph,
+                currentFile: undefined,
+                options: {},
+            });
+            totalTransformations += stats.transformationsApplied;
+            logVerbose(verbose, `Applied ${stats.transformationsApplied} transformation(s)`);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            return {
+                filesProcessed: 0,
+                totalTransformations,
+                errors: [`Transform '${transform.id}' failed: ${message}`],
+            };
+        }
+    }
+    // Generate final code from ASTs using @babel/generator
+    const finalFiles = new Map();
+    for (const [filePath, fileInfo] of projectGraph.files) {
+        const generated = generateCode(fileInfo.ast);
+        finalFiles.set(filePath, generated);
+    }
+    // Output results
+    const inputBase = inputStat.isDirectory() ? input : path.dirname(input);
+    if (dryRun) {
+        printDryRunSummary(finalFiles, otherFilePaths, inputBase);
+    }
+    else {
+        try {
+            await writeOutputFiles(finalFiles, otherFilePaths, inputBase, output, queue, { overwrite });
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            return {
+                filesProcessed: 0,
+                totalTransformations,
+                errors: [message],
+            };
+        }
+    }
+    logVerbose(verbose, `Processed ${finalFiles.size + otherFilePaths.length} file(s)`);
+    logVerbose(verbose, `Total transformations applied: ${totalTransformations}`);
+    return {
+        filesProcessed: finalFiles.size + otherFilePaths.length,
+        totalTransformations,
+        errors: [],
+    };
+};

package/dist/cli/runner.d.ts

@@ -0,0 +1,3 @@
+export type { RunnerOptions, RunnerResult } from "./run-transforms.js";
+export { runTransforms } from "./run-transforms.js";
+export { transformStdin } from "./transform-stdin.js";

package/dist/cli/runner.js

@@ -0,0 +1,2 @@
+export { runTransforms } from "./run-transforms.js";
+export { transformStdin } from "./transform-stdin.js";

package/dist/cli/transform-stdin.d.ts

@@ -0,0 +1,14 @@
+import type { Transform } from "../core/types.js";
+type StdinTransformOptions = {
+    transforms: Transform[];
+    verbose: boolean;
+};
+type StdinTransformResult = {
+    ok: true;
+    output: string;
+} | {
+    ok: false;
+    error: string;
+};
+export declare const transformStdin: (options: StdinTransformOptions) => Promise<StdinTransformResult>;
+export {};

package/dist/cli/transform-stdin.js

@@ -0,0 +1,58 @@
+import { buildProjectGraph } from "../core/project-graph.js";
+import { generateCode } from "./generate-code.js";
+const logVerbose = (verbose, message) => {
+    if (!verbose)
+        return;
+    console.error(message);
+};
+const readStdin = async () => {
+    return new Promise((resolve, reject) => {
+        let text = "";
+        process.stdin.setEncoding("utf8");
+        process.stdin.on("data", (chunk) => {
+            text += chunk;
+        });
+        process.stdin.on("end", () => {
+            resolve(text);
+        });
+        process.stdin.on("error", reject);
+    });
+};
+export const transformStdin = async (options) => {
+    const { transforms, verbose } = options;
+    const inputText = await readStdin();
+    const stdinPath = "stdin.tsx";
+    const parsedFiles = [{ path: stdinPath, content: inputText }];
+    const projectGraph = buildProjectGraph(parsedFiles);
+    const stdinFile = projectGraph.files.get(stdinPath);
+    if (!stdinFile) {
+        return { ok: false, error: "Failed to parse input" };
+    }
+    let totalTransformations = 0;
+    for (const transform of transforms) {
+        try {
+            const stats = await transform.transform({
+                projectGraph,
+                currentFile: undefined,
+                options: {},
+            });
+            totalTransformations += stats.transformationsApplied;
+            logVerbose(verbose, `Applied ${stats.transformationsApplied} transformation(s) from ${transform.id}`);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            return {
+                ok: false,
+                error: `Transform '${transform.id}' failed: ${message}`,
+            };
+        }
+    }
+    const generated = generateCode(stdinFile.ast);
+    const output = generated === ""
+        ? ""
+        : generated.endsWith("\n")
+            ? generated
+            : `${generated}\n`;
+    logVerbose(verbose, `Total transformations applied: ${totalTransformations}`);
+    return { ok: true, output };
+};

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};