@falconwry/creator 0.36.0-alpha.1

package/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "@falconwry/creator",
+  "version": "0.36.0-alpha.1",
+  "private": false,
+  "main": "./dist/index.js",
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit",
+    "dev": "tsx src/cli.ts"
+  },
+  "dependencies": {
+    "@falconwry/scanner-vue": "workspace:*",
+    "@opencode-ai/sdk": "^1.17.8"
+  },
+  "devDependencies": {
+    "tsx": "^4.19.0",
+    "typescript": "^5.5.0"
+  }
+}

package/src/ai-analyzer.ts

@@ -0,0 +1,331 @@
+import type { Analyzer, AnalyzedTool, RawTool, PromptContext, Scanner } from './types.js'
+import type { Logger } from './logger.js'
+import { RuleBasedAnalyzer } from './analyzer.js'
+
+const MAX_RETRY = 3
+const BATCH_SIZE = 15
+const TIMEOUT_MS = 60_000
+const MAX_FEEDBACK_LEN = 2000
+
+function buildBatchPrompt(
+  batch: RawTool[],
+  context: PromptContext,
+  errorFeedback?: string,
+): string {
+  let prompt = `你是 ${context.projectType} 的一个代码分析助手。
+以下列出了该项目中多个封装好的 ${context.toolConcept}，请为每个工具生成分析信息。
+
+工具列表：
+---
+`
+  for (let i = 0; i < batch.length; i++) {
+    const tool = batch[i]
+    prompt += `序号: ${i + 1}
+文件路径: ${tool.src}
+行号: ${tool.startLine}-${tool.endLine}
+代码:
+\`\`\`
+${tool.code}
+\`\`\`
+---
+`
+  }
+
+  prompt += `
+请为每个工具返回一个 JSON 数组，每个元素包含以下字段：
+1. name：工具名称（必须与上面给出的名称一致）
+2. description：一句话概括该工具的功能（中文，50 字左右）
+3. category：分类，必须是以下之一：${context.categories.join(' / ')}
+4. tags：5 个左右的标签，如：${context.exampleTags.join('、')}
+
+请严格返回 JSON 数组格式，不要包含任何其他文字。
+`
+
+  if (errorFeedback) {
+    prompt += `\n注意：${errorFeedback}\n`
+  }
+
+  return prompt
+}
+
+function tryParseJSON(text: string): any | null {
+  // Try to extract JSON array from the response
+  const cleaned = text.trim()
+    .replace(/^```json\s*/i, '')
+    .replace(/^```\s*/i, '')
+    .replace(/\s*```$/, '')
+
+  try {
+    return JSON.parse(cleaned)
+  } catch {
+    // Try to find a JSON array in the text
+    const match = cleaned.match(/\[\s*\{[\s\S]*\}\s*\]/)
+    if (match) {
+      try {
+        return JSON.parse(match[0])
+      } catch {
+        return null
+      }
+    }
+    return null
+  }
+}
+
+function validateStructural(
+  output: any[],
+  batch: RawTool[],
+): string[] {
+  const errors: string[] = []
+
+  if (!Array.isArray(output)) {
+    return ['Response is not a JSON array']
+  }
+
+  if (output.length !== batch.length) {
+    errors.push(`Expected ${batch.length} tools in response, got ${output.length}`)
+  }
+
+  for (let i = 0; i < Math.min(output.length, batch.length); i++) {
+    const item = output[i]
+    const prefix = `Tool #${i + 1} ("${batch[i]?.name ?? '?'}"):`
+
+    if (!item.name) {
+      errors.push(`${prefix} missing "name" field`)
+    }
+
+    if (!item.description || typeof item.description !== 'string') {
+      errors.push(`${prefix} missing or invalid "description" field`)
+    }
+
+    if (!item.category || typeof item.category !== 'string') {
+      errors.push(`${prefix} missing "category" field`)
+    }
+
+    if (!item.tags || !Array.isArray(item.tags)) {
+      errors.push(`${prefix} missing or invalid "tags" field`)
+    }
+  }
+
+  return errors
+}
+
+function truncateFeedback(text: string): string {
+  if (text.length <= MAX_FEEDBACK_LEN) return text
+  return text.slice(0, MAX_FEEDBACK_LEN - 3) + '...'
+}
+
+async function analyzeBatch(
+  batch: RawTool[],
+  context: PromptContext,
+  scanner: Scanner,
+  log: Logger,
+  retryCount: number,
+  errorFeedback?: string,
+): Promise<AnalyzedTool[]> {
+  const { createOpencodeClient } = await import('@opencode-ai/sdk')
+
+  const client = createOpencodeClient({ baseUrl: 'http://localhost:4096' } as any)
+
+  const sessionResult = await client.session.create({
+    body: { title: 'falconwry-analyze' },
+  })
+
+  const sessionId = sessionResult.data?.id
+  if (!sessionId) {
+    throw new Error('Failed to create session')
+  }
+
+  try {
+    const promptText = buildBatchPrompt(batch, context, errorFeedback)
+    const controller = new AbortController()
+    const timeout = setTimeout(() => controller.abort(), TIMEOUT_MS)
+
+    const result = await client.session.prompt({
+      path: { id: sessionId },
+      body: {
+        model: { providerID: 'deepseek', modelID: 'deepseek-v4-pro' },
+        parts: [
+          {
+            type: 'text',
+            text: promptText,
+          },
+        ],
+      },
+    })
+
+    clearTimeout(timeout)
+
+    // Extract text from response parts
+    const parts = result.data?.parts ?? []
+    const responseText = parts
+      .filter((p: any) => p.type === 'text')
+      .map((p: any) => p.text)
+      .join('\n')
+
+    const output = tryParseJSON(responseText)
+    if (!output || !Array.isArray(output)) {
+      log.warn('AI response was not valid JSON')
+      if (retryCount < MAX_RETRY) {
+        console.warn(`  ⚠️  Batch parse failed, retrying (${retryCount + 1}/${MAX_RETRY})...`)
+        return analyzeBatch(
+          batch,
+          context,
+          scanner,
+          log,
+          retryCount + 1,
+          'Response was not valid JSON. Please return ONLY a JSON array.',
+        )
+      }
+      console.warn(`  ❌ Batch failed after ${MAX_RETRY} retries, using rule-based fallback`)
+      log.error(`Batch failed after ${MAX_RETRY} retries: not valid JSON`)
+      return RuleBasedAnalyzer.analyze(batch, context)
+    }
+
+    // Step 1: Structural validation (creator)
+    const structuralErrors = validateStructural(output, batch)
+    if (structuralErrors.length > 0) {
+      console.warn(`  ⚠️  ${structuralErrors.length} structural error(s):`)
+      for (const e of structuralErrors.slice(0, 3)) {
+        console.warn(`     - ${e}`)
+      }
+      log.warn(`Structural validation failed (${structuralErrors.length} errors):`)
+      for (const e of structuralErrors) {
+        log.warn(`  ${e}`)
+      }
+      if (retryCount < MAX_RETRY) {
+        console.warn(`     Retrying (${retryCount + 1}/${MAX_RETRY})...`)
+        return analyzeBatch(
+          batch, context, scanner, log,
+          retryCount + 1,
+          truncateFeedback(structuralErrors.join('; ')),
+        )
+      }
+      console.warn(`  ❌ Structural validation failed after ${MAX_RETRY} retries, using rule-based fallback`)
+      log.error(`Structural validation failed after ${MAX_RETRY} retries`)
+      return RuleBasedAnalyzer.analyze(batch, context)
+    }
+
+    // Step 2: Content validation (scanner per tool, creator iterates)
+    const rules = scanner.getValidationRules()
+    const contentErrors: string[] = []
+
+    for (const [i, item] of output.entries()) {
+      const tool = { ...batch[i], ...item }
+      const toolErrors = scanner.validateTool(tool, rules)
+      for (const e of toolErrors) {
+        contentErrors.push(`Tool #${i + 1} ("${tool.name}"): ${e}`)
+      }
+    }
+
+    if (contentErrors.length > 0) {
+      // Console: first 3 errors
+      console.warn(`  ⚠️  ${contentErrors.length} validation error(s):`)
+      for (const e of contentErrors.slice(0, 3)) {
+        console.warn(`     - ${e}`)
+      }
+      if (contentErrors.length > 3) {
+        console.warn(`     ... and ${contentErrors.length - 3} more (see .falconry/log/creator.log)`)
+      }
+
+      // Log: all errors
+      log.warn(`Content validation failed (${contentErrors.length} errors):`)
+      for (const e of contentErrors) {
+        log.warn(`  ${e}`)
+      }
+
+      if (retryCount < MAX_RETRY) {
+        console.warn(`     Retrying (${retryCount + 1}/${MAX_RETRY})...`)
+        return analyzeBatch(
+          batch, context, scanner, log,
+          retryCount + 1,
+          truncateFeedback(contentErrors.join('; ')),
+        )
+      }
+      console.warn(`  ❌ Validation failed after ${MAX_RETRY} retries, using rule-based fallback`)
+      log.error(`Validation failed after ${MAX_RETRY} retries`)
+      return RuleBasedAnalyzer.analyze(batch, context)
+    }
+
+    return output.map((item: any, i: number) => ({
+      ...batch[i],
+      description: item.description,
+      category: item.category,
+      tags: item.tags,
+    }))
+  } finally {
+    // Clean up session
+    try {
+      await client.session.delete({ path: { id: sessionId } })
+    } catch {
+      // Ignore cleanup errors
+    }
+  }
+}
+
+function chunkArray<T>(arr: T[], size: number): T[][] {
+  const chunks: T[][] = []
+  for (let i = 0; i < arr.length; i += size) {
+    chunks.push(arr.slice(i, i + size))
+  }
+  return chunks
+}
+
+export function createOpenCodeAnalyzer(scanner: Scanner, log: Logger): Analyzer {
+  return {
+    async analyze(tools: RawTool[], context: PromptContext): Promise<AnalyzedTool[]> {
+      if (tools.length === 0) return []
+
+      // Pre-flight: check if OpenCode server is reachable
+      try {
+        const { createOpencodeClient } = await import('@opencode-ai/sdk')
+        const client = createOpencodeClient({ baseUrl: 'http://localhost:4096' } as any)
+        await client.session.list()
+      } catch {
+        throw new Error(
+          'OpenCode server not available at localhost:4096. ' +
+          'Start the server or the analysis will fall back to rules.',
+        )
+      }
+
+      const batches = chunkArray(tools, BATCH_SIZE)
+      const results: AnalyzedTool[] = []
+
+      log.info(`AI analysis started: ${tools.length} tools in ${batches.length} batch(es)`)
+
+      for (let i = 0; i < batches.length; i++) {
+        const batch = batches[i]
+        console.log(`  🧠 AI analyzing batch ${i + 1}/${batches.length} (${batch.length} tools)...`)
+        log.info(`Batch ${i + 1}/${batches.length}: ${batch.length} tools`)
+        try {
+          const analyzed = await analyzeBatch(batch, context, scanner, log, 0)
+          results.push(...analyzed)
+          log.info(`Batch ${i + 1} complete: ${analyzed.length} tools analyzed`)
+        } catch (err: any) {
+          console.warn(`  ⚠️  Batch ${i + 1} failed: ${err.message}`)
+          console.warn(`  ⬇   Falling back to rule-based analysis for this batch`)
+          log.warn(`Batch ${i + 1} failed: ${err.message}, falling back to rules`)
+          const fallback = await RuleBasedAnalyzer.analyze(batch, context)
+          results.push(...fallback)
+        }
+      }
+
+      log.info(`AI analysis complete: ${results.length} tools`)
+      return results
+    },
+  }
+}
+
+// Legacy static export for compatibility
+export const OpenCodeAnalyzer: Analyzer = createOpenCodeAnalyzer(
+  {
+    name: 'noop',
+    scanFiles: () => [],
+    scanRegistrations: () => [],
+    scanDependencies: () => ({}),
+    buildRegistry: () => [],
+    getPromptContext: () => ({ projectType: '', toolConcept: '', categories: [], exampleTags: [] }),
+    getValidationRules: () => ({ description: { minLength: 0, maxLength: 999 }, tags: { minCount: 0, maxCount: 99 }, nameMatch: 'loose', allowedCategories: [] }),
+    validateTool: () => [],
+  },
+  { debug: () => {}, info: () => {}, warn: () => {}, error: () => {} },
+)

