@launch77/cli 1.2.0

package/src/modules/catalog/types/catalog-types.ts

@@ -0,0 +1,149 @@
+/**
+ * Shared types for the Launch77 catalog system
+ */
+
+// ============================================================================
+// Catalog File Structure
+// ============================================================================
+
+/**
+ * UI Component catalog structure
+ * Generated by individual component libraries during build
+ */
+export interface UiComponentCatalog {
+  $schema?: string
+  catalogType: 'ui-components'
+  catalogVersion: string
+  packageName: string
+  packageVersion: string
+  generatedAt: string
+  components: UiComponent[]
+}
+
+// ============================================================================
+// Component Metadata
+// ============================================================================
+
+/**
+ * Complete UI component metadata in catalog
+ */
+export interface UiComponent {
+  id: string
+  kind: 'ui_component'
+  name: string
+  packageName: string
+  category: string
+  description: string
+  tags: string[]
+  props?: string[]
+  sourcePath?: string
+  library?: string
+  guidance?: ComponentGuidance
+  example?: string
+  examples?: ComponentExamples
+}
+
+/**
+ * Component usage guidance
+ */
+export interface ComponentGuidance {
+  whenToUse: string
+  whenNotToUse: string
+}
+
+/**
+ * Component examples reference
+ */
+export interface ComponentExamples {
+  module: string
+  export: string
+  sourcePath: string
+}
+
+/**
+ * Component metadata extracted from JSDoc
+ */
+export interface ComponentMetadata {
+  description: string
+  category: string
+  whenToUse: string
+  whenNotToUse: string
+  tags: string[]
+  example: string
+  ignored: boolean
+  ignoreReason?: string
+}
+
+// ============================================================================
+// Validation
+// ============================================================================
+
+/**
+ * Validation result for a single component
+ */
+export interface ValidationResult {
+  valid: boolean
+  errors: string[]
+  warnings: string[]
+  componentName: string
+  filePath: string
+}
+
+/**
+ * Quality report for catalog generation
+ */
+export interface QualityReport {
+  totalComponents: number
+  withMetadata: number
+  missingMetadata: number
+  excluded: number
+  errors: ValidationResult[]
+  warnings: ValidationResult[]
+  qualityScore: number
+}
+
+// ============================================================================
+// Configuration
+// ============================================================================
+
+/**
+ * Catalog generation configuration
+ */
+export interface CatalogConfig {
+  type: 'ui-components'
+  packageName: string
+  sourceDir: string
+  componentsDir: string
+  exportsFile: string
+  outputFile: string
+  catalogVersion: string
+  validation: ValidationConfig
+}
+
+/**
+ * Validation rules configuration
+ */
+export interface ValidationConfig {
+  strict: boolean
+  requireCategory: boolean
+  requireDescription: boolean
+  minDescriptionLength: number
+  requireWhenToUse: boolean
+  requireWhenNotToUse: boolean
+  minTags: number
+}
+
+// ============================================================================
+// Generation Results
+// ============================================================================
+
+/**
+ * Result of catalog generation
+ */
+export interface GenerationResult {
+  success: boolean
+  catalogFile: string
+  qualityReport: QualityReport
+  errors: ValidationResult[]
+  warnings: ValidationResult[]
+}

package/src/modules/catalog/utils/examples-generator.ts

