@launch77/cli 1.2.0

package/src/modules/catalog/scanners/metadata-extractor.ts

@@ -0,0 +1,134 @@
+/**
+ * Extract Launch77 metadata from JSDoc comments in source files
+ */
+
+import fs from 'fs-extra'
+
+import type { ComponentMetadata } from '../types/catalog-types.js'
+
+/**
+ * Extract metadata from a component source file
+ * Looks for @launch77-component JSDoc tag and extracts metadata fields
+ */
+export async function extractComponentMetadata(filePath: string): Promise<ComponentMetadata> {
+  try {
+    const content = await fs.readFile(filePath, 'utf-8')
+
+    // Check for @launch77-ignore tag first
+    const ignoreRegex = /\/\*\*[\s\S]*?@launch77-ignore[\s\S]*?\*\//
+    const ignoreMatch = content.match(ignoreRegex)
+
+    if (ignoreMatch) {
+      const reason = extractField(ignoreMatch[0], 'reason')
+      return {
+        description: '',
+        category: '',
+        whenToUse: '',
+        whenNotToUse: '',
+        tags: [],
+        example: '',
+        ignored: true,
+        ignoreReason: reason || 'Excluded from catalog',
+      }
+    }
+
+    // Look for JSDoc comment with @launch77-component marker
+    const jsdocRegex = /\/\*\*[\s\S]*?@launch77-component[\s\S]*?\*\//
+
+    const match = content.match(jsdocRegex)
+    if (!match) {
+      // No Launch77 metadata found - return empty
+      return {
+        description: '',
+        category: '',
+        whenToUse: '',
+        whenNotToUse: '',
+        tags: [],
+        example: '',
+        ignored: false,
+      }
+    }
+
+    const jsdoc = match[0]
+
+    // Extract individual fields
+    const description = extractField(jsdoc, 'description')
+    const category = extractField(jsdoc, 'category')
+    const whenToUse = extractField(jsdoc, 'whenToUse')
+    const whenNotToUse = extractField(jsdoc, 'whenNotToUse')
+    const tags = extractTags(jsdoc)
+    const example = extractExample(jsdoc)
+
+    return {
+      description,
+      category,
+      whenToUse,
+      whenNotToUse,
+      tags,
+      example,
+      ignored: false,
+    }
+  } catch (error) {
+    // If we can't read the file or parse fails, return empty metadata
+    // This ensures the scan doesn't fail if metadata is missing
+    return {
+      description: '',
+      category: '',
+      whenToUse: '',
+      whenNotToUse: '',
+      tags: [],
+      example: '',
+      ignored: false,
+    }
+  }
+}
+
+/**
+ * Extract a single-line field from JSDoc
+ * Format: @fieldName value here until end of line
+ */
+function extractField(jsdoc: string, fieldName: string): string {
+  const regex = new RegExp(`@${fieldName}\\s+(.+?)(?=\\n|\\*\\/|@)`, 's')
+  const match = jsdoc.match(regex)
+  if (!match) return ''
+
+  // Clean up the value: remove extra whitespace, asterisks from line breaks
+  return match[1]
+    .split('\n')
+    .map((line) => line.replace(/^\s*\*\s?/, '').trim())
+    .filter((line) => line.length > 0)
+    .join(' ')
+    .trim()
+}
+
+/**
+ * Extract tags (comma or space separated)
+ * Format: @tags tag1, tag2, tag3
+ */
+function extractTags(jsdoc: string): string[] {
+  const tagsString = extractField(jsdoc, 'tags')
+  if (!tagsString) return []
+
+  // Split by comma or whitespace, clean up
+  return tagsString
+    .split(/[,\s]+/)
+    .map((tag) => tag.trim())
+    .filter((tag) => tag.length > 0)
+}
+
+/**
+ * Extract example code block
+ * Format: @example followed by code until next @ tag or end of comment
+ */
+function extractExample(jsdoc: string): string {
+  const regex = /@example\s+([\s\S]+?)(?=@|\*\/)/
+  const match = jsdoc.match(regex)
+  if (!match) return ''
+
+  // Clean up the example: remove leading asterisks and extra whitespace
+  return match[1]
+    .split('\n')
+    .map((line) => line.replace(/^\s*\*\s?/, ''))
+    .join('\n')
+    .trim()
+}

package/src/modules/catalog/scanners/metadata-validator.ts

