agmd 0.3.15 → 1.0.1

package/AGENTS.md

@@ -0,0 +1,215 @@
+# AGENTS.md — agmd (auto-generate-md)
+
+> 本文件面向 AI 编程助手。若你对本项目一无所知，请先阅读本文档再修改代码。
+
+---
+
+## 项目概述
+
+`agmd` 是一个用 **Rust** 编写的 CLI 工具兼库，用于扫描前端工程目录并自动生成 Markdown 文档、统计代码量、规范化 import 路径、批量重命名文件/文件夹，以及按路由对工程文件进行标记和拆分。
+
+- **包名**: `agmd`
+- **版本**: `0.4.0` (Rust crate) / `1.0.0` (npm 包)
+- **协议**: MIT
+- **仓库**: https://github.com/kakajun/auto-generate-md
+
+> ⚠️ 当前 `Cargo.toml` (`0.4.0`) 与 `package.json` (`1.0.0`) 版本号不一致，发布前务必同步。
+
+本项目同时提供：
+1. **Rust 二进制** (`cargo run --bin agmd`) —— 独立可执行文件，零 Node.js 依赖。
+2. **Rust 库** (`src/lib.rs`) —— 暴露异步 API `get_file_nodes_api` 和 `get_md_api`。
+3. **npm 包** (根目录 `package.json`) —— 内含多平台预编译二进制，安装时自动匹配当前平台。
+
+---
+
+## 技术栈
+
+| 层级 | 技术 |
+|------|------|
+| 语言 | Rust (Edition 2024) |
+| 异步运行时 | Tokio (`features = ["full"]`) |
+| CLI 解析 | clap (derive 宏) |
+| 交互菜单 | dialoguer + console |
+| 序列化 | serde + serde_json |
+| 正则 | regex |
+| 文件遍历 | walkdir |
+| 路径差分 | pathdiff |
+| 命名转换 | convert_case |
+| 测试辅助 | tempfile (dev-dependency) |
+| 分发 | npm 包包裹预编译二进制 |
+
+---
+
+## 项目结构
+
+```
+├── src/
+│   ├── main.rs              # 二进制入口：解析 CLI 参数 + 交互菜单
+│   ├── lib.rs               # 库入口：公开模块 + 两个公开 API
+│   ├── cli.rs               # clap 派生的 Args 结构体和帮助文本
+│   ├── types.rs             # 核心数据结构：FileNode, Options, Router, RouterItem, CountResult, RenameInfo
+│   ├── commands.rs          # 高层动作分发器（对应菜单每一项）
+│   ├── utils.rs             # 工具函数：正则解析、命名转换、默认忽略/包含列表
+│   ├── get_file.rs          # 递归扫描文件系统、提取注释/大小/行数/import
+│   ├── write_md.rs          # 生成 Markdown、统计输出、codeAndPrompt.md
+│   ├── change_path.rs       # 批量重写 import 路径（相对 ↔ @ 别名）
+│   ├── rename_path.rs       # 批量重命名文件/文件夹（kebab-case ↔ CamelCase）
+│   ├── get_router.rs        # 解析 router 配置或 classify.js
+│   ├── mark_file.rs         # 按路由给文件打标记（//markname）
+│   ├── mark_write_file.rs   # 按标记分类复制文件到路由目录
+│   └── bin/                 # 开发调试用的独立可执行脚本（硬编码本地路径）
+├── tests/                   # 集成测试与单元测试
+│   ├── integration_test.rs
+│   ├── get_file_tests.rs
+│   ├── router_tests.rs
+│   ├── utils_tests.rs
+│   ├── write_md_tests.rs
+│   └── rename_path_tests.rs
+├── bin/                     # 预编译二进制存放目录（多平台分发）
+├── imgs/                    # 文档图片（README 引用）
+├── Cargo.toml               # Rust 包配置
+├── package.json             # npm 包配置（含 files、scripts、bin）
+├── agmd.js                  # Node 入口：检测平台并 spawn 二进制
+├── install.js               # postinstall：复制对应平台二进制到 agmd / agmd.exe
+├── .cargo/config.toml       # 交叉编译链接器配置
+├── .github/workflows/test.yml # CI（Rust 原生测试）
+├── classify.js              # 路由分类配置示例（@/ 别名路径）
+├── README.md                # 中文文档（主文档）
+└── README.EN.md             # 英文文档
+```
+
+---
+
+## 构建与测试命令
+
+### 日常开发
+
+```bash
+# 编译调试版本
+cargo build
+
+# 编译 release 版本
+cargo build --release
+
+# 运行所有测试（36+ 个）
+cargo test
+
+# 运行单个测试并打印输出
+cargo test <测试名> -- --nocapture
+
+# 直接运行 CLI
+cargo run --bin agmd
+```
+
+### 交叉编译 / 发布
+
+项目支持多平台二进制分发。参考 `.cargo/config.toml` 中已配置的交叉编译目标：
+
+- `aarch64-unknown-linux-gnu`
+- `x86_64-pc-windows-gnu`
+
+完整发布流程见 `README.md` 中「开发者打包发布说明」一节。发布前必须同步以下文件的版本号：
+- `Cargo.toml`
+- `package.json`
+
+编译后将二进制复制到 `bin/` 并执行 `npm publish`。
+
+### npm 脚本
+
+```bash
+npm run build    # => cargo build --release
+npm run test     # => cargo test
+```
+
+---
+
+## 代码组织与模块划分
+
+### 核心流程
+
+1. **扫描** (`get_file.rs`) —— 递归读取目录，构建 `FileNode` 树，提取文件元数据（大小、行数、首行注释、import 语句）。
+2. **输出** (`write_md.rs`) —— 将 `FileNode` 树渲染为 Markdown，或输出 `codeAndPrompt.md`（目录树 + 完整源码）。
+3. **路径操作** (`change_path.rs`) —— 根据 `FileNode` 中的 `imports`，批量替换文件内的 `from '...'` 路径：支持「相对路径 → `@` 别名」和「`@` 别名 → 相对路径」两种方向，以及仅补全后缀的模式。
+4. **重命名** (`rename_path.rs`) —— 对文件/文件夹在 `kebab-case` 与 `CamelCase`/`UpperCamelCase` 之间批量转换，并同步更新文件内的 import 路径。Windows 下对大小写不敏感文件系统采用“先临时重命名再最终重命名”的策略。
+5. **路由与标记** (`get_router.rs` → `mark_file.rs` → `mark_write_file.rs`) —— 解析路由配置，沿组件依赖链注入标记注释，最后按路由将文件复制到独立目录。
+
+### 数据结构中心
+
+所有跨模块传递的数据结构定义在 `src/types.rs`：
+- `Options` —— 扫描/操作的全局选项（ignore, include, dry_run, silent）。
+- `FileNode` —— 文件/目录树节点，含子节点、import 列表、所属路由等。
+- `Router` / `RouterItem` —— 路由配置结构。
+- `CountResult` —— 统计结果（总行数、总字符数、按后缀计数）。
+- `RenameInfo` —— 重命名前后名称映射。
+
+### 交互入口
+
+`main.rs` 使用 `dialoguer::Select` 提供中文交互菜单，共 14 个选项，对应 `commands.rs` 中的动作函数。
+
+---
+
+## 代码风格规范
+
+1. **注释语言**：代码注释和文档字符串以 **中文** 为主。新增注释请保持中文。
+2. **错误处理**：统一使用 `anyhow::Result` 进行错误传播，顶层 `main` 函数直接返回 `Result`。
+3. **异步**：IO 密集型操作使用 `tokio` 异步 API（如 `tokio::fs`），公开 API 均为 `async fn`。
+4. **命名**：
+   - 模块/函数：蛇形命名（`get_file_nodes`, `change_path_sync`）。
+   - 结构体：大驼峰（`FileNode`, `Options`）。
+   - 布尔标志字段：以动词或状态命名（`dry_run`, `is_dir`, `copyed`）。
+5. **序列化**：对外暴露的数据结构使用 `serde` 的 `Serialize`/`Deserialize` derive，可选字段配合 `skip_serializing_if = "Option::is_none"`。
+6. **不安全代码**：仅在 `mark_file.rs` 和 `mark_write_file.rs` 中使用 `unsafe` 指针技巧实现可变树遍历（`find_nodes_mut`）。修改此类代码需格外谨慎。
+7. **字符串处理**：路径和文本处理大量使用 `regex` 进行解析（如 `parse_router_path`, `parse_component_path`）。
+
+---
+
+## 测试策略
+
+测试全部位于 `tests/` 目录，按功能分文件：
+
+| 测试文件 | 覆盖内容 |
+|----------|----------|
+| `integration_test.rs` | 端到端集成测试：临时目录构造真实文件，测试扫描、路径替换、后缀补全、两遍绝对路径操作等 |
+| `get_file_tests.rs` | `resolve_alias_path`, `get_relative_path`, `change_import`, `set_md`, `get_note` |
+| `router_tests.rs` | `parse_router_path`, `parse_component_path` 的正则解析 |
+| `utils_tests.rs` | 命名转换、数字格式化、默认列表等工具函数 |
+| `write_md_tests.rs` | `get_count_md`, `set_count_md` 统计与 Markdown 格式化 |
+| `rename_path_tests.rs` | 路径转换、真实文件系统重命名（含嵌套目录和 Windows 大小写处理）|
+
+### 运行建议
+
+```bash
+# 全量测试
+cargo test
+
+# 查看测试覆盖率（若已安装 cargo-tarpaulin）
+cargo tarpaulin --out Html
+```
+
+### 新增功能的测试约定
+
+- 凡涉及文件系统写入的操作，优先使用 `tempfile::TempDir` 构造隔离环境。
+- `dry_run` 模式应在测试中被覆盖，确保不会实际修改文件系统。
+- 涉及 import 路径替换的测试需覆盖：同级目录、兄弟目录、深层目录、`@` 别名互转、仅补全后缀等场景。
+
+---
+
+## 安全与注意事项
+
+1. **文件系统写入**：`dry_run` 模式仅用于预览，但代码中仍有多处直接 `fs::write` / `rename`。修改路径操作相关代码时，务必检查 `dry_run` 和 `silent` 标志是否正确传递。
+2. **Windows 大小写敏感**：`rename_path.rs` 对 Windows 文件系统做了特殊处理（临时重命名策略）。改动重命名逻辑时应在 Windows 环境验证。
+3. **npm 分发安全**：`bin/` 中的预编译二进制按惯例不纳入 Git 跟踪（`.gitignore` 已排除）。发布时需手动将可信构建产物放入该目录。
+4. **classify.js 路径格式**：路由分类功能要求配置中使用 `@/` 开头的别名路径。若扩展路由解析逻辑，需保持对该约定的兼容。
+5. **开发调试脚本**：`src/bin/` 下的多个测试二进制硬编码了本地路径（如 `E:\cwd\front1.5`）。这些文件仅供原作者本地调试，不应作为通用入口依赖。
+
+---
+
+## 快速参考
+
+| 目标 | 命令 |
+|------|------|
+| 本地运行 CLI | `cargo run --bin agmd` |
+| 运行全部测试 | `cargo test` |
+| Release 构建 | `cargo build --release` |
+| 构建 Windows GNU 目标 | `cargo build --release --target x86_64-pc-windows-gnu` |
+| 发布 npm 包 | 同步版本号后 `npm publish` |

