component-auto-docs 0.1.0

package/core/generate-component-docs.mjs

@@ -0,0 +1,1643 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import ts from 'typescript';
+
+const rootDir = process.cwd();
+const argv = process.argv.slice(2);
+const args = new Set(argv);
+const isCheckMode = args.has('--check');
+const isInitMode = args.has('--init');
+const generatedBy = 'component-auto-docs';
+
+const defaultDocsConfig = {
+  projectName: 'uni-vue3-ts-vite',
+  componentRoot: 'src/components',
+  metaFileName: 'docs.meta.json',
+  output: {
+    aiDir: 'docs/ai',
+    markdownDir: 'docs/components',
+    pageDataRoot: 'src/docs/components',
+    indexDataFile: 'src/docs/data.json',
+    catalogFile: 'components.catalog.json',
+    aiIndexFile: 'components.index.md',
+    llmsFile: 'llms.txt',
+    qualityFile: 'components.quality.json',
+  },
+  routes: {
+    enabled: true,
+    pagesJson: 'src/pages.json',
+    indexPath: 'docs/index',
+    indexTitle: '组件文档',
+    basePath: 'docs/components',
+    insertBeforeMarker: '    // -- 示例 demo --',
+    titleSuffix: ' 文档',
+  },
+  runtime: {
+    componentDocPageImport: '@/docs/runtime/component-doc-page.vue',
+    autoDocHookImport: '@/docs/runtime/use-auto-component-doc',
+    componentImportBase: '@/components',
+    componentDocPageName: 'ComponentDocPage',
+    autoDocHookName: 'useAutoComponentDoc',
+  },
+  quality: {
+    requireDocPage: true,
+    shellHints: ['<ComponentDocPage', '<app-page', '<AppPage'],
+  },
+};
+
+function getArgValue(name) {
+  const index = argv.indexOf(name);
+  if (index >= 0) return argv[index + 1];
+
+  const inline = argv.find((item) => item.startsWith(`${name}=`));
+  return inline ? inline.slice(name.length + 1) : '';
+}
+
+function mergeConfig(base, override = {}) {
+  const result = { ...base };
+
+  for (const [key, value] of Object.entries(override || {})) {
+    if (
+      value &&
+      typeof value === 'object' &&
+      !Array.isArray(value) &&
+      base[key] &&
+      typeof base[key] === 'object' &&
+      !Array.isArray(base[key])
+    ) {
+      result[key] = mergeConfig(base[key], value);
+    } else if (value !== undefined) {
+      result[key] = value;
+    }
+  }
+
+  return result;
+}
+
+async function loadDocsConfig() {
+  const configArg = getArgValue('--config') || process.env.DOCS_CONFIG || 'docs.config.mjs';
+  const configPath = path.resolve(rootDir, configArg);
+
+  if (!fs.existsSync(configPath)) return defaultDocsConfig;
+
+  const module = await import(pathToFileURL(configPath).href);
+  return mergeConfig(defaultDocsConfig, module.default || module.docsConfig || module);
+}
+
+const docsConfig = await loadDocsConfig();
+const componentRoot = path.resolve(rootDir, docsConfig.componentRoot);
+const aiDocsDir = path.resolve(rootDir, docsConfig.output.aiDir);
+const markdownDocsDir = path.resolve(rootDir, docsConfig.output.markdownDir);
+const pageDataRoot = path.resolve(rootDir, docsConfig.output.pageDataRoot);
+const indexDataFile = path.resolve(rootDir, docsConfig.output.indexDataFile);
+const pagesJsonFile = path.resolve(rootDir, docsConfig.routes.pagesJson);
+
+function getMetaFile(componentDir) {
+  return path.join(componentDir, docsConfig.metaFileName);
+}
+
+function getDocsRoute(componentName) {
+  return `${docsConfig.routes.basePath}/${componentName}/index`;
+}
+
+function createPageRouteEntry(routePath, title) {
+  return `    {
+      "path": "${routePath}",
+      "style": {
+        "navigationBarTitleText": "${title}"
+      }
+    },
+`;
+}
+
+function insertPageRoute(source, entry) {
+  const marker = docsConfig.routes.insertBeforeMarker;
+  const markerIndex = source.indexOf(marker);
+
+  if (markerIndex >= 0) {
+    return `${source.slice(0, markerIndex)}${entry}${source.slice(markerIndex)}`;
+  }
+
+  const pagesEndIndex = source.indexOf('\n  ],');
+  if (pagesEndIndex < 0) return source;
+
+  return `${source.slice(0, pagesEndIndex)}${entry}${source.slice(pagesEndIndex)}`;
+}
+
+const constructorTypeMap = {
+  String: 'string',
+  Number: 'number',
+  Boolean: 'boolean',
+  Array: 'array',
+  Object: 'object',
+  Function: 'function',
+  Date: 'Date',
+};
+
+function toPosix(filePath) {
+  return filePath.split(path.sep).join('/');
+}
+
+function ensureDir(dir) {
+  fs.mkdirSync(dir, { recursive: true });
+}
+
+function readJson(filePath) {
+  return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+}
+
+function writeJson(filePath, data) {
+  ensureDir(path.dirname(filePath));
+  fs.writeFileSync(filePath, `${JSON.stringify(data, null, 2)}\n`);
+}
+
+function writeText(filePath, content) {
+  ensureDir(path.dirname(filePath));
+  fs.writeFileSync(filePath, `${content.trimEnd()}\n`);
+}
+
+function normalizeTypeText(typeText) {
+  return typeText
+    .replace(/\s+/g, ' ')
+    .replace(/\s*\|\s*/g, ' | ')
+    .replace(/\s*,\s*/g, ' | ')
+    .trim();
+}
+
+function normalizeJsdocType(typeText) {
+  return normalizeTypeText(typeText)
+    .split(' | ')
+    .map((part) => constructorTypeMap[part] || part.toLowerCase?.() || part)
+    .join(' | ');
+}
+
+function toTitleCase(componentName) {
+  return componentName
+    .replace(/^app-/, '')
+    .split('-')
+    .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+    .join(' ');
+}
+
+function inferPropDescription(name, type = '', values = []) {
+  const lowerName = name.toLowerCase();
+  const known = {
+    modelValue: '组件绑定值，通常通过 v-model 双向更新。',
+    value: '组件当前值。',
+    checked: '是否处于选中状态。',
+    disabled: '是否禁用组件交互。',
+    readonly: '是否只读。',
+    placeholder: '输入或选择为空时展示的占位提示。',
+    title: '组件标题文本。',
+    text: '组件展示文本。',
+    label: '组件标签文本或数据项标签字段名。',
+    content: '组件主体内容。',
+    type: '组件视觉类型或展示模式。',
+    size: '组件尺寸规格。',
+    w: '组件宽度，支持数字或带单位字符串。',
+    h: '组件高度，支持数字或带单位字符串。',
+    width: '组件宽度。',
+    height: '组件高度。',
+    radius: '组件圆角大小。',
+    margin: '组件外边距。',
+    padding: '组件内边距。',
+    bg: '组件背景色。',
+    color: '组件颜色。',
+    src: '资源地址。',
+    icon: '图标资源地址。',
+    items: '选项数据列表。',
+    list: '展示数据列表。',
+    range: '选择器数据源。',
+    tabs: '标签页数据列表。',
+    max: '最大数量或最大值。',
+    min: '最小数量或最小值。',
+    maxlength: '允许输入的最大字符数。',
+    maxLength: '允许输入的最大字符数。',
+    focus: '是否自动聚焦。',
+    autoplay: '是否自动播放。',
+    openType: '小程序开放能力类型。',
+  };
+
+  if (known[name]) return known[name];
+  if (values.length) return `可选值为 ${values.join('、')}。`;
+  if (lowerName.startsWith('show')) return `是否展示${name.replace(/^show/i, '') || '对应元素'}。`;
+  if (lowerName.startsWith('is')) return `是否启用${name.replace(/^is/i, '') || '对应状态'}。`;
+  if (type.includes('boolean')) return '布尔开关配置。';
+  if (type.includes('number')) return '数值配置项。';
+  if (type.includes('array') || type.includes('Array')) return '列表数据配置。';
+  if (type.includes('object') || type.includes('Object')) return '对象配置项。';
+
+  return `${name} 配置项。`;
+}
+
+function inferEventDescription(name) {
+  const known = {
+    click: '点击组件时触发。',
+    change: '组件值或状态变化时触发。',
+    input: '输入内容变化时触发。',
+    blur: '组件失焦时触发。',
+    focus: '组件聚焦时触发。',
+    confirm: '确认操作时触发。',
+    cancel: '取消操作时触发。',
+    close: '关闭组件时触发。',
+    clear: '清空内容时触发。',
+    search: '触发搜索动作时触发。',
+    load: '资源加载成功时触发。',
+    error: '资源加载失败时触发。',
+    result: '异步处理完成并返回结果时触发。',
+  };
+
+  if (known[name]) return known[name];
+  if (name.startsWith('update:')) return `更新 ${name.slice('update:'.length)} 绑定值时触发。`;
+
+  return `${name} 事件触发时回调。`;
+}
+
+function getNodeText(node, sourceFile) {
+  return normalizeTypeText(node.getText(sourceFile));
+}
+
+function readLiteralValue(node, sourceFile) {
+  if (!node) return null;
+  if (ts.isStringLiteralLike(node)) return node.text;
+  if (ts.isNumericLiteral(node)) return Number(node.text);
+  if (node.kind === ts.SyntaxKind.TrueKeyword) return true;
+  if (node.kind === ts.SyntaxKind.FalseKeyword) return false;
+  if (node.kind === ts.SyntaxKind.NullKeyword) return null;
+  if (ts.isPropertyAccessExpression(node)) {
+    const text = node.getText(sourceFile);
+    if (text === 'Number.MAX_SAFE_INTEGER') return Number.MAX_SAFE_INTEGER;
+    if (text === 'Number.MIN_SAFE_INTEGER') return Number.MIN_SAFE_INTEGER;
+    if (text === 'Number.POSITIVE_INFINITY') return 'Infinity';
+    if (text === 'Number.NEGATIVE_INFINITY') return '-Infinity';
+  }
+  if (ts.isPrefixUnaryExpression(node) && ts.isNumericLiteral(node.operand)) {
+    const value = Number(node.operand.text);
+    return node.operator === ts.SyntaxKind.MinusToken ? -value : value;
+  }
+
+  return node.getText(sourceFile);
+}
+
+function extractSfcBlock(source, tagName, matcher = () => true) {
+  const blockPattern = new RegExp(`<${tagName}\\b([^>]*)>([\\s\\S]*?)<\\/${tagName}>`, 'gi');
+  const blocks = [...source.matchAll(blockPattern)];
+  const block = blocks.find((item) => matcher(item[1]));
+
+  return block?.[2] || '';
+}
+
+function parseJsdoc(script) {
+  const blocks = [...script.matchAll(/\/\*\*([\s\S]*?)\*\//g)].map((match) => match[1]);
+  const result = {
+    description: '',
+    props: new Map(),
+    events: new Map(),
+    examples: [],
+  };
+
+  for (const block of blocks) {
+    const lines = block
+      .split('\n')
+      .map((line) => line.replace(/^\s*\*\s?/, '').trimEnd())
+      .filter(Boolean);
+    const descriptionLines = [];
+    const tags = [];
+    let currentTag = null;
+
+    for (const line of lines) {
+      if (line.startsWith('@')) {
+        if (currentTag) tags.push(currentTag);
+        const [, tag = '', body = ''] = line.match(/^@(\S+)\s*(.*)$/) || [];
+        currentTag = { tag, body };
+      } else if (currentTag) {
+        currentTag.body = `${currentTag.body}\n${line}`;
+      } else {
+        descriptionLines.push(line);
+      }
+    }
+
+    if (currentTag) tags.push(currentTag);
+    if (!result.description && descriptionLines.length) {
+      result.description = descriptionLines.join('\n').trim();
+    }
+
+    for (const item of tags) {
+      if (item.tag === 'property') {
+        const match = item.body.match(/^\{([^}]+)\}\s+([\w:$-]+)\s*(.*)$/s);
+        if (!match) continue;
+        const [, type, name, description] = match;
+        result.props.set(name, {
+          name,
+          jsdocType: normalizeJsdocType(type),
+          description: description.trim(),
+        });
+      }
+
+      if (item.tag === 'event') {
+        const match = item.body.match(/^\{([^}]+)\}\s+([\w:$-]+)\s*(.*)$/s);
+        if (!match) continue;
+        const [, type, name, description] = match;
+        result.events.set(name, {
+          name,
+          type: normalizeJsdocType(type),
+          description: description.trim(),
+        });
+      }
+
+      if (item.tag === 'example') {
+        const code = item.body.trim();
+        if (code) {
+          result.examples.push({
+            title: '源码示例',
+            description: '来自组件源码 JSDoc。',
+            code,
+          });
+        }
+      }
+    }
+  }
+
+  return result;
+}
+
+function extractStringUnionValues(typeNode) {
+  if (!typeNode) return [];
+
+  if (ts.isParenthesizedTypeNode(typeNode)) {
+    return extractStringUnionValues(typeNode.type);
+  }
+
+  const nodes = ts.isUnionTypeNode(typeNode) ? typeNode.types : [typeNode];
+  const values = [];
+
+  for (const node of nodes) {
+    if (ts.isLiteralTypeNode(node)) {
+      const literal = node.literal;
+      if (ts.isStringLiteralLike(literal) || ts.isNumericLiteral(literal)) {
+        values.push(literal.text);
+      }
+    }
+  }
+
+  return values;
+}
+
+function collectTypeAliases(componentDir) {
+  const aliases = new Map();
+  const typingFiles = fs
+    .readdirSync(componentDir)
+    .filter((fileName) => fileName.endsWith('.ts'))
+    .map((fileName) => path.join(componentDir, fileName));
+
+  for (const filePath of typingFiles) {
+    const source = fs.readFileSync(filePath, 'utf8');
+    const sourceFile = ts.createSourceFile(filePath, source, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS);
+
+    const visit = (node) => {
+      if (ts.isTypeAliasDeclaration(node)) {
+        aliases.set(node.name.text, {
+          name: node.name.text,
+          type: getNodeText(node.type, sourceFile),
+          values: extractStringUnionValues(node.type),
+          source: toPosix(path.relative(rootDir, filePath)),
+        });
+      }
+
+      ts.forEachChild(node, visit);
+    };
+
+    visit(sourceFile);
+  }
+
+  return aliases;
+}
+
+function parseTypeNode(typeNode, sourceFile, aliases) {
+  if (!typeNode) return { type: 'unknown', values: [] };
+
+  if (
+    ts.isTypeReferenceNode(typeNode) &&
+    ts.isIdentifier(typeNode.typeName) &&
+    typeNode.typeName.text === 'PropType' &&
+    typeNode.typeArguments?.length
+  ) {
+    return parseTypeNode(typeNode.typeArguments[0], sourceFile, aliases);
+  }
+
+  const type = getNodeText(typeNode, sourceFile);
+  const alias = aliases.get(type);
+
+  return {
+    type,
+    values: alias?.values?.length ? alias.values : extractStringUnionValues(typeNode),
+    typeSource: alias?.source,
+  };
+}
+
+function parsePropTypeExpression(expression, sourceFile, aliases) {
+  if (!expression) return { type: 'unknown', values: [] };
+
+  if (ts.isAsExpression(expression)) {
+    const fromTypeNode = parseTypeNode(expression.type, sourceFile, aliases);
+    if (fromTypeNode.type !== 'unknown') return fromTypeNode;
+
+    return parsePropTypeExpression(expression.expression, sourceFile, aliases);
+  }
+
+  if (ts.isArrayLiteralExpression(expression)) {
+    const parts = expression.elements.map((item) => parsePropTypeExpression(item, sourceFile, aliases).type);
+    return {
+      type: [...new Set(parts)].join(' | '),
+      values: [],
+    };
+  }
+
+  if (ts.isIdentifier(expression)) {
+    return {
+      type: constructorTypeMap[expression.text] || expression.text,
+      values: [],
+    };
+  }
+
+  return {
+    type: getNodeText(expression, sourceFile),
+    values: [],
+  };
+}
+
+function getPropertyName(nameNode) {
+  if (!nameNode) return '';
+  if (ts.isIdentifier(nameNode) || ts.isStringLiteralLike(nameNode) || ts.isNumericLiteral(nameNode)) {
+    return nameNode.text;
+  }
+
+  return '';
+}
+
+function getObjectProperty(objectNode, propertyName) {
+  if (!ts.isObjectLiteralExpression(objectNode)) return null;
+
+  return objectNode.properties.find((property) => {
+    if (!ts.isPropertyAssignment(property)) return false;
+    return getPropertyName(property.name) === propertyName;
+  });
+}
+
+function extractProps(script, componentFile, aliases, jsdoc) {
+  const sourceFile = ts.createSourceFile(componentFile, script, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS);
+  let definePropsCall = null;
+  let withDefaultsCall = null;
+
+  const visit = (node) => {
+    if (ts.isCallExpression(node) && ts.isIdentifier(node.expression)) {
+      if (node.expression.text === 'defineProps') {
+        definePropsCall = node;
+      }
+
+      if (
+        node.expression.text === 'withDefaults' &&
+        node.arguments.length &&
+        ts.isCallExpression(node.arguments[0]) &&
+        ts.isIdentifier(node.arguments[0].expression) &&
+        node.arguments[0].expression.text === 'defineProps'
+      ) {
+        definePropsCall = node.arguments[0];
+        withDefaultsCall = node;
+      }
+    }
+
+    ts.forEachChild(node, visit);
+  };
+
+  visit(sourceFile);
+
+  if (!definePropsCall) return [];
+
+  const props = [];
+  const propsArg = definePropsCall.arguments[0];
+  const defaultsArg = withDefaultsCall?.arguments?.[1];
+
+  if (propsArg && ts.isObjectLiteralExpression(propsArg)) {
+    for (const property of propsArg.properties) {
+      if (!ts.isPropertyAssignment(property) && !ts.isShorthandPropertyAssignment(property)) continue;
+
+      const name = getPropertyName(property.name);
+      if (!name) continue;
+
+      const initializer = ts.isPropertyAssignment(property) ? property.initializer : null;
+      const doc = jsdoc.props.get(name);
+      let parsedType = { type: doc?.jsdocType || 'unknown', values: [] };
+      let defaultValue = null;
+      let required = false;
+
+      if (initializer && ts.isObjectLiteralExpression(initializer)) {
+        const typeProperty = getObjectProperty(initializer, 'type');
+        const defaultProperty = getObjectProperty(initializer, 'default');
+        const requiredProperty = getObjectProperty(initializer, 'required');
+
+        if (typeProperty) {
+          parsedType = parsePropTypeExpression(typeProperty.initializer, sourceFile, aliases);
+        }
+
+        if (defaultProperty) {
+          defaultValue = readLiteralValue(defaultProperty.initializer, sourceFile);
+        }
+
+        if (requiredProperty) {
+          required = readLiteralValue(requiredProperty.initializer, sourceFile) === true;
+        }
+      } else if (initializer) {
+        parsedType = parsePropTypeExpression(initializer, sourceFile, aliases);
+      }
+
+      if (defaultValue === null && parsedType.type === 'boolean') {
+        defaultValue = false;
+      }
+
+      props.push({
+        name,
+        type: parsedType.type === 'unknown' && doc?.jsdocType ? doc.jsdocType : parsedType.type,
+        default: defaultValue,
+        required,
+        values: parsedType.values || [],
+        description: doc?.description || inferPropDescription(name, parsedType.type, parsedType.values || []),
+        typeSource: parsedType.typeSource,
+      });
+    }
+  } else if (definePropsCall.typeArguments?.length) {
+    const typeArg = definePropsCall.typeArguments[0];
+    if (ts.isTypeLiteralNode(typeArg)) {
+      for (const member of typeArg.members) {
+        if (!ts.isPropertySignature(member)) continue;
+        const name = getPropertyName(member.name);
+        const doc = jsdoc.props.get(name);
+        const parsedType = parseTypeNode(member.type, sourceFile, aliases);
+        const defaultValue =
+          defaultsArg && ts.isObjectLiteralExpression(defaultsArg)
+            ? readLiteralValue(getObjectProperty(defaultsArg, name)?.initializer, sourceFile)
+            : parsedType.type === 'boolean'
+              ? false
+              : null;
+
+        props.push({
+          name,
+          type: parsedType.type,
+          default: defaultValue,
+          required: !member.questionToken,
+          values: parsedType.values || [],
+          description: doc?.description || inferPropDescription(name, parsedType.type, parsedType.values || []),
+          typeSource: parsedType.typeSource,
+        });
+      }
+    }
+  }
+
+  return props;
+}
+
+function extractEvents(script, componentFile, jsdoc) {
+  const sourceFile = ts.createSourceFile(componentFile, script, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS);
+  const eventNames = [];
+
+  const visit = (node) => {
+    if (ts.isCallExpression(node) && ts.isIdentifier(node.expression) && node.expression.text === 'defineEmits') {
+      const firstArg = node.arguments[0];
+
+      if (firstArg && ts.isArrayLiteralExpression(firstArg)) {
+        for (const item of firstArg.elements) {
+          if (ts.isStringLiteralLike(item)) eventNames.push(item.text);
+        }
+      }
+
+      if (node.typeArguments?.length) {
+        const typeArg = node.typeArguments[0];
+        if (ts.isTypeLiteralNode(typeArg)) {
+          for (const member of typeArg.members) {
+            if (!ts.isCallSignatureDeclaration(member) || !member.parameters.length) continue;
+            const firstParam = member.parameters[0];
+            if (!firstParam.type) continue;
+            for (const value of extractStringUnionValues(firstParam.type)) {
+              eventNames.push(value);
+            }
+          }
+        }
+      }
+    }
+
+    ts.forEachChild(node, visit);
+  };
+
+  visit(sourceFile);
+
+  for (const eventName of jsdoc.events.keys()) {
+    eventNames.push(eventName);
+  }
+
+  return [...new Set(eventNames)].map((name) => {
+    const doc = jsdoc.events.get(name);
+
+    return {
+      name,
+      type: doc?.type || 'function',
+      description: doc?.description || inferEventDescription(name),
+    };
+  });
+}
+
+function extractSlots(template) {
+  const matches = [...template.matchAll(/<slot\b([^>]*)>/gi)];
+  const slots = [];
+
+  for (const match of matches) {
+    const attrs = match[1] || '';
+    const nameMatch = attrs.match(/(?:^|\s):?name\s*=\s*["']([^"']+)["']/);
+    const name = nameMatch?.[1] || 'default';
+
+    slots.push({
+      name,
+      description: name === 'default' ? '默认插槽，用于渲染按钮内容。' : '',
+      props: [],
+    });
+  }
+
+  if (!slots.length) return [];
+
+  return [...new Map(slots.map((slot) => [slot.name, slot])).values()];
+}
+
+function normalizeExamples(metaExamples = [], jsdocExamples = []) {
+  const examples = [];
+  const seen = new Set();
+
+  for (const example of [...metaExamples, ...jsdocExamples]) {
+    const normalized = typeof example === 'string' ? { title: '示例', description: '', code: example } : example;
+    const code = normalized.code?.trim();
+    if (!code || seen.has(code)) continue;
+
+    seen.add(code);
+    examples.push({
+      title: normalized.title || '示例',
+      description: normalized.description || '',
+      code,
+    });
+  }
+
+  return examples;
+}
+
+function findAllComponentDirs() {
+  if (!fs.existsSync(componentRoot)) return [];
+
+  return fs
+    .readdirSync(componentRoot, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory())
+    .map((entry) => path.join(componentRoot, entry.name))
+    .filter((componentDir) => Boolean(findComponentFile(componentDir)));
+}
+
+function findComponentDirs() {
+  if (!fs.existsSync(componentRoot)) return [];
+
+  return fs
+    .readdirSync(componentRoot, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory())
+    .map((entry) => path.join(componentRoot, entry.name))
+    .filter((componentDir) => fs.existsSync(getMetaFile(componentDir)));
+}
+
+function findComponentFile(componentDir) {
+  const componentName = path.basename(componentDir);
+  const preferredFile = path.join(componentDir, `${componentName}.vue`);
+
+  if (fs.existsSync(preferredFile)) return preferredFile;
+
+  const vueFile = fs.readdirSync(componentDir).find((fileName) => fileName.endsWith('.vue'));
+  return vueFile ? path.join(componentDir, vueFile) : null;
+}
+
+function inferCategory(componentName) {
+  if (/page|header|footer|safearea|status-bar/.test(componentName)) return '布局组件';
+  if (/input|textarea|picker|radio|checkbox|switch|upload|search/.test(componentName)) return '表单组件';
+  if (/dialog|pop|toast|modal|popup/.test(componentName)) return '反馈组件';
+  if (/tabs|tab|back|totop/.test(componentName)) return '导航组件';
+  if (/item|list|img|tag|dot|title|highlight|marquee|qrcode|radar|progress|steps|timeline|timer|video|swiper|star|tree/.test(componentName)) {
+    return '展示组件';
+  }
+
+  return '基础组件';
+}
+
+function buildUsageHints(componentName, title, props, events, slots) {
+  const hasModel = props.some((prop) => prop.name === 'modelValue');
+  const hasList = props.some((prop) => ['items', 'list', 'range', 'tabs', 'arr'].includes(prop.name));
+  const hasDisabled = props.some((prop) => prop.name === 'disabled');
+  const hasOpen = props.some((prop) => prop.name === 'modelValue' && prop.type.includes('boolean'));
+  const hasClick = events.some((event) => event.name === 'click');
+  const hasSlot = slots.length > 0;
+
+  const useWhen = [
+    `需要在页面中统一使用${title}相关能力时。`,
+    hasModel ? `需要通过 v-model 管理${title}的当前值或显示状态时。` : `需要复用项目内一致的${title}视觉和交互规范时。`,
+    hasList ? `需要基于业务数据列表渲染${title}内容时。` : hasClick ? `需要响应用户点击并触发业务动作时。` : `需要减少页面内重复实现时。`,
+  ];
+
+  const avoidWhen = [
+    `只是一次性、强业务定制且无法复用的页面片段时。`,
+    hasOpen ? `只需要静态展示内容、不需要打开或关闭状态管理时。` : `组件默认结构无法表达当前业务语义时，应优先扩展组件或新增更合适的组件。`,
+    hasDisabled ? `需要禁用状态以外的复杂权限控制时，应在业务层先完成权限判断。` : `需要承载复杂业务流程时，不建议把流程逻辑直接塞进${componentName}。`,
+  ];
+
+  const notes = [
+    `API 契约优先从 ${componentName}.vue 的 defineProps、defineEmits 和 JSDoc 自动生成。`,
+    hasSlot ? `该组件包含插槽，使用时注意插槽内容的尺寸、换行和点击区域。` : `该组件当前未暴露显式插槽，内容主要通过 props 配置。`,
+    hasModel ? `使用 v-model 时，应以 update:modelValue 作为状态同步来源。` : `如需新增对外配置，请同步维护 props 类型和 JSDoc。`,
+  ];
+
+  return { useWhen, avoidWhen, notes };
+}
+
+function buildSamplePropValue(prop) {
+  if (prop.default !== null && prop.default !== undefined && prop.default !== '') return prop.default;
+  if (prop.values?.length) return prop.values[0];
+
+  const type = prop.type || '';
+  const name = prop.name.toLowerCase();
+
+  if (type.includes('boolean')) return false;
+  if (type.includes('number') || type.includes('Number')) {
+    if (name.includes('percent')) return 60;
+    if (name.includes('max')) return 10;
+    if (name.includes('min')) return 0;
+    if (name.includes('size')) return 32;
+    if (name === 'w' || name.includes('width')) return 240;
+    if (name === 'h' || name.includes('height')) return 80;
+    return 1;
+  }
+  if (type.includes('Array') || type.includes('array') || ['items', 'list', 'range', 'tabs', 'arr'].includes(prop.name)) {
+    return [
+      { label: '选项一', value: 'one' },
+      { label: '选项二', value: 'two' },
+    ];
+  }
+  if (type.includes('Object') || type.includes('object')) return {};
+  if (name.includes('placeholder')) return '请输入';
+  if (name.includes('title')) return '标题';
+  if (name.includes('label')) return '标签';
+  if (name.includes('text') || name.includes('content')) return '示例内容';
+  if (name.includes('phone')) return '13800000000';
+  if (name === 'icon') return '/static/icon/avatar.svg';
+  if (name === 'src' || name.includes('poster')) return '';
+
+  return '';
+}
+
+function renderExampleFromProps(componentName, props) {
+  const importantProps = props
+    .filter((prop) => prop.required || ['modelValue', 'title', 'text', 'label', 'items', 'range', 'tabs', 'src', 'icon', 'type', 'size'].includes(prop.name))
+    .slice(0, 5);
+  const attrs = importantProps
+    .map((prop) => {
+      if (prop.name === 'modelValue') return 'v-model="value"';
+      const value = buildSamplePropValue(prop);
+      if (typeof value === 'boolean') return value ? prop.name : `:${prop.name}="false"`;
+      if (typeof value === 'number') return `:${prop.name}="${value}"`;
+      if (Array.isArray(value) || (value && typeof value === 'object')) return `:${prop.name}="${prop.name}"`;
+      if (!value) return '';
+
+      return `${prop.name}="${value}"`;
+    })
+    .filter(Boolean)
+    .join(' ');
+  const attrText = attrs ? ` ${attrs}` : '';
+
+  return `<${componentName}${attrText}>示例内容</${componentName}>`;
+}
+
+function inferComponentInfo(componentDir) {
+  const componentName = path.basename(componentDir);
+  const componentFile = findComponentFile(componentDir);
+  const sfcSource = fs.readFileSync(componentFile, 'utf8');
+  const script = extractSfcBlock(sfcSource, 'script', (attrs) => attrs.includes('setup'));
+  const template = extractSfcBlock(sfcSource, 'template');
+  const jsdoc = parseJsdoc(script);
+  const aliases = collectTypeAliases(componentDir);
+  const props = extractProps(script, componentFile, aliases, jsdoc);
+  const events = extractEvents(script, componentFile, jsdoc);
+  const slots = extractSlots(template);
+
+  return {
+    componentName,
+    componentFile,
+    jsdoc,
+    props,
+    events,
+    slots,
+  };
+}
+
+function inferInitialMeta(componentDir) {
+  const { componentName, jsdoc, props, events, slots } = inferComponentInfo(componentDir);
+  const examples = normalizeExamples([], jsdoc.examples);
+  const title = jsdoc.description?.split('\n')[0]?.trim() || toTitleCase(componentName);
+  const usageHints = buildUsageHints(componentName, title, props, events, slots);
+  const exampleCode = renderExampleFromProps(componentName, props);
+
+  return {
+    title,
+    category: inferCategory(componentName),
+    description: jsdoc.description || `${title}，用于在项目中复用 ${componentName} 的标准视觉、状态和交互能力。`,
+    useWhen: usageHints.useWhen,
+    avoidWhen: usageHints.avoidWhen,
+    related: [],
+    notes: usageHints.notes,
+    examples: examples.length
+      ? examples
+      : [
+          {
+            title: '基础用法',
+            description: `自动根据 ${componentName} 的 props 生成，可按业务语义继续调整。`,
+            code: exampleCode,
+          },
+        ],
+  };
+}
+
+function mergeMeta(existingMeta, inferredMeta) {
+  const merged = { ...existingMeta };
+  const scalarKeys = ['title', 'category', 'description'];
+  const arrayKeys = ['useWhen', 'avoidWhen', 'related', 'notes', 'examples'];
+
+  for (const key of scalarKeys) {
+    if (!merged[key] || merged[key] === `${merged.title} 组件。`) {
+      merged[key] = inferredMeta[key];
+    }
+  }
+
+  for (const key of arrayKeys) {
+    if (!Array.isArray(merged[key]) || merged[key].length === 0) {
+      merged[key] = inferredMeta[key];
+    }
+  }
+
+  return merged;
+}
+
+function isAutoGeneratedDocPage(filePath) {
+  if (!fs.existsSync(filePath)) return true;
+
+  const source = fs.readFileSync(filePath, 'utf8');
+  return source.includes('@generated by docs:init') || source.includes('交互预览待补充');
+}
+
+function renderGeneratedControlStyles() {
+  return `.control-panel,
+.control-list {
+  box-sizing: border-box;
+  display: flex;
+  flex-direction: column;
+  gap: 14rpx;
+  width: 100%;
+  padding: 18rpx;
+  background: #f8fafc;
+  border: 1rpx solid #e2e8f0;
+  border-radius: 10rpx;
+}
+
+.control-item {
+  display: flex;
+  flex-direction: column;
+  gap: 8rpx;
+  width: 100%;
+  padding-bottom: 4rpx;
+}
+
+.control-item.is-inline,
+.control-row {
+  display: flex;
+  flex-direction: row;
+  gap: 10rpx;
+  align-items: center;
+  justify-content: space-between;
+  width: 100%;
+}
+
+.control-label {
+  flex-shrink: 0;
+  font-size: 22rpx;
+  font-weight: 600;
+  line-height: 1.4;
+  color: #475569;
+}
+
+.control-meta {
+  display: flex;
+  flex: 1 1 320rpx;
+  flex-wrap: wrap;
+  gap: 8rpx;
+  justify-content: flex-end;
+  min-width: 0;
+}
+
+.control-type {
+  max-width: 100%;
+  padding: 6rpx 10rpx;
+  font-family: Menlo, Monaco, Consolas, monospace;
+  font-size: 21rpx;
+  line-height: 1.35;
+  color: #475569;
+  overflow-wrap: anywhere;
+  background: #fff;
+  border: 1rpx solid #e2e8f0;
+  border-radius: 8rpx;
+}
+
+.control-input {
+  box-sizing: border-box;
+  display: block;
+  width: 100%;
+  min-height: 64rpx;
+  padding: 0 16rpx;
+  font-size: 26rpx;
+  line-height: 64rpx;
+  color: #111827;
+  background: #fff;
+  border: 1rpx solid #d7e0ee;
+  border-radius: 8rpx;
+}
+
+.control-textarea {
+  box-sizing: border-box;
+  display: block;
+  width: 100%;
+  height: 150rpx;
+  padding: 14rpx;
+  font-size: 23rpx;
+  line-height: 1.45;
+  color: #111827;
+  background: #fff;
+  border: 1rpx solid #d7e0ee;
+  border-radius: 8rpx;
+}
+
+.tag-list {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 8rpx;
+  width: 100%;
+}
+
+.option-tag {
+  box-sizing: border-box;
+  display: inline-flex;
+  align-items: center;
+  max-width: 100%;
+  min-height: 48rpx;
+  padding: 8rpx 12rpx;
+  font-size: 22rpx;
+  line-height: 1.35;
+  color: #374151;
+  overflow-wrap: anywhere;
+  background: #fff;
+  border: 1rpx solid #e2e8f0;
+  border-radius: 8rpx;
+}
+
+.option-tag.active {
+  color: #1d4ed8;
+  background: #eff6ff;
+  border-color: #93c5fd;
+}
+
+.code-card-mini {
+  box-sizing: border-box;
+  width: 100%;
+  padding: 16rpx;
+  background: #111827;
+  border-radius: 10rpx;
+}
+
+.code-text-mini {
+  display: block;
+  width: 100%;
+  font-family: Menlo, Monaco, Consolas, monospace;
+  font-size: 22rpx;
+  line-height: 1.5;
+  color: #e5e7eb;
+  overflow-wrap: anywhere;
+  white-space: pre-wrap;
+}`;
+}
+
+function renderAutoDocPage(componentName, componentFile) {
+  const fileName = path.basename(componentFile);
+  const importName = componentName
+    .replace(/(^|-)(\w)/g, (_, __, char) => char.toUpperCase())
+    .replace(/[^\w]/g, '');
+  const {
+    componentDocPageImport,
+    autoDocHookImport,
+    componentImportBase,
+    componentDocPageName,
+    autoDocHookName,
+  } = docsConfig.runtime;
+
+  return `<!-- @generated by docs:init. You can edit this file to customize the interactive docs page. -->
+<script setup lang="ts">
+import ${componentDocPageName} from '${componentDocPageImport}';
+import { ${autoDocHookName} } from '${autoDocHookImport}';
+import ${importName} from '${componentImportBase}/${componentName}/${fileName}';
+import doc from './data.json';
+
+const {
+  propControls,
+  previewProps,
+  slotText,
+  codeSnippet,
+  isBooleanProp,
+  isNumberProp,
+  isArrayProp,
+  isObjectProp,
+  formatControlDefault,
+  setBooleanProp,
+  setControlValue,
+  setOptionProp,
+} = ${autoDocHookName}(doc);
+</script>
+
+<template>
+  <${componentDocPageName} :doc="doc" :show-controls="doc.props.length > 0">
+    <template #preview>
+      <view class="preview-frame">
+        <${importName} v-bind="previewProps">
+          {{ slotText }}
+        </${importName}>
+      </view>
+    </template>
+
+    <template #controls>
+      <view v-if="doc.props.length" class="control-panel">
+        <view v-for="prop in doc.props" :key="prop.name" class="control-item">
+          <view class="control-row">
+            <text class="control-label">{{ prop.name }}</text>
+            <view class="control-meta">
+              <text class="control-type">{{ prop.type }}</text>
+              <text class="control-type">default: {{ formatControlDefault(prop.default) }}</text>
+            </view>
+          </view>
+
+          <view v-if="isBooleanProp(prop)" class="tag-list">
+            <text class="option-tag" :class="{ active: propControls[prop.name] === true }" @click="setBooleanProp(prop.name, true)">
+              true
+            </text>
+            <text class="option-tag" :class="{ active: propControls[prop.name] === false }" @click="setBooleanProp(prop.name, false)">
+              false
+            </text>
+          </view>
+
+          <view v-else-if="prop.values?.length" class="tag-list">
+            <text
+              v-for="value in prop.values"
+              :key="value"
+              class="option-tag"
+              :class="{ active: propControls[prop.name] === value }"
+              @click="setOptionProp(prop.name, value)"
+            >
+              {{ value }}
+            </text>
+          </view>
+
+          <textarea
+            v-else-if="isArrayProp(prop) || isObjectProp(prop)"
+            :value="propControls[prop.name]"
+            class="control-textarea"
+            :placeholder="prop.description || prop.name"
+            @input="setControlValue(prop.name, $event.detail.value)"
+          />
+
+          <input
+            v-else
+            :value="propControls[prop.name]"
+            class="control-input"
+            :type="isNumberProp(prop) ? 'number' : 'text'"
+            :placeholder="prop.description || prop.name"
+            @input="setControlValue(prop.name, $event.detail.value)"
+          />
+        </view>
+      </view>
+    </template>
+
+    <template #code>
+      <view class="code-card-mini">
+        <text class="code-text-mini">{{ codeSnippet }}</text>
+      </view>
+    </template>
+  </${componentDocPageName}>
+</template>
+
+<style lang="scss">
+${renderGeneratedControlStyles()}
+</style>
+`;
+}
+
+function renderGenericDocPage() {
+  const { componentDocPageImport, componentDocPageName } = docsConfig.runtime;
+
+  return `<script setup lang="ts">
+import ${componentDocPageName} from '${componentDocPageImport}';
+import doc from './data.json';
+</script>
+
+<template>
+  <${componentDocPageName} :doc="doc">
+    <template #preview>
+      <view class="preview-frame">
+        <text class="empty-preview">该组件已生成基础文档页，交互预览待补充。</text>
+      </view>
+    </template>
+  </${componentDocPageName}>
+</template>
+
+<style lang="scss">
+.empty-preview {
+  display: block;
+  font-size: 24rpx;
+  line-height: 1.6;
+  color: #64748b;
+  overflow-wrap: anywhere;
+}
+</style>
+`;
+}
+
+function ensureAutoDocPage(componentName, componentFile) {
+  const pageFile = path.join(pageDataRoot, componentName, 'index.vue');
+  if (!isAutoGeneratedDocPage(pageFile)) return false;
+
+  writeText(pageFile, renderAutoDocPage(componentName, componentFile));
+  return true;
+}
+
+function ensureDocsRoutes(componentNames) {
+  if (!docsConfig.routes.enabled) return [];
+  const pagesFile = pagesJsonFile;
+  if (!fs.existsSync(pagesFile)) return [];
+
+  let source = fs.readFileSync(pagesFile, 'utf8');
+  const added = [];
+  const indexPath = docsConfig.routes.indexPath;
+
+  if (indexPath && !source.includes(`"path": "${indexPath}"`)) {
+    source = insertPageRoute(source, createPageRouteEntry(indexPath, docsConfig.routes.indexTitle));
+    added.push(indexPath);
+  }
+
+  for (const componentName of componentNames) {
+    const routePath = getDocsRoute(componentName);
+    if (source.includes(`"path": "${routePath}"`)) continue;
+
+    source = insertPageRoute(source, createPageRouteEntry(routePath, `${componentName}${docsConfig.routes.titleSuffix}`));
+
+    added.push(componentName);
+  }
+
+  if (added.length) {
+    fs.writeFileSync(pagesFile, source);
+  }
+
+  return added;
+}
+
+function hasDocPageShell(pageSource) {
+  return docsConfig.quality.shellHints.some((hint) => pageSource.includes(hint));
+}
+
+function initComponentMetas() {
+  const componentDirs = findAllComponentDirs();
+  const created = [];
+  const enriched = [];
+  const untouched = [];
+  const createdPages = [];
+  const preservedPages = [];
+
+  for (const componentDir of componentDirs) {
+    const metaFile = getMetaFile(componentDir);
+    const componentName = path.basename(componentDir);
+    const inferredMeta = inferInitialMeta(componentDir);
+
+    if (fs.existsSync(metaFile)) {
+      const existingMeta = readJson(metaFile);
+      const mergedMeta = mergeMeta(existingMeta, inferredMeta);
+
+      if (JSON.stringify(existingMeta) !== JSON.stringify(mergedMeta)) {
+        writeJson(metaFile, mergedMeta);
+        enriched.push(componentName);
+      } else {
+        untouched.push(componentName);
+      }
+
+      continue;
+    }
+
+    writeJson(metaFile, inferredMeta);
+    created.push(componentName);
+  }
+
+  for (const componentDir of componentDirs) {
+    const componentName = path.basename(componentDir);
+    const componentFile = findComponentFile(componentDir);
+
+    if (ensureAutoDocPage(componentName, componentFile)) {
+      createdPages.push(componentName);
+    } else {
+      preservedPages.push(componentName);
+    }
+  }
+
+  const addedRoutes = ensureDocsRoutes(componentDirs.map((componentDir) => path.basename(componentDir)));
+
+  console.log(`Initialized ${docsConfig.metaFileName} for ${created.length} component(s): ${created.join(', ') || 'none'}`);
+  console.log(`Enriched ${docsConfig.metaFileName} for ${enriched.length} component(s): ${enriched.join(', ') || 'none'}`);
+  console.log(`Preserved ${docsConfig.metaFileName} for ${untouched.length} component(s): ${untouched.join(', ') || 'none'}`);
+  console.log(`Created or refreshed auto docs page for ${createdPages.length} component(s): ${createdPages.join(', ') || 'none'}`);
+  console.log(`Preserved custom docs page for ${preservedPages.length} component(s): ${preservedPages.join(', ') || 'none'}`);
+  console.log(`Registered docs route for ${addedRoutes.length} component(s): ${addedRoutes.join(', ') || 'none'}`);
+}
+
+function collectComponentDoc(componentDir) {
+  const componentFile = findComponentFile(componentDir);
+  if (!componentFile) return null;
+
+  const componentName = path.basename(componentDir);
+  const sfcSource = fs.readFileSync(componentFile, 'utf8');
+  const script = extractSfcBlock(sfcSource, 'script', (attrs) => attrs.includes('setup'));
+  const template = extractSfcBlock(sfcSource, 'template');
+  const meta = readJson(getMetaFile(componentDir));
+  const jsdoc = parseJsdoc(script);
+  const aliases = collectTypeAliases(componentDir);
+  const props = extractProps(script, componentFile, aliases, jsdoc);
+  const events = extractEvents(script, componentFile, jsdoc);
+  const slots = extractSlots(template);
+
+  const component = {
+    name: componentName,
+    title: meta.title || jsdoc.description || componentName,
+    category: meta.category || '未分类',
+    description: meta.description || jsdoc.description || '',
+    source: toPosix(path.relative(rootDir, componentFile)),
+    meta: toPosix(path.relative(rootDir, getMetaFile(componentDir))),
+    props,
+    events,
+    slots,
+    examples: normalizeExamples(meta.examples, jsdoc.examples),
+    useWhen: meta.useWhen || [],
+    avoidWhen: meta.avoidWhen || [],
+    notes: meta.notes || [],
+    related: meta.related || [],
+  };
+
+  Object.defineProperties(component, {
+    __jsdocProps: { value: [...jsdoc.props.keys()] },
+    __jsdocEvents: { value: [...jsdoc.events.keys()] },
+  });
+
+  return component;
+}
+
+function renderList(items, emptyText = '暂无') {
+  if (!items?.length) return `- ${emptyText}`;
+
+  return items.map((item) => `- ${item}`).join('\n');
+}
+
+function renderDefault(value) {
+  if (value === null || value === undefined) return '未设置';
+  if (typeof value === 'string') return value ? `"${value}"` : '空字符串';
+
+  return String(value);
+}
+
+function renderProps(props) {
+  if (!props.length) return '暂无 Props。';
+
+  return props
+    .map((prop) => {
+      const lines = [
+        `### ${prop.name}`,
+        `- 类型：\`${prop.type}\``,
+        `- 默认值：\`${renderDefault(prop.default)}\``,
+        `- 必填：${prop.required ? '是' : '否'}`,
+      ];
+
+      if (prop.values?.length) lines.push(`- 可选值：${prop.values.map((value) => `\`${value}\``).join('、')}`);
+      if (prop.description) lines.push(`- 说明：${prop.description}`);
+      if (prop.typeSource) lines.push(`- 类型来源：\`${prop.typeSource}\``);
+
+      return lines.join('\n');
+    })
+    .join('\n\n');
+}
+
+function renderEvents(events) {
+  if (!events.length) return '暂无 Events。';
+
+  return events
+    .map((event) => {
+      const lines = [`### ${event.name}`, `- 类型：\`${event.type}\``];
+      if (event.description) lines.push(`- 说明：${event.description}`);
+
+      return lines.join('\n');
+    })
+    .join('\n\n');
+}
+
+function renderSlots(slots) {
+  if (!slots.length) return '暂无 Slots。';
+
+  return slots
+    .map((slot) => {
+      const lines = [`### ${slot.name}`];
+      if (slot.description) lines.push(`- 说明：${slot.description}`);
+      if (slot.props?.length) lines.push(`- Slot Props：${slot.props.map((item) => `\`${item}\``).join('、')}`);
+
+      return lines.join('\n');
+    })
+    .join('\n\n');
+}
+
+function renderExamples(examples) {
+  if (!examples.length) return '暂无示例。';
+
+  return examples
+    .map((example) => {
+      const description = example.description ? `\n${example.description}\n` : '';
+
+      return `### ${example.title}${description}\n\`\`\`vue\n${example.code}\n\`\`\``;
+    })
+    .join('\n\n');
+}
+
+function renderComponentMarkdown(component) {
+  return `# ${component.name} - ${component.title}
+
+${component.description}
+
+- 分类：${component.category}
+- 源码：\`${component.source}\`
+- 元数据：\`${component.meta}\`
+
+## 何时使用
+
+${renderList(component.useWhen)}
+
+## 不建议使用
+
+${renderList(component.avoidWhen)}
+
+## Props
+
+${renderProps(component.props)}
+
+## Events
+
+${renderEvents(component.events)}
+
+## Slots
+
+${renderSlots(component.slots)}
+
+## 注意事项
+
+${renderList(component.notes)}
+
+## 示例
+
+${renderExamples(component.examples)}
+
+## 相关组件
+
+${renderList(component.related)}
+`;
+}
+
+function renderAiIndex(catalog) {
+  const componentSections = catalog.components
+    .map((component) => {
+      return `## ${component.name}
+
+- 标题：${component.title}
+- 分类：${component.category}
+- 描述：${component.description}
+- 源码：\`${component.source}\`
+
+### Props
+
+${renderProps(component.props)}
+
+### Events
+
+${renderEvents(component.events)}
+
+### Slots
+
+${renderSlots(component.slots)}
+
+### 何时使用
+
+${renderList(component.useWhen)}
+
+### 不建议使用
+
+${renderList(component.avoidWhen)}
+
+### 注意事项
+
+${renderList(component.notes)}
+
+### 示例
+
+${renderExamples(component.examples)}
+`;
+    })
+    .join('\n');
+
+  return `# Components AI Index
+
+本文件由 \`${generatedBy}\` 生成，供 AI 和检索系统读取。结构化 JSON 以 \`${toPosix(path.relative(rootDir, path.join(aiDocsDir, docsConfig.output.catalogFile)))}\` 为准。
+
+${componentSections}
+`;
+}
+
+function renderLlmsTxt(catalog) {
+  const catalogPath = toPosix(path.relative(rootDir, path.join(aiDocsDir, docsConfig.output.catalogFile)));
+  const aiIndexPath = toPosix(path.relative(rootDir, path.join(aiDocsDir, docsConfig.output.aiIndexFile)));
+  const markdownPath = `${toPosix(path.relative(rootDir, markdownDocsDir))}/*.md`;
+  const pagePath = `${toPosix(path.relative(rootDir, pageDataRoot))}/*/index.vue`;
+  const lines = [
+    `# ${docsConfig.projectName} component docs`,
+    '',
+    `Use ${catalogPath} as the canonical structured component API catalog.`,
+    `Use ${aiIndexPath} for a readable Markdown summary of the same catalog.`,
+    `Human-facing component pages live in ${markdownPath} and ${pagePath}.`,
+    '',
+  ];
+
+  for (const component of catalog.components) {
+    lines.push(`## ${component.name}`);
+    lines.push(`Title: ${component.title}`);
+    lines.push(`Category: ${component.category}`);
+    lines.push(`Description: ${component.description}`);
+    lines.push(`Source: ${component.source}`);
+    lines.push(`Props: ${component.props.map((prop) => `${prop.name}:${prop.type}`).join(', ') || 'none'}`);
+    lines.push(`Events: ${component.events.map((event) => event.name).join(', ') || 'none'}`);
+    lines.push(`Slots: ${component.slots.map((slot) => slot.name).join(', ') || 'none'}`);
+    lines.push(`UseWhen: ${component.useWhen.join(' | ') || 'none'}`);
+    lines.push(`AvoidWhen: ${component.avoidWhen.join(' | ') || 'none'}`);
+    lines.push('');
+  }
+
+  return lines.join('\n');
+}
+
+function buildPageIndex(components) {
+  return {
+    generatedBy,
+    components: components.map((component) => ({
+      name: component.name,
+      title: component.title,
+      category: component.category,
+      description: component.description,
+      route: `/${getDocsRoute(component.name)}`,
+      source: component.source,
+      propsCount: component.props.length,
+      eventsCount: component.events.length,
+      slotsCount: component.slots.length,
+    })),
+  };
+}
+
+function collectQualityReport(components) {
+  const allComponentNames = new Set(
+    fs
+      .readdirSync(componentRoot, { withFileTypes: true })
+      .filter((entry) => entry.isDirectory())
+      .map((entry) => entry.name),
+  );
+  const documentedNames = new Set(components.map((component) => component.name));
+  const warnings = [];
+  const errors = [];
+
+  const addWarning = (component, message) => warnings.push({ component, message });
+  const addError = (component, message) => errors.push({ component, message });
+
+  for (const component of components) {
+    if (!component.title) addError(component.name, 'missing title');
+    if (!component.category) addError(component.name, 'missing category');
+    if (!component.description) addError(component.name, 'missing description');
+    if (!component.examples.length) addWarning(component.name, 'missing examples');
+    if (!fs.existsSync(path.join(rootDir, component.source))) {
+      addError(component.name, `source not found: ${component.source}`);
+    }
+
+    const pageFile = path.join(pageDataRoot, component.name, 'index.vue');
+    if (docsConfig.quality.requireDocPage && !fs.existsSync(pageFile)) {
+      addWarning(component.name, `docs page not found: ${toPosix(path.relative(rootDir, pageFile))}`);
+    } else if (fs.existsSync(pageFile)) {
+      const pageSource = fs.readFileSync(pageFile, 'utf8');
+      if (!hasDocPageShell(pageSource)) {
+        addWarning(
+          component.name,
+          `docs page should include one of configured shell hints: ${docsConfig.quality.shellHints.join(', ')}`,
+        );
+      }
+    }
+
+    const propNames = new Set(component.props.map((prop) => prop.name));
+    const eventNames = new Set(component.events.map((event) => event.name));
+
+    for (const prop of component.props) {
+      if (!prop.type || prop.type === 'unknown') addWarning(component.name, `prop "${prop.name}" has unknown type`);
+      if (!prop.description) addWarning(component.name, `prop "${prop.name}" missing description`);
+    }
+
+    for (const event of component.events) {
+      if (!event.description) addWarning(component.name, `event "${event.name}" missing description`);
+    }
+
+    for (const jsdocProp of component.__jsdocProps || []) {
+      if (!propNames.has(jsdocProp)) {
+        addWarning(component.name, `JSDoc @property "${jsdocProp}" does not match defineProps`);
+      }
+    }
+
+    for (const jsdocEvent of component.__jsdocEvents || []) {
+      if (!eventNames.has(jsdocEvent)) {
+        addWarning(component.name, `JSDoc @event "${jsdocEvent}" does not match defineEmits`);
+      }
+    }
+
+    for (const related of component.related) {
+      if (!allComponentNames.has(related)) {
+        addWarning(component.name, `related component "${related}" does not exist in ${docsConfig.componentRoot}`);
+      } else if (!documentedNames.has(related)) {
+        addWarning(component.name, `related component "${related}" is not documented yet`);
+      }
+    }
+  }
+
+  return {
+    generatedBy,
+    componentsCount: components.length,
+    errors,
+    warnings,
+    ok: errors.length === 0,
+  };
+}
+
+function main() {
+  if (isInitMode) {
+    initComponentMetas();
+    return;
+  }
+
+  const components = findComponentDirs().map(collectComponentDoc).filter(Boolean);
+
+  if (!components.length) {
+    console.warn(
+      `No component docs found. Add ${docsConfig.metaFileName} under ${docsConfig.componentRoot}/<component-name>.`,
+    );
+    return;
+  }
+
+  const catalog = {
+    schemaVersion: '1.0.0',
+    generatedBy,
+    components,
+  };
+
+  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 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);
+  }
+
+  console.log(`Generated component docs for ${components.length} component(s): ${components.map((item) => item.name).join(', ')}`);
+  console.log(
+    `Docs quality: ${qualityReport.errors.length} error(s), ${qualityReport.warnings.length} warning(s). See ${toPosix(path.relative(rootDir, path.join(aiDocsDir, docsConfig.output.qualityFile)))}`,
+  );
+
+  if (isCheckMode && qualityReport.errors.length) {
+    process.exitCode = 1;
+  }
+}
+
+main();