@@ -0,0 +1,67 @@
+/**
+ * Validate Launch77 component metadata for quality and completeness
+ */
+
+import type { ComponentMetadata, ValidationResult } from '../types/catalog-types.js'
+
+/**
+ * Validate component metadata against Launch77 quality standards
+ */
+// Valid category values for UI components
+const VALID_CATEGORIES: readonly string[] = ['actions', 'forms', 'feedback', 'layout', 'marketing', 'typography', 'infrastructure', 'compliance']
+
+export function validateMetadata(metadata: ComponentMetadata, componentName: string, filePath: string): ValidationResult {
+  const errors: string[] = []
+  const warnings: string[] = []
+
+  // REQUIRED: @launch77-component tag (indicated by non-empty description)
+  if (!metadata.description) {
+    errors.push('Missing @launch77-component tag')
+  }
+
+  // REQUIRED: @category tag
+  if (!metadata.category) {
+    errors.push('Missing @category tag (required)')
+  } else if (!VALID_CATEGORIES.includes(metadata.category)) {
+    errors.push(`Invalid category "${metadata.category}". Must be one of: ${VALID_CATEGORIES.join(', ')}`)
+  }
+
+  // Check description quality
+  if (metadata.description && metadata.description.length < 20) {
+    warnings.push('Description is too short (< 20 characters)')
+  }
+
+  // Check for generic descriptions
+  if (metadata.description && /^[A-Z][a-z]+ component$/.test(metadata.description)) {
+    warnings.push(`Generic description detected: "${metadata.description}"`)
+  }
+
+  // RECOMMENDED: Guidance fields
+  if (!metadata.whenToUse) {
+    warnings.push('Missing @whenToUse guidance')
+  }
+
+  if (!metadata.whenNotToUse) {
+    warnings.push('Missing @whenNotToUse guidance')
+  }
+
+  // RECOMMENDED: Tags
+  if (metadata.tags.length === 0) {
+    warnings.push('Missing @tags')
+  } else if (metadata.tags.length < 3) {
+    warnings.push('Too few tags (< 3 recommended)')
+  }
+
+  // RECOMMENDED: Example code
+  if (!metadata.example) {
+    warnings.push('Missing @example code')
+  }
+
+  return {
+    valid: errors.length === 0,
+    errors,
+    warnings,
+    componentName,
+    filePath,
+  }
+}

package/src/modules/catalog/scanners/ui-component-scanner.ts