package/src/analyzer.ts

@@ -0,0 +1,154 @@
+import type { RawTool, AnalyzedTool, Analyzer, PromptContext } from './types.js'
+
+const KEYWORD_MAP: Record<string, string> = {
+  date: '日期',
+  time: '时间',
+  format: '格式化',
+  currency: '货币',
+  number: '数字',
+  button: '按钮',
+  table: '表格',
+  modal: '弹窗',
+  dialog: '弹窗',
+  request: '请求',
+  fetch: '请求',
+  pagination: '分页',
+  page: '分页',
+  focus: '聚焦',
+  badge: '角标',
+  icon: '图标',
+  data: '数据',
+  base: '基础',
+  upload: '上传',
+  download: '下载',
+  select: '选择',
+  input: '输入',
+  form: '表单',
+  validate: '验证',
+  toast: '提示',
+  loading: '加载',
+  error: '错误',
+  search: '搜索',
+  filter: '过滤',
+  sort: '排序',
+  copy: '复制',
+  clipboard: '剪贴板',
+  storage: '存储',
+  cookie: 'Cookie',
+  router: '路由',
+  auth: '认证',
+  permission: '权限',
+  user: '用户',
+  list: '列表',
+  card: '卡片',
+  avatar: '头像',
+  progress: '进度',
+  tooltip: '提示',
+  dropdown: '下拉',
+  menu: '菜单',
+  nav: '导航',
+  tab: '标签页',
+  tree: '树',
+  chart: '图表',
+}
+
+const CATEGORY_SUFFIX: Record<string, string> = {
+  component: '组件',
+  composable: '组合式函数',
+  function: '工具',
+  directive: '指令',
+  mixin: '混入',
+  plugin: '插件',
+}
+
+const COMMON_PREFIXES = new Set([
+  'use', 'v', 'on', 'handle', 'get', 'set', 'is', 'has', 'create',
+])
+
+function splitCamelCase(name: string): string[] {
+  const words: string[] = []
+  let current = ''
+  for (const ch of name) {
+    if (ch >= 'A' && ch <= 'Z') {
+      if (current) words.push(current)
+      current = ch
+    } else {
+      current += ch
+    }
+  }
+  if (current) words.push(current)
+  return words
+}
+
+function wordsToChinese(words: string[]): string[] {
+  const result: string[] = []
+  for (const w of words) {
+    const lower = w.toLowerCase()
+    const cn = KEYWORD_MAP[lower]
+    if (cn) {
+      // Avoid consecutive duplicates (e.g., "Modal" + "Dialog" → only one "弹窗")
+      if (result.length > 0 && result[result.length - 1] === cn) continue
+      result.push(cn)
+    }
+  }
+  return result
+}
+
+function generateDescription(name: string, category: string, src: string): string {
+  const rawWords = splitCamelCase(name)
+  const meaningful = rawWords.filter((w) => !COMMON_PREFIXES.has(w))
+  const chineseWords = wordsToChinese(meaningful)
+
+  // For components, use the raw words if no Chinese mapping found
+  const suffix = CATEGORY_SUFFIX[category] || ''
+  if (chineseWords.length === 0) {
+    const fallback = meaningful.join('')
+    return fallback ? `${fallback}${suffix}` : name
+  }
+
+  return chineseWords.join('') + suffix
+}
+
+function generateTags(name: string, src: string): string[] {
+  const rawWords = splitCamelCase(name)
+  const meaningful = rawWords.filter((w) => !COMMON_PREFIXES.has(w))
+  const chineseWords = wordsToChinese(meaningful)
+
+  // Also add tags from the directory name
+  const dirParts = src.split('/')
+  if (dirParts.length >= 2) {
+    const parentDir = dirParts[dirParts.length - 2]
+    const dirTag = KEYWORD_MAP[parentDir.toLowerCase()]
+    if (dirTag && !chineseWords.includes(dirTag)) {
+      chineseWords.push(dirTag)
+    }
+  }
+
+  return chineseWords.length > 0 ? chineseWords : [name]
+}
+
+function inferCategory(name: string, src: string): string {
+  if (src.endsWith('.vue')) return 'component'
+  if (/^use[A-Z]/.test(name)) return 'composable'
+  if (/^v[A-Z]/.test(name)) return 'directive'
+  if (/mixin$/i.test(name)) return 'mixin'
+  if (src.includes('/directives/')) return 'directive'
+  if (src.includes('/composables/')) return 'composable'
+  if (src.includes('/mixins/')) return 'mixin'
+  if (src.includes('/components/')) return 'component'
+  return 'function'
+}
+
+export const RuleBasedAnalyzer: Analyzer = {
+  async analyze(tools: RawTool[], _context: PromptContext): Promise<AnalyzedTool[]> {
+    return tools.map((tool) => {
+      const category = inferCategory(tool.name, tool.src)
+      return {
+        ...tool,
+        category,
+        description: generateDescription(tool.name, category, tool.src),
+        tags: generateTags(tool.name, tool.src),
+      }
+    })
+  },
+}

