@kezh/my-custom-js-converter 1.1.11 → 1.5.0

package/.claude/plan.md

@@ -0,0 +1,65 @@
+# 日志优化方案
+
+## 现状问题
+
+1. **格式不统一** — 有的用 `=>` 分隔，有的直接打印数组，风格混乱
+2. **缺少层级结构** — 所有日志平铺输出，无法区分步骤/阶段
+3. **信息不完整** — `scanf dirs => ` 和数组分两行打印，`the map is not found!` 没有上下文
+4. **缺少状态标识** — 没有成功/失败/警告等视觉区分
+5. **中英混杂** — `路径不存在[...]忽略` vs `scanf dirs` vs `the map is not found!`
+6. **缺少汇总** — 处理完成后没有统计摘要
+
+## 优化方案
+
+### 1. 新建 `src/util/logger.ts` — 统一日志工具
+
+```typescript
+export function createLogger(scope: string) {
+  return {
+    info(msg: string)  { console.log(`[${scope}] ✔ ${msg}`); },
+    warn(msg: string)  { console.log(`[${scope}] ⚠ ${msg}`); },
+    error(msg: string) { console.log(`[${scope}] ✖ ${msg}`); },
+    step(title: string) {
+      console.log(`\n[${scope}] ── ${title} ${'─'.repeat(Math.max(0, 50 - title.length))}`);
+    },
+  };
+}
+```
+
+简洁、无外部依赖、终端友好。
+
+### 2. 日志对照表
+
+| 原始 | 优化后 |
+|---|---|
+| `console.log("scanf dirs => ")` + `console.log(targetDirs)` | `logger.info('scanf dirs: ' + targetDirs.join(', '))` |
+| `console.log(\`scanf file => ${inPath}\`)` | `logger.info(\`scanf file: ${inPath}\`)` |
+| `console.log(\`output file => ${outPath}\`)` | `logger.info(\`output: ${outPath}\`)` |
+| `console.log(\`output => ${outPath}\`)` | `logger.info(\`output: ${outPath}\`)` |
+| `console.log(\`input map => ${inPath}\`)` | `logger.info(\`read map: ${inPath}\`)` |
+| `console.log("the map is not found!")` | `logger.warn('map file not found')` |
+| `console.log(\`output map => ${outPath}\`)` | `logger.info(\`write map: ${outPath}\`)` |
+| `console.log(\`not found entry => ${entry}\`)` | `logger.warn(\`entry not found: ${entry}\`)` |
+| `console.log(\`路径不存在[${dirPath}]忽略\`)` | `logger.warn(\`dir not found, skipping: ${dirPath}\`)` |
+| `console.log(\`ignore module => ${item.id.name}\`)` | `logger.info(\`ignore module: ${item.id.name}\`)` |
+
+### 3. 增加步骤分隔和汇总
+
+**encode** 流程增加：
+- 步骤标题：扫描目录 → 查找文件 → 编码处理
+- 汇总：处理文件数、方法总数、版本号
+
+**decode** 流程增加：
+- 步骤标题：扫描目录 → 查找文件 → 解码处理
+- 汇总：处理文件数
+
+### 4. 修改文件清单
+
+| 文件 | 变更 |
+|---|---|
+| `src/util/logger.ts` | **新建** — 日志工具模块 |
+| `src/encode/index.ts` | 替换 4 处 console.log，增加步骤和汇总 |
+| `src/decode/index.ts` | 替换 4 处 console.log，增加步骤和汇总 |
+| `src/context/map_context.ts` | 替换 3 处 console.log |
+| `src/scanf/index.ts` | 替换 1 处 console.log |
+| `src/util/ast.ts` | 替换 1 处 console.log |

package/CLAUDE.md