@@ -0,0 +1,68 @@
+import * as path from 'path'
+
+import fs from 'fs-extra'
+
+import type { UiComponent } from '../types/catalog-types.js'
+
+/**
+ * Generate examples.generated.ts files for each library that has components with examples
+ */
+export async function generateExamplesFiles(components: UiComponent[], launch77Root: string): Promise<void> {
+  // Group components by package
+  const componentsByPackage = new Map<string, UiComponent[]>()
+
+  for (const component of components) {
+    if (component.examples) {
+      const existing = componentsByPackage.get(component.packageName) || []
+      existing.push(component)
+      componentsByPackage.set(component.packageName, existing)
+    }
+  }
+
+  // Generate examples file for each package
+  for (const [packageName, packageComponents] of componentsByPackage) {
+    // Determine library path based on package name
+    // Extract library name from scoped package (e.g., @launch77/ui -> ui)
+    const libraryName = packageName.split('/').pop() || packageName
+    const libraryPath = path.join(launch77Root, 'libraries', libraryName)
+    const examplesFilePath = path.join(libraryPath, 'src', 'examples.generated.ts')
+
+    // Generate content
+    const content = generateExamplesContent(packageComponents, libraryName)
+
+    // Write file
+    await fs.writeFile(examplesFilePath, content, 'utf-8')
+
+    console.log(`  ✓ Generated ${packageName}/examples`)
+  }
+}
+
+function generateExamplesContent(components: UiComponent[], _libraryName: string): string {
+  const lines: string[] = ['// AUTO-GENERATED by launch77 scan - DO NOT EDIT', "// This file is automatically generated when running 'launch77 scan'", '// To add new examples, create a ComponentName.examples.tsx file next to your component', '']
+
+  // Sort components alphabetically for deterministic output
+  const sortedComponents = [...components].sort((a, b) => a.name.localeCompare(b.name))
+
+  // Add export statements
+  for (const component of sortedComponents) {
+    if (component.examples && component.examples.sourcePath) {
+      // Extract relative path from sourcePath
+      // e.g., "launch77/libraries/ui/src/components/Button/Button.examples.tsx"
+      // becomes "./components/Button/Button.examples"
+      const sourcePath = component.examples.sourcePath
+      const srcIndex = sourcePath.indexOf('/src/')
+      if (srcIndex !== -1) {
+        const relativePath = sourcePath
+          .substring(srcIndex + 5) // Skip "/src/"
+          .replace(/\.tsx$/, '') // Remove extension
+
+        // Export structured examples using ComponentNameExamples convention
+        // e.g., Button -> ButtonExamples, CTAButton -> CTAButtonExamples
+        const structuredExportName = `${component.name}Examples`
+        lines.push(`export { ${structuredExportName} } from './${relativePath}'`)
+      }
+    }
+  }
+
+  return lines.join('\n') + '\n'
+}

package/src/modules/catalog/utils/quality-reporter.ts

