agmd 0.3.15 → 1.0.1

package/README.md

@@ -1,71 +1,374 @@
-# Auto-Generate-MD (agmd)
-
-> Auto-Generate-MD is a versatile tool designed to enhance front-end code management. Perfect for developers and teams looking to streamline their documentation process, it offers a range of features from automatic markdown generation to detailed project analysis.
-
-[![]( https://camo.githubusercontent.com/28479a7a834310a667f36760a27283f7389e864a/68747470733a2f2f696d672e736869656c64732e696f2f6e706d2f6c2f76322d646174657069636b65722e737667)]( https://camo.githubusercontent.com/28479a7a834310a667f36760a27283f7389e864a/68747470733a2f2f696d672e736869656c64732e696f2f6e706d2f6c2f76322d646174657069636b65722e737667)
-[![]( https://github.com/kakajun/auto-generate-md/actions/workflows/test.yml/badge.svg?branch=master)]( https://github.com/kakajun/auto-generate-md/actions/workflows/test.yml)
-[![]( https://app.circleci.com/pipelines/github/kakajun/auto-generate-md)]( https://app.circleci.com/pipelines/github/kakajun/auto-generate-md)
-
-简体中文 | [English](https://github.com/kakajun/auto-generate-md/blob/master/README.EN.md)
-
- ## 🚀 Features
-
-
-*   **Automatic Markdown Generation**: Enter `agmd` in any directory to create a markdown file summarizing its contents.
-*   **Code and File Analysis**: Provides statistics on code volume and file types within your project.
-*   **Path Conversion**: Converts absolute paths to relative for easier file navigation in VS Code.
-*   **Route Marking**: Classifies the project based on routes, aiding in project segmentation.
-*   **Interface-Friendly**: Offers a GUI for command operations, eliminating the need to memorize commands.
-*   **Comprehensive Structure Tree**: Generates a JSON tree representing the entire project structure.
-*   **TypeScript Support**: Written in TypeScript with 85% of the code covered by test cases.
-
-### Interface Preview
-
-![image](https://github.com/kakajun/auto-generate-md/blob/master/md3.png)
-### Use Cases
-
-![image](https://github.com/kakajun/auto-generate-md/blob/master/md2.png)
-
-### Installation and Usage
-1.  **Global Installation**:
-
-    *   Install globally using `npm i agmd -g`.
-    *   Run `agmd` in the desired directory to generate markdown files.
-2.  **Dependency Installation**:
-
-    *   Install as a dev dependency with `npm i agmd -D`.
-    *   Configure in `package.json` for automatic documentation updates.
-
-
-###  Command Descriptions
-*   Help
-*   Generate structure tree document
-*   Convert to relative paths
-*   Complete file suffix
-*   Rename files and folders to KebabCase
-*   Mark and categorize files
-
- ### Advanced Use
-
-*   Classify files using `classify.js` in the src directory.
-*   Access `getFileNodes()` and `getMd()` for custom documentation.
-
-#### Command Line Arguments
-*   `agmd -h` for help.
-*   `--ignore` to exclude files or folders.
-*   `--include` to specify file types for inclusion.
-
- ### Development and Contribution
-This project includes 26 tests for easy expansion and modification. Contributions and PRs are welcome.
-
-### Changelog
-*   **0.3.15**: Code refactoring and updates.
-*   **0.3.8**: Interface improvements and feature additions.
-*   **0.3.0**: Major feature updates and UI improvements.
-*   **0.2.9**: File statistic feature added.
-*   **0.2.6**: Global installation bug fix.
-*   **0.2.0**: Support for command-line argument parsing.
-*   **0.1.3**: Initial release with basic features.
-
-### Related Articles
-[掘金-自动生成目录 md 文件](https://juejin.cn/post/7030030599268073508)
+# agmd(auto generate md)
+
+> 这是一个前端代码管理的辅助工具，在任何需要生成文档的，文件夹下的控制台中输入`agmd`， 就能自动生成目录 md 说明(部分功能需要在src目录下), 同时能够统计分析当前工程的各类型文件总量和代码总量，还提供一些实用的工具，具体看下面功能特征
+
+[![]( https://camo.githubusercontent.com/28479a7a834310a667f36760a27283f7389e864a/68747470733a2f2f696d672e736869656c64732e696f2f6e706d2f6c2f76322d646174657069636b65722e737667)]( https://camo.githubusercontent.com/28479a7a834310a667f36760a27283f7389e864a/68747470733a2f2f696d672e736869656c64732e696f2f6e706d2f6c2f76322d646174657069636b65722e737667)
+[![]( https://github.com/kakajun/auto-generate-md/actions/workflows/test.yml/badge.svg?branch=master)]( https://github.com/kakajun/auto-generate-md/actions/workflows/test.yml)
+[![]( https://app.circleci.com/pipelines/github/kakajun/auto-generate-md)]( https://app.circleci.com/pipelines/github/kakajun/auto-generate-md)
+
+简体中文 | [English](https://github.com/kakajun/auto-generate-md/blob/master/README.EN.md)
+
+## 🚀  功能特性
+
+😍 一键统计工程的文件数和代码总量
+
+📦 一键补充缺省后缀名 .js .vue 这样子能方便vscode编辑器点击直接跳转查看代码
+
+🚘 一键更改文件或者文件名,驼峰命名为kable-case
+
+⛵ 把工程所有引用更改绝对路径为相对路径(方便点击下钻查看文件)
+🔧 支持将相对路径统一转换为基于 '@' 别名的绝对路径
+
+♨️ 把工程按路由标记分类(对拆分工程很重要)
+
+☝️ 把工程按分类对拆分工程(自动拆分的错误可控, 手动拆分会有各种问题)
+
+✈️ 全程界面命令选择操作, 不用记命令
+
+😍 得到一个包含整个工程结构树的json
+
+💡 一键拿到文件和文件夹名字, 并生成JSON输出
+
+🔥 **v2 版本使用 Rust 重写，性能提升 10 倍以上，零 Node.js 依赖**
+
+## 设计初衷
+
+1. 统计工程量, 看看咱们工程究竟有多少个文件, 多少代码量
+2. 如果仅仅只是为了重命文件和文件夹, 那么其实这个库没有存在的必要, 因为我们可以自己随手写个node代码, 就全部重命名了, 问题的关键是, 我们内部工程有很多依赖, 像这样子 `import { replaceName } from '../src/commands/rename-path'` , 我们需要一个工具, 能够帮我们自动生成目录, 快速定位到文件,也进行重命名来减少重复劳动, 提升效率.
+3. 如果想把工程1分2做成按路由拆分的微服务, 那么需要知道哪些文件被工程1用到了, 哪些文件被工程2用到了, 那么就需要一个工具, 来进行标记,甚至清除没有被标记的文件.
+
+
+### 操作界面
+
+![image](https://github.com/kakajun/auto-generate-md/blob/master/imgs/md3.jpg)
+### 案例
+
+![image](https://github.com/kakajun/auto-generate-md/blob/master/imgs/md2.png)
+
+### 使用方法
+
+**v2 版本基于 Rust 构建，通过 npm 分发预编译二进制，无需本地 Rust 环境。**
+
+1. 全局安装
+> npm i agmd -g
+
+安装完成后，在需要记录 md 的文件夹下面输入`agmd`，会自动生成相对路径下的文件夹和文件的名字，如果文件里面还有在头部写注释的话，那么会一并带过来自动生成 md 文件。生成的文件名为`readme-md.md`， 路径为刚刚输入命名的路径同级别下，对于工程比较大的开发来说，这个脚本或许会帮你省下些许时间。
+
+2. 作为依赖安装
+> npm i agmd -D
+
+在package.json的scripts 中配置 agmd: npx agmd --ignore lib,node_modules,dist --include .js,.ts,.vue [--dry-run] [--silent]   可以在每次启动或打包时,带上命令行来自动更新文档
+
+
+example，是我为演示准备的一些文件，并没有其他用
+
+
+3. 命令说明
+- 帮助
+- 生成结构树文档
+- 修改为相对路径
+- 修改为绝对路径
+- 补全文件后缀
+- 统一命名文件夹为 Kebab-Case
+- 统一命名文件为 Kebab-Case
+- 记录节点 JSON
+- 给需要分类的都打上标记
+- 删除标记
+- 分类
+
+
+4. 代码结构说明
+```
+├── src/
+│   ├── main.rs              # CLI 入口：解析参数 + 交互菜单
+│   ├── lib.rs               # 库入口：公开 API
+│   ├── cli.rs               # clap 命令行参数定义
+│   ├── types.rs             # 核心数据结构
+│   ├── commands.rs          # 高层动作分发（对应菜单每一项）
+│   ├── get_file.rs          # 递归扫描、提取注释/大小/import
+│   ├── write_md.rs          # 生成 Markdown、统计输出
+│   ├── change_path.rs       # 批量重写 import 路径
+│   ├── rename_path.rs       # 批量重命名文件/文件夹
+│   ├── get_router.rs        # 解析路由配置
+│   ├── mark_file.rs         # 按路由给文件打标记
+│   ├── mark_write_file.rs   # 按标记分类复制文件
+│   └── bin/                 # 开发调试脚本
+├── tests/                   # 集成测试与单元测试
+├── bin/                     # 预编译二进制（多平台分发）
+├── Cargo.toml               # Rust 包配置
+├── package.json             # npm 包配置
+├── agmd.js                  # Node 入口：检测平台并 spawn 二进制
+├── install.js               # postinstall：复制对应平台二进制
+└── classify.js              # 路由分类配置示例
+```
+
+5. 高级用法
+给文件打标记分类, 需要在src的同级目录下, 设置一个文件叫classify.js, 从里面读取需要配置的信息, 注意路径一定是带@符号的路径，@代表项目根目录（如 `@/components/Button.vue`）, 没有配置, 那么程序会自动退出
+
+
+#### Rust 库 API
+
+本项目同时提供 Rust 库，暴露两个异步 API：
+
+```rust
+use agmd::{get_file_nodes_api, get_md_api, types::Options};
+use std::path::Path;
+
+let option = Options {
+    ignore: Some(vec!["node_modules".to_string()]),
+    include: Some(vec![".rs".to_string()]),
+    ..Default::default()
+};
+
+// 获取文件节点树
+let nodes = get_file_nodes_api(Path::new("./src"), Some(&option)).await?;
+
+// 获取 Markdown 输出
+let (md, nodes) = get_md_api(Some(&option), Path::new(".")).await?;
+```
+#### 命令行参数说明
+1. 使用agmd -h 来查看帮助
+2. 可以带上 --ignore 忽略输出文件或文件夹, 默认为: img,styles,node_modules,LICENSE,.git,.github,dist,.husky,.vscode,readme-file.js,readme-md.js
+3. 可以带上 --include 要求只输出带此后缀文件, 默认只输出 .js,.vue,.ts, 可自己加jsx,json 等
+
+### 创作背景
+
+1. 大家有没有被要求写一个目录文件的 md 说明呢？
+2. 或者工程目录和文件被移动位置重构了，这时还需要重新修改 md 文件里面的目录说明
+3. 接手老工程，看了 md 说明，能对文件夹里面的文件功能做到一目了然，而不是点开对应文件去看
+4. 分析源码工程需要做点笔记
+5. 拆分老代码工程, 手工量大还容易出错, 程序控制又快又好
+6. 为什么绝对路径要改相对路径? 大家用vscode重命名文件时, 有没发现, 引用文件是绝对路径时, 文件没变化.....而且点击下钻查看文件详情还点不下去????但是相对路径不会有这个问题
+7. 文件有后缀能一目了然文件是js文件还是vue文件
+8. 一切需要手工重复操作的, 都可以用插件脚本搞定, 留时间学新知识更好
+9. 补全缀是刚需, 很多伙伴就不喜欢写文件后缀, 所以import引入的是组件还是js 得去查看, 很不方便
+
+### 功能
+
+1. 自动生成匹配目录的文件夹名和文件(已经按名称进行排序)
+2. 自动进行层级目录判断进行缩进
+3. 如果文件顶部有注释， 那么会自动进行判断
+4. 支持在任意文件目录下递归查找下级文件(不要在很大目录下执行啊!!!递归直到该级目录下没有文件为止)
+5. 支持命令行参数配置, 可以自定义忽略文件和过滤后缀名文件
+6. 命令行解析
+
+控制台命令: agmd --include <string> --ignore <string> [--dry-run] [--silent]
+
+可选项:
+  --include string  / -in string.......... 包含解析的后缀 (以空格分隔)
+  --ignore string  / -i string........... 忽略文件名或目录 (以空格分隔)
+  --dry-run        / -d..................  预演模式, 不对文件系统进行写入
+  --silent         / -s..................  静默模式, 最小化日志输出
+
+例子:
+  --ignore / -i  img,styles,node_modules,LICENSE,.git,.github,dist,.husky,.vscode,readme-file.js,readme-md.js
+  --include / -in  .js,.vue,.ts
+
+注意:
+配置中的字符串之间不应有空格
+
+命令行例子:
+$ agmd --ignore lib node_modules dist --include .js .ts .vue --dry-run --silent
+
+### 相关文章
+
+[掘金-自动生成目录 md 文件](https://juejin.cn/post/7030030599268073508)
+
+### 写在最后
+
+本工程有36个测试, 大家如果想扩展什么功能, 测试代码跑起来, 很方便, 也欢迎大家克隆本工程然后提交进行PR！
+
+### 更新记录
+0.1.3
+1. 采用esbuild 进行打包
+2. 并且用eslint, preter规范写法, 规范
+3. 用ts进行改写
+4. 支持gitee一键同步
+
+0.2.0
+支持命令行解析参数,可以动态传参
+
+0.2.6
+修复全局安装报错
+
+0.2.9
+新增文件统计功能
+
+0.3.0
+✈️ 全程界面命令选择操作
+
+⛵ 把工程所有引用更改绝对路径为相对路径(方便点击下钻查看文件)
+
+♨️ 把工程所有引用文件都加上后缀(方便点击下钻查看文件)
+
+👏 把工程按路由标记分类(对拆分工程很重要)
+
+☝️ 把工程按分类对拆分工程(自动拆分的错误可控, 手动拆分会有各种问题)
+
+0.3.3
+优化提示日志打印
+对路由进行自动分析
+增加单元测试到26个,覆盖率达到84%,一些没必要的方法就没测试
+
+0.3.7
+升级所有依赖到最新
+
+0.3.8
+操作界面改成中文的, 我还是做不到大爱全世界, 先给自己和中国伙伴用好就行了, 同时增加功能只补全后缀, 但不更改路径
+
+0.3.14
+重构代码, 修改打包有esbuild转为tsc编译, 同时修改里面本身为异步操作的fs.readFileSync改为await  readFile ,同时新增部分测试用例使得覆盖率达到85%
+
+0.4.1
+重构代码, 新增功能:
+1. 新增命令行参数 --dry-run / -d 预演模式, 不对文件系统进行写入
+2. 新增命令行参数 --silent / -s 静默模式, 最小化日志输出
+3. 新增命令行参数 --absolute-alias / -a 把工程所有引用文件都加上绝对路径别名(方便点击下钻查看文件)
+
+0.5.0 / v2
+🔥 **使用 Rust 完全重写**
+1. 性能提升 10 倍以上，大型工程秒级扫描
+2. 零 Node.js 运行时依赖，单二进制文件分发
+3. 支持多平台：Linux x64/ARM64、macOS x64/ARM64、Windows x64
+4. npm 包内含所有平台预编译二进制，安装时自动选择当前平台
+5. 安装包体积大幅缩小
+
+### 开发者打包发布说明
+
+v2 版本使用 Rust 编写，npm 包通过内嵌多平台预编译二进制分发。
+
+#### 本地开发环境搭建（Windows）
+
+如果你需要在 Windows 本地编译和测试，按以下步骤安装 Rust 环境：
+
+1. **创建目录**（建议非 C 盘）
+   ```powershell
+   New-Item -ItemType Directory -Force -Path E:\rust\cargo, E:\rust\rustup, E:\mingw
+   ```
+
+2. **下载并安装 Rust**
+   ```powershell
+   $env:CARGO_HOME='E:\rust\cargo'
+   $env:RUSTUP_HOME='E:\rust\rustup'
+   Invoke-WebRequest -Uri https://win.rustup.rs/x86_64 -OutFile E:\rustup-init.exe
+   E:\rustup-init.exe -y --default-toolchain stable
+   ```
+
+3. **下载 MinGW-w64（GNU 工具链）**
+   ```powershell
+   Invoke-WebRequest -Uri https://github.com/brechtsanders/winlibs_mingw/releases/download/13.2.0posix-17.0.6-11.0.1-ucrt-r5/winlibs-x86_64-posix-seh-gcc-13.2.0-llvm-17.0.6-mingw-w64ucrt-11.0.1-r5.zip -OutFile E:\mingw.zip
+   Expand-Archive -Path E:\mingw.zip -DestinationPath E:\mingw -Force
+   ```
+
+4. **添加环境变量**
+
+   在系统环境变量中添加：
+   - `CARGO_HOME` = `E:\rust\cargo`
+   - `RUSTUP_HOME` = `E:\rust\rustup`
+   - `Path` 追加 `E:\rust\cargo\bin;E:\mingw\mingw64\bin`
+
+5. **安装 GNU 目标并切换默认工具链**
+   ```powershell
+   rustup target add x86_64-pc-windows-gnu
+   rustup toolchain install stable-x86_64-pc-windows-gnu
+   rustup default stable-x86_64-pc-windows-gnu
+   ```
+
+6. **验证安装**
+   ```powershell
+   rustc --version
+   cargo --version
+   gcc --version
+   ```
+
+#### 运行测试
+
+```powershell
+# 进入项目目录
+cd e:\git\auto-generate-md
+
+# 运行所有测试
+cargo test
+
+# 运行单个测试（带输出）
+cargo test test_write_to_file_sync_replacement_logic -- --nocapture
+```
+
+#### 打包 Windows 版本
+
+```powershell
+# 编译 release 版本
+cargo build --release --target x86_64-pc-windows-gnu
+
+# 复制到 bin 目录
+Copy-Item target\x86_64-pc-windows-gnu\release\agmd.exe bin\agmd-windows-x64.exe -Force
+```
+
+#### 打包步骤（全平台）
+
+1. **编译各平台二进制**
+
+   在对应平台执行（或交叉编译）：
+
+   ```bash
+   # Linux x64
+   cargo build --release --target x86_64-unknown-linux-gnu
+   cp target/x86_64-unknown-linux-gnu/release/agmd bin/agmd-linux-x64
+
+   # Linux ARM64
+   cargo build --release --target aarch64-unknown-linux-gnu
+   cp target/aarch64-unknown-linux-gnu/release/agmd bin/agmd-linux-arm64
+
+   # macOS x64
+   cargo build --release --target x86_64-apple-darwin
+   cp target/x86_64-apple-darwin/release/agmd bin/agmd-macos-x64
+
+   # macOS ARM64
+   cargo build --release --target aarch64-apple-darwin
+   cp target/aarch64-apple-darwin/release/agmd bin/agmd-macos-arm64
+
+   # Windows x64（MSVC 工具链，需安装 Visual Studio）
+   cargo build --release --target x86_64-pc-windows-msvc
+   cp target/x86_64-pc-windows-msvc/release/agmd.exe bin/agmd-windows-x64.exe
+
+   # Windows x64（GNU 工具链，无需 Visual Studio）
+   cargo build --release --target x86_64-pc-windows-gnu
+   cp target/x86_64-pc-windows-gnu/release/agmd.exe bin/agmd-windows-x64.exe
+   ```
+
+2. **确保二进制可执行**
+
+   ```bash
+   chmod +x bin/agmd-linux-* bin/agmd-macos-*
+   ```
+
+3. **更新版本号**
+
+   同步修改以下文件的版本号：
+   - `Cargo.toml`
+   - `package.json`
+
+4. **发布到 npm**
+
+   ```bash
+   npm publish
+   ```
+
+   需要提前登录 npm：`npm login`
+
+#### npm 包结构
+
+```
+├── package.json      # npm 包配置
+├── agmd.js           # 入口脚本，检测平台并 spawn 二进制
+├── install.js        # postinstall，复制对应平台二进制为 agmd
+├── bin/              # 预编译二进制目录
+│   ├── agmd-linux-x64
+│   ├── agmd-linux-arm64
+│   ├── agmd-macos-x64
+│   ├── agmd-macos-arm64
+│   └── agmd-windows-x64.exe
+└── ...
+```
+
+用户安装时，`postinstall` 脚本会自动检测当前平台，从 `bin/` 复制对应二进制并命名为 `agmd`，无需联网下载。

package/agmd.js

@@ -0,0 +1,55 @@
+#!/usr/bin/env node
+const { spawn } = require('child_process');
+const path = require('path');
+const fs = require('fs');
+const os = require('os');
+
+function getBinaryPath() {
+  const binDir = path.join(__dirname, 'bin');
+  const platform = os.platform();
+  const targetName = platform === 'win32' ? 'agmd.exe' : 'agmd';
+  const targetPath = path.join(binDir, targetName);
+
+  if (fs.existsSync(targetPath)) {
+    return targetPath;
+  }
+
+  const arch = os.arch();
+  const platformMap = { win32: 'windows', darwin: 'macos', linux: 'linux' };
+  const archMap = { x64: 'x64', arm64: 'arm64' };
+  const p = platformMap[platform];
+  const a = archMap[arch];
+
+  if (!p || !a) {
+    console.error(`Unsupported platform: ${platform} ${arch}`);
+    process.exit(1);
+  }
+
+  const ext = platform === 'win32' ? '.exe' : '';
+  const binaryName = `agmd-${p}-${a}${ext}`;
+  const fallbackPath = path.join(binDir, binaryName);
+
+  if (fs.existsSync(fallbackPath)) {
+    return fallbackPath;
+  }
+
+  console.error(`Binary not found. Please reinstall agmd.`);
+  process.exit(1);
+}
+
+const binaryPath = getBinaryPath();
+const args = process.argv.slice(2);
+
+const child = spawn(binaryPath, args, {
+  stdio: 'inherit',
+  shell: false,
+});
+
+child.on('error', (err) => {
+  console.error('Failed to start agmd:', err.message);
+  process.exit(1);
+});
+
+child.on('exit', (code) => {
+  process.exit(code ?? 0);
+});

package/install.js

@@ -0,0 +1,59 @@
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+function getBinaryName() {
+  const platform = os.platform();
+  const arch = os.arch();
+
+  const platformMap = {
+    win32: 'windows',
+    darwin: 'macos',
+    linux: 'linux',
+  };
+
+  const archMap = {
+    x64: 'x64',
+    arm64: 'arm64',
+  };
+
+  const p = platformMap[platform];
+  const a = archMap[arch];
+
+  if (!p || !a) {
+    console.error(`Unsupported platform: ${platform} ${arch}`);
+    process.exit(1);
+  }
+
+  const ext = platform === 'win32' ? '.exe' : '';
+  return `agmd-${p}-${a}${ext}`;
+}
+
+function main() {
+  const binaryName = getBinaryName();
+  const binDir = path.join(__dirname, 'bin');
+  const sourcePath = path.join(binDir, binaryName);
+
+  if (!fs.existsSync(sourcePath)) {
+    console.error(`Binary not found for your platform: ${binaryName}`);
+    console.error('Supported platforms: Linux x64/ARM64, macOS x64/ARM64, Windows x64');
+    process.exit(1);
+  }
+
+  const targetName = os.platform() === 'win32' ? 'agmd.exe' : 'agmd';
+  const targetPath = path.join(binDir, targetName);
+
+  try {
+    if (fs.existsSync(targetPath)) {
+      fs.unlinkSync(targetPath);
+    }
+    fs.copyFileSync(sourcePath, targetPath);
+    fs.chmodSync(targetPath, 0o755);
+    console.log(`agmd installed: ${binaryName}`);
+  } catch (err) {
+    console.error('Failed to setup binary:', err.message);
+    process.exit(1);
+  }
+}
+
+main();