Initial commit: ClaudeForge v1.0.0

skill/generator.py

@@ -0,0 +1,480 @@
+"""
+CLAUDE.md Content Generator
+
+Generates new CLAUDE.md files or enhances existing ones based on templates and analysis.
+Supports modular architecture with context-specific files.
+"""
+
+from typing import Dict, List, Any, Optional
+from template_selector import TemplateSelector
+import re
+
+
+class ContentGenerator:
+    """Generates and enhances CLAUDE.md files based on project context."""
+
+    def __init__(self, project_context: Dict[str, Any]):
+        """
+        Initialize content generator with project context.
+
+        Args:
+            project_context: Dictionary containing project type, tech_stack, team_size, etc.
+        """
+        self.project_context = project_context
+        self.template_selector = TemplateSelector(project_context)
+
+    def generate_root_file(self) -> str:
+        """
+        Generate root CLAUDE.md file (navigation hub).
+
+        Returns:
+            Complete CLAUDE.md content as string
+        """
+        template = self.template_selector.select_template()
+
+        # Use template selector's customization
+        if template.get('modular_recommended'):
+            return self._generate_modular_root(template)
+        else:
+            return self._generate_standalone_file(template)
+
+    def _generate_modular_root(self, template: Dict[str, Any]) -> str:
+        """Generate root file for modular architecture (navigation hub)."""
+        lines = []
+
+        # Title
+        lines.append("# CLAUDE.md")
+        lines.append("")
+        lines.append(f"This file provides top-level guidance for Claude Code when working with this {self.project_context.get('type', 'project')}.")
+        lines.append("")
+
+        # Quick Navigation
+        lines.append("## Quick Navigation")
+        lines.append("")
+        lines.extend(self._generate_navigation_section(template))
+        lines.append("")
+
+        # Core Principles (concise, 5-7 principles)
+        lines.append("## Core Principles")
+        lines.append("")
+        principles = self._generate_core_principles(template, max_count=5)
+        lines.extend(principles)
+        lines.append("")
+
+        # Tech Stack (summary only)
+        if self.project_context.get('tech_stack'):
+            lines.append("## Tech Stack")
+            lines.append("")
+            lines.extend(self._generate_tech_stack_summary())
+            lines.append("")
+
+        # Key Commands/Shortcuts
+        lines.append("## Quick Reference")
+        lines.append("")
+        lines.extend(self._generate_quick_reference())
+        lines.append("")
+
+        # Footer
+        lines.append("---")
+        lines.append("")
+        lines.append("For detailed guidelines, see context-specific CLAUDE.md files in subdirectories.")
+
+        return '\n'.join(lines)
+
+    def _generate_standalone_file(self, template: Dict[str, Any]) -> str:
+        """Generate standalone CLAUDE.md file (all-in-one)."""
+        return self.template_selector.customize_template(template)
+
+    def generate_context_file(self, context: str) -> str:
+        """
+        Generate context-specific CLAUDE.md file (e.g., backend, frontend).
+
+        Args:
+            context: Context name ('backend', 'frontend', 'database', etc.)
+
+        Returns:
+            Context-specific CLAUDE.md content
+        """
+        generators = {
+            'backend': self._generate_backend_file,
+            'frontend': self._generate_frontend_file,
+            'database': self._generate_database_file,
+            'docs': self._generate_docs_file,
+            '.github': self._generate_github_file
+        }
+
+        generator = generators.get(context, self._generate_generic_context_file)
+        return generator()
+
+    def _generate_backend_file(self) -> str:
+        """Generate backend-specific CLAUDE.md."""
+        lines = []
+        lines.append("# Backend Development Guidelines")
+        lines.append("")
+        lines.append("This file provides guidance for backend development in this project.")
+        lines.append("")
+
+        # API Design
+        lines.append("## API Design")
+        lines.append("")
+        lines.append("- Use RESTful conventions for API endpoints")
+        lines.append("- Implement proper HTTP status codes (200, 201, 400, 404, 500)")
+        lines.append("- Version APIs when breaking changes are needed (/api/v1/, /api/v2/)")
+        lines.append("- Document all endpoints with OpenAPI/Swagger")
+        lines.append("")
+
+        # Database Guidelines
+        lines.append("## Database Operations")
+        lines.append("")
+        lines.append("- Use migrations for all schema changes")
+        lines.append("- Implement proper indexes for query performance")
+        lines.append("- Use transactions for multi-step operations")
+        lines.append("- Avoid N+1 queries - use joins or batch loading")
+        lines.append("")
+
+        # Error Handling
+        lines.append("## Error Handling")
+        lines.append("")
+        lines.append("- Implement global error handling middleware")
+        lines.append("- Log errors with context (request ID, user ID, timestamp)")
+        lines.append("- Return consistent error response format")
+        lines.append("- Never expose stack traces to clients in production")
+        lines.append("")
+
+        # Testing
+        lines.append("## Testing Requirements")
+        lines.append("")
+        lines.append("- Write unit tests for business logic")
+        lines.append("- Write integration tests for API endpoints")
+        lines.append("- Mock external services in tests")
+        lines.append("- Aim for 80%+ code coverage")
+        lines.append("")
+
+        return '\n'.join(lines)
+
+    def _generate_frontend_file(self) -> str:
+        """Generate frontend-specific CLAUDE.md."""
+        lines = []
+        lines.append("# Frontend Development Guidelines")
+        lines.append("")
+        lines.append("This file provides guidance for frontend development in this project.")
+        lines.append("")
+
+        # Component Standards
+        lines.append("## Component Standards")
+        lines.append("")
+        tech_stack = [t.lower() for t in self.project_context.get('tech_stack', [])]
+
+        if 'react' in tech_stack:
+            lines.append("- Prefer functional components with hooks over class components")
+            lines.append("- Use TypeScript for type safety")
+            lines.append("- Keep components small and focused (< 200 lines)")
+            lines.append("- Extract reusable logic into custom hooks")
+        elif 'vue' in tech_stack:
+            lines.append("- Use Composition API for complex components")
+            lines.append("- Keep components small and focused (< 200 lines)")
+            lines.append("- Use TypeScript with Vue 3")
+            lines.append("- Extract reusable logic into composables")
+        else:
+            lines.append("- Keep components small and focused")
+            lines.append("- Extract reusable logic into utilities")
+            lines.append("- Use TypeScript for type safety")
+        lines.append("")
+
+        # State Management
+        lines.append("## State Management")
+        lines.append("")
+        lines.append("- Keep component state local when possible")
+        lines.append("- Use global state only for truly shared data")
+        lines.append("- Avoid prop drilling - use context/store for deep state")
+        lines.append("- Document state shape and update patterns")
+        lines.append("")
+
+        # Styling
+        lines.append("## Styling Guidelines")
+        lines.append("")
+        lines.append("- Use consistent naming conventions (BEM, CSS Modules, etc.)")
+        lines.append("- Avoid inline styles except for dynamic values")
+        lines.append("- Use design tokens for colors, spacing, typography")
+        lines.append("- Ensure responsive design for all breakpoints")
+        lines.append("")
+
+        # Performance
+        lines.append("## Performance Optimization")
+        lines.append("")
+        lines.append("- Lazy load routes and heavy components")
+        lines.append("- Optimize images (use WebP, lazy loading)")
+        lines.append("- Minimize bundle size - code split where possible")
+        lines.append("- Use memoization for expensive calculations")
+        lines.append("")
+
+        return '\n'.join(lines)
+
+    def _generate_database_file(self) -> str:
+        """Generate database-specific CLAUDE.md."""
+        lines = []
+        lines.append("# Database Guidelines")
+        lines.append("")
+        lines.append("This file provides guidance for database operations and migrations.")
+        lines.append("")
+
+        # Schema Design
+        lines.append("## Schema Design")
+        lines.append("")
+        lines.append("- Use meaningful table and column names")
+        lines.append("- Always include created_at and updated_at timestamps")
+        lines.append("- Use proper foreign key constraints")
+        lines.append("- Add indexes for frequently queried columns")
+        lines.append("")
+
+        # Migrations
+        lines.append("## Migration Guidelines")
+        lines.append("")
+        lines.append("- Never edit existing migrations - create new ones")
+        lines.append("- Test migrations on copy of production data")
+        lines.append("- Include both up and down migrations")
+        lines.append("- Document breaking changes in migration comments")
+        lines.append("")
+
+        # Query Optimization
+        lines.append("## Query Optimization")
+        lines.append("")
+        lines.append("- Use EXPLAIN to analyze slow queries")
+        lines.append("- Avoid SELECT * - specify needed columns")
+        lines.append("- Use appropriate JOIN types")
+        lines.append("- Limit result sets with pagination")
+        lines.append("")
+
+        return '\n'.join(lines)
+
+    def _generate_docs_file(self) -> str:
+        """Generate documentation-specific CLAUDE.md."""
+        lines = []
+        lines.append("# Documentation Guidelines")
+        lines.append("")
+        lines.append("This file provides guidance for project documentation.")
+        lines.append("")
+
+        lines.append("## Documentation Standards")
+        lines.append("")
+        lines.append("- Keep README.md updated with setup instructions")
+        lines.append("- Document all public APIs with examples")
+        lines.append("- Include architecture diagrams for complex systems")
+        lines.append("- Maintain changelog with semantic versioning")
+        lines.append("")
+
+        return '\n'.join(lines)
+
+    def _generate_github_file(self) -> str:
+        """Generate .github-specific CLAUDE.md for CI/CD."""
+        lines = []
+        lines.append("# CI/CD Workflows")
+        lines.append("")
+        lines.append("This file provides guidance for GitHub Actions and CI/CD processes.")
+        lines.append("")
+
+        lines.append("## Workflow Guidelines")
+        lines.append("")
+        lines.append("- Run linting and tests on all pull requests")
+        lines.append("- Automate deployments to staging on main branch")
+        lines.append("- Require manual approval for production deployments")
+        lines.append("- Cache dependencies to speed up builds")
+        lines.append("")
+
+        return '\n'.join(lines)
+
+    def _generate_generic_context_file(self) -> str:
+        """Generate generic context-specific file."""
+        return "# Context-Specific Guidelines\n\n[Add guidelines specific to this context]\n"
+
+    def generate_section(self, section_name: str) -> str:
+        """
+        Generate a specific section for CLAUDE.md.
+
+        Args:
+            section_name: Name of section to generate
+
+        Returns:
+            Section content as string
+        """
+        generators = {
+            'Core Principles': self._generate_core_principles_section,
+            'Tech Stack': self._generate_tech_stack_section,
+            'Workflow Instructions': self._generate_workflow_section,
+            'Testing Requirements': self._generate_testing_section,
+            'Error Handling': self._generate_error_handling_section,
+            'Documentation Standards': self._generate_documentation_section
+        }
+
+        generator = generators.get(section_name, self._generate_generic_section)
+        return generator(section_name)
+
+    def _generate_core_principles_section(self, section_name: str) -> str:
+        """Generate Core Principles section."""
+        template = self.template_selector.select_template()
+        lines = [f"## {section_name}", ""]
+        lines.extend(self._generate_core_principles(template, max_count=7))
+        return '\n'.join(lines)
+
+    def _generate_tech_stack_section(self, section_name: str) -> str:
+        """Generate Tech Stack section."""
+        lines = [f"## {section_name}", ""]
+        lines.extend(self._generate_tech_stack_summary())
+        return '\n'.join(lines)
+
+    def _generate_workflow_section(self, section_name: str) -> str:
+        """Generate Workflow Instructions section."""
+        lines = [f"## {section_name}", ""]
+
+        workflows = self.project_context.get('workflows', [])
+        if workflows:
+            for i, workflow in enumerate(workflows, 1):
+                workflow_title = workflow.replace('_', ' ').title()
+                lines.append(f"{i}. **{workflow_title}**: [Add {workflow} workflow description]")
+        else:
+            lines.append("[Add workflow instructions specific to your project]")
+
+        return '\n'.join(lines)
+
+    def _generate_testing_section(self, section_name: str) -> str:
+        """Generate Testing Requirements section."""
+        lines = [f"## {section_name}", ""]
+        lines.append("- Write tests before or alongside feature implementation")
+        lines.append("- Maintain minimum 80% code coverage")
+        lines.append("- Include unit, integration, and e2e tests")
+        lines.append("- Mock external dependencies in tests")
+        return '\n'.join(lines)
+
+    def _generate_error_handling_section(self, section_name: str) -> str:
+        """Generate Error Handling section."""
+        lines = [f"## {section_name}", ""]
+        lines.append("- Implement comprehensive error handling from the start")
+        lines.append("- Log errors with context (user ID, request ID, timestamp)")
+        lines.append("- Provide helpful error messages to users")
+        lines.append("- Never expose sensitive information in error messages")
+        return '\n'.join(lines)
+
+    def _generate_documentation_section(self, section_name: str) -> str:
+        """Generate Documentation Standards section."""
+        lines = [f"## {section_name}", ""]
+        lines.append("- Keep documentation in sync with code")
+        lines.append("- Document all public APIs and interfaces")
+        lines.append("- Include code examples in documentation")
+        lines.append("- Update README.md with setup and usage instructions")
+        return '\n'.join(lines)
+
+    def _generate_generic_section(self, section_name: str) -> str:
+        """Generate generic section placeholder."""
+        return f"## {section_name}\n\n[Add {section_name.lower()} guidelines specific to your project]\n"
+
+    def merge_with_existing(self, existing_content: str, new_sections: List[str]) -> str:
+        """
+        Merge new sections with existing CLAUDE.md content.
+
+        Args:
+            existing_content: Current CLAUDE.md content
+            new_sections: List of new sections to add
+
+        Returns:
+            Merged content as string
+        """
+        lines = existing_content.split('\n')
+        existing_sections = self._extract_existing_sections(existing_content)
+
+        # Add new sections that don't already exist
+        for new_section in new_sections:
+            section_name = new_section.split('\n')[0].replace('## ', '')
+            if section_name not in existing_sections:
+                lines.append("")
+                lines.append(new_section)
+
+        return '\n'.join(lines)
+
+    def _extract_existing_sections(self, content: str) -> List[str]:
+        """Extract section names from existing content."""
+        sections = []
+        for line in content.split('\n'):
+            if line.startswith('## '):
+                sections.append(line[3:].strip())
+        return sections
+
+    def _generate_navigation_section(self, template: Dict[str, Any]) -> List[str]:
+        """Generate navigation section for modular architecture."""
+        project_type = self.project_context.get('type')
+        links = []
+
+        if project_type == 'fullstack':
+            links.append("- [Backend Guidelines](backend/CLAUDE.md)")
+            links.append("- [Frontend Guidelines](frontend/CLAUDE.md)")
+            links.append("- [Database Operations](database/CLAUDE.md)")
+
+        if 'cicd' in self.project_context.get('workflows', []):
+            links.append("- [CI/CD Workflows](.github/CLAUDE.md)")
+
+        if not links:
+            links.append("- [Add links to context-specific CLAUDE.md files]")
+
+        return links
+
+    def _generate_core_principles(self, template: Dict[str, Any], max_count: int = 7) -> List[str]:
+        """Generate core principles list."""
+        principles = []
+        workflows = self.project_context.get('workflows', [])
+
+        # Add workflow-based principles
+        if 'tdd' in workflows:
+            principles.append("1. **Test-Driven Development**: Write tests before implementation")
+
+        # Add tech-specific principles
+        tech_custom = template.get('tech_customization', {})
+        for guideline in tech_custom.get('specific_guidelines', [])[:3]:
+            principle_num = len(principles) + 1
+            principles.append(f"{principle_num}. **{guideline.split(':')[0] if ':' in guideline else 'Guideline'}**: {guideline}")
+
+        # Add generic essential principles
+        generic = [
+            "**Code Quality**: Maintain high code quality with clear, readable implementations",
+            "**Documentation**: Keep documentation in sync with code changes",
+            "**Error Handling**: Implement comprehensive error handling from the start",
+            "**Performance**: Consider performance implications in implementation decisions",
+            "**Security**: Follow security best practices and avoid common vulnerabilities"
+        ]
+
+        for principle in generic:
+            if len(principles) >= max_count:
+                break
+            principle_num = len(principles) + 1
+            principles.append(f"{principle_num}. {principle}")
+
+        return principles
+
+    def _generate_tech_stack_summary(self) -> List[str]:
+        """Generate tech stack summary."""
+        lines = []
+        template = self.template_selector.select_template()
+        tech_custom = template.get('tech_customization', {})
+
+        if tech_custom.get('languages'):
+            lines.append(f"- **Languages**: {', '.join(tech_custom['languages'])}")
+
+        if tech_custom.get('frameworks'):
+            lines.append(f"- **Frameworks**: {', '.join(tech_custom['frameworks'])}")
+
+        if tech_custom.get('tools'):
+            lines.append(f"- **Tools**: {', '.join(tech_custom['tools'])}")
+
+        if not lines:
+            lines.append("- [Add your tech stack details here]")
+
+        return lines
+
+    def _generate_quick_reference(self) -> List[str]:
+        """Generate quick reference commands."""
+        lines = []
+        lines.append("```bash")
+        lines.append("# Common development commands")
+        lines.append("npm test          # Run tests")
+        lines.append("npm run lint      # Run linter")
+        lines.append("npm run build     # Build for production")
+        lines.append("```")
+        return lines