component-auto-docs 0.1.0

package/README.md

@@ -0,0 +1,107 @@
+# component-auto-docs
+
+uni-app 组件库文档自动化 CLI。
+
+它会从组件源码中自动抽取 `defineProps`、`defineEmits`、slots、JSDoc 和类型信息，再结合每个组件目录下的 `docs.meta.json`，生成 Markdown 文档、App 内组件文档页数据、AI 结构化索引和质量报告。
+
+## 安装
+
+```bash
+pnpm add -D component-auto-docs
+```
+
+## 快速使用
+
+```bash
+pnpm exec component-auto-docs scaffold
+pnpm exec component-auto-docs init
+pnpm exec component-auto-docs gen
+pnpm exec component-auto-docs check
+```
+
+执行后会生成或更新：
+
+- `docs/components/*.md`：给开发者阅读的组件 Markdown 文档。
+- `docs/ai/components.catalog.json`：AI 和检索系统使用的结构化组件目录。
+- `docs/ai/components.index.md`、`docs/ai/llms.txt`：AI 友好的文本索引。
+- `docs/ai/components.quality.json`：文档质量报告。
+- `src/docs/data.json`、`src/docs/components/*/data.json`：App 内文档页数据。
+- `src/docs/components/*/index.vue`：可交互组件文档页。
+
+## 命令说明
+
+- `scaffold`：向当前项目复制 `docs.config.mjs`、`src/docs/runtime/*`、`src/docs/index.vue` 和文档接入说明，并向 `package.json` 写入 `docs:init`、`docs:gen`、`docs:check`、`docs:dev` 脚本。
+- `init`：初始化或补齐组件的 `docs.meta.json`、自动文档页、文档入口路由和组件文档路由。
+- `gen`：生成 Markdown 文档、AI catalog、页面数据和质量报告。
+- `check`：执行生成流程，并在质量报告存在 error 时以非 0 状态退出，适合放进 CI。
+
+已有模板文件默认不会覆盖。如需覆盖，使用：
+
+```bash
+pnpm exec component-auto-docs scaffold --force
+```
+
+如果只想复制模板，不想自动修改 `package.json` 脚本，使用：
+
+```bash
+pnpm exec component-auto-docs scaffold --no-scripts
+```
+
+## 配置
+
+CLI 默认读取当前项目根目录的 `docs.config.mjs`。可以通过命令指定其他配置文件：
+
+```bash
+pnpm exec component-auto-docs gen --config ./docs.config.mjs
+```
+
+也可以通过环境变量指定：
+
+```bash
+DOCS_CONFIG=./docs.config.mjs pnpm exec component-auto-docs gen
+```
+
+常用配置项：
+
+- `projectName`：项目名称，会写入 AI 文档标题。
+- `componentRoot`：组件目录，默认 `src/components`。
+- `metaFileName`：组件元数据文件名，默认 `docs.meta.json`。
+- `output`：Markdown、AI 文档、页面数据和质量报告输出位置。
+- `routes`：是否自动写入 `pages.json`，以及文档路由前缀、插入锚点、标题后缀。
+- `runtime`：自动文档页使用的页面壳、hook 和组件导入别名。
+- `quality`：质量检查规则，例如是否要求 App 内文档页存在。
+
+## docs.meta.json
+
+每个组件目录下建议维护一个 `docs.meta.json`：
+
+```json
+{
+  "title": "按钮",
+  "category": "基础组件",
+  "description": "用于触发页面动作、提交表单或打开小程序开放能力的通用按钮。",
+  "useWhen": ["需要用户明确触发一个主要或次要操作时。"],
+  "avoidWhen": ["只展示静态文本，不需要点击反馈时。"],
+  "related": ["app-input", "app-dialog"],
+  "notes": ["新增按钮视觉类型时，应同步维护类型定义。"],
+  "examples": [
+    {
+      "title": "基础按钮",
+      "description": "使用默认主按钮样式触发提交动作。",
+      "code": "<app-button @click=\"onSubmit\">提交</app-button>"
+    }
+  ]
+}
+```
+
+API 信息优先从组件源码自动抽取，`docs.meta.json` 主要负责补充业务语义、使用建议和高质量示例。
+
+## 典型接入流程
+
+1. 在目标项目安装依赖：`pnpm add -D component-auto-docs`。
+2. 执行 `pnpm exec component-auto-docs scaffold`，生成配置和文档页模板。
+3. 按目标项目目录结构调整 `docs.config.mjs`。
+4. 执行 `pnpm exec component-auto-docs init`，初始化组件元数据和文档页。
+5. 人工优化各组件的 `docs.meta.json`。
+6. 执行 `pnpm exec component-auto-docs gen` 生成文档。
+7. 执行 `pnpm exec component-auto-docs check` 校验质量报告。