@@ -0,0 +1,50 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+`@kezh/my-custom-js-converter` is a Babel-based JavaScript code transformer that **encodes** (flattens) and **decodes** (restores) CommonJS module structures. It takes JavaScript files that use `require()` + object-oriented patterns and flattens them into a single object with renamed methods, then can reverse the process.
+
+## Build & Run
+
+```bash
+pnpm install          # install dependencies
+pnpm build            # compile TypeScript (npx tsc --build)
+```
+
+The compiled output goes to `core/` (gitignored). Source is in `src/`.
+
+Two CLI entry points (declared in `package.json` bin):
+- `encode` → `core/encode/index.js` — flattens modules into a single file
+- `decode` → `core/decode/index.js` — restores the original module structure
+
+No test framework is configured.
+
+## Architecture
+
+### Data Flow
+
+**Encode**: Scan target dirs → find entry JS files → build dependency map (`MapContext`) → extract & rename methods from all modules → output single flattened file + `mod.map`
+
+**Decode**: Read `mod.map` → read encoded file → re-insert `require` statements → remove inlined dependency methods → restore original method names → output restored file
+
+### Key Modules
+
+- **`src/config/`** — Configuration loading. `MainConfig` defines encode/decode settings (entry object name, file names, ignore list). Reads `config.json` from the parent project root when installed as a dependency.
+- **`src/context/map_context.ts`** — Core orchestration. `MapContext` builds a dependency graph by recursively walking `require()` calls, then performs **filtering** (removing invalid method references) and **tree-shaking** (removing unused methods). Serializes to `mod.map` JSON file.
+- **`src/util/ast.ts`** — All Babel AST manipulation: parsing, traversing, extracting object methods, renaming methods (appending `__modName` suffix), generating import statements, and reversing the renaming during decode.
+- **`src/scanf/`** — File system scanning: finding target files by name, resolving `require()` paths (handles both `dir/index.js` and `file.js` patterns).
+- **`src/util/parent_path.ts`** — Detects whether the tool is running inside `node_modules/` and resolves the parent project root.
+
+### Encoding Convention
+
+Methods from dependency modules are renamed with a `__modName` suffix (e.g., `helperMethod` becomes `helperMethod__util`). `this.method()` calls in the root module stay as-is; in dependency modules, `this.method()` becomes `this.method__modName()`. The decode step reverses this convention.
+
+### Configuration
+
+When used as a dependency, the tool reads `config.json` from the parent project's root. Default config:
+- `encode.file`: `"index.js"`, `encode.output`: `"coded.js"`, `encode.entry`: `"customEvent"`
+- `decode.file`: `"coded.js"`, `decode.output`: `"decoded.js"`, `decode.mount`: `"customEvent"`
+- `settingDir`: `".setting"` (where `mod.map` is stored)
+- `target`: directories to scan relative to `baseDir`

package/README.en.md

@@ -0,0 +1,116 @@
+[中文](README.md)
+
+# my-custom-js-converter
+
+A Babel-based JavaScript code transformer that flattens and restores CommonJS module structures.
+
+## Features
+
+- **Encode** — Recursively scans `require()` dependencies, extracts used methods from each module, and flattens them into a single file with renamed methods (e.g., `helperMethod__util`).
+- **Decode** — Reads the generated dependency map and restores the original module structure by re-inserting `require()` statements and reversing method renaming.
+- **Tree-shaking** — Only methods that are actually used are included in the encoded output; unused methods are stripped.
+- **Configurable** — Entry object name, file names, ignore list, and scan directories are all configurable via `config.json`.
+
+## Installation
+
+```bash
+npm install @kezh/my-custom-js-converter
+# or
+pnpm add @kezh/my-custom-js-converter
+```
+
+## Usage
+
+### 1. Create a config file
+
+Create `config.json` in your project root:
+
+```json
+{
+  "encode": {
+    "file": "index.js",
+    "output": "coded.js",
+    "entry": "customEvent",
+    "ignoreMod": ["commonUtil"]
+  },
+  "decode": {
+    "file": "coded.js",
+    "output": "decoded.js",
+    "mount": "customEvent"
+  },
+  "target": ["src"],
+  "settingDir": ".setting"
+}
+```
+
+#### Config Options
+
+| Field | Description |
+|---|---|
+| `encode.file` | Source file name to encode |
+| `encode.output` | Encoded output file name |
+| `encode.entry` | Entry object name in source |
+| `encode.ignoreMod` | Module names to skip during encoding |
+| `decode.file` | Encoded file to decode |
+| `decode.output` | Decoded output file name |
+| `decode.mount` | Object name to mount decoded code |
+| `target` | Directories to scan (relative to project root) |
+| `settingDir` | Directory for the dependency map file |
+
+### 2. Encode
+
+```bash
+npx encode
+```
+
+Scans the `target` directories for files matching `encode.file`, builds a dependency map, and outputs:
+- `encode.output` — the flattened code file
+- `settingDir/mod.map` — the dependency map (needed for decoding)
+
+### 3. Decode
+
+```bash
+npx decode
+```
+
+Reads the dependency map from `settingDir/mod.map`, restores `require()` imports, reverses method renaming, and outputs `decode.output`.
+
+## How It Works
+
+### Encode Flow
+
+```
+index.js (entry: customEvent)
+  ├── require('./util')     → util.methodA(), util.methodB()
+  └── require('./helper')   → helper.process()
+
+        ↓ encode
+
+coded.js
+  customEvent = {
+    ownMethod() { ... },
+    methodA__util() { ... },      // from util
+    methodB__util() { ... },      // from util
+    process__helper() { ... }     // from helper
+  }
+```
+
+### Decode Flow
+
+```
+coded.js + mod.map
+
+        ↓ decode
+
+decoded.js
+  const util = require('./util');
+  const helper = require('./helper');
+  customEvent = {
+    ownMethod() { ... },
+    // methodA__util, methodB__util, process__helper removed
+  }
+```
+
+## License
+
+MIT