@@ -0,0 +1,185 @@
+import * as path from 'path'
+
+import fs from 'fs-extra'
+
+import { extractComponentMetadata } from './metadata-extractor.js'
+import { validateMetadata } from './metadata-validator.js'
+import { extractProps, isReactComponent } from '../parsers/typescript-parser.js'
+import { validateComponentName } from '../validators/component-name-validator.js'
+
+import type { UiComponent, ValidationResult } from '../types/catalog-types.js'
+
+export interface ScanResult {
+  components: UiComponent[]
+  validations: ValidationResult[]
+  excluded: number
+}
+
+/**
+ * Scan a UI library package for components
+ */
+export async function scanUILibrary(libraryPath: string, packageName: string): Promise<ScanResult> {
+  const components: UiComponent[] = []
+  const validations: ValidationResult[] = []
+  let excluded = 0
+
+  // Read the main index file to find exports
+  const indexPath = path.join(libraryPath, 'src/index.ts')
+  if (!(await fs.pathExists(indexPath))) {
+    return { components, validations, excluded }
+  }
+
+  const indexContent = await fs.readFile(indexPath, 'utf-8')
+
+  // Parse exports: export * from './components/Button'
+  const exportRegex = /export\s+\*\s+from\s+['"](\.\/[^'"]+)['"]/g
+  const exports: string[] = []
+
+  let match
+  while ((match = exportRegex.exec(indexContent)) !== null) {
+    exports.push(match[1])
+  }
+
+  // Also parse: export { Button } from './components/Button'
+  const namedExportRegex = /export\s+\{([^}]+)\}\s+from\s+['"](\.\/[^'"]+)['"]/g
+  while ((match = namedExportRegex.exec(indexContent)) !== null) {
+    exports.push(match[2])
+  }
+
+  // Scan each export path
+  for (const exportPath of exports) {
+    const fullPath = path.join(libraryPath, 'src', exportPath.replace('./', ''))
+
+    // Check if it's a directory with index.ts or a .tsx file
+    let componentFile: string | undefined
+
+    if (await fs.pathExists(fullPath + '.tsx')) {
+      componentFile = fullPath + '.tsx'
+    } else if (await fs.pathExists(fullPath + '.ts')) {
+      componentFile = fullPath + '.ts'
+    } else if (await fs.pathExists(path.join(fullPath, 'index.ts'))) {
+      // It's a directory, find the main component file
+      const files = await fs.readdir(fullPath)
+      const mainFile = files.find((f) => f.endsWith('.tsx') && !f.includes('.test.') && !f.includes('.stories.') && !f.includes('.examples.'))
+      if (mainFile) {
+        componentFile = path.join(fullPath, mainFile)
+      }
+    }
+
+    if (componentFile && (await isReactComponent(componentFile))) {
+      const result = await scanComponent(componentFile, packageName, libraryPath)
+      if (result) {
+        if (result.excluded) {
+          excluded++
+        } else {
+          components.push(result.component)
+          validations.push(result.validation)
+        }
+      }
+    }
+  }
+
+  return { components, validations, excluded }
+}
+
+interface ComponentScanResult {
+  component: UiComponent
+  validation: ValidationResult
+  excluded: boolean
+}
+
+async function scanComponent(filePath: string, packageName: string, libraryRoot: string): Promise<ComponentScanResult | null> {
+  try {
+    // Extract component name from filename
+    const fileName = path.basename(filePath, path.extname(filePath))
+    const componentName = fileName
+
+    // Validate component name
+    const nameValidation = validateComponentName(componentName)
+    if (!nameValidation.valid) {
+      console.warn(`Skipping ${filePath}: Invalid component name - ${nameValidation.errors.join(', ')}`)
+      return null
+    }
+
+    // Calculate source path relative to repo root for validation
+    const sourcePath = path.relative(path.join(libraryRoot, '../../..'), filePath)
+
+    // Extract metadata from JSDoc (Launch77-specific)
+    const metadata = await extractComponentMetadata(filePath)
+
+    // Check if component is excluded via @launch77-ignore
+    if (metadata.ignored) {
+      // Return excluded marker - no validation needed for ignored components
+      return {
+        component: {} as UiComponent, // Won't be used, but satisfies type
+        validation: { valid: true, errors: [], warnings: [], componentName: '', filePath: '' },
+        excluded: true,
+      }
+    }
+
+    // Validate metadata (all non-ignored components must have @launch77-component and @category)
+    const validation = validateMetadata(metadata, componentName, sourcePath)
+
+    // Use category from metadata - validation ensures it exists and is valid
+    const category = metadata.category
+
+    // Extract props
+    const props = await extractProps(filePath)
+
+    // Use metadata description - validation ensures it exists
+    const description: string = metadata.description
+
+    // Generate ID
+    const id = `${packageName}#${componentName}`
+
+    // Use explicit tags from metadata only (no auto-generation)
+    const tags = metadata.tags
+
+    // Build guidance object if we have both fields
+    const guidance =
+      metadata.whenToUse && metadata.whenNotToUse
+        ? {
+            whenToUse: metadata.whenToUse,
+            whenNotToUse: metadata.whenNotToUse,
+          }
+        : undefined
+
+    // Check for examples file
+    let examples: UiComponent['examples'] | undefined
+    const examplesPath = filePath.replace(/\.tsx?$/, '.examples.tsx')
+    if (await fs.pathExists(examplesPath)) {
+      // Calculate examples source path relative to repo root
+      const examplesSourcePath = path.relative(path.join(libraryRoot, '../../..'), examplesPath)
+      examples = {
+        module: `${packageName}/examples`,
+        export: `${componentName}Examples`,
+        sourcePath: examplesSourcePath,
+      }
+    }
+
+    const component: UiComponent = {
+      id,
+      kind: 'ui_component',
+      name: componentName,
+      packageName,
+      category,
+      description,
+      tags,
+      props: props.length > 0 ? props : undefined,
+      sourcePath,
+      library: packageName, // Link component to its library
+      guidance,
+      example: metadata.example || undefined,
+      examples,
+    }
+
+    return {
+      component,
+      validation,
+      excluded: false,
+    }
+  } catch (error) {
+    console.error(`Error scanning component ${filePath}:`, error)
+    return null
+  }
+}

package/src/modules/catalog/schemas/catalog-ui-components.schema.json