@@ -0,0 +1,76 @@
+/**
+ * Generate and display catalog quality reports
+ */
+
+import chalk from 'chalk'
+
+import type { ValidationResult, QualityReport } from '../types/catalog-types.js'
+
+/**
+ * Generate quality report from validation results
+ */
+export function generateQualityReport(totalScanned: number, excluded: number, validations: ValidationResult[]): QualityReport {
+  const errors = validations.filter((v) => !v.valid)
+  const withMetadata = validations.filter((v) => v.valid)
+
+  const qualityScore = totalScanned > 0 ? Math.round((withMetadata.length / totalScanned) * 100) : 100
+
+  return {
+    totalComponents: totalScanned,
+    withMetadata: withMetadata.length,
+    missingMetadata: errors.length,
+    excluded,
+    errors,
+    warnings: validations.filter((v) => v.warnings.length > 0),
+    qualityScore,
+  }
+}
+
+/**
+ * Print quality report to console
+ */
+export function printQualityReport(report: QualityReport, strict: boolean): void {
+  console.log(chalk.blue('\n📊 Catalog Quality Report\n'))
+  console.log(chalk.gray(`  Total components scanned: ${report.totalComponents}`))
+  console.log(chalk.green(`  ✓ With metadata: ${report.withMetadata} (${report.qualityScore}%)`))
+
+  if (report.missingMetadata > 0) {
+    console.log(chalk.red(`  ✗ Missing metadata: ${report.missingMetadata}`))
+  }
+
+  if (report.excluded > 0) {
+    console.log(chalk.gray(`  ℹ Excluded: ${report.excluded}`))
+  }
+
+  // Show errors
+  if (report.errors.length > 0) {
+    console.log(chalk.red('\n  ❌ Components missing metadata:\n'))
+    report.errors.forEach((err) => {
+      console.log(chalk.red(`    - ${err.componentName}`))
+      console.log(chalk.gray(`      ${err.filePath}`))
+      err.errors.forEach((e) => console.log(chalk.gray(`      • ${e}`)))
+    })
+  }
+
+  // Show warnings (limit to 5)
+  if (report.warnings.length > 0 && !strict) {
+    console.log(chalk.yellow('\n  ⚠️  Metadata warnings:\n'))
+    report.warnings.slice(0, 5).forEach((warn) => {
+      console.log(chalk.yellow(`    - ${warn.componentName}`))
+      warn.warnings.forEach((w) => console.log(chalk.gray(`      • ${w}`)))
+    })
+    if (report.warnings.length > 5) {
+      console.log(chalk.gray(`\n    ... and ${report.warnings.length - 5} more`))
+    }
+  }
+
+  console.log()
+
+  // Help message if there are errors
+  if (report.errors.length > 0) {
+    console.log(chalk.blue('💡 To fix:\n'))
+    console.log(chalk.gray('  • Add @launch77-component JSDoc to public components'))
+    console.log(chalk.gray('  • Add @launch77-ignore to exclude internal components'))
+    console.log(chalk.gray('  • See: launch77/docs/CATALOG_METADATA_GUIDE.md\n'))
+  }
+}

package/src/modules/catalog/validators/component-name-validator.test.ts

