feat(semantic): add component semantic structure query command (#17)

- Add ComponentSemanticStructureRecord interface to types
- Extend ComponentRecord with semanticStructure field
- Create loadComponent utility function in loader.ts
- Implement semantic command with text/markdown/json output formats
- Add tree-style and table-style display for semantic structure
- Include error handling for missing components
- Support capitalized component name matching

Author: lonewolfyx

src/commands/semantic.ts

@@ -1,13 +1,73 @@
+import type { ComponentSemanticStructureRecord } from '#/components.ts'
 import { defineCommand } from 'citty'
+import { componentArgs } from '@/args/component.ts'
+import { defaultArgs } from '@/args/default.ts'
+import { resolveConfig } from '@/config.ts'
+import capitalize from '@/utils/capitalize.ts'
+import { loadComponent, loadVersionMetaData } from '@/utils/loader.ts'
+import { output } from '@/utils/output.ts'
+import { resolveVersion } from '@/utils/version.ts'
+
+function outputTextSemantic(component: string, semantic: ComponentSemanticStructureRecord[]): string {
+  let content = `${component} Semantic Structure:\n`
+
+  semantic.forEach((item, index, array) => {
+    if (index === array.length - 1) {
+      content += `└── ${item.key}         # ${item.description}\n`
+    }
+    else {
+      content += `├── ${item.key}         # ${item.description}\n`
+    }
+  })
+
+  return content
+}
+
+function outputMarkdownSemantic(component: string, semantic: ComponentSemanticStructureRecord[]): string {
+  return [
+    `## ${component} Semantic Structure:`,
+    '',
+    '| Key | Description |',
+    '| --- | --- |',
+    ...semantic.map(item => `| ${item.key} | ${item.description} |`),
+  ].join('\n')
+}
 
 export default defineCommand({
   meta: {
     name: 'semantic',
     description: 'Query the semantic customization structure of a component',
   },
-  run({ args }) {
-    // antd semantic <Component>
-    // 语义化 classNames / styles 结构及用法示例
-    console.log('Parsed args:', args)
+  args: {
+    ...defaultArgs,
+    ...componentArgs,
+  },
+  async run({ args }) {
+    const config = resolveConfig(args)
+    const component = capitalize(args.component)
+
+    try {
+      const version = await resolveVersion(config)
+      const metaData = loadComponent(component, await loadVersionMetaData(version))
+
+      const semantic = metaData.semanticStructure
+
+      if (!semantic.length) {
+        console.log(`No semantic structure data available for ${capitalize(component)}.`)
+        return ''
+      }
+
+      output({
+        json: {
+          name: component,
+          semanticStructure: semantic,
+        },
+        text: outputTextSemantic(component, semantic),
+        markdown: outputMarkdownSemantic(component, semantic),
+      }, args.format)
+    }
+    catch (error) {
+      console.log(`Error: Component ${component} not found!`)
+    }
   },
 })

src/types/components.ts

@@ -39,6 +39,12 @@ export interface ComponentDemoRecord {
   code: string
 }
 
+export interface ComponentSemanticStructureRecord {
+  key: string
+  description: string
+  descriptionZh: string
+}
+
 export interface ComponentRecord {
   name: string
   nameZh: string
@@ -55,4 +61,5 @@ export interface ComponentRecord {
   tokens: ComponentPropRecord[]
   faq: ComponentFaqRecord[]
   demos: ComponentDemoRecord[]
+  semanticStructure: ComponentSemanticStructureRecord[]
 }

src/utils/loader.ts

@@ -1,8 +1,9 @@
-import type { ChangelogFile } from '#/components.ts'
+import type { ChangelogFile, ComponentRecord } from '#/components.ts'
 import type { ResolvedVersion } from '@/types.ts'
 import { readFile } from 'node:fs/promises'
 import { join } from 'node:path'
 import { __dirname } from '@/constants/dirname.ts'
+import capitalize from '@/utils/capitalize.ts'
 
 export function getDataPath(): string {
   return join(__dirname, '..', 'data')
@@ -16,3 +17,13 @@ export async function loadVersionMetaData(version: ResolvedVersion): Promise<Cha
   }
   return JSON.parse(await readFile(join(getDataPath(), `v${version.version}.json`), 'utf-8')) as ChangelogFile
 }
+
+export function loadComponent(name: string, components: ChangelogFile): ComponentRecord {
+  const component = components.components.filter(c => c.name === capitalize(name))?.at(0)
+
+  if (!component) {
+    throw new Error(`Component ${name} not found`)
+  }
+
+  return component
+}