@ramathibodi/nuxt-commons 0.1.72 → 0.1.74

package/scripts/enrich-vue-docs-from-ai.mjs

@@ -0,0 +1,197 @@
+import fs from 'node:fs'
+import path from 'node:path'
+
+const rootDir = process.cwd()
+const aiPath = path.join(rootDir, 'docs/ai-summary.json')
+const docsDir = path.join(rootDir, 'docs/components')
+
+if (!fs.existsSync(aiPath) || !fs.existsSync(docsDir)) {
+  console.log('Skip enrich: required docs/ai-summary.json or docs/components missing.')
+  process.exit(0)
+}
+
+const ai = JSON.parse(fs.readFileSync(aiPath, 'utf8'))
+const componentMap = new Map(ai.components.map((c) => [c.path, c]))
+
+function toPosix(p) {
+  return p.split(path.sep).join('/')
+}
+
+function guessSourcePathFromDoc(docFile) {
+  const rel = toPosix(path.relative(docsDir, docFile))
+  const noExt = rel.replace(/\.md$/, '')
+  return `src/runtime/components/${noExt}.vue`
+}
+
+function mdEscape(str) {
+  return String(str ?? '').replace(/\|/g, '\\|')
+}
+
+const propHints = {
+  modelName: { type: 'string', description: 'GraphQL model name used to resolve query/mutation operations.' },
+  modelBy: { type: 'Record<string, any>', description: 'Base filter object applied to read/search/create flows.' },
+  modelKey: { type: 'string', description: 'Unique key field used to identify and update existing rows/items.' },
+  fields: { type: 'Array<string | object>', description: 'Requested GraphQL fields used when loading records.' },
+  headers: { type: 'any[]', description: 'Column definitions used by table/iterator rendering.' },
+  itemTitle: { type: 'string', description: 'Item field used as display label.' },
+  itemValue: { type: 'string', description: 'Item field used as stored value.' },
+  filterKeys: { type: 'string | string[]', description: 'Keys used for client-side filtering/searching.' },
+  multiple: { type: 'boolean', description: 'Enables multi-select mode.' },
+  placeholder: { type: 'string', description: 'Placeholder text shown when input has no value.' },
+  noDataText: { type: 'string', description: 'Text shown when no matching data is available.' },
+}
+
+function inferTypeFromDocDefault(defaultCell) {
+  const v = (defaultCell || '').trim().replace(/^`|`$/g, '')
+  if (!v || v === '-' || v === 'undefined') return undefined
+  if (v === 'true' || v === 'false') return 'boolean'
+  if (/^-?\d+(\.\d+)?$/.test(v)) return 'number'
+  if ((v.startsWith("'") && v.endsWith("'")) || (v.startsWith('"') && v.endsWith('"'))) return 'string'
+  if (v.includes('=> []') || v === '[]') return 'any[]'
+  if (v.includes('=> ({') || v === '{}' || v === 'null') return 'Record<string, any>'
+  return undefined
+}
+
+function inferEventDescription(eventName, payload) {
+  if (eventName === 'update:modelValue') return 'Emitted when the bound model value changes.'
+  if (eventName === 'open:dialog') return 'Emitted when the component opens its dialog/form editor.'
+  if (eventName === 'close:dialog') return 'Emitted when the component closes its dialog/form editor.'
+  if (eventName === 'create') return 'Emitted after a create action completes.'
+  if (eventName === 'update') return 'Emitted after an update action completes.'
+  if (eventName === 'delete') return 'Emitted after a delete action completes.'
+  if (eventName === 'import') return 'Emitted after import data is parsed and ready.'
+  if (eventName === 'error') return 'Emitted when an operation fails.'
+  if (payload) return `Emits payload: \`${payload}\`.`
+  return 'Custom event emitted by this component.'
+}
+
+function splitRow(line) {
+  const cols = line.split('|').slice(1, -1).map((c) => c.trim())
+  return cols
+}
+
+function joinRow(cols) {
+  return `| ${cols.join(' | ')} |`
+}
+
+function updatePropsTable(lines, sectionStartIdx, component) {
+  // table starts after "## Props", header and separator rows
+  let i = sectionStartIdx + 1
+  while (i < lines.length && !lines[i].startsWith('|')) i++
+  if (i + 1 >= lines.length) return 0
+
+  const propsByName = new Map((component.props || []).map((p) => [p.name, p]))
+  let changed = 0
+
+  // skip header + separator
+  for (let r = i + 2; r < lines.length; r++) {
+    const line = lines[r]
+    if (!line.startsWith('|')) break
+    const cols = splitRow(line)
+    if (cols.length < 5) continue
+
+    const propName = cols[0].replace(/`/g, '').trim()
+    const meta = propsByName.get(propName)
+    const hint = propHints[propName]
+
+    const desc = cols[1]
+    const type = cols[2]
+    const def = cols[4]
+
+    if ((!desc || desc === '-') && meta?.description) cols[1] = mdEscape(meta.description)
+    else if ((!desc || desc === '-') && hint?.description) cols[1] = mdEscape(hint.description)
+
+    if ((type === '-' || !type) && meta?.type) cols[2] = `\`${mdEscape(meta.type)}\``
+    else if ((type === '-' || !type) && hint?.type) cols[2] = `\`${mdEscape(hint.type)}\``
+    else if ((type === '-' || !type)) {
+      const inferred = inferTypeFromDocDefault(def)
+      if (inferred) cols[2] = `\`${mdEscape(inferred)}\``
+    }
+
+    if ((!def || def === '-') && meta?.default !== undefined) cols[4] = `\`${mdEscape(meta.default)}\``
+
+    const next = joinRow(cols)
+    if (next !== line) {
+      lines[r] = next
+      changed++
+    }
+  }
+
+  return changed
+}
+
+function updateEventsTable(lines, sectionStartIdx, component) {
+  let i = sectionStartIdx + 1
+  while (i < lines.length && !lines[i].startsWith('|')) i++
+  if (i + 1 >= lines.length) return 0
+
+  const emitsByName = new Map((component.emits || []).map((e) => [e.event, e]))
+  let changed = 0
+
+  // skip header + separator
+  for (let r = i + 2; r < lines.length; r++) {
+    const line = lines[r]
+    if (!line.startsWith('|')) break
+    const cols = splitRow(line)
+    while (cols.length < 3) cols.push('')
+
+    const eventName = cols[0].replace(/`/g, '').trim()
+    const meta = emitsByName.get(eventName)
+    if (!meta) continue
+
+    const propsCol = cols[1]
+    const descCol = cols[2]
+
+    if ((!propsCol || propsCol === '-') && meta.payload) cols[1] = `\`${mdEscape(meta.payload)}\``
+    if (!descCol || descCol === '-') cols[2] = mdEscape(inferEventDescription(eventName, meta.payload))
+
+    const next = joinRow(cols)
+    if (next !== line) {
+      lines[r] = next
+      changed++
+    }
+  }
+
+  return changed
+}
+
+function processDocFile(docFile) {
+  const sourcePath = guessSourcePathFromDoc(docFile)
+  const component = componentMap.get(sourcePath)
+  if (!component) return 0
+
+  const content = fs.readFileSync(docFile, 'utf8')
+  const lines = content.split('\n')
+  let changed = 0
+
+  for (let i = 0; i < lines.length; i++) {
+    if (lines[i].trim() === '## Props') changed += updatePropsTable(lines, i, component)
+    if (lines[i].trim() === '## Events') changed += updateEventsTable(lines, i, component)
+  }
+
+  if (changed > 0) fs.writeFileSync(docFile, lines.join('\n'))
+  return changed
+}
+
+function walkMd(dir) {
+  const out = []
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const full = path.join(dir, entry.name)
+    if (entry.isDirectory()) out.push(...walkMd(full))
+    else if (entry.name.endsWith('.md')) out.push(full)
+  }
+  return out
+}
+
+const mdFiles = walkMd(docsDir)
+let changedFiles = 0
+let changedRows = 0
+for (const file of mdFiles) {
+  const changed = processDocFile(file)
+  if (changed > 0) {
+    changedFiles++
+    changedRows += changed
+  }
+}
+
+console.log(`Enriched ${changedRows} table rows across ${changedFiles} files.`)

package/scripts/generate-ai-summary.mjs

@@ -0,0 +1,321 @@
+import fs from 'node:fs'
+import path from 'node:path'
+
+const rootDir = process.cwd()
+const componentsDir = path.join(rootDir, 'src/runtime/components')
+const composablesDir = path.join(rootDir, 'src/runtime/composables')
+const outMdFile = path.join(rootDir, 'docs/ai-summary.md')
+const outJsonFile = path.join(rootDir, 'docs/ai-summary.json')
+const outTypeIndexFile = path.join(rootDir, 'docs/type-index.json')
+
+function walkFiles(dir, exts = new Set(['.vue', '.ts'])) {
+  const result = []
+  if (!fs.existsSync(dir)) return result
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const full = path.join(dir, entry.name)
+    if (entry.isDirectory()) {
+      result.push(...walkFiles(full, exts))
+    } else if (exts.has(path.extname(entry.name))) {
+      result.push(full)
+    }
+  }
+  return result.sort((a, b) => a.localeCompare(b))
+}
+
+function toPosix(p) {
+  return p.split(path.sep).join('/')
+}
+
+function extractTopDescription(content) {
+  const m = content.match(/\/\*\*([\s\S]*?)\*\//)
+  if (!m) return 'No top-level description found.'
+  const lines = m[1]
+    .split('\n')
+    .map((l) => l.replace(/^\s*\*\s?/, '').trim())
+    .filter(Boolean)
+    .filter((l) => !l.toLowerCase().includes('vue-docgen'))
+  return lines[0] || 'No top-level description found.'
+}
+
+function compact(str) {
+  return str.replace(/\s+/g, ' ').trim()
+}
+
+function findInterfaceBody(content, interfaceName) {
+  const needle = `interface ${interfaceName}`
+  const start = content.indexOf(needle)
+  if (start === -1) return null
+
+  const braceStart = content.indexOf('{', start)
+  if (braceStart === -1) return null
+
+  let depth = 0
+  for (let i = braceStart; i < content.length; i++) {
+    const ch = content[i]
+    if (ch === '{') depth++
+    if (ch === '}') depth--
+    if (depth === 0) {
+      return content.slice(braceStart + 1, i)
+    }
+  }
+  return null
+}
+
+function extractWithDefaults(content) {
+  const defaults = {}
+  const m = content.match(/withDefaults\s*\(\s*defineProps[\s\S]*?,\s*\{([\s\S]*?)\}\s*\)/)
+  if (!m) return defaults
+
+  const lines = m[1].split('\n')
+  for (const line of lines) {
+    const clean = line.trim()
+    if (!clean || clean.startsWith('//')) continue
+    const kv = clean.match(/^([A-Za-z_][A-Za-z0-9_]*)\s*:\s*(.+?)(?:,\s*)?(?:\/\/\s*(.*))?$/)
+    if (!kv) continue
+    const key = kv[1]
+    const rawValue = kv[2].trim()
+    const description = (kv[3] || '').trim()
+    defaults[key] = { value: rawValue, description }
+  }
+
+  return defaults
+}
+
+function inferTypeFromDefault(rawValue) {
+  if (rawValue === 'true' || rawValue === 'false') return 'boolean'
+  if (rawValue === 'null') return 'null'
+  if (/^['"].*['"]$/.test(rawValue)) return 'string'
+  if (/^-?\d+(\.\d+)?$/.test(rawValue)) return 'number'
+  if (/^\(\)\s*=>\s*\[\s*\]$/.test(rawValue)) return 'any[]'
+  if (/^\(\)\s*=>\s*\(\s*\{\s*\}\s*\)$/.test(rawValue)) return 'Record<string, any>'
+  if (/^\(\)\s*=>\s*\[/.test(rawValue)) return 'any[]'
+  if (/^\(\)\s*=>\s*\(\s*\{/.test(rawValue)) return 'Record<string, any>'
+  return 'unknown'
+}
+
+function extractProps(content) {
+  const props = []
+  const ifaceBody = findInterfaceBody(content, 'Props')
+  const defaults = extractWithDefaults(content)
+
+  if (ifaceBody) {
+    const lines = ifaceBody.split('\n')
+    for (const line of lines) {
+      const m = line.match(/^\s*([A-Za-z_][A-Za-z0-9_]*)(\?)?\s*:\s*([^/;]+(?:\|[^/;]+)*)[;]?\s*(?:\/\/\s*(.+))?\s*$/)
+      if (m) {
+        const name = m[1]
+        const optional = !!m[2]
+        const type = compact(m[3].trim())
+        const description = (m[4] || '').trim()
+        props.push({
+          name,
+          type,
+          required: !optional,
+          default: Object.prototype.hasOwnProperty.call(defaults, name) ? defaults[name].value : undefined,
+          description: description || (defaults[name]?.description || ''),
+        })
+      }
+    }
+  }
+
+  // Fallback for components where Props is empty and typed props come from imported intersections.
+  if (!props.length && Object.keys(defaults).length) {
+    for (const [name, meta] of Object.entries(defaults)) {
+      props.push({
+        name,
+        type: inferTypeFromDefault(meta.value),
+        required: false,
+        default: meta.value,
+        description: meta.description || 'Inferred from withDefaults()',
+      })
+    }
+  }
+
+  return props
+}
+
+function extractEmits(content) {
+  const emits = []
+
+  const typed = content.match(/defineEmits<\{([\s\S]*?)\}>\(\)/)
+  if (typed) {
+    const overloads = typed[1].matchAll(/\(\s*e\s*:\s*'([^']+)'\s*(?:,\s*([^)]*))?\)\s*:\s*void/g)
+    for (const m of overloads) {
+      emits.push({
+        event: m[1],
+        payload: m[2] ? compact(m[2]) : undefined,
+      })
+    }
+  }
+
+  const arr = content.match(/defineEmits\s*\(\s*\[([\s\S]*?)\]\s*\)/)
+  if (arr) {
+    const names = arr[1].matchAll(/'([^']+)'|"([^"]+)"/g)
+    for (const m of names) {
+      emits.push({ event: m[1] || m[2] })
+    }
+  }
+
+  return emits
+}
+
+function extractExports(content) {
+  const functions = []
+  const constants = []
+  const interfaces = []
+  const types = []
+  const enums = []
+
+  const fnMatches = content.matchAll(/export\s+function\s+([A-Za-z_][A-Za-z0-9_]*)\s*\(([\s\S]*?)\)\s*(?::\s*([^({;\n]+(?:<[\s\S]*?>)?))?\s*\{/g)
+  for (const m of fnMatches) {
+    functions.push({
+      name: m[1],
+      params: compact(m[2]),
+      returns: m[3] ? compact(m[3]) : undefined,
+      signature: compact(`function ${m[1]}(${m[2]})${m[3] ? `: ${m[3]}` : ''}`),
+    })
+  }
+
+  const constMatches = content.matchAll(/export\s+const\s+([A-Za-z_][A-Za-z0-9_]*)\s*(?::\s*([^=;\n]+))?\s*=/g)
+  for (const m of constMatches) {
+    constants.push({
+      name: m[1],
+      type: m[2] ? compact(m[2]) : undefined,
+    })
+  }
+
+  const interfaceMatches = content.matchAll(/export\s+interface\s+([A-Za-z_][A-Za-z0-9_]*)\s*\{([\s\S]*?)\n\}/g)
+  for (const m of interfaceMatches) {
+    interfaces.push({
+      name: m[1],
+      shape: compact(m[2]),
+    })
+  }
+
+  const typeMatches = content.matchAll(/export\s+type\s+([A-Za-z_][A-Za-z0-9_]*)\s*=\s*([^;\n]+(?:\n[^;\n]+)*)/g)
+  for (const m of typeMatches) {
+    types.push({
+      name: m[1],
+      definition: compact(m[2].replace(/\n/g, ' ')),
+    })
+  }
+
+  const enumMatches = content.matchAll(/export\s+enum\s+([A-Za-z_][A-Za-z0-9_]*)\s*\{([\s\S]*?)\}/g)
+  for (const m of enumMatches) {
+    const members = m[2]
+      .split('\n')
+      .map((line) => line.trim())
+      .filter(Boolean)
+      .map((line) => line.replace(/,$/, ''))
+    enums.push({
+      name: m[1],
+      members,
+    })
+  }
+
+  return { functions, constants, interfaces, types, enums }
+}
+
+const componentFiles = walkFiles(componentsDir, new Set(['.vue']))
+const composableFiles = walkFiles(composablesDir, new Set(['.ts']))
+
+const generatedAt = new Date().toISOString()
+const docModel = {
+  generatedAt,
+  scope: {
+    componentCount: componentFiles.length,
+    composableCount: composableFiles.length,
+  },
+  components: [],
+  composables: [],
+}
+
+const lines = []
+lines.push('# AI Summary')
+lines.push('')
+lines.push('AI-first summary generated from source files with explicit type metadata.')
+lines.push('')
+lines.push(`Generated at: ${generatedAt}`)
+lines.push('')
+lines.push('## Scope')
+lines.push('')
+lines.push(`- Components: ${componentFiles.length}`)
+lines.push(`- Composables: ${composableFiles.length}`)
+lines.push('')
+lines.push('## Components')
+lines.push('')
+
+for (const file of componentFiles) {
+  const rel = toPosix(path.relative(rootDir, file))
+  const content = fs.readFileSync(file, 'utf8')
+  const summary = extractTopDescription(content)
+  const props = extractProps(content)
+  const emits = extractEmits(content)
+  const componentEntry = {
+    path: rel,
+    summary,
+    props,
+    emits,
+  }
+  docModel.components.push(componentEntry)
+
+  lines.push(`### \`${rel}\``)
+  lines.push(`- Summary: ${summary}`)
+  if (props.length) {
+    lines.push(`- Props (${props.length}):`)
+    for (const prop of props) {
+      const chunks = [
+        `type=${prop.type}`,
+        prop.required ? 'required=true' : 'required=false',
+      ]
+      if (prop.default !== undefined) chunks.push(`default=${prop.default}`)
+      if (prop.description) chunks.push(`desc=${prop.description}`)
+      lines.push(`  - \`${prop.name}\` { ${chunks.join(' | ')} }`)
+    }
+  } else {
+    lines.push('- Props: None declared in a local `Props` interface.')
+  }
+  if (emits.length) {
+    lines.push(`- Emits (${emits.length}):`)
+    for (const e of emits) {
+      lines.push(`  - \`${e.event}\`${e.payload ? ` payload: ${e.payload}` : ''}`)
+    }
+  } else {
+    lines.push('- Emits: None detected.')
+  }
+  lines.push('')
+}
+
+lines.push('## Composables')
+lines.push('')
+
+for (const file of composableFiles) {
+  const rel = toPosix(path.relative(rootDir, file))
+  const content = fs.readFileSync(file, 'utf8')
+  const summary = extractTopDescription(content)
+  const exports = extractExports(content)
+  const composableEntry = {
+    path: rel,
+    summary,
+    exports,
+  }
+  docModel.composables.push(composableEntry)
+
+  lines.push(`### \`${rel}\``)
+  lines.push(`- Summary: ${summary}`)
+  lines.push(`- Export functions (${exports.functions.length}): ${exports.functions.map((f) => `\`${f.signature}\``).join(', ') || 'none'}`)
+  lines.push(`- Export interfaces (${exports.interfaces.length}): ${exports.interfaces.map((i) => `\`${i.name}\``).join(', ') || 'none'}`)
+  lines.push(`- Export types (${exports.types.length}): ${exports.types.map((t) => `\`${t.name}\``).join(', ') || 'none'}`)
+  lines.push(`- Export consts (${exports.constants.length}): ${exports.constants.map((c) => `\`${c.name}\``).join(', ') || 'none'}`)
+  lines.push(`- Export enums (${exports.enums.length}): ${exports.enums.map((e) => `\`${e.name}\``).join(', ') || 'none'}`)
+  lines.push('')
+}
+
+fs.mkdirSync(path.dirname(outMdFile), { recursive: true })
+fs.writeFileSync(outMdFile, lines.join('\n'))
+fs.writeFileSync(outJsonFile, JSON.stringify(docModel, null, 2))
+fs.writeFileSync(outTypeIndexFile, JSON.stringify(docModel, null, 2))
+
+console.log(`Generated ${toPosix(path.relative(rootDir, outMdFile))}`)
+console.log(`Generated ${toPosix(path.relative(rootDir, outJsonFile))}`)
+console.log(`Generated ${toPosix(path.relative(rootDir, outTypeIndexFile))}`)

package/scripts/generate-composables-md.mjs

@@ -0,0 +1,129 @@
+import fs from 'node:fs'
+import path from 'node:path'
+
+const rootDir = process.cwd()
+const aiSummaryPath = path.join(rootDir, 'docs/ai-summary.json')
+const outDir = path.join(rootDir, 'docs/composables-md')
+
+if (!fs.existsSync(aiSummaryPath)) {
+  console.error('docs/ai-summary.json not found. Run: npm run docs:ai:summary')
+  process.exit(1)
+}
+
+const ai = JSON.parse(fs.readFileSync(aiSummaryPath, 'utf8'))
+const composables = ai.composables || []
+
+function safeName(filePath) {
+  return filePath
+    .replace(/^src\/runtime\/composables\//, '')
+    .replace(/\//g, '__')
+    .replace(/\.ts$/, '')
+}
+
+function mdEscape(str) {
+  return String(str ?? '').replace(/\|/g, '\\|')
+}
+
+fs.mkdirSync(outDir, { recursive: true })
+
+const index = []
+index.push('# Composables (Markdown)')
+index.push('')
+index.push(`Generated at: ${ai.generatedAt}`)
+index.push('')
+index.push('| Composable | Source |')
+index.push('| ---------- | ------ |')
+
+for (const c of composables) {
+  const fileBase = safeName(c.path)
+  const outFile = path.join(outDir, `${fileBase}.md`)
+  const content = []
+
+  content.push(`# ${fileBase}`)
+  content.push('')
+  content.push(`- Source: \`${c.path}\``)
+  content.push(`- Summary: ${c.summary || ''}`)
+  content.push('')
+
+  const exp = c.exports || {}
+  const functions = exp.functions || []
+  const interfaces = exp.interfaces || []
+  const types = exp.types || []
+  const consts = exp.constants || []
+  const enums = exp.enums || []
+
+  content.push('## Exported Functions')
+  content.push('')
+  if (functions.length) {
+    content.push('| Name | Signature | Returns |')
+    content.push('| ---- | --------- | ------- |')
+    for (const fn of functions) {
+      content.push(`| \`${mdEscape(fn.name)}\` | \`${mdEscape(fn.signature || '')}\` | \`${mdEscape(fn.returns || '')}\` |`)
+    }
+  } else {
+    content.push('No exported functions.')
+  }
+  content.push('')
+
+  content.push('## Exported Interfaces')
+  content.push('')
+  if (interfaces.length) {
+    for (const i of interfaces) {
+      content.push(`### \`${i.name}\``)
+      content.push('')
+      content.push('```ts')
+      content.push(i.shape || '')
+      content.push('```')
+      content.push('')
+    }
+  } else {
+    content.push('No exported interfaces.')
+    content.push('')
+  }
+
+  content.push('## Exported Types')
+  content.push('')
+  if (types.length) {
+    content.push('| Name | Definition |')
+    content.push('| ---- | ---------- |')
+    for (const t of types) {
+      content.push(`| \`${mdEscape(t.name)}\` | \`${mdEscape(t.definition || '')}\` |`)
+    }
+  } else {
+    content.push('No exported types.')
+  }
+  content.push('')
+
+  content.push('## Exported Constants')
+  content.push('')
+  if (consts.length) {
+    content.push('| Name | Type |')
+    content.push('| ---- | ---- |')
+    for (const k of consts) {
+      content.push(`| \`${mdEscape(k.name)}\` | \`${mdEscape(k.type || '')}\` |`)
+    }
+  } else {
+    content.push('No exported constants.')
+  }
+  content.push('')
+
+  content.push('## Exported Enums')
+  content.push('')
+  if (enums.length) {
+    for (const e of enums) {
+      content.push(`### \`${e.name}\``)
+      content.push('')
+      for (const m of e.members || []) content.push(`- \`${m}\``)
+      content.push('')
+    }
+  } else {
+    content.push('No exported enums.')
+    content.push('')
+  }
+
+  fs.writeFileSync(outFile, content.join('\n'))
+  index.push(`| [\`${fileBase}\`](${fileBase}.md) | \`${c.path}\` |`)
+}
+
+fs.writeFileSync(path.join(outDir, 'README.md'), index.join('\n'))
+console.log(`Generated markdown docs for ${composables.length} composables at docs/composables-md`)