@@ -0,0 +1,233 @@
+import { describe, test, expect } from 'vitest'
+
+import { validateComponentName } from './component-name-validator.js'
+
+describe('validateComponentName', () => {
+  describe('valid names', () => {
+    test('single word PascalCase', () => {
+      expect(validateComponentName('Button').valid).toBe(true)
+      expect(validateComponentName('Alert').valid).toBe(true)
+      expect(validateComponentName('Input').valid).toBe(true)
+    })
+
+    test('multi-word PascalCase', () => {
+      expect(validateComponentName('AlertDialog').valid).toBe(true)
+      expect(validateComponentName('FormField').valid).toBe(true)
+      expect(validateComponentName('NavigationMenu').valid).toBe(true)
+    })
+
+    test('with numbers', () => {
+      expect(validateComponentName('Button2').valid).toBe(true)
+      expect(validateComponentName('Alert3D').valid).toBe(true)
+      expect(validateComponentName('H1').valid).toBe(true)
+      expect(validateComponentName('Input123').valid).toBe(true)
+    })
+
+    test('common abbreviations', () => {
+      expect(validateComponentName('HTTPClient').valid).toBe(true)
+      expect(validateComponentName('URLInput').valid).toBe(true)
+      expect(validateComponentName('APIKey').valid).toBe(true)
+    })
+
+    test('long valid names', () => {
+      const name50 = 'A'.repeat(50)
+      expect(validateComponentName(name50).valid).toBe(true)
+    })
+  })
+
+  describe('invalid names - symbols and special characters', () => {
+    test('special symbols', () => {
+      const result1 = validateComponentName('===')
+      expect(result1.valid).toBe(false)
+      expect(result1.errors[0]).toContain('PascalCase')
+
+      const result2 = validateComponentName('!!!')
+      expect(result2.valid).toBe(false)
+
+      const result3 = validateComponentName('@@@')
+      expect(result3.valid).toBe(false)
+    })
+
+    test('with special characters', () => {
+      const result1 = validateComponentName('Button$')
+      expect(result1.valid).toBe(false)
+      expect(result1.errors[0]).toContain('PascalCase')
+
+      const result2 = validateComponentName('Alert#Icon')
+      expect(result2.valid).toBe(false)
+
+      const result3 = validateComponentName('Form_Field')
+      expect(result3.valid).toBe(false)
+    })
+
+    test('with hyphens', () => {
+      const result = validateComponentName('Alert-Dialog')
+      expect(result.valid).toBe(false)
+      expect(result.errors[0]).toContain('PascalCase')
+    })
+
+    test('with spaces', () => {
+      const result1 = validateComponentName('My Button')
+      expect(result1.valid).toBe(false)
+
+      const result2 = validateComponentName('Alert Dialog')
+      expect(result2.valid).toBe(false)
+
+      const result3 = validateComponentName(' Button')
+      expect(result3.valid).toBe(false)
+    })
+
+    test('with dots', () => {
+      const result = validateComponentName('Button.Icon')
+      expect(result.valid).toBe(false)
+      expect(result.errors[0]).toContain('PascalCase')
+    })
+  })
+
+  describe('invalid names - casing', () => {
+    test('lowercase', () => {
+      const result = validateComponentName('button')
+      expect(result.valid).toBe(false)
+      expect(result.errors[0]).toContain('PascalCase')
+    })
+
+    test('camelCase', () => {
+      const result = validateComponentName('alertDialog')
+      expect(result.valid).toBe(false)
+      expect(result.errors[0]).toContain('PascalCase')
+    })
+
+    test('snake_case', () => {
+      const result = validateComponentName('alert_dialog')
+      expect(result.valid).toBe(false)
+      expect(result.errors[0]).toContain('PascalCase')
+    })
+
+    test('SCREAMING_SNAKE_CASE', () => {
+      const result = validateComponentName('ALERT_DIALOG')
+      expect(result.valid).toBe(false)
+      expect(result.errors[0]).toContain('PascalCase')
+    })
+
+    test('kebab-case', () => {
+      const result = validateComponentName('alert-dialog')
+      expect(result.valid).toBe(false)
+      expect(result.errors[0]).toContain('PascalCase')
+    })
+  })
+
+  describe('invalid names - numbers', () => {
+    test('only numbers', () => {
+      const result = validateComponentName('123')
+      expect(result.valid).toBe(false)
+      expect(result.errors[0]).toContain('PascalCase')
+    })
+
+    test('starting with number', () => {
+      const result = validateComponentName('3DButton')
+      expect(result.valid).toBe(false)
+      expect(result.errors[0]).toContain('PascalCase')
+    })
+  })
+
+  describe('invalid names - empty and length', () => {
+    test('empty string', () => {
+      const result = validateComponentName('')
+      expect(result.valid).toBe(false)
+      expect(result.errors[0]).toContain('cannot be empty')
+    })
+
+    test('exceeds maximum length', () => {
+      const name51 = 'A'.repeat(51)
+      const result = validateComponentName(name51)
+      expect(result.valid).toBe(false)
+      expect(result.errors[0]).toContain('maximum length')
+      expect(result.errors[0]).toContain('50')
+    })
+
+    test('very long name', () => {
+      const name100 = 'A'.repeat(100)
+      const result = validateComponentName(name100)
+      expect(result.valid).toBe(false)
+      expect(result.errors[0]).toContain('maximum length')
+    })
+  })
+
+  describe('multiple errors', () => {
+    test('empty string has one error', () => {
+      const result = validateComponentName('')
+      expect(result.errors.length).toBeGreaterThan(0)
+    })
+
+    test('lowercase name has error', () => {
+      const result = validateComponentName('button')
+      expect(result.errors.length).toBeGreaterThanOrEqual(1)
+      expect(result.errors[0]).toContain('PascalCase')
+    })
+
+    test('symbol-only name has error', () => {
+      const result = validateComponentName('$$$')
+      expect(result.valid).toBe(false)
+      expect(result.errors.length).toBeGreaterThan(0)
+    })
+  })
+
+  describe('edge cases', () => {
+    test('single letter uppercase', () => {
+      expect(validateComponentName('A').valid).toBe(true)
+      expect(validateComponentName('Z').valid).toBe(true)
+    })
+
+    test('exactly 50 characters', () => {
+      const name = 'A'.repeat(50)
+      expect(validateComponentName(name).valid).toBe(true)
+    })
+
+    test('51 characters', () => {
+      const name = 'A'.repeat(51)
+      expect(validateComponentName(name).valid).toBe(false)
+    })
+
+    test('unicode characters', () => {
+      const result = validateComponentName('Buttoné')
+      expect(result.valid).toBe(false)
+      expect(result.errors[0]).toContain('PascalCase')
+    })
+
+    test('emoji', () => {
+      const result = validateComponentName('Button😀')
+      expect(result.valid).toBe(false)
+      expect(result.errors[0]).toContain('PascalCase')
+    })
+  })
+
+  describe('common real-world component names', () => {
+    test('UI library components', () => {
+      expect(validateComponentName('Dialog').valid).toBe(true)
+      expect(validateComponentName('Popover').valid).toBe(true)
+      expect(validateComponentName('Tooltip').valid).toBe(true)
+      expect(validateComponentName('Select').valid).toBe(true)
+      expect(validateComponentName('Checkbox').valid).toBe(true)
+      expect(validateComponentName('RadioGroup').valid).toBe(true)
+      expect(validateComponentName('Accordion').valid).toBe(true)
+      expect(validateComponentName('Tabs').valid).toBe(true)
+      expect(validateComponentName('Card').valid).toBe(true)
+      expect(validateComponentName('Badge').valid).toBe(true)
+    })
+
+    test('form components', () => {
+      expect(validateComponentName('FormField').valid).toBe(true)
+      expect(validateComponentName('FormError').valid).toBe(true)
+      expect(validateComponentName('FormHelperText').valid).toBe(true)
+      expect(validateComponentName('TextField').valid).toBe(true)
+      expect(validateComponentName('TextArea').valid).toBe(true)
+    })
+
+    test('navigation components', () => {
+      expect(validateComponentName('Navbar').valid).toBe(true)
+      expect(validateComponentName('Sidebar').valid).toBe(true)
+      expect(validateComponentName('Breadcrumbs').valid).toBe(true)
+      expect(validateComponentName('NavigationMenu').valid).toBe(true)
+    })
+  })
+})

