showtext — 代码库智能文档化工具

把一个源码目录（或多个目录/文件）里所有文本代码按规则收集起来，自动追踪它们之间的引用关系，最后打包输出成一份结构化 Markdown 文档。

纯 Node.js 实现，零第三方依赖。

典型用途：把整个项目喂给 AI 分析、项目交接留档、Code Review 前通览、老系统逆向梳理。

---

✨ 核心特性

#	功能	说明
F1	多源扫描	sources 可同时填多个目录和/或多个文件，逐个递归遍历
F2	全文本模式（默认）	不配置 allowedExts 时自动收集一切文本文件
F3	二进制识别	读取文件头 512 字节判断空字节/BOM，命中则跳过；扩展名黑名单兜底
F4	白名单模式	配置 allowedExts 后只收指定扩展名，如 [".ts", ".js"]
F5	特殊文件名强制包含	specialFilenames 可越过白名单与二进制黑名单（如 Dockerfile）
F6	依赖解析	自动追踪 require/import/include/src= 引用的文件并纳入报告
F7	多语言依赖支持	JS/TS/Vue/Svelte、Python、PHP、C/C++、HTML 五类语法
F8	解析深度控制	resolveDepth，-1 表示无限制
F9	目录级忽略	默认忽略 node_modules、.git、dist、build、coverage、.next 等 40+ 项
F10	自定义忽略	支持按名称（任何层级）或按精确路径忽略
F11	文件大小上限	maxFileSize 超过即跳过，防止日志/大文件撑爆报告
F12	符号链接处理	followSymlinks 控制是否跟随，默认关闭（防死循环）
F13	双分组模式	内容区按目录结构（默认）或按扩展名（groupByExtension）组织
F14	语法高亮	按扩展名/文件名自动标注代码块语言（40+ 种，含 Makefile、CMakeLists.txt）
F15	文件大小清单	文件结构表可选显示每个文件 KB 数
F16	输出自保护	输出文件自身永远不会被收进报告（避免自我嵌套）
F17	调试模式	debug: true 或 DEBUG=showtext，打印每一步跳过/命中原因
F18	可编程调用	require('./index.js') 导出 collectCodebase()，可嵌入构建脚本
F19	目录自动创建	输出目录不存在时自动 mkdir -p

---

🚀 快速开始

# 1. 复制配置模板
cp showtext.example.json showtext.json

# 2. 编辑配置，填入要扫描的目录和输出文件
# 3. 运行
node index.js ./showtext.json

# 或用 npm
npm run build

最小配置示例

{
  "sources": ["./src"],
  "output": "./docs/codebase.md",
  "allowedExts": [".js", ".ts"],
  "resolveDepth": 2,
  "maxFileSize": 512
}

完整配置项说明见 使用说明.md 与 doc/说明.md。

---

🏗 模块架构

文件	职责
index.js	主入口。① 命令行：加载配置 → 校验 → 调核心函数；② 模块导出 collectCodebase()
config.js	读并解析 JSON 配置文件，失败直接 process.exit(1)
ignore.js	把忽略规则拆成 ignoreNames（名称集）与 ignorePaths（绝对路径集）
collector.js	目录递归遍历 + 单文件准入判定（shouldCollectFile）+ 依赖 BFS 收集
resolver.js	各语言 import 语句正则解析 + Node 模块解析（含 package.json main、index.* 补全、扩展名补全）
markdown.js	生成配置表、文件结构表、文件内容代码块；语言标识映射
constants.js	默认忽略库、二进制扩展名黑名单、依赖解析扩展名表
utils.js	调试开关、时间/大小格式化、文本文件探测

数据流：配置加载 → 目录递归遍历 → 单文件准入判定 → 依赖 BFS 补全 → Markdown 渲染 → 写盘

---

📦 输出示例

生成的 Markdown 包含三部分：

1. 配置表 — 本次运行的完整参数快照
2. 文件结构表 — 树形清单（可选显示每个文件 KB 数）
3. 文件内容 — 每个文件的完整源码，按目录或扩展名分组，带语法高亮语言标识

---

🧩 可编程调用

const { collectCodebase } = require('./index.js');

await collectCodebase({
  sources: ['./src'],
  output: './docs/codebase.md',
});

---

📜 许可证 / License

本项目基于 Apache License 2.0 开源 — 详见 LICENSE 与 NOTICE。

Copyright 2026 白志明 (Bai Zhiming)

---

🔑 关键词

codebase · markdown · documentation · ai-context · dependency · code-analysis · Node.js