package/README.md

@@ -0,0 +1,116 @@
+[English](README.en.md)
+
+# my-custom-js-converter
+
+基于 Babel 的 JavaScript 代码转换器，用于扁平化和还原 CommonJS 模块结构。
+
+## 功能
+
+- **编码（Encode）** — 递归扫描 `require()` 依赖，从每个模块中提取被使用的方法，扁平化到单个文件中并重命名方法（如 `helperMethod__util`）。
+- **解码（Decode）** — 读取生成的依赖映射文件，还原原始模块结构，重新插入 `require()` 语句并恢复方法命名。
+- **摇树优化（Tree-shaking）** — 编码输出仅包含实际使用的方法，未使用的方法会被移除。
+- **可配置** — 入口对象名、文件名、忽略列表和扫描目录均可通过 `config.json` 配置。
+
+## 安装
+
+```bash
+npm install @kezh/my-custom-js-converter
+# 或
+pnpm add @kezh/my-custom-js-converter
+```
+
+## 使用方式
+
+### 1. 创建配置文件
+
+在项目根目录创建 `config.json`：
+
+```json
+{
+  "encode": {
+    "file": "index.js",
+    "output": "coded.js",
+    "entry": "customEvent",
+    "ignoreMod": ["commonUtil"]
+  },
+  "decode": {
+    "file": "coded.js",
+    "output": "decoded.js",
+    "mount": "customEvent"
+  },
+  "target": ["src"],
+  "settingDir": ".setting"
+}
+```
+
+#### 配置项
+
+| 字段 | 说明 |
+|---|---|
+| `encode.file` | 编码的源文件名 |
+| `encode.output` | 编码输出文件名 |
+| `encode.entry` | 源码中的入口对象名 |
+| `encode.ignoreMod` | 编码时忽略的模块名 |
+| `decode.file` | 待解码的文件名 |
+| `decode.output` | 解码输出文件名 |
+| `decode.mount` | 解码代码的挂载对象名 |
+| `target` | 扫描目录（相对于项目根目录） |
+| `settingDir` | 依赖映射文件存放目录 |
+
+### 2. 编码
+
+```bash
+npx encode
+```
+
+扫描 `target` 目录中匹配 `encode.file` 的文件，构建依赖映射，输出：
+- `encode.output` — 扁平化后的代码文件
+- `settingDir/mod.map` — 依赖映射文件（解码时需要）
+
+### 3. 解码
+
+```bash
+npx decode
+```
+
+读取 `settingDir/mod.map` 中的依赖映射，还原 `require()` 导入，恢复方法命名，输出 `decode.output`。
+
+## 工作原理
+
+### 编码流程
+
+```
+index.js (entry: customEvent)
+  ├── require('./util')     → util.methodA(), util.methodB()
+  └── require('./helper')   → helper.process()
+
+        ↓ encode
+
+coded.js
+  customEvent = {
+    ownMethod() { ... },
+    methodA__util() { ... },      // 来自 util
+    methodB__util() { ... },      // 来自 util
+    process__helper() { ... }     // 来自 helper
+  }
+```
+
+### 解码流程
+
+```
+coded.js + mod.map
+
+        ↓ decode
+
+decoded.js
+  const util = require('./util');
+  const helper = require('./helper');
+  customEvent = {
+    ownMethod() { ... },
+    // methodA__util 等已移除
+  }
+```
+
+## 许可证
+
+MIT

package/TASKS.md