@@ -0,0 +1,145 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://launch77.io/schemas/catalog-ui-components.schema.json",
+  "title": "Launch77 UI Components Catalog",
+  "description": "Catalog metadata for UI component libraries. Generated during library build and consumed by Launch77 platform for component discovery.",
+  "type": "object",
+  "required": ["catalogType", "catalogVersion", "packageName", "packageVersion", "generatedAt", "components"],
+  "additionalProperties": false,
+  "properties": {
+    "catalogType": {
+      "type": "string",
+      "const": "ui-components",
+      "description": "Type of catalog - identifies this as a UI components catalog"
+    },
+    "catalogVersion": {
+      "type": "string",
+      "pattern": "^\\d+\\.\\d+\\.\\d+$",
+      "description": "Semantic version of the catalog schema (e.g., 0.1.0)"
+    },
+    "packageName": {
+      "type": "string",
+      "pattern": "^@[a-z0-9-]+/[a-z0-9-]+$",
+      "description": "NPM package name (e.g., @launch77/ui)"
+    },
+    "packageVersion": {
+      "type": "string",
+      "description": "Version of the package containing these components"
+    },
+    "generatedAt": {
+      "type": "string",
+      "format": "date-time",
+      "description": "ISO 8601 timestamp when catalog was generated"
+    },
+    "components": {
+      "type": "array",
+      "description": "Array of UI component metadata",
+      "items": {
+        "$ref": "#/definitions/UiComponent"
+      }
+    }
+  },
+  "definitions": {
+    "UiComponent": {
+      "type": "object",
+      "description": "Metadata for a single UI component",
+      "required": ["id", "kind", "name", "packageName", "category", "description", "tags"],
+      "additionalProperties": false,
+      "properties": {
+        "id": {
+          "type": "string",
+          "pattern": "^@[a-z0-9-]+/[a-z0-9-]+#[A-Z][a-zA-Z0-9]*$",
+          "description": "Unique identifier: packageName#ComponentName (e.g., @launch77/ui#Button)"
+        },
+        "kind": {
+          "type": "string",
+          "const": "ui_component",
+          "description": "Component kind - always 'ui_component' for UI components"
+        },
+        "name": {
+          "type": "string",
+          "pattern": "^[A-Z][a-zA-Z0-9]*$",
+          "description": "Component name in PascalCase (e.g., Button, AlertDialog)"
+        },
+        "packageName": {
+          "type": "string",
+          "pattern": "^@[a-z0-9-]+/[a-z0-9-]+$",
+          "description": "NPM package containing this component"
+        },
+        "category": {
+          "type": "string",
+          "enum": ["actions", "forms", "feedback", "layout", "marketing", "typography", "infrastructure", "compliance"],
+          "description": "Component category for organization and discovery"
+        },
+        "description": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Human-readable description of the component"
+        },
+        "tags": {
+          "type": "array",
+          "description": "Search tags for component discovery",
+          "items": {
+            "type": "string",
+            "minLength": 1
+          },
+          "minItems": 1
+        },
+        "props": {
+          "type": "array",
+          "description": "Component props (optional - extracted from TypeScript)",
+          "items": {
+            "type": "string"
+          }
+        },
+        "sourcePath": {
+          "type": "string",
+          "description": "Relative path to component source file from repository root (optional)"
+        },
+        "library": {
+          "type": "string",
+          "description": "Parent library package name (optional - typically same as packageName)"
+        },
+        "guidance": {
+          "type": "object",
+          "description": "Usage guidance for the component (optional)",
+          "additionalProperties": false,
+          "properties": {
+            "whenToUse": {
+              "type": "string",
+              "description": "When to use this component"
+            },
+            "whenNotToUse": {
+              "type": "string",
+              "description": "When NOT to use this component (anti-patterns)"
+            }
+          }
+        },
+        "example": {
+          "type": "string",
+          "description": "Code example showing component usage (optional)"
+        },
+        "examples": {
+          "type": "object",
+          "description": "Reference to examples module (optional)",
+          "required": ["module", "export", "sourcePath"],
+          "additionalProperties": false,
+          "properties": {
+            "module": {
+              "type": "string",
+              "description": "Module path to import examples (e.g., @launch77/ui/examples)"
+            },
+            "export": {
+              "type": "string",
+              "description": "Export name for examples (e.g., ButtonExamples)"
+            },
+            "sourcePath": {
+              "type": "string",
+              "description": "Relative path to examples source file from repository root"
+            }
+          }
+        }
+      }
+    }
+  }
+}