@launch77/cli 1.2.0

package/src/modules/catalog/config/catalog-config.test.ts

@@ -0,0 +1,404 @@
+import { describe, test, expect } from 'vitest'
+
+import { validateConfig, getDefaultConfig } from './catalog-config.js'
+
+describe('validateConfig', () => {
+  describe('valid configurations', () => {
+    test('minimal valid config', () => {
+      const config = {
+        type: 'ui-components',
+        packageName: '@launch77/ui',
+      }
+      const result = validateConfig(config)
+      expect(result.type).toBe('ui-components')
+      expect(result.packageName).toBe('@launch77/ui')
+    })
+
+    test('full valid config', () => {
+      const config = {
+        type: 'ui-components',
+        packageName: '@launch77/ui',
+        sourceDir: './src',
+        componentsDir: './src/components',
+        exportsFile: './src/index.ts',
+        outputFile: 'catalog-ui-components.json',
+        catalogVersion: '0.1.0',
+        validation: {
+          strict: true,
+          requireCategory: true,
+          requireDescription: true,
+          minDescriptionLength: 20,
+          requireWhenToUse: true,
+          requireWhenNotToUse: true,
+          minTags: 3,
+        },
+      }
+      const result = validateConfig(config)
+      expect(result).toEqual(config)
+    })
+
+    test('various valid package names', () => {
+      expect(validateConfig({ type: 'ui-components', packageName: '@launch77/ui' })).toBeTruthy()
+      expect(validateConfig({ type: 'ui-components', packageName: '@my-company/components' })).toBeTruthy()
+      expect(validateConfig({ type: 'ui-components', packageName: '@org/lib' })).toBeTruthy()
+      expect(validateConfig({ type: 'ui-components', packageName: '@abc123/xyz789' })).toBeTruthy()
+    })
+
+    test('various valid catalog versions', () => {
+      expect(
+        validateConfig({
+          type: 'ui-components',
+          packageName: '@launch77/ui',
+          catalogVersion: '0.1.0',
+        })
+      ).toBeTruthy()
+      expect(
+        validateConfig({
+          type: 'ui-components',
+          packageName: '@launch77/ui',
+          catalogVersion: '1.0.0',
+        })
+      ).toBeTruthy()
+      expect(
+        validateConfig({
+          type: 'ui-components',
+          packageName: '@launch77/ui',
+          catalogVersion: '12.34.56',
+        })
+      ).toBeTruthy()
+    })
+  })
+
+  describe('defaults applied', () => {
+    test('applies default sourceDir', () => {
+      const config = {
+        type: 'ui-components',
+        packageName: '@launch77/ui',
+      }
+      const result = validateConfig(config)
+      expect(result.sourceDir).toBe('./src')
+    })
+
+    test('applies default componentsDir', () => {
+      const config = {
+        type: 'ui-components',
+        packageName: '@launch77/ui',
+      }
+      const result = validateConfig(config)
+      expect(result.componentsDir).toBe('./src/components')
+    })
+
+    test('applies default exportsFile', () => {
+      const config = {
+        type: 'ui-components',
+        packageName: '@launch77/ui',
+      }
+      const result = validateConfig(config)
+      expect(result.exportsFile).toBe('./src/index.ts')
+    })
+
+    test('applies default outputFile', () => {
+      const config = {
+        type: 'ui-components',
+        packageName: '@launch77/ui',
+      }
+      const result = validateConfig(config)
+      expect(result.outputFile).toBe('catalog-ui-components.json')
+    })
+
+    test('applies default catalogVersion', () => {
+      const config = {
+        type: 'ui-components',
+        packageName: '@launch77/ui',
+      }
+      const result = validateConfig(config)
+      expect(result.catalogVersion).toBe('0.1.0')
+    })
+
+    test('applies default validation config', () => {
+      const config = {
+        type: 'ui-components',
+        packageName: '@launch77/ui',
+      }
+      const result = validateConfig(config)
+      expect(result.validation).toEqual({
+        strict: true,
+        requireCategory: true,
+        requireDescription: true,
+        minDescriptionLength: 20,
+        requireWhenToUse: true,
+        requireWhenNotToUse: true,
+        minTags: 3,
+      })
+    })
+
+    test('partial validation config merges with defaults', () => {
+      const config = {
+        type: 'ui-components',
+        packageName: '@launch77/ui',
+        validation: {
+          strict: false,
+        },
+      }
+      const result = validateConfig(config)
+      expect(result.validation.strict).toBe(false)
+      expect(result.validation.requireCategory).toBe(true) // default
+    })
+  })
+
+  describe('invalid type', () => {
+    test('missing type', () => {
+      const config = {
+        packageName: '@launch77/ui',
+      }
+      expect(() => validateConfig(config)).toThrow('Invalid catalog configuration')
+    })
+
+    test('wrong type value', () => {
+      const config = {
+        type: 'server-functions',
+        packageName: '@launch77/ui',
+      }
+      expect(() => validateConfig(config)).toThrow('Type must be "ui-components"')
+    })
+
+    test('type is number', () => {
+      const config = {
+        type: 123,
+        packageName: '@launch77/ui',
+      }
+      expect(() => validateConfig(config)).toThrow()
+    })
+  })
+
+  describe('invalid packageName', () => {
+    test('missing packageName', () => {
+      const config = {
+        type: 'ui-components',
+      }
+      expect(() => validateConfig(config)).toThrow('Invalid catalog configuration')
+    })
+
+    test('no scope', () => {
+      const config = {
+        type: 'ui-components',
+        packageName: 'ui',
+      }
+      expect(() => validateConfig(config)).toThrow('Package name must match pattern')
+    })
+
+    test('missing package name after scope', () => {
+      const config = {
+        type: 'ui-components',
+        packageName: '@launch77/',
+      }
+      expect(() => validateConfig(config)).toThrow('Package name must match pattern')
+    })
+
+    test('uppercase letters', () => {
+      const config = {
+        type: 'ui-components',
+        packageName: '@Launch77/UI',
+      }
+      expect(() => validateConfig(config)).toThrow('Package name must match pattern')
+    })
+
+    test('spaces', () => {
+      const config = {
+        type: 'ui-components',
+        packageName: '@launch 77/ui',
+      }
+      expect(() => validateConfig(config)).toThrow('Package name must match pattern')
+    })
+
+    test('special characters', () => {
+      const config = {
+        type: 'ui-components',
+        packageName: '@launch77/ui!',
+      }
+      expect(() => validateConfig(config)).toThrow('Package name must match pattern')
+    })
+
+    test('multiple slashes', () => {
+      const config = {
+        type: 'ui-components',
+        packageName: '@launch77/ui/components',
+      }
+      expect(() => validateConfig(config)).toThrow('Package name must match pattern')
+    })
+  })
+
+  describe('invalid catalogVersion', () => {
+    test('not semantic version', () => {
+      const config = {
+        type: 'ui-components',
+        packageName: '@launch77/ui',
+        catalogVersion: 'v1.0',
+      }
+      expect(() => validateConfig(config)).toThrow('Catalog version must be semantic version')
+    })
+
+    test('with v prefix', () => {
+      const config = {
+        type: 'ui-components',
+        packageName: '@launch77/ui',
+        catalogVersion: 'v1.0.0',
+      }
+      expect(() => validateConfig(config)).toThrow('Catalog version must be semantic version')
+    })
+
+    test('missing patch', () => {
+      const config = {
+        type: 'ui-components',
+        packageName: '@launch77/ui',
+        catalogVersion: '1.0',
+      }
+      expect(() => validateConfig(config)).toThrow('Catalog version must be semantic version')
+    })
+
+    test('extra segments', () => {
+      const config = {
+        type: 'ui-components',
+        packageName: '@launch77/ui',
+        catalogVersion: '1.0.0.0',
+      }
+      expect(() => validateConfig(config)).toThrow('Catalog version must be semantic version')
+    })
+  })
+
+  describe('invalid validation config', () => {
+    test('strict is not boolean', () => {
+      const config = {
+        type: 'ui-components',
+        packageName: '@launch77/ui',
+        validation: {
+          strict: 'yes',
+        },
+      }
+      expect(() => validateConfig(config)).toThrow()
+    })
+
+    test('negative minDescriptionLength', () => {
+      const config = {
+        type: 'ui-components',
+        packageName: '@launch77/ui',
+        validation: {
+          minDescriptionLength: -1,
+        },
+      }
+      expect(() => validateConfig(config)).toThrow()
+    })
+
+    test('negative minTags', () => {
+      const config = {
+        type: 'ui-components',
+        packageName: '@launch77/ui',
+        validation: {
+          minTags: -5,
+        },
+      }
+      expect(() => validateConfig(config)).toThrow()
+    })
+  })
+
+  describe('error messages', () => {
+    test('provides clear field name in error', () => {
+      const config = {
+        type: 'ui-components',
+        packageName: 'invalid',
+      }
+      try {
+        validateConfig(config)
+        expect(true).toBe(false) // Should not reach here
+      } catch (error) {
+        expect((error as Error).message).toContain('packageName')
+      }
+    })
+
+    test('provides helpful message for invalid type', () => {
+      const config = {
+        type: 'wrong',
+        packageName: '@launch77/ui',
+      }
+      try {
+        validateConfig(config)
+        expect(true).toBe(false) // Should not reach here
+      } catch (error) {
+        expect((error as Error).message).toContain('ui-components')
+      }
+    })
+
+    test('multiple errors shown together', () => {
+      const config = {
+        type: 'wrong',
+        packageName: 'invalid',
+        catalogVersion: 'bad',
+      }
+      try {
+        validateConfig(config)
+        expect(true).toBe(false) // Should not reach here
+      } catch (error) {
+        expect((error as Error).message).toContain('type')
+        expect((error as Error).message).toContain('packageName')
+        expect((error as Error).message).toContain('catalogVersion')
+      }
+    })
+  })
+
+  describe('getDefaultConfig', () => {
+    test('returns default values', () => {
+      const defaults = getDefaultConfig()
+      expect(defaults.sourceDir).toBe('./src')
+      expect(defaults.componentsDir).toBe('./src/components')
+      expect(defaults.exportsFile).toBe('./src/index.ts')
+      expect(defaults.outputFile).toBe('catalog-ui-components.json')
+      expect(defaults.catalogVersion).toBe('0.1.0')
+    })
+
+    test('returns default validation config', () => {
+      const defaults = getDefaultConfig()
+      expect(defaults.validation).toEqual({
+        strict: true,
+        requireCategory: true,
+        requireDescription: true,
+        minDescriptionLength: 20,
+        requireWhenToUse: true,
+        requireWhenNotToUse: true,
+        minTags: 3,
+      })
+    })
+  })
+
+  describe('edge cases', () => {
+    test('null config', () => {
+      expect(() => validateConfig(null)).toThrow()
+    })
+
+    test('undefined config', () => {
+      expect(() => validateConfig(undefined)).toThrow()
+    })
+
+    test('empty object', () => {
+      expect(() => validateConfig({})).toThrow()
+    })
+
+    test('array instead of object', () => {
+      expect(() => validateConfig([])).toThrow()
+    })
+
+    test('string instead of object', () => {
+      expect(() => validateConfig('config')).toThrow()
+    })
+
+    test('extra fields are allowed', () => {
+      const config = {
+        type: 'ui-components',
+        packageName: '@launch77/ui',
+        extraField: 'ignored',
+      }
+      const result = validateConfig(config)
+      expect(result).toBeTruthy()
+      // Extra fields don't cause errors (passthrough mode)
+    })
+  })
+})

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