@@ -0,0 +1,2 @@
+# 任务
+项目encode和decode输出日志可读性差，请帮我优化日志。

package/core/config/index.d.ts

@@ -1,2 +1,2 @@
-import { MainConfig } from "./main_config";
-export declare const config: MainConfig;
+import { MainConfig } from "./main_config";
+export declare const config: MainConfig;

package/core/config/index.js

@@ -1,44 +1,69 @@
-"use strict";
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.config = void 0;
-const fs_1 = __importDefault(require("fs"));
-const path_1 = __importDefault(require("path"));
-exports.config = initConfig();
-function initConfig() {
-    const defConfig = {
-        encode: {
-            file: "index.js",
-            output: "coded.js",
-            entry: "customEvent",
-            ignoreMod: ["commonUtil"],
-        },
-        decode: {
-            file: "coded.js",
-            output: "decoded.js",
-            mount: "customEvent",
-        },
-        baseDir: "",
-        target: [""],
-        settingDir: ".setting",
-        customConfig: "config.json",
-    };
-    const curDir = __dirname;
-    const baseDir = curDir.replace(/node_modules.*/g, "");
-    try {
-        const configPath = path_1.default.join(baseDir, defConfig.customConfig);
-        fs_1.default.accessSync(configPath);
-        const json = fs_1.default.readFileSync(configPath, { encoding: "utf-8" });
-        const customConfig = JSON.parse(json);
-        defConfig.baseDir = baseDir;
-        Object.keys(customConfig).map(key => key).forEach((key) => {
-            if (customConfig[key]) {
-                defConfig[key] = customConfig[key];
-            }
-        });
-    }
-    catch (err) { }
-    return defConfig;
-}
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.config = void 0;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+exports.config = initConfig();
+function initConfig() {
+    const defConfig = {
+        encode: {
+            file: "index.js",
+            output: "coded.js",
+            entry: "customEvent",
+            ignoreMod: ["commonUtil"],
+            useAlias: false,
+        },
+        decode: {
+            file: "coded.js",
+            output: "decoded.js",
+            mount: "customEvent",
+        },
+        baseDir: "",
+        target: [""],
+        settingDir: ".setting",
+        customConfig: "config.js",
+    };
+    const curDir = __dirname;
+    let baseDir = curDir.replace(/node_modules.*/g, "");
+    // 当 __dirname 不包含 node_modules 时（如 junction symlink 场景），
+    // 尝试从 process.cwd() 查找配置文件
+    if (!curDir.includes("node_modules")) {
+        baseDir = process.cwd();
+    }
+    // 尝试查找配置文件：先 customConfig 指定的文件名，再 config.json
+    const configCandidates = [defConfig.customConfig, "config.json"];
+    for (const configName of configCandidates) {
+        try {
+            const configPath = path_1.default.join(baseDir, configName);
+            fs_1.default.accessSync(configPath);
+            let customConfig;
+            if (configPath.endsWith(".js")) {
+                // 支持 .js 配置文件，可使用注释
+                customConfig = require(configPath);
+            }
+            else {
+                // 兼容 .json 配置文件
+                const json = fs_1.default.readFileSync(configPath, { encoding: "utf-8" });
+                customConfig = JSON.parse(json);
+            }
+            defConfig.baseDir = baseDir;
+            Object.keys(customConfig).map(key => key).forEach((key) => {
+                if (customConfig[key]) {
+                    defConfig[key] = customConfig[key];
+                }
+            });
+            // baseDir 允许从配置文件中显式覆盖
+            if (customConfig.baseDir) {
+                defConfig.baseDir = customConfig.baseDir;
+            }
+            break;
+        }
+        catch (err) {
+            continue;
+        }
+    }
+    return defConfig;
+}

package/core/config/main_config.d.ts

@@ -1,19 +1,20 @@
-export interface MainConfig {
-    encode: EncodeConfig;
-    decode: DecodeConfig;
-    baseDir: string;
-    target: string[];
-    settingDir: string;
-    customConfig: string;
-}
-export interface EncodeConfig {
-    file: string;
-    output: string;
-    entry: string;
-    ignoreMod: string[];
-}
-export interface DecodeConfig {
-    file: string;
-    output: string;
-    mount: string;
-}
+export interface MainConfig {
+    encode: EncodeConfig;
+    decode: DecodeConfig;
+    baseDir: string;
+    target: string[];
+    settingDir: string;
+    customConfig: string;
+}
+export interface EncodeConfig {
+    file: string;
+    output: string;
+    entry: string;
+    ignoreMod: string[];
+    useAlias: boolean;
+}
+export interface DecodeConfig {
+    file: string;
+    output: string;
+    mount: string;
+}

