component-auto-docs 0.1.2 → 0.2.0

package/README.md

@@ -40,6 +40,7 @@ App 内组件详情页默认使用 Tab 分区：
 - `docs/ai/components.quality.json`：文档质量报告。
 - `src/docs/data.json`：App 内文档首页数据。
 - `src/docs/components/*/data.json`：单组件详情页数据。
+- `src/docs/data.js`、`src/docs/components/*/data.js`：App/小程序运行时使用的数据模块，避免部分小程序编译链把 JSON 字段提升成同名顶层变量。
 - `src/docs/components/*/index.vue`：单组件交互文档页。
 
 ## 快速开始
@@ -117,6 +118,7 @@ DOCS_CONFIG=./docs.config.mjs pnpm exec component-auto-docs gen
 - `componentRoot`：组件目录，默认 `src/components`。
 - `metaFileName`：组件元数据文件名，默认 `docs.meta.json`。
 - `output`：Markdown、AI 文档、页面数据和质量报告输出位置。
+  - `pageDataModuleFileName`：单组件页面运行时数据模块文件名，默认 `data.js`。
 - `routes`：是否自动写入 `pages.json`，以及文档路由前缀、插入锚点、标题后缀。
 - `runtime`：自动文档页使用的页面壳、hook 和组件导入别名。
 - `quality`：质量检查规则，例如是否要求 App 内文档页存在。

package/core/generate-component-docs.mjs