package/README.EN.md

@@ -1,175 +1,164 @@
-# agmd(auto generate md)
-
-
-
->For any document that needs to be generated, enter 'AGMD' in the console under the folder to automatically generate the directory MD description
-
-
-
-[![]( https://camo.githubusercontent.com/28479a7a834310a667f36760a27283f7389e864a/68747470733a2f2f696d672e736869656c64732e696f2f6e706d2f6c2f76322d646174657069636b65722e737667 )]( https://camo.githubusercontent.com/28479a7a834310a667f36760a27283f7389e864a/68747470733a2f2f696d672e736869656c64732e696f2f6e706d2f6c2f76322d646174657069636b65722e737667 )
-
-
-🚀 Features
-
-🔥 Written in TypeScript
-
-🔋 build with esbuild
-
-💡 easy get foldName and fileName.
-
-
-
-### Case
-
-
-
-! [image]( https://github.com/kakajun/auto-generate-md/blob/master/md2.png )
-
-
-
-### Method of use
-
-Node environment is required
-
-1. Global installation
-
-> npm i agmd -g
-
-
-
-After installation, enter 'AGMD' under the folder where MD needs to be recorded, and the names of folders and files under the relative path will be automatically generated. If comments are written in the header of the file, it will be brought together to automatically generate MD files. The generated file name is' readme md.md ', and the path is the path just entered. At the same level, for the development of large projects, this script may save you some time.
-
-
-
-2. Install as a dependency
-
-> npm i agmd -D
-
-
-
-In package Configure AGMD in scripts of JSON: NPX AGMD -- ignore lib, node_ modules,dist --include . js,. ts,. Vue can automatically update the document with the command line every time it is started or packaged
-
-
-
-
-Example is some of the files I prepared for the demonstration, which is of no other use
-
-
-
-3. Advanced usage
-
-Some need to insert the automatically generated documents into an automatically generated MD. the plug-in exports the automatically generated MD data method, and 'getfilenodes' obtains the specific information of all files. You can DIY different documents (the method name does not need to be remembered, because it is written by TS, so it will be automatically clicked)
-
->const agmd = require('agmd')
-
-
-
-In es:
-
->import agmd from 'agmd'
-
-
-
-- AGMD Getfilenodes () can obtain information related to specific files, and this function can pass a parameter
-
-
-
-- agmd. Getmd() gets the final output information
-
-Note: the above two methods can pass an option input parameter in the following format:
-
-option: { ignore: string[] | undefined; include: string[] | undefined }
-
-#### Command line parameter description
-
-1. Use AGMD - h to view help
-
-2. You can bring -- ignore to ignore the output file or folder. The default is: IMG, styles, node_ modules,LICENSE,. git,. github,dist,. husky,. vscode,readme-file. js,readme-md.js
-
-3. You can bring -- include. Only files with this suffix are required to be output. By default, only files are output js,. vue,. TS, you can add JSX, JSON, etc
-
-
-
-### Creative background
-
-1. Have you been asked to write a MD description of the directory file?
-
-2. Or if the project directory and files are reconstructed after being moved, the directory description in the MD file needs to be modified again
-
-3. After taking over the old project and reading the MD instructions, you can see the file functions in the folder at a glance, rather than clicking on the corresponding file
-
-4. You need to take notes to analyze the source code project
-
-
-
-### Function
-
-1. Automatically generate folder names and files matching directories (sorted by name)
-
-2. Automatically determine the hierarchical directory and indent it
-
-3. If there is a comment at the top of the file, it will be judged automatically
-
-4. Support recursive search of subordinate files in any file directory (do not execute in a large directory!!! Recursion until there are no files in this directory)
-
-5. Support command line parameter configuration, and can customize ignore files and filter suffix files
-
-6. Command line parsing
-
-
-
-`Usage: agmd--include str--ignore str
-
-
-
-Options:
-
---include string / -i string.......... include file extension
-
---ignore string / -in string........... ignore file or fold
-
-
-
-Str deafult:
-
---ignore / -i img,styles,node_ modules,LICENSE,. git,. github,dist,. husky,. vscode,readme-file. js,readme-md.js
-
---include / -in . js,. vue,. ts
-
-
-
-Note:
-
-There should be no space between strings in a configuration
-
-
-
-Examples:
-
-$ agmd --ignore lib,node_ modules,dist --include . js,. ts,. vue`
-
-
-
-### Related articles
-
-[Nuggets - auto generate directory MD file]（ https://juejin.cn/post/7030030599268073508 )
-
-
-
-### Update record
-
-0.1.3
-
-1. Package with esbuild
-
-2. It is written in eslint and preter specification
-
-3. Rewrite with TS
-
-4. Support gitee one key synchronization test11253123
-
-
-
-0.2.0
-1
-Support command-line parsing parameters, and can transfer parameters dynamically
+# agmd (auto generate md)
+
+> A CLI and library that scans your project to generate Markdown docs for directory structures, counts code metrics, and provides utilities to normalize imports, rename paths, and classify files via routes.
+
+## Features
+- Count files and total lines/characters in the project
+- Auto-complete missing suffixes like `.js` and `.vue`
+- Rename files/folders from CamelCase to Kebab-Case
+- Convert imports from absolute to relative paths for easy navigation
+- Classify files by routes and export JSON of nodes
+- Interactive CLI for all operations
+- Output the full tree as JSON
+- Convert relative imports to absolute alias-based paths using `@`
+- **v2 rewritten in Rust — 10x faster, zero Node.js dependency**
+
+## Usage
+
+**v2 is built with Rust and distributed via npm as precompiled binaries. No Rust toolchain required.**
+
+- Global: `npm i agmd -g`
+- Local: `npm i agmd -D`
+- Run: `agmd` in the directory you want to document
+
+The generated Markdown (`readme-md.md`) contains:
+- A "Directory Structure" section
+- A "Statistics" section with totals per suffix, lines and characters
+
+When you install via npm, the `postinstall` script automatically downloads the correct precompiled binary for your platform (Linux x64/ARM64, macOS x64/ARM64, Windows x64).
+
+## Scripts
+Add to `package.json`:
+
+`npx agmd --ignore lib,node_modules,dist --include .js,.ts,.vue [--dry-run] [--silent]`
+
+## CLI Commands (interactive)
+- Help
+- Generate Structure Markdown
+- Change Relative Path
+- Change Absolute Path
+- Completion suffix
+- Rename folders to Kebab-Case
+- Rename files to Kebab-Case
+- Record nodes as JSON
+- Mark files for classification
+- Delete marks
+- Classification
+
+## CLI Options
+- `--include string` / `-in string` Include suffixes (space-separated)
+- `--ignore string` / `-i string` Ignore file or directory names (space-separated)
+- `--dry-run` / `-d` Preview changes without writing to disk
+- `--silent` / `-s` Minimize logs
+
+Defaults:
+- `--ignore` img,styles,node_modules,LICENSE,.git,.github,dist,.husky,.vscode,readme-file.js,readme-md.js
+- `--include` .js,.vue,.ts
+
+Example:
+`agmd --ignore lib node_modules dist --include .js .ts .vue --dry-run --silent`
+
+## Advanced
+Create `classify.js` at the project root to define route-based classification. Use `@` alias paths in the config. If missing, the tool scans `router/` automatically.
+
+## Rust Library 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()
+};
+
+// Get file node tree
+let nodes = get_file_nodes_api(Path::new("./src"), Some(&option)).await?;
+
+// Get Markdown output
+let (md, nodes) = get_md_api(Some(&option), Path::new(".")).await?;
+```
+
+## Notes
+- Prefer running path operations inside `src` due to alias resolution conventions
+- Dry-run and silent modes are supported across write operations
+
+## Changelog
+
+### v2.0.0
+- **Completely rewritten in Rust**
+- 10x+ performance improvement for large projects
+- Zero Node.js runtime dependency — single binary distribution
+- Multi-platform support: Linux x64/ARM64, macOS x64/ARM64, Windows x64
+- npm package includes all platform binaries, auto-selects on install
+- Smaller install footprint
+
+## Developer Build & Publish Guide
+
+v2 is written in Rust. The npm package distributes precompiled binaries for all platforms.
+
+### Build Steps
+
+1. **Compile binaries for each platform**
+
+   Run on each target platform (or cross-compile):
+
+   ```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
+   cargo build --release --target x86_64-pc-windows-msvc
+   cp target/x86_64-pc-windows-msvc/release/agmd.exe bin/agmd-windows-x64.exe
+   ```
+
+2. **Make binaries executable**
+
+   ```bash
+   chmod +x bin/agmd-linux-* bin/agmd-macos-*
+   ```
+
+3. **Bump version**
+
+   Update version in both:
+   - `Cargo.toml`
+   - `package.json`
+
+4. **Publish to npm**
+
+   ```bash
+   npm publish
+   ```
+
+   Make sure you are logged in: `npm login`
+
+### npm Package Structure
+
+```
+├── package.json      # npm package config
+├── agmd.js           # Entry script, detects platform and spawns binary
+├── install.js        # postinstall, copies platform binary as 'agmd'
+├── bin/              # Precompiled binaries
+│   ├── agmd-linux-x64
+│   ├── agmd-linux-arm64
+│   ├── agmd-macos-x64
+│   ├── agmd-macos-arm64
+│   └── agmd-windows-x64.exe
+└── ...
+```
+
+On install, the `postinstall` script detects the current platform, copies the matching binary from `bin/`, and renames it to `agmd`. No network download required.