package/src/cli.ts

@@ -0,0 +1,26 @@
+#!/usr/bin/env node
+import { runPipeline } from './pipeline.js'
+
+const args = process.argv.slice(2)
+const cwdIndex = args.indexOf('--cwd')
+const cwd = cwdIndex !== -1 ? args[cwdIndex + 1] : process.cwd()
+
+  console.log('🔍 Falconwry Creator v0.36.0-alpha.1')
+  console.log(`📦 Scanner: @falconwry/scanner-vue`)
+  console.log(`📂 Project: ${cwd}\n`)
+
+  runPipeline(cwd)
+    .then(({ stats }) => {
+      console.log(`📂 File scan: ${stats.fileTools} tools`)
+      console.log(`🔗 Registrations: ${stats.regTools} tools`)
+      console.log(`📎 Dependencies: ${stats.depsEntries} resolved`)
+      console.log(`🔀 Merged: ${stats.merged}`)
+      console.log(`🔬 Filtered: ${stats.filtered}`)
+      console.log(`📝 Registry: ${stats.registry} entries`)
+      console.log(`✅ Done in ${stats.elapsed}ms`)
+      console.log(`📄 Output: .falconry/map.json`)
+    })
+  .catch((err) => {
+    console.error('❌ Error:', err.message)
+    process.exit(1)
+  })

