@brms/ai-skills 0.1.0

package/skills/brms-prototype-generator/scripts/analyze-doc.mjs

@@ -0,0 +1,554 @@
+#!/usr/bin/env node
+import fs from 'node:fs'
+import path from 'node:path'
+
+const PAGE_HEADING_RE = /^##\s+(?:(\d+)[.、]\s*)?(.+?)\s*$/
+const SUB_HEADING_RE = /^###\s+(.+?)\s*$/
+const LINK_RE = /\[[^\]]*]\(([^)]+\.md(?:#[^)]+)?)\)/gi
+const BARE_MD_RE = /(?:^|[\s>：:（(])([A-Za-z0-9_.\-\/\\]+\.md)(?=$|[\s）)。,，.;；])/gi
+
+function parseArgs(argv) {
+  const args = {
+    entry: '',
+    repoRoot: process.cwd(),
+    format: 'markdown',
+  }
+
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i]
+    if (arg === '--repo-root') {
+      args.repoRoot = argv[i + 1] || ''
+      i += 1
+    }
+    else if (arg === '--format') {
+      args.format = argv[i + 1] || ''
+      i += 1
+    }
+    else if (arg === '--help' || arg === '-h') {
+      args.help = true
+    }
+    else if (!args.entry) {
+      args.entry = arg
+    }
+    else {
+      throw new Error(`Unknown argument: ${arg}`)
+    }
+  }
+
+  if (!['json', 'markdown', 'both'].includes(args.format))
+    throw new Error('--format must be one of: json, markdown, both')
+
+  return args
+}
+
+function normalizePath(filePath) {
+  return filePath.replaceAll('\\', '/')
+}
+
+function toRepoRelative(filePath, repoRoot) {
+  return normalizePath(path.relative(repoRoot, filePath))
+}
+
+function stripAnchor(link) {
+  return link.replace(/#.*$/, '')
+}
+
+function resolveMdReference(reference, fromFile, repoRoot) {
+  const cleanReference = decodeURI(stripAnchor(reference.trim())).replace(/^file:\/\//, '')
+  if (/^[a-z]+:/i.test(cleanReference))
+    return null
+
+  const candidate = path.isAbsolute(cleanReference)
+    ? cleanReference
+    : path.resolve(path.dirname(fromFile), cleanReference)
+
+  if (!candidate.startsWith(repoRoot))
+    return null
+
+  if (fs.existsSync(candidate) && fs.statSync(candidate).isFile())
+    return candidate
+
+  const repoCandidate = path.resolve(repoRoot, cleanReference)
+  if (repoCandidate.startsWith(repoRoot) && fs.existsSync(repoCandidate) && fs.statSync(repoCandidate).isFile())
+    return repoCandidate
+
+  return candidate
+}
+
+function findMarkdownReferences(text) {
+  const references = new Set()
+  let match
+
+  while ((match = LINK_RE.exec(text)))
+    references.add(match[1])
+
+  while ((match = BARE_MD_RE.exec(text)))
+    references.add(match[1])
+
+  return [...references]
+}
+
+function collectDocuments(entryFile, repoRoot) {
+  const queue = [entryFile]
+  const seen = new Set()
+  const documents = []
+  const missingReferences = []
+
+  while (queue.length) {
+    const file = path.resolve(queue.shift())
+    if (seen.has(file))
+      continue
+
+    seen.add(file)
+    if (!fs.existsSync(file)) {
+      missingReferences.push(toRepoRelative(file, repoRoot))
+      continue
+    }
+
+    const text = fs.readFileSync(file, 'utf8')
+    documents.push({ file, text })
+
+    for (const ref of findMarkdownReferences(text)) {
+      const resolved = resolveMdReference(ref, file, repoRoot)
+      if (!resolved)
+        continue
+
+      if (!seen.has(resolved))
+        queue.push(resolved)
+    }
+  }
+
+  return { documents, missingReferences: [...new Set(missingReferences)] }
+}
+
+function parseMarkdownTable(lines, startIndex) {
+  if (!lines[startIndex]?.trim().startsWith('|'))
+    return null
+
+  const headerLine = lines[startIndex]
+  const separatorLine = lines[startIndex + 1] || ''
+  if (!separatorLine.trim().startsWith('|') || !separatorLine.includes('-'))
+    return null
+
+  const headers = splitTableRow(headerLine)
+  const rows = []
+  let endIndex = startIndex + 2
+
+  while (endIndex < lines.length && lines[endIndex].trim().startsWith('|')) {
+    const values = splitTableRow(lines[endIndex])
+    const row = {}
+    headers.forEach((header, index) => {
+      row[header] = values[index] || ''
+    })
+    rows.push(row)
+    endIndex += 1
+  }
+
+  return {
+    startLine: startIndex + 1,
+    endLine: endIndex,
+    headers,
+    rows,
+  }
+}
+
+function splitTableRow(line) {
+  return line
+    .trim()
+    .replace(/^\|/, '')
+    .replace(/\|$/, '')
+    .split('|')
+    .map(cell => cell.trim())
+}
+
+function isFieldTable(table, activeSubHeading) {
+  const headers = table.headers.join('|').toLowerCase()
+  return /字段|field|类型|type/.test(headers) && (/字段|field/.test(headers) || /字段清单|表结构|table/i.test(activeSubHeading))
+}
+
+function isFunctionTable(table, activeSubHeading) {
+  const headers = table.headers.join('|').toLowerCase()
+  return /功能|operation|button|action|处理逻辑/.test(headers) || /功能清单|按钮|操作/.test(activeSubHeading)
+}
+
+function hasFieldKey(headers) {
+  const normalized = headers.map(header => header.trim().toLowerCase())
+  return normalized.some(header =>
+    ['fieldname', 'field_name', 'field', '字段名', '字段编码', '字段key', '字段 key', '字段代码'].includes(header),
+  )
+}
+
+function hasDisplayName(headers) {
+  const normalized = headers.map(header => header.trim().toLowerCase())
+  return normalized.some(header =>
+    ['displayname', 'display_name', 'label', 'title', '显示名', '展示名', '字段', '字段名称', '名称'].includes(header),
+  )
+}
+
+function hasType(headers) {
+  const normalized = headers.map(header => header.trim().toLowerCase())
+  return normalized.some(header =>
+    ['type', 'fieldtype', 'field_type', '类型', '字段类型'].includes(header),
+  )
+}
+
+function summarizeFieldTable(table, lineOffset = 0) {
+  return {
+    startLine: table.startLine + lineOffset,
+    rows: table.rows.length,
+    headers: table.headers,
+    hasFieldKey: hasFieldKey(table.headers),
+    hasDisplayName: hasDisplayName(table.headers),
+    hasType: hasType(table.headers),
+  }
+}
+
+function extractPurpose(lines) {
+  for (const line of lines) {
+    const trimmed = line.trim()
+    if (!trimmed || trimmed.startsWith('|') || trimmed.startsWith('#') || trimmed === '---')
+      continue
+    return trimmed.replace(/^>\s*/, '')
+  }
+
+  return ''
+}
+
+function analyzePage(section, repoRoot) {
+  const lines = section.content
+  const fieldTables = []
+  const functionTables = []
+  let activeSubHeading = ''
+
+  for (let i = 0; i < lines.length; i += 1) {
+    const subHeading = lines[i].match(SUB_HEADING_RE)
+    if (subHeading)
+      activeSubHeading = subHeading[1]
+
+    const table = parseMarkdownTable(lines, i)
+    if (!table)
+      continue
+
+    if (isFieldTable(table, activeSubHeading))
+      fieldTables.push(summarizeFieldTable(table, section.line))
+    if (isFunctionTable(table, activeSubHeading))
+      functionTables.push({ startLine: table.startLine + section.line, rows: table.rows.length, headers: table.headers })
+
+    i = table.endLine - 1
+  }
+
+  const purpose = extractPurpose(lines)
+  const hasRenderableFields = fieldTables.some(table => table.rows > 0 && table.hasDisplayName && table.hasType)
+  const hasCompleteFieldDesign = fieldTables.some(table => table.rows > 0 && table.hasFieldKey && table.hasDisplayName && table.hasType)
+  const hasFunctions = functionTables.some(table => table.rows > 0)
+  const complete = Boolean(section.title && (purpose || hasFunctions) && hasRenderableFields)
+  const issues = []
+
+  if (!purpose && !hasFunctions)
+    issues.push('missing purpose or function list')
+  if (!fieldTables.length)
+    issues.push('missing field table')
+  if (fieldTables.length && !hasCompleteFieldDesign)
+    issues.push('field design missing field keys')
+  if (!complete)
+    issues.push('page incomplete')
+
+  return {
+    source: toRepoRelative(section.file, repoRoot),
+    line: section.line,
+    index: section.index,
+    title: section.title,
+    purpose,
+    fieldTables,
+    functionTables,
+    complete,
+    hasCompleteFieldDesign,
+    issues,
+  }
+}
+
+function extractSections(document) {
+  const lines = document.text.split(/\r?\n/)
+  const sections = []
+
+  for (let i = 0; i < lines.length; i += 1) {
+    const match = lines[i].match(PAGE_HEADING_RE)
+    if (!match)
+      continue
+
+    const title = match[2].trim()
+    if (/附录|页面间导航关系|导航关系/.test(title))
+      continue
+
+    let end = i + 1
+    while (end < lines.length && !PAGE_HEADING_RE.test(lines[end]))
+      end += 1
+
+    sections.push({
+      file: document.file,
+      line: i + 1,
+      index: match[1] ? Number(match[1]) : null,
+      title,
+      content: lines.slice(i + 1, end),
+    })
+  }
+
+  return sections
+}
+
+function extractNavigationBlocks(document, repoRoot) {
+  const lines = document.text.split(/\r?\n/)
+  const blocks = []
+  let inNavigation = false
+
+  for (let i = 0; i < lines.length; i += 1) {
+    if (/^##\s+.*(?:页面间导航关系|导航关系)/.test(lines[i])) {
+      inNavigation = true
+      continue
+    }
+
+    if (inNavigation && /^##\s+/.test(lines[i]))
+      inNavigation = false
+
+    if (!inNavigation)
+      continue
+
+    if (lines[i].trim().startsWith('```')) {
+      const start = i + 1
+      let end = start
+      while (end < lines.length && !lines[end].trim().startsWith('```'))
+        end += 1
+
+      blocks.push({
+        source: toRepoRelative(document.file, repoRoot),
+        line: start + 1,
+        text: lines.slice(start, end).join('\n').trim(),
+        tree: parseNavigationTree(lines.slice(start, end)),
+      })
+      i = end
+    }
+  }
+
+  return blocks
+}
+
+function parseNavigationTree(lines) {
+  const root = []
+  const stack = []
+
+  for (const rawLine of lines) {
+    const line = rawLine.replace(/\s+$/, '')
+    if (!line.trim())
+      continue
+
+    const branchIndex = line.search(/[├└]/)
+    const pipeCount = branchIndex >= 0 ? (line.slice(0, branchIndex).match(/│/g) || []).length : 0
+    let level = 0
+    if (branchIndex >= 0)
+      level = Math.max(pipeCount + 1, Math.max(1, Math.floor(branchIndex / 6) + 1))
+
+    const label = line
+      .replace(/^[\s│├└─]+/, '')
+      .trim()
+    if (!label)
+      continue
+
+    const noteMatch = label.match(/^(.*?)[（(]([^（）()]*)[）)]$/)
+    const title = (noteMatch ? noteMatch[1] : label).trim()
+    const note = noteMatch ? noteMatch[2].trim() : ''
+    const node = {
+      title,
+      note,
+      level,
+      children: [],
+    }
+
+    while (stack.length && stack[stack.length - 1].level >= level)
+      stack.pop()
+
+    if (stack.length)
+      stack[stack.length - 1].node.children.push(node)
+    else
+      root.push(node)
+
+    stack.push({ level, node })
+  }
+
+  return root
+}
+
+function countNavigationNodes(nodes) {
+  return nodes.reduce((count, node) => count + 1 + countNavigationNodes(node.children || []), 0)
+}
+
+function formatNavigationTree(nodes, indent = 0) {
+  const lines = []
+  for (const node of nodes) {
+    const prefix = '  '.repeat(indent)
+    const note = node.note ? ` (${node.note})` : ''
+    lines.push(`${prefix}- ${node.title}${note}`)
+    lines.push(...formatNavigationTree(node.children || [], indent + 1))
+  }
+  return lines
+}
+
+function analyze(entry, repoRoot) {
+  const entryFile = path.resolve(repoRoot, entry)
+  if (!fs.existsSync(entryFile))
+    throw new Error(`Entry Markdown not found: ${entry}`)
+
+  const { documents, missingReferences } = collectDocuments(entryFile, repoRoot)
+  const pages = documents.flatMap(document => extractSections(document).map(section => analyzePage(section, repoRoot)))
+  const navigationBlocks = documents.flatMap(document => extractNavigationBlocks(document, repoRoot))
+  const incompletePages = pages.filter(page => !page.complete)
+  const pagesMissingFieldKeys = pages.filter(page => page.fieldTables.length && !page.hasCompleteFieldDesign)
+  const completePages = pages.filter(page => page.complete).length
+  const generationModes = getGenerationModes(completePages)
+  const navigationTreeNodes = navigationBlocks.reduce((count, block) => count + countNavigationNodes(block.tree || []), 0)
+
+  return {
+    entry: toRepoRelative(entryFile, repoRoot),
+    documents: documents.map(document => toRepoRelative(document.file, repoRoot)),
+    missingReferences,
+    summary: {
+      pageCount: pages.length,
+      completePages,
+      incompletePages: incompletePages.length,
+      pagesMissingFieldKeys: pagesMissingFieldKeys.length,
+      navigationBlocks: navigationBlocks.length,
+      navigationTreeNodes,
+      menuStructureDetected: navigationTreeNodes > 0,
+      shouldStop: completePages === 0,
+      shouldAskForTableDesign: pagesMissingFieldKeys.length > 0,
+      recommendedGenerationMode: generationModes.recommended,
+    },
+    generationModes: generationModes.modes,
+    pages,
+    navigationBlocks,
+  }
+}
+
+function getGenerationModes(completePages) {
+  const modes = [
+    {
+      id: 'single-agent-package',
+      name: '整包一次性生成',
+      recommendedWhen: '1-3 个完整页面，页面关系简单',
+      tradeoff: '最快，但页面多时更容易遗漏细节或规则漂移',
+    },
+    {
+      id: 'coordinator-sequential',
+      name: '总控逐页顺序生成',
+      recommendedWhen: '4 个以上页面，或产品希望每页更稳但不使用子智能体',
+      tradeoff: '最稳妥，速度较慢；总控每次只生成一个页面并做局部检查',
+    },
+    {
+      id: 'coordinator-subagents',
+      name: '总控 + 子智能体逐页生成',
+      recommendedWhen: '4 个以上页面，且当前环境支持子智能体/并行 agent',
+      tradeoff: '速度快、上下文更小；必须由总控统一共享数据、菜单和最终集成',
+    },
+  ]
+
+  let recommended = 'single-agent-package'
+  if (completePages >= 4)
+    recommended = 'coordinator-subagents'
+  if (completePages === 0)
+    recommended = 'none'
+
+  return { recommended, modes }
+}
+
+function toMarkdown(report) {
+  const lines = [
+    '# BRMS Prototype Document Analysis',
+    '',
+    `- Entry: \`${report.entry}\``,
+    `- Documents scanned: ${report.documents.length}`,
+    `- Pages detected: ${report.summary.pageCount}`,
+    `- Complete pages: ${report.summary.completePages}`,
+    `- Pages missing field keys: ${report.summary.pagesMissingFieldKeys}`,
+    `- Navigation blocks: ${report.summary.navigationBlocks}`,
+    `- Menu structure detected: ${report.summary.menuStructureDetected ? 'yes' : 'no'}`,
+    `- Navigation tree nodes: ${report.summary.navigationTreeNodes}`,
+    `- Recommended generation mode: ${report.summary.recommendedGenerationMode}`,
+    `- Stop required: ${report.summary.shouldStop ? 'yes' : 'no'}`,
+    '',
+  ]
+
+  if (report.missingReferences.length) {
+    lines.push('## Missing References', '')
+    report.missingReferences.forEach(ref => lines.push(`- \`${ref}\``))
+    lines.push('')
+  }
+
+  lines.push('## Generation Modes', '')
+  report.generationModes.forEach((mode) => {
+    lines.push(`- **${mode.name}** (\`${mode.id}\`): ${mode.recommendedWhen}；${mode.tradeoff}`)
+  })
+  lines.push('')
+
+  lines.push('## Pages', '')
+  report.pages.forEach((page) => {
+    lines.push(`### ${page.index ? `${page.index}. ` : ''}${page.title}`)
+    lines.push(`- Source: \`${page.source}:${page.line}\``)
+    lines.push(`- Complete: ${page.complete ? 'yes' : 'no'}`)
+    lines.push(`- Field tables: ${page.fieldTables.length}`)
+    lines.push(`- Function tables: ${page.functionTables.length}`)
+    lines.push(`- Field design complete: ${page.hasCompleteFieldDesign ? 'yes' : 'no'}`)
+    if (page.issues.length)
+      lines.push(`- Issues: ${page.issues.join('; ')}`)
+    lines.push('')
+  })
+
+  if (report.navigationBlocks.length) {
+    lines.push('## Navigation Blocks', '')
+    report.navigationBlocks.forEach((block, index) => {
+      lines.push(`### Block ${index + 1} (${block.source}:${block.line})`, '')
+      lines.push('```text')
+      lines.push(block.text)
+      lines.push('```', '')
+      if (block.tree?.length) {
+        lines.push('Parsed menu/navigation tree:', '')
+        lines.push(...formatNavigationTree(block.tree))
+        lines.push('')
+      }
+    })
+  }
+
+  return lines.join('\n')
+}
+
+function main() {
+  const args = parseArgs(process.argv.slice(2))
+  if (args.help || !args.entry) {
+    console.log('Usage: node scripts/analyze-doc.mjs <entry-md> --repo-root <repo> --format json|markdown|both')
+    process.exit(args.help ? 0 : 1)
+  }
+
+  const repoRoot = path.resolve(args.repoRoot || process.cwd())
+  const report = analyze(args.entry, repoRoot)
+
+  if (args.format === 'json') {
+    console.log(JSON.stringify(report, null, 2))
+    return
+  }
+
+  if (args.format === 'markdown') {
+    console.log(toMarkdown(report))
+    return
+  }
+
+  console.log('---MARKDOWN---')
+  console.log(toMarkdown(report))
+  console.log('---JSON---')
+  console.log(JSON.stringify(report, null, 2))
+}
+
+try {
+  main()
+}
+catch (error) {
+  console.error(error instanceof Error ? error.message : String(error))
+  process.exit(1)
+}