@@ -0,0 +1,130 @@
+/**
+ * Configuration system for catalog generation
+ */
+
+import path from 'path'
+import { pathToFileURL } from 'url'
+
+import fs from 'fs-extra'
+import { z } from 'zod'
+
+import type { CatalogConfig } from '../types/catalog-types.js'
+
+/**
+ * Zod schema for catalog configuration
+ * Provides runtime validation and type safety
+ */
+export const CatalogConfigSchema = z.object({
+  type: z.literal('ui-components'),
+  packageName: z.string().regex(/^@[a-z0-9-]+\/[a-z0-9-]+$/, 'Package name must match pattern @scope/name (e.g., @launch77/ui)'),
+  sourceDir: z.string().default('./src'),
+  componentsDir: z.string().default('./src/components'),
+  exportsFile: z.string().default('./src/index.ts'),
+  outputFile: z.string().default('catalog-ui-components.json'),
+  catalogVersion: z
+    .string()
+    .regex(/^\d+\.\d+\.\d+$/, 'Catalog version must be semantic version (e.g., 0.1.0)')
+    .default('0.1.0'),
+  validation: z
+    .object({
+      strict: z.boolean().default(true),
+      requireCategory: z.boolean().default(true),
+      requireDescription: z.boolean().default(true),
+      minDescriptionLength: z.number().min(0).default(20),
+      requireWhenToUse: z.boolean().default(true),
+      requireWhenNotToUse: z.boolean().default(true),
+      minTags: z.number().min(0).default(3),
+    })
+    .default({
+      strict: true,
+      requireCategory: true,
+      requireDescription: true,
+      minDescriptionLength: 20,
+      requireWhenToUse: true,
+      requireWhenNotToUse: true,
+      minTags: 3,
+    }),
+})
+
+/**
+ * Type helper to ensure CatalogConfig matches schema
+ */
+type InferredConfig = z.infer<typeof CatalogConfigSchema>
+
+// Ensure our type matches the Zod schema
+const _typeCheck: InferredConfig extends CatalogConfig ? true : false = true
+const _typeCheck2: CatalogConfig extends InferredConfig ? true : false = true
+
+/**
+ * Read catalog configuration from a library directory
+ *
+ * @param libraryPath - Absolute path to the library directory
+ * @returns Validated catalog configuration
+ * @throws Error if config file not found or invalid
+ */
+export async function readCatalogConfig(libraryPath: string): Promise<CatalogConfig> {
+  const configPath = path.join(libraryPath, 'catalog.config.js')
+
+  if (!(await fs.pathExists(configPath))) {
+    throw new Error(`Catalog config file not found: ${configPath}\n\n` + 'Create a catalog.config.js file in your library root with:\n' + 'export default {\n' + '  type: "ui-components",\n' + '  packageName: "@your-scope/your-package",\n' + '  ...\n' + '}')
+  }
+
+  try {
+    // Convert to file URL for ES module import
+    const fileUrl = pathToFileURL(configPath).href
+    const configModule = await import(fileUrl)
+    const config = configModule.default || configModule
+
+    return validateConfig(config)
+  } catch (error) {
+    if (error instanceof Error && error.message.includes('Cannot find module')) {
+      throw new Error(`Failed to import config file: ${configPath}\n${error.message}`)
+    }
+    throw error
+  }
+}
+
+/**
+ * Validate catalog configuration against schema
+ *
+ * @param config - Raw configuration object
+ * @returns Validated and typed configuration
+ * @throws Error with detailed validation errors if invalid
+ */
+export function validateConfig(config: unknown): CatalogConfig {
+  try {
+    return CatalogConfigSchema.parse(config)
+  } catch (error) {
+    if (error instanceof z.ZodError) {
+      const messages = error.issues.map((issue) => {
+        const field = issue.path.join('.')
+        return `  - ${field}: ${issue.message}`
+      })
+      throw new Error(`Invalid catalog configuration:\n\n${messages.join('\n')}\n`)
+    }
+    throw error
+  }
+}
+
+/**
+ * Get default configuration values
+ * Useful for documentation and testing
+ */
+export function getDefaultConfig(): Partial<CatalogConfig> {
+  return {
+    sourceDir: './src',
+    componentsDir: './src/components',
+    exportsFile: './src/index.ts',
+    outputFile: 'catalog-ui-components.json',
+    catalogVersion: '0.1.0',
+    validation: {
+      strict: true,
+      requireCategory: true,
+      requireDescription: true,
+      minDescriptionLength: 20,
+      requireWhenToUse: true,
+      requireWhenNotToUse: true,
+      minTags: 3,
+    },
+  }
+}