package/core/config/main_config.js

@@ -1,2 +1,2 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/core/config/map_config.d.ts

@@ -1,15 +1,15 @@
-export declare class MapConfig {
-    [mod: string]: Mod;
-}
-export declare class Mod {
-    src: string;
-    dependencies: Dependencies;
-    constructor(src: string, dependencies?: Dependencies);
-}
-export declare class Dependencies {
-    [name: string]: Dependency;
-}
-export declare class Dependency {
-    methods: string[];
-    constructor(methods?: string[]);
-}
+export declare class MapConfig {
+    [mod: string]: Mod;
+}
+export declare class Mod {
+    src: string;
+    dependencies: Dependencies;
+    constructor(src: string, dependencies?: Dependencies);
+}
+export declare class Dependencies {
+    [name: string]: Dependency;
+}
+export declare class Dependency {
+    methods: string[];
+    constructor(methods?: string[]);
+}

package/core/config/map_config.js

@@ -1,22 +1,22 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.Dependency = exports.Dependencies = exports.Mod = exports.MapConfig = void 0;
-class MapConfig {
-}
-exports.MapConfig = MapConfig;
-class Mod {
-    constructor(src, dependencies = new Dependencies()) {
-        this.src = src;
-        this.dependencies = dependencies;
-    }
-}
-exports.Mod = Mod;
-class Dependencies {
-}
-exports.Dependencies = Dependencies;
-class Dependency {
-    constructor(methods = []) {
-        this.methods = methods;
-    }
-}
-exports.Dependency = Dependency;
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Dependency = exports.Dependencies = exports.Mod = exports.MapConfig = void 0;
+class MapConfig {
+}
+exports.MapConfig = MapConfig;
+class Mod {
+    constructor(src, dependencies = new Dependencies()) {
+        this.src = src;
+        this.dependencies = dependencies;
+    }
+}
+exports.Mod = Mod;
+class Dependencies {
+}
+exports.Dependencies = Dependencies;
+class Dependency {
+    constructor(methods = []) {
+        this.methods = methods;
+    }
+}
+exports.Dependency = Dependency;

package/core/context/map_context.d.ts

@@ -1,28 +1,28 @@
-import { Mod } from "../config/map_config";
-export declare class MapContext {
-    static SAVE_FILE: string;
-    private srcPath;
-    private entry;
-    private outDir;
-    private map;
-    constructor(srcPath?: string, entry?: string, outDir?: string, initMap?: boolean);
-    appendModMap(mod: Mod, self: boolean, name?: string): void;
-    getModNames(): string[];
-    getMod(name: string): Mod | null | undefined;
-    getMethodNamesByMod(name: string): string[];
-    getDependencyNameByMod(name: string): string[];
-    getSrcPathByMod(name: string): string | undefined;
-    getAbsoluteSrcPathByMod(name: string): string | undefined;
-    static readFromLocal(inDir: string): MapContext;
-    private init;
-    private writeToLocal;
-    private buildMapContext;
-    /**
-     * 过滤self的dependencies中无效方法
-     */
-    private filtering;
-    /**
-     * 去除dependencies中未使用方法
-     */
-    private shaking;
-}
+import { Mod } from "../config/map_config";
+export declare class MapContext {
+    static SAVE_FILE: string;
+    private srcPath;
+    private entry;
+    private outDir;
+    private map;
+    constructor(srcPath?: string, entry?: string, outDir?: string, initMap?: boolean);
+    appendModMap(mod: Mod, self: boolean, name?: string): void;
+    getModNames(): string[];
+    getMod(name: string): Mod | null | undefined;
+    getMethodNamesByMod(name: string): string[];
+    getDependencyNameByMod(name: string): string[];
+    getSrcPathByMod(name: string): string | undefined;
+    getAbsoluteSrcPathByMod(name: string): string | undefined;
+    static readFromLocal(inDir: string): MapContext;
+    private init;
+    private writeToLocal;
+    private buildMapContext;
+    /**
+     * 过滤self的dependencies中无效方法
+     */
+    private filtering;
+    /**
+     * 去除dependencies中未使用方法
+     */
+    private shaking;
+}