package/src/index.ts

@@ -0,0 +1,16 @@
+export type {
+  RawTool,
+  AnalyzedTool,
+  BaseRegistry,
+  FrontendRegistry,
+  DependentsMap,
+  ValidationRules,
+  Scanner,
+  Analyzer,
+  PromptContext,
+} from './types.js'
+
+export { RuleBasedAnalyzer } from './analyzer.js'
+export { OpenCodeAnalyzer, createOpenCodeAnalyzer } from './ai-analyzer.js'
+export { runPipeline } from './pipeline.js'
+export type { PipelineStats } from './pipeline.js'

package/src/logger.ts

@@ -0,0 +1,58 @@
+import * as fs from 'fs'
+import * as nodePath from 'path'
+
+export type LogLevel = 'DEBUG' | 'INFO' | 'WARN' | 'ERROR'
+
+const NAME = 'creator'
+
+const LEVEL_ORDER: Record<LogLevel, number> = {
+  DEBUG: 0,
+  INFO: 1,
+  WARN: 2,
+  ERROR: 3,
+}
+
+function resolveLevel(minLevel?: LogLevel): number {
+  const env = (process.env.FALCONRY_LOG_LEVEL?.toUpperCase() || 'INFO') as LogLevel
+  const threshold = LEVEL_ORDER[minLevel || env]
+  return threshold !== undefined ? threshold : LEVEL_ORDER.INFO
+}
+
+function ensureLogDir(projectRoot: string): string {
+  const dir = nodePath.join(projectRoot, '.falconry', 'log')
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true })
+  }
+  return dir
+}
+
+function writeLine(dir: string, file: string, line: string) {
+  try {
+    fs.appendFileSync(nodePath.join(dir, file), line + '\n', 'utf-8')
+  } catch {
+    // Silently ignore write failures
+  }
+}
+
+export function createLogger(projectRoot: string, minLevel?: LogLevel) {
+  const dir = ensureLogDir(projectRoot)
+  const threshold = resolveLevel(minLevel)
+  const levels = Object.keys(LEVEL_ORDER)
+
+  function log(level: LogLevel, msg: string) {
+    if (LEVEL_ORDER[level] < threshold) return
+    const ts = new Date().toISOString()
+    const line = `${ts} [${level.padEnd(5)}] [${NAME}] ${msg}`
+    writeLine(dir, `${NAME}.log`, line)
+    writeLine(dir, 'all.log', line)
+  }
+
+  return {
+    debug: (msg: string) => log('DEBUG', msg),
+    info: (msg: string) => log('INFO', msg),
+    warn: (msg: string) => log('WARN', msg),
+    error: (msg: string) => log('ERROR', msg),
+  }
+}
+
+export type Logger = ReturnType<typeof createLogger>