package/src/modules/catalog/index.ts

@@ -0,0 +1,9 @@
+/**
+ * Catalog Module
+ *
+ * Scans Launch77 artifacts and generates catalog.json for AI discovery
+ */
+
+export * from './commands/scan.js'
+export * from './commands/generate.js'
+export * from './services/catalog-svc.js'

package/src/modules/catalog/parsers/typescript-parser.ts

@@ -0,0 +1,93 @@
+import * as path from 'path'
+
+import fs from 'fs-extra'
+import * as ts from 'typescript'
+
+export interface PropInfo {
+  name: string
+  type?: string
+  required?: boolean
+}
+
+/**
+ * Extract prop names from a React component TypeScript file
+ * Looks for Props interfaces/types and exports
+ */
+export async function extractProps(filePath: string): Promise<string[]> {
+  try {
+    const content = await fs.readFile(filePath, 'utf-8')
+    const sourceFile = ts.createSourceFile(path.basename(filePath), content, ts.ScriptTarget.Latest, true)
+
+    const props: Set<string> = new Set()
+
+    // Visit all nodes in the AST
+    const visitor = (node: ts.Node): void => {
+      // Look for type/interface definitions with "Props" in the name
+      if (ts.isInterfaceDeclaration(node) || ts.isTypeAliasDeclaration(node)) {
+        const name = node.name.text
+        if (name.includes('Props')) {
+          extractPropsFromType(node, props)
+        }
+      }
+
+      ts.forEachChild(node, visitor)
+    }
+
+    visitor(sourceFile)
+
+    return Array.from(props)
+  } catch (error) {
+    // If parsing fails, return empty array
+    return []
+  }
+}
+
+function extractPropsFromType(node: ts.InterfaceDeclaration | ts.TypeAliasDeclaration, props: Set<string>) {
+  if (ts.isInterfaceDeclaration(node)) {
+    // Extract from interface members
+    node.members.forEach((member) => {
+      if (ts.isPropertySignature(member) && member.name && ts.isIdentifier(member.name)) {
+        props.add(member.name.text)
+      }
+    })
+  } else if (ts.isTypeAliasDeclaration(node)) {
+    // Extract from type alias
+    const typeNode = node.type
+    if (ts.isIntersectionTypeNode(typeNode)) {
+      // Handle intersection types (e.g., A & B & C)
+      typeNode.types.forEach((type) => {
+        if (ts.isTypeLiteralNode(type)) {
+          type.members.forEach((member) => {
+            if (ts.isPropertySignature(member) && member.name && ts.isIdentifier(member.name)) {
+              props.add(member.name.text)
+            }
+          })
+        }
+      })
+    } else if (ts.isTypeLiteralNode(typeNode)) {
+      // Handle type literal (e.g., { prop1: string })
+      typeNode.members.forEach((member) => {
+        if (ts.isPropertySignature(member) && member.name && ts.isIdentifier(member.name)) {
+          props.add(member.name.text)
+        }
+      })
+    }
+  }
+
+  // Add common HTML attributes that are usually inherited
+  const commonProps = ['className', 'style', 'children', 'onClick', 'onChange']
+  commonProps.forEach((prop) => props.add(prop))
+}
+
+/**
+ * Detect if a file is a React component
+ */
+export async function isReactComponent(filePath: string): Promise<boolean> {
+  try {
+    const content = await fs.readFile(filePath, 'utf-8')
+    // Simple heuristic: contains React import and JSX/TSX
+    return content.includes('import') && (content.includes('React') || content.includes("from 'react'")) && (filePath.endsWith('.tsx') || filePath.endsWith('.jsx'))
+  } catch {
+    return false
+  }
+}