@@ -20,6 +20,7 @@ const defaultDocsConfig = {
     markdownDir: 'docs/components',
     pageDataRoot: 'src/docs/components',
     indexDataFile: 'src/docs/data.json',
+    pageDataModuleFileName: 'data.js',
     catalogFile: 'components.catalog.json',
     aiIndexFile: 'components.index.md',
     llmsFile: 'llms.txt',
@@ -158,6 +159,57 @@ function writeText(filePath, content) {
   fs.writeFileSync(filePath, `${content.trimEnd()}\n`);
 }
 
+function hashText(text) {
+  let hash = 5381;
+
+  for (const char of String(text)) {
+    hash = (hash * 33) ^ char.codePointAt(0);
+  }
+
+  return (hash >>> 0).toString(36);
+}
+
+function toDataModuleIdentifier(name, fallback) {
+  const words = String(name).match(/[A-Za-z0-9]+/g) || [];
+  const base = words
+    .map((word, index) => {
+      const lower = word.toLowerCase();
+      return index === 0 ? lower : lower.charAt(0).toUpperCase() + lower.slice(1);
+    })
+    .join('');
+  const identifierBase = base && /^[A-Za-z_$]/.test(base) ? base : fallback;
+
+  return `${identifierBase}Data_${hashText(name)}`;
+}
+
+function serializeJsValue(value) {
+  return JSON.stringify(value, null, 2)
+    .replace(/\u2028/g, '\\u2028')
+    .replace(/\u2029/g, '\\u2029');
+}
+
+function renderDataModule(data, identifier) {
+  return `// @generated by ${generatedBy}. Keep this file in sync by running docs:gen.
+const ${identifier} = ${serializeJsValue(data)};
+
+export default ${identifier};
+`;
+}
+
+function writeDataModule(filePath, data, identifier) {
+  writeText(filePath, renderDataModule(data, identifier));
+}
+
+function getIndexDataModuleFile() {
+  const parsed = path.parse(indexDataFile);
+
+  return path.join(parsed.dir, `${parsed.name}.js`);
+}
+
+function getPageDataModuleFileName() {
+  return docsConfig.output.pageDataModuleFileName || 'data.js';
+}
+
 function normalizeTypeText(typeText) {
   return typeText
     .replace(/\s+/g, ' ')
@@ -1532,6 +1584,7 @@ function renderAutoDocPage(componentName, componentFile) {
   const importName = componentName
     .replace(/(^|-)(\w)/g, (_, __, char) => char.toUpperCase())
     .replace(/[^\w]/g, '');
+  const dataModuleImport = `./${getPageDataModuleFileName()}`;
   const {
     componentDocPageImport,
     autoDocHookImport,
@@ -1545,7 +1598,7 @@ function renderAutoDocPage(componentName, componentFile) {
 import ${componentDocPageName} from '${componentDocPageImport}';
 import { ${autoDocHookName} } from '${autoDocHookImport}';
 import ${importName} from '${componentImportBase}/${componentName}/${fileName}';
-import doc from './data.json';
+import doc from '${dataModuleImport}';
 
 const {
   propControls,
@@ -1650,10 +1703,11 @@ ${renderGeneratedControlStyles()}
 
 function renderGenericDocPage() {
   const { componentDocPageImport, componentDocPageName } = docsConfig.runtime;
+  const dataModuleImport = `./${getPageDataModuleFileName()}`;
 
   return `<script setup lang="ts">
 import ${componentDocPageName} from '${componentDocPageImport}';
-import doc from './data.json';
+import doc from '${dataModuleImport}';
 </script>
 
 <template>
@@ -2128,13 +2182,24 @@ function main() {
   writeJson(path.join(aiDocsDir, docsConfig.output.catalogFile), catalog);
   writeText(path.join(aiDocsDir, docsConfig.output.aiIndexFile), renderAiIndex(catalog));
   writeText(path.join(aiDocsDir, docsConfig.output.llmsFile), renderLlmsTxt(catalog));
-  writeJson(indexDataFile, buildPageIndex(components));
+  const pageIndex = buildPageIndex(components);
+  writeJson(indexDataFile, pageIndex);
+  writeDataModule(
+    getIndexDataModuleFile(),
+    pageIndex,
+    toDataModuleIdentifier(docsConfig.projectName || 'docs-index', 'docsIndex'),
+  );
   const qualityReport = collectQualityReport(components);
   writeJson(path.join(aiDocsDir, docsConfig.output.qualityFile), qualityReport);
 
   for (const component of components) {
     writeText(path.join(markdownDocsDir, `${component.name}.md`), renderComponentMarkdown(component));
     writeJson(path.join(pageDataRoot, component.name, 'data.json'), component);
+    writeDataModule(
+      path.join(pageDataRoot, component.name, getPageDataModuleFileName()),
+      component,
+      toDataModuleIdentifier(component.name, 'componentDoc'),
+    );
   }
 
   console.log(`Generated component docs for ${components.length} component(s): ${components.map((item) => item.name).join(', ')}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "component-auto-docs",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "description": "Component docs automation CLI for uni-app component libraries.",
   "type": "module",
   "bin": {

package/templates/docs/components/README.md

@@ -12,7 +12,7 @@
 生成产物分为三类：
 
 - 人类阅读：`docs/components/*.md`。
-- App 内页面：`src/docs/data.json`、`src/docs/components/*/data.json`、`src/docs/components/*/index.vue`。
+- App 内页面：`src/docs/data.json`、`src/docs/data.js`、`src/docs/components/*/data.json`、`src/docs/components/*/data.js`、`src/docs/components/*/index.vue`。
 - AI/检索：`docs/ai/components.catalog.json`、`docs/ai/components.index.md`、`docs/ai/llms.txt`、`docs/ai/components.quality.json`。
 
 ## 新组件接入
@@ -80,6 +80,7 @@ pnpm exec component-auto-docs scaffold --force
 - `componentRoot`：组件目录，例如 `src/components`。
 - `metaFileName`：组件元数据文件名，默认 `docs.meta.json`。
 - `output`：AI 文档、Markdown、页面数据和质量报告输出位置。
+- `output.pageDataModuleFileName`：单组件页面运行时数据模块文件名，默认 `data.js`。
 - `routes`：是否自动写入 `pages.json`、文档入口路由、组件文档路由前缀、插入锚点和标题后缀。
 - `runtime`：自动文档页使用的页面壳、hook 和组件导入别名。
 - `quality`：质量检查是否要求 App 内文档页，以及页面壳识别规则。

package/templates/docs.config.mjs

@@ -13,6 +13,7 @@ export default {
     markdownDir: 'docs/components',
     pageDataRoot: 'src/docs/components',
     indexDataFile: 'src/docs/data.json',
+    pageDataModuleFileName: 'data.js',
     catalogFile: 'components.catalog.json',
     aiIndexFile: 'components.index.md',
     llmsFile: 'llms.txt',

package/templates/src/docs/index.vue

@@ -1,6 +1,6 @@
 <script setup lang="ts">
 import { computed, ref } from 'vue';
-import docsIndex from './data.json';
+import docsIndex from './data.js';
 
 type MenuComponent = {
   name: string;