package/bin/component-auto-docs.mjs

@@ -0,0 +1,130 @@
+#!/usr/bin/env node
+import { spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const projectRoot = process.cwd();
+const command = process.argv[2] || 'help';
+const args = process.argv.slice(3);
+
+function hasFlag(name) {
+  return args.includes(name);
+}
+
+function printHelp() {
+  console.log(`component-auto-docs <command>
+
+Commands:
+  scaffold        Copy docs config/runtime templates into the current project
+  init            Initialize component docs metadata, pages, and routes
+  gen             Generate Markdown, AI catalog, and page data
+  check           Generate docs and fail when quality errors exist
+
+Options:
+  --config <path> Use a custom docs config file
+  --force         Overwrite existing scaffold files
+  --no-scripts    Do not add package.json docs scripts during scaffold
+`);
+}
+
+function runCore(extraArgs = []) {
+  const coreFile = path.join(packageRoot, 'core/generate-component-docs.mjs');
+  const result = spawnSync(process.execPath, [coreFile, ...extraArgs, ...args], {
+    cwd: projectRoot,
+    stdio: 'inherit',
+  });
+
+  process.exit(result.status ?? 1);
+}
+
+function copyTemplateFile(relativePath, options) {
+  const source = path.join(packageRoot, 'templates', relativePath);
+  const target = path.join(projectRoot, relativePath);
+
+  if (!fs.existsSync(source)) return false;
+  if (fs.existsSync(target) && !options.force) {
+    options.skipped.push(relativePath);
+    return false;
+  }
+
+  fs.mkdirSync(path.dirname(target), { recursive: true });
+  fs.copyFileSync(source, target);
+  options.copied.push(relativePath);
+  return true;
+}
+
+function addPackageScripts(options) {
+  const packageFile = path.join(projectRoot, 'package.json');
+  if (!fs.existsSync(packageFile)) {
+    options.skipped.push('package.json scripts (package.json not found)');
+    return;
+  }
+
+  const packageJson = JSON.parse(fs.readFileSync(packageFile, 'utf8'));
+  packageJson.scripts ||= {};
+
+  const scripts = {
+    'docs:init': 'component-auto-docs init',
+    'docs:gen': 'component-auto-docs gen',
+    'docs:check': 'component-auto-docs check',
+    'docs:dev': "pnpm docs:gen && DOCS_OPEN_PATH='/#/docs/index' uni --mode development",
+  };
+
+  let changed = false;
+  for (const [name, value] of Object.entries(scripts)) {
+    if (packageJson.scripts[name] && !options.force) {
+      options.skipped.push(`package.json scripts.${name}`);
+      continue;
+    }
+
+    packageJson.scripts[name] = value;
+    changed = true;
+  }
+
+  if (changed) {
+    fs.writeFileSync(packageFile, `${JSON.stringify(packageJson, null, 2)}\n`);
+    options.copied.push('package.json docs scripts');
+  }
+}
+
+function scaffold() {
+  const options = {
+    force: hasFlag('--force'),
+    copied: [],
+    skipped: [],
+  };
+  const templateFiles = [
+    'docs.config.mjs',
+    'docs/components/README.md',
+    'src/docs/index.vue',
+    'src/docs/runtime/component-doc-page.vue',
+    'src/docs/runtime/use-auto-component-doc.ts',
+  ];
+
+  for (const file of templateFiles) {
+    copyTemplateFile(file, options);
+  }
+
+  if (!hasFlag('--no-scripts')) {
+    addPackageScripts(options);
+  }
+
+  console.log(`Scaffold complete.
+Copied: ${options.copied.join(', ') || 'none'}
+Skipped: ${options.skipped.join(', ') || 'none'}`);
+}
+
+if (command === 'init') {
+  runCore(['--init']);
+} else if (command === 'gen' || command === 'generate') {
+  runCore([]);
+} else if (command === 'check') {
+  runCore(['--check']);
+} else if (command === 'scaffold') {
+  scaffold();
+} else {
+  printHelp();
+  process.exit(command === 'help' || command === '--help' || command === '-h' ? 0 : 1);
+}