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

package/.claude/plan.md

@@ -0,0 +1,53 @@
+# 实现 @ 路径别名支持
+
+## 目标
+在 `config.js` 中添加开关配置，支持 `@` 写法：`const mod = require('@/util/@3.0.0/mod.js')`，其中 `@` 代表项目根目录（baseDir）。
+
+## 修改文件
+
+### 1. `src/config/main_config.ts` — 添加配置项
+在 `EncodeConfig` 中添加 `useAlias: boolean` 开关（默认 `false`）。
+
+### 2. `src/config/index.ts` — 添加默认值
+在 `defConfig.encode` 中添加 `useAlias: false`。
+
+### 3. `src/scanf/index.ts` — `scanfRequieMod` 支持 @ 路径
+当 `modPath` 以 `@/` 或 `@\\` 开头时，将 `@` 替换为 `baseDir`（项目根目录），然后再进行路径解析。
+
+修改逻辑：
+```typescript
+export function scanfRequieMod(baseDir: string, modPath: string): string {
+  // 支持 @ 别名：@/xxx => baseDir/xxx
+  if (modPath.startsWith("@/") || modPath.startsWith("@\\")) {
+    modPath = modPath.replace(/^@[/\\]/, baseDir + path.sep);
+  }
+  // ... 原有逻辑不变
+}
+```
+
+### 4. `src/util/ast.ts` — `importMods` 支持 @ 路径生成
+decode 时生成 require 语句，如果 `config.encode.useAlias` 为 `true`，则生成 `@/...` 格式而非相对路径。
+
+需要将 `config` 传入 `importMods` 函数，或在函数内读取全局 config。
+
+修改逻辑：
+```typescript
+// 当 useAlias 开启时，使用 @ 别名路径替代相对路径
+if (useAlias) {
+  const aliasPath = srcPath.replace(baseDir, "").replace(/\\/g, "/");
+  requireFrom = "@" + aliasPath;
+} else {
+  requireFrom = relative(outDir, srcPath.replace(/(index)?\.js$/, "")).replace(/[\\]+/g, "/");
+}
+```
+
+### 5. `src/decode/index.ts` — 传递 config 给 importMods
+`importMods` 调用处需要传递 config 信息。
+
+## 实现顺序
+1. 修改 `MainConfig` 添加 `useAlias` 字段
+2. 修改 `initConfig` 添加默认值
+3. 修改 `scanfRequieMod` 支持 `@` 路径解析
+4. 修改 `importMods` 支持 `@` 路径生成
+5. 修改 `decode/index.ts` 传递 config
+6. 编译验证

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,36 @@
+# 任务
+编写体验优化，当前编写导入模块仅支持`const mod = require('../../util/@3.0.0/mod.js');`，我希望能够在`config.js`配置中加入开关配置，支持@写法：`const mod = require('@/util/@3.0.0/mod.js');`
+
+# 实现方案
+
+在 `EncodeConfig` 中添加 `useAlias: boolean` 开关：
+- `useAlias: true` — encode 阶段解析 `@/` 路径别名（`@` 代表项目根目录），decode 阶段生成 `@/` 路径
+- `useAlias: false`（默认）— 使用传统的相对路径
+
+### 修改的文件
+
+| 文件 | 改动 |
+|------|------|
+| `src/config/main_config.ts` | `EncodeConfig` 添加 `useAlias` 字段 |
+| `src/config/index.ts` | 默认 `useAlias: false`；`__dirname` 不含 `node_modules` 时回退到 `process.cwd()`；尝试 `config.js` 和 `config.json` 两种配置文件 |
+| `src/scanf/index.ts` | `scanfRequieMod` 添加 `rootDir` 参数，支持 `@/` 路径解析 |
+| `src/util/ast.ts` | `getRequireModPaths` 传递 `rootDir`；`importMods` 根据 `useAlias` 生成 `@/` 或相对路径；修复相对路径缺少 `./` 前缀的问题 |
+| `src/util/parent_path.ts` | `getParentRootDir` 在 junction symlink 场景下回退到 `config.baseDir` |
+| `src/context/map_context.ts` | `buildMapContext` 根据 `useAlias` 条件传递 `rootDir` |
+| `src/decode/index.ts` | 传递 `config.encode.useAlias` 给 `importMods` |
+
+# 测试结果 ✅
+
+### useAlias: true
+- **Encode**: `@/src/util/index` 正确解析为绝对路径，方法正确内联并添加 `__modName` 后缀
+- **Decode**: 生成 `require("@/src/util")` 和 `require("@/src/helper")`，`__modName` 后缀正确移除
+
+### useAlias: false
+- **Encode**: 相对路径 `./util/index` 正常解析
+- **Decode**: 生成 `require("./util")` 和 `require("./helper")`，路径以 `./` 开头
+
+### 修复的问题
+1. `useAlias` 无效 — `scanfRequieMod` 缺少 `rootDir` 参数，`@` 路径无法解析
+2. `Error: src\@\util\index.js is not exists!` — junction symlink 导致 `__dirname` 不含 `node_modules`，`getParentRootDir()` 返回 undefined
+3. `require("util")` 缺少 `./` 前缀 — `path.relative()` 返回的路径不以 `./` 开头，Node.js 会当作 npm 包名
+4. 配置文件查找失败 — 只尝试 `config.js`，不尝试 `config.json`

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;
+}