package/src/pipeline.ts

@@ -0,0 +1,130 @@
+import * as fs from 'fs'
+import * as nodePath from 'path'
+import { VueScanner } from '@falconwry/scanner-vue'
+import { RuleBasedAnalyzer } from './analyzer.js'
+import { createOpenCodeAnalyzer } from './ai-analyzer.js'
+import { createLogger } from './logger.js'
+import type { RawTool, AnalyzedTool, BaseRegistry, DependentsMap, Scanner } from './types.js'
+
+const EXCLUDE_NAMES = new Set([
+  'App',
+  'main',
+  'createApp',
+  'default',
+])
+
+function filterNonTools(tools: RawTool[]): RawTool[] {
+  return tools.filter((tool) => {
+    if (EXCLUDE_NAMES.has(tool.name)) return false
+    // Filter out type-only exports (no real code)
+    if (tool.code.trim().startsWith('type ') || tool.code.trim().startsWith('interface ')) return false
+    // Filter out empty or tiny exports
+    if (tool.endLine - tool.startLine < 1) return false
+    return true
+  })
+}
+
+function mergeAndDedupe(fileTools: RawTool[], regTools: RawTool[]): RawTool[] {
+  const seen = new Set<string>()
+  const merged: RawTool[] = []
+
+  for (const tool of fileTools) {
+    const key = `${tool.src}:${tool.name}`
+    if (!seen.has(key)) {
+      seen.add(key)
+      merged.push(tool)
+    }
+  }
+
+  for (const tool of regTools) {
+    const key = `${tool.src}:${tool.name}`
+    if (!seen.has(key)) {
+      seen.add(key)
+      merged.push(tool)
+    }
+  }
+
+  return merged
+}
+
+export async function runPipeline(
+  projectRoot: string,
+  scanner: Scanner = VueScanner,
+): Promise<{ registry: BaseRegistry[]; stats: PipelineStats }> {
+  const log = createLogger(projectRoot)
+  const startTime = Date.now()
+
+  log.info('Pipeline started')
+  log.info(`Project: ${projectRoot}`)
+  log.info(`Scanner: ${scanner.name}`)
+
+  // Step 1+2: Scan files and registrations
+  log.info('Step 1: Scanning files...')
+  const t1 = Date.now()
+  const fileTools = scanner.scanFiles(projectRoot)
+  const regTools = scanner.scanRegistrations(projectRoot)
+  const deps: DependentsMap = scanner.scanDependencies(projectRoot)
+  log.info(`File scan complete: ${fileTools.length} tools (${Date.now() - t1}ms)`)
+  log.info(`Registration scan complete: ${regTools.length} registrations`)
+  log.info(`Dependency scan complete: ${Object.keys(deps).length} resolved`)
+
+  // Step 3: Merge and filter
+  const merged = mergeAndDedupe(fileTools, regTools)
+  const filtered = filterNonTools(merged)
+  log.info(`Merge: ${fileTools.length} + ${regTools.length} → ${merged.length} (filtered to ${filtered.length})`)
+
+  // Step 4: Analyze (AI first, fallback to rule-based)
+  const context = scanner.getPromptContext(projectRoot)
+  log.info(`Context: ${context.projectType}`)
+  let analyzed: AnalyzedTool[]
+  const t4 = Date.now()
+  try {
+    log.info('Analysis: trying AI via OpenCode server...')
+    analyzed = await createOpenCodeAnalyzer(scanner, log).analyze(filtered, context)
+    log.info(`AI analysis complete: ${analyzed.length} tools (${Date.now() - t4}ms)`)
+  } catch {
+    console.warn('⚠️  OpenCode server not available, falling back to rule-based analysis')
+    log.warn('OpenCode server not available, falling back to rule-based analysis')
+    analyzed = await RuleBasedAnalyzer.analyze(filtered, context)
+    log.info(`Rule-based analysis complete: ${analyzed.length} tools (${Date.now() - t4}ms)`)
+  }
+
+  // Step 5: Build registry
+  const registry = scanner.buildRegistry(analyzed, deps)
+  log.info(`Registry built: ${registry.length} entries`)
+
+  // Step 6: Write .falconry/map.json
+  const falconryDir = nodePath.join(projectRoot, '.falconry')
+  if (!fs.existsSync(falconryDir)) {
+    fs.mkdirSync(falconryDir, { recursive: true })
+  }
+  const mapPath = nodePath.join(falconryDir, 'map.json')
+  fs.writeFileSync(mapPath, JSON.stringify(registry, null, 2), 'utf-8')
+  log.info(`Registry written to ${mapPath}`)
+
+  const elapsed = Date.now() - startTime
+  log.info(`Pipeline complete: ${registry.length} entries in ${elapsed}ms`)
+
+  return {
+    registry,
+    stats: {
+      fileTools: fileTools.length,
+      regTools: regTools.length,
+      depsEntries: Object.keys(deps).length,
+      merged: merged.length,
+      filtered: filtered.length,
+      registry: registry.length,
+      elapsed,
+    },
+  }
+}
+
+export interface PipelineStats {
+  fileTools: number
+  regTools: number
+  depsEntries: number
+  merged: number
+  filtered: number
+  registry: number
+  elapsed: number
+}