package/src/modules/catalog/validators/component-name-validator.ts

@@ -0,0 +1,43 @@
+/**
+ * Validate component names for Launch77 catalog
+ */
+
+const VALID_COMPONENT_NAME = /^[A-Z][a-zA-Z0-9]*$/
+const MAX_COMPONENT_NAME_LENGTH = 50
+
+export interface ComponentNameValidation {
+  valid: boolean
+  errors: string[]
+}
+
+/**
+ * Validate a component name against Launch77 naming conventions
+ *
+ * Rules:
+ * - Must start with uppercase letter (A-Z)
+ * - Only alphanumeric characters (no symbols, spaces, or special characters)
+ * - Maximum 50 characters
+ *
+ * @param name - Component name to validate
+ * @returns Validation result with errors if invalid
+ */
+export function validateComponentName(name: string): ComponentNameValidation {
+  const errors: string[] = []
+
+  if (!name || name.length === 0) {
+    errors.push('Component name cannot be empty')
+  }
+
+  if (name.length > MAX_COMPONENT_NAME_LENGTH) {
+    errors.push(`Component name exceeds maximum length of ${MAX_COMPONENT_NAME_LENGTH} characters`)
+  }
+
+  if (!VALID_COMPONENT_NAME.test(name)) {
+    errors.push('Component name must be PascalCase (start with uppercase letter A-Z, alphanumeric only)')
+  }
+
+  return {
+    valid: errors.length === 0,
+    errors,
+  }
+}