package/src/types.ts

@@ -0,0 +1,74 @@
+// @falconwry/creator — 核心类型定义
+// Scanner 包通过 creator 的导出引入
+
+/** Scanner 产出的原始工具条目（语言无关） */
+export type RawTool = {
+  name: string
+  src: string
+  startLine: number
+  endLine: number
+  code: string
+}
+
+/** AI Prompt 上下文，由 Scanner 提供 */
+export type PromptContext = {
+  projectType: string
+  toolConcept: string
+  categories: string[]
+  exampleTags: string[]
+}
+
+/** 分析后的工具条目（RawTool + AI/规则分析结果） */
+export type AnalyzedTool = RawTool & {
+  description: string
+  category: string
+  tags: string[]
+}
+
+/** 引用关系映射，key = `${src}:${name}` */
+export type DependentsMap = Record<string, {
+  count: number
+  list: string[]
+}>
+
+/** 基础注册表字段（所有语言通用） */
+export type BaseRegistry = {
+  name: string
+  description: string
+  src: string
+  startLine: number
+  endLine: number
+  category: string
+  tags: string[]
+  dependents: { count: number; list: string[] }
+}
+
+/** 前端 JS/TS/Vue 注册表扩展 */
+export type FrontendRegistry = BaseRegistry & {
+  exportName: string
+}
+
+/** 分析器接口 — V0.2 规则引擎，V0.3 替换为 AI */
+export interface Analyzer {
+  analyze(tools: RawTool[], context: PromptContext): Promise<AnalyzedTool[]>
+}
+
+/** 校验规则 — 类型由 creator 定义，值由各 Scanner 提供 */
+export type ValidationRules = {
+  description: { minLength: number; maxLength: number }
+  tags: { minCount: number; maxCount: number }
+  nameMatch: 'strict' | 'loose'
+  allowedCategories: string[]
+}
+
+/** Scanner 插件接口 */
+export interface Scanner {
+  name: string
+  scanFiles(projectRoot: string): RawTool[]
+  scanRegistrations(projectRoot: string): RawTool[]
+  scanDependencies(projectRoot: string): DependentsMap
+  buildRegistry(tools: AnalyzedTool[], deps: DependentsMap): BaseRegistry[]
+  getPromptContext(projectRoot: string): PromptContext
+  getValidationRules(): ValidationRules
+  validateTool(tool: AnalyzedTool, rules: ValidationRules): string[]
+}

package/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "types": ["node"]
+  },
+  "include": ["src"]
+}