forge-dev 0.1.0__py3-none-any.whl

forge_core/editor_bridge.py

@@ -0,0 +1,543 @@
+"""CLAUDE.md Generator — bridges Forge governance to AI editors.
+
+This is the core value proposition of Forge: it translates all governance
+knowledge (standards, patterns, anti-patterns, project context, journal
+learnings, MCP recommendations) into a single CLAUDE.md file that any
+AI coding editor can read and follow.
+
+The generated CLAUDE.md acts as the "constitution" for the AI editor —
+it tells the editor exactly how to behave in this specific project.
+
+Supported outputs:
+- CLAUDE.md for Claude Code
+- .cursorrules for Cursor
+- .github/copilot-instructions.md for GitHub Copilot
+- Generic .ai-rules.md for any editor
+"""
+
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+from forge_core.models import ProjectContext, Regulatory
+from forge_core.registry import load_mcps, load_standards
+
+
+def generate_editor_instructions(
+    project_path: Path,
+    context: ProjectContext,
+    format: str = "claude",  # claude, cursor, copilot, generic
+) -> str:
+    """Generate complete editor instructions from Forge governance.
+    
+    This is the main function — it reads ALL Forge knowledge and
+    produces a single document that tells the AI editor everything
+    it needs to know to generate correct code in this project.
+    
+    Args:
+        project_path: Root of the project
+        context: Resolved project context
+        format: Output format (claude, cursor, copilot, generic)
+    
+    Returns:
+        Complete instruction document as string
+    """
+    sections: list[str] = []
+
+    # ── Header ──
+    sections.append(_generate_header(context, format))
+
+    # ── Project Identity ──
+    sections.append(_generate_project_identity(context))
+
+    # ── Stack & Architecture Rules ──
+    sections.append(_generate_stack_rules(context))
+
+    # ── Standards (the hard rules) ──
+    standards = load_standards(include_user=True)
+    sections.append(_generate_standards_section(standards, context))
+
+    # ── Patterns & Anti-Patterns ──
+    sections.append(_generate_patterns_section(project_path))
+
+    # ── API Design Rules ──
+    sections.append(_generate_api_rules(context))
+
+    # ── Security & Compliance ──
+    sections.append(_generate_security_rules(context))
+
+    # ── Observability Rules ──
+    sections.append(_generate_observability_rules(context))
+
+    # ── AI-Specific Rules (if project uses AI) ──
+    if context.ai.enabled:
+        sections.append(_generate_ai_rules(context))
+
+    # ── Code Quality Rules ──
+    sections.append(_generate_code_quality_rules(context))
+
+    # ── Project Journal (learnings & nuances) ──
+    journal_content = _load_journal(project_path)
+    if journal_content:
+        sections.append(_generate_journal_section(journal_content))
+
+    # ── MCP Recommendations ──
+    mcps = load_mcps()
+    if mcps:
+        sections.append(_generate_mcp_section(mcps))
+
+    # ── Self-Audit Instructions ──
+    sections.append(_generate_self_audit_instructions(context))
+
+    # ── Implementation Ordering ──
+    sections.append(_generate_implementation_order())
+
+    return "\n\n".join(sections)
+
+
+def write_editor_file(
+    project_path: Path,
+    context: ProjectContext,
+    format: str = "claude",
+) -> Path:
+    """Generate and write the editor instructions file.
+    
+    Returns the path to the written file.
+    """
+    content = generate_editor_instructions(project_path, context, format)
+
+    filename_map = {
+        "claude": "CLAUDE.md",
+        "cursor": ".cursorrules",
+        "copilot": ".github/copilot-instructions.md",
+        "generic": ".ai-rules.md",
+    }
+
+    filename = filename_map.get(format, "CLAUDE.md")
+    file_path = project_path / filename
+
+    # Ensure parent directory exists (for copilot)
+    file_path.parent.mkdir(parents=True, exist_ok=True)
+
+    file_path.write_text(content)
+    return file_path
+
+
+def sync_editor_file(project_path: Path, context: ProjectContext) -> list[Path]:
+    """Regenerate all editor instruction files that exist in the project.
+    
+    Only regenerates files that already exist — doesn't create new ones.
+    Returns list of updated files.
+    """
+    updated = []
+    checks = [
+        ("claude", "CLAUDE.md"),
+        ("cursor", ".cursorrules"),
+        ("copilot", ".github/copilot-instructions.md"),
+        ("generic", ".ai-rules.md"),
+    ]
+    for fmt, filename in checks:
+        path = project_path / filename
+        if path.exists():
+            write_editor_file(project_path, context, fmt)
+            updated.append(path)
+
+    return updated
+
+
+# ── Section Generators ─────────────────────────────────────────────────────
+
+def _generate_header(context: ProjectContext, format: str) -> str:
+    timestamp = datetime.now(timezone.utc).strftime("%Y-%m-%d %H:%M UTC")
+    return f"""# {context.name} — AI Editor Instructions
+# Generated by Forge v{context.forge_version} on {timestamp}
+# DO NOT EDIT MANUALLY — regenerate with `forge sync`
+# Source of truth: .forge/context.yaml + ~/.forge/ standards"""
+
+
+def _generate_project_identity(context: ProjectContext) -> str:
+    lines = [
+        "## Project Overview",
+        "",
+        f"**Name:** {context.name}",
+        f"**Type:** {context.type.value}",
+    ]
+    if context.description:
+        lines.append(f"**Purpose:** {context.description}")
+    if context.regulatory:
+        regs = ", ".join(r.value.upper() for r in context.regulatory)
+        lines.append(f"**Regulatory:** {regs} — all code must comply with these requirements")
+    return "\n".join(lines)
+
+
+def _generate_stack_rules(context: ProjectContext) -> str:
+    return f"""## Stack & Architecture
+
+This project uses the following stack. All code must be consistent with these choices.
+
+- **Cloud:** {context.cloud.value}
+- **Backend:** {context.backend.value}
+- **Frontend:** {context.frontend.value}
+- **Database:** {context.database.value}
+- **Auth:** {context.auth.value}
+- **API Style:** {context.api.style} with {context.api.spec}
+- **IaC:** {context.cicd.iac}
+- **CI/CD:** {context.cicd.provider}
+
+Do NOT introduce alternative frameworks, libraries, or patterns that conflict with this stack
+unless explicitly approved and documented in .forge/overrides/."""
+
+
+def _generate_standards_section(standards: list[dict], context: ProjectContext) -> str:
+    if not standards:
+        return "## Standards\n\nNo standards configured yet."
+
+    lines = [
+        "## Standards — Hard Rules",
+        "",
+        "These are non-negotiable. All code must comply.",
+        "",
+    ]
+
+    for std in standards:
+        name = std.get("name", "unnamed")
+        area = std.get("area", "general")
+        desc = std.get("description", "")
+        enforcement = std.get("enforcement", "required")
+        rules = std.get("rules", [])
+
+        lines.append(f"### {name} ({area}) [{enforcement}]")
+        lines.append(f"{desc}")
+        lines.append("")
+
+        if rules:
+            for rule in rules:
+                lines.append(f"- {rule}")
+            lines.append("")
+
+        # Include examples if available
+        examples = std.get("examples", {})
+        if examples.get("good"):
+            lines.append("**Good:**")
+            for ex in examples["good"]:
+                lines.append(f"- `{ex}`")
+            lines.append("")
+        if examples.get("bad"):
+            lines.append("**Bad (never do this):**")
+            for ex in examples["bad"]:
+                lines.append(f"- `{ex}`")
+            lines.append("")
+
+    return "\n".join(lines)
+
+
+def _generate_patterns_section(project_path: Path) -> str:
+    """Load patterns and anti-patterns from both global and project level."""
+    lines = [
+        "## Approved Patterns & Anti-Patterns",
+        "",
+    ]
+
+    # Global patterns
+    from forge_core.registry import USER_DIR
+    patterns_dir = USER_DIR / "patterns"
+    anti_dir = USER_DIR / "anti-patterns"
+
+    # Project-level overrides
+    project_patterns_dir = project_path / ".forge" / "overrides" / "patterns"
+    project_anti_dir = project_path / ".forge" / "overrides" / "anti-patterns"
+
+    patterns = _load_yaml_dir(patterns_dir) + _load_yaml_dir(project_patterns_dir)
+    anti_patterns = _load_yaml_dir(anti_dir) + _load_yaml_dir(project_anti_dir)
+
+    if patterns:
+        lines.append("### Approved Patterns (use these)")
+        lines.append("")
+        for p in patterns:
+            lines.append(f"**{p.get('name', 'unnamed')}**: {p.get('description', '')}")
+            if p.get("example"):
+                lines.append(f"```\n{p['example']}\n```")
+            lines.append("")
+
+    if anti_patterns:
+        lines.append("### Anti-Patterns (NEVER do these)")
+        lines.append("")
+        for ap in anti_patterns:
+            lines.append(f"**{ap.get('name', 'unnamed')}**: {ap.get('description', '')}")
+            if ap.get("instead"):
+                lines.append(f"**Instead:** {ap['instead']}")
+            if ap.get("example_bad"):
+                lines.append(f"```\n# BAD — do not do this\n{ap['example_bad']}\n```")
+            if ap.get("example_good"):
+                lines.append(f"```\n# GOOD — do this instead\n{ap['example_good']}\n```")
+            lines.append("")
+
+    if not patterns and not anti_patterns:
+        lines.append("No patterns or anti-patterns defined yet.")
+        lines.append("Add them via `forge standards` or in ~/.forge/user/patterns/")
+
+    return "\n".join(lines)
+
+
+def _generate_api_rules(context: ProjectContext) -> str:
+    lines = [
+        "## API Design Rules",
+        "",
+        "When creating any API endpoint, controller, or route:",
+        "",
+        f"- Use {context.api.versioning} versioning (e.g., /v1/resource)",
+        f"- Document with {context.api.spec} decorators/annotations",
+        "- Return RFC 7807 Problem Details for all errors",
+        "- Include pagination (cursor-based preferred) for list endpoints",
+        "- Add rate limiting configuration",
+        "- Include health check endpoint (/health, /ready)",
+        "- Every endpoint must have request/response type validation",
+    ]
+
+    if context.api.mcp_ready:
+        lines.extend([
+            "",
+            "### MCP-Ready Design",
+            "- Every endpoint must be usable as an MCP tool — clear inputs, clear outputs, no implicit state",
+            "- Response schemas must be self-describing (include field descriptions)",
+            "- Endpoints must be independently callable without session context",
+        ])
+
+    return "\n".join(lines)
+
+
+def _generate_security_rules(context: ProjectContext) -> str:
+    lines = [
+        "## Security Rules",
+        "",
+        f"- Authentication: {context.auth.value} — implement before any business endpoint",
+        "- All user input must be validated at the API boundary with typed models",
+        "- Secrets must NEVER appear in code or config — use environment variables or vault",
+        "- CORS must be explicitly configured — never use wildcard (*) in production",
+        "- All SQL must use parameterized queries — no string concatenation",
+        "- Dependencies must be scanned for vulnerabilities in CI",
+        "- Security headers must be set (HSTS, X-Content-Type-Options, CSP)",
+    ]
+
+    for reg in context.regulatory:
+        if reg == Regulatory.HIPAA:
+            lines.extend([
+                "",
+                "### HIPAA Compliance (REQUIRED)",
+                "- All PHI must be encrypted at rest (AES-256) and in transit (TLS 1.2+)",
+                "- Audit logging of ALL PHI access with user identity and timestamp",
+                "- Minimum necessary access via RBAC — no broad data access",
+                "- Session timeouts must not exceed 15 minutes of inactivity",
+                "- BAA must be in place for all cloud services handling PHI",
+                "- Never log PHI in application logs — use tokenized references",
+            ])
+        elif reg == Regulatory.FERPA:
+            lines.extend([
+                "",
+                "### FERPA Compliance (REQUIRED)",
+                "- Student education records must have restricted access controls",
+                "- Consent tracking for all data sharing",
+                "- Audit trail for all record access",
+            ])
+        elif reg == Regulatory.GDPR:
+            lines.extend([
+                "",
+                "### GDPR Compliance (REQUIRED)",
+                "- Explicit consent must be recorded for data processing",
+                "- Right to deletion must be implementable for all user data",
+                "- Data portability exports must be available",
+            ])
+        elif reg == Regulatory.SOC2:
+            lines.extend([
+                "",
+                "### SOC2 Compliance (REQUIRED)",
+                "- Access controls and audit logging on all systems",
+                "- Change management procedures must be documented",
+                "- Incident response procedures must exist",
+            ])
+
+    return "\n".join(lines)
+
+
+def _generate_observability_rules(context: ProjectContext) -> str:
+    obs = context.observability
+    return f"""## Observability Rules
+
+Every piece of code must be observable from day one.
+
+- **APM:** {obs.apm} — instrument all HTTP requests, database queries, and external calls
+- **Metrics:** {obs.metrics} — expose custom metrics via /metrics endpoint
+- **Logs:** {obs.logs} — ALL logs must be structured JSON with correlation IDs
+- **Dashboards:** {obs.dashboards} — dashboard definitions must be version-controlled
+- **Tracing:** {'Enabled' if obs.tracing else 'Disabled'} — use W3C Trace Context for distributed tracing
+
+### When creating any new service or endpoint:
+1. Add APM instrumentation (auto or manual)
+2. Add custom metrics for business-relevant events
+3. Use structured logging with correlation ID propagation
+4. Add to the service's Grafana dashboard
+5. Define alert rules for error rate and latency"""
+
+
+def _generate_ai_rules(context: ProjectContext) -> str:
+    ai = context.ai
+    providers = ", ".join(ai.providers) if ai.providers else "not specified"
+    return f"""## AI Integration Rules
+
+This project uses AI capabilities internally.
+
+- **Providers:** {providers}
+- **Observability:** {'Required' if ai.observability else 'Optional'}
+
+### When integrating AI:
+- Track per-request: model, tokens in/out, latency, cost estimate
+- Implement cost controls — daily spend limits and alerts
+- Add prompt injection detection on all user-facing AI inputs
+- Log all AI interactions with trace IDs for debugging
+- Monitor context window utilization — alert if consistently >80%
+- Implement graceful degradation when AI services are unavailable
+- Rate limit AI-powered endpoints separately from standard endpoints
+- Never expose raw model responses to users without safety filtering
+- Cache AI responses where appropriate to reduce cost and latency
+- Track and alert on AI response quality metrics where measurable"""
+
+
+def _generate_code_quality_rules(context: ProjectContext) -> str:
+    std = context.standards
+    return f"""## Code Quality Rules
+
+- **Type checking:** {std.type_checking} — no exceptions
+- **Linting:** {std.linting} — must pass before commit
+- **Test coverage minimum:** {std.test_coverage_min}%
+
+### Before writing any code:
+1. Check if similar functionality already exists — do NOT duplicate
+2. Follow existing patterns in the codebase — consistency over personal preference
+3. Add types to everything — parameters, returns, variables where non-obvious
+4. Write tests for new functionality
+5. Ensure all imports are used and all exports are intentional
+
+### Self-audit checklist (run mentally before completing any task):
+- [ ] Does this follow the project's established patterns?
+- [ ] Are all types explicit and correct?
+- [ ] Is error handling consistent with the rest of the codebase?
+- [ ] Is there any duplicated logic that should be extracted?
+- [ ] Are security boundaries respected?
+- [ ] Is this observable? (logs, metrics, traces)
+- [ ] Would a new team member understand this code?"""
+
+
+def _generate_journal_section(journal_content: str) -> str:
+    return f"""## Project-Specific Context (Journal)
+
+These are learnings and nuances specific to this project. Read and respect them.
+
+{journal_content}"""
+
+
+def _generate_mcp_section(mcps: list) -> str:
+    lines = [
+        "## Recommended MCP Servers",
+        "",
+        "Use these MCP servers for better development context:",
+        "",
+    ]
+    for mcp in mcps:
+        lines.append(f"- **{mcp.name}**: {mcp.description}")
+        if mcp.url:
+            lines.append(f"  Command: `{mcp.url}`")
+    return "\n".join(lines)
+
+
+def _generate_self_audit_instructions(context: ProjectContext) -> str:
+    return """## Self-Audit Instructions
+
+After generating or modifying any code, perform these checks automatically:
+
+### 1. Pattern Compliance
+- Does the new code follow established patterns in the codebase?
+- If introducing a new pattern, is it documented and justified?
+- Are there any anti-patterns present?
+
+### 2. Security Check
+- Is all user input validated?
+- Are secrets properly managed (no hardcoded values)?
+- Is authentication/authorization applied correctly?
+- Are SQL queries parameterized?
+
+### 3. API Compliance (if applicable)
+- Does the endpoint have OpenAPI documentation?
+- Does it follow the versioning strategy?
+- Are error responses in RFC 7807 format?
+- Is rate limiting configured?
+- Is it MCP-ready (clear inputs/outputs, no implicit state)?
+
+### 4. Observability Check
+- Is the code instrumented for APM?
+- Are relevant custom metrics added?
+- Is logging structured with correlation IDs?
+- Are dashboard updates needed?
+
+### 5. Type Safety
+- Are all types explicit?
+- Are there any `any` or untyped values?
+- Is input/output validation in place at boundaries?
+
+### 6. Duplication Check
+- Does similar functionality already exist?
+- Can existing utilities/services be reused?
+- Should this be extracted into a shared utility?
+
+If any check fails, fix it before presenting the code."""
+
+
+def _generate_implementation_order() -> str:
+    return """## Implementation Order for New Features
+
+When building anything new, follow this order to ensure each step has full context:
+
+1. **Types & Contracts** — Define models, interfaces, schemas first
+2. **Data Layer** — Migrations, repository methods
+3. **Business Logic** — Service classes, pure logic
+4. **API Endpoints** — Thin controllers wiring services to HTTP
+5. **Frontend** — Components consuming typed API contracts
+6. **Observability** — Instrument the new code
+7. **Tests** — Validate against acceptance criteria
+
+This order minimizes errors because each step has complete context from the previous steps."""
+
+
+# ── Helpers ────────────────────────────────────────────────────────────────
+
+def _load_journal(project_path: Path) -> str:
+    """Load the project journal content (just the entries, not the header)."""
+    journal_path = project_path / ".forge" / "journal.md"
+    if not journal_path.exists():
+        return ""
+
+    content = journal_path.read_text()
+    # Extract just the entries section
+    marker = "## Entries"
+    if marker in content:
+        entries = content.split(marker, 1)[1].strip()
+        return entries if entries else ""
+    return ""
+
+
+def _load_yaml_dir(dir_path: Path) -> list[dict]:
+    """Load all YAML files from a directory."""
+    if not dir_path.exists():
+        return []
+    results = []
+    for f in sorted(dir_path.glob("*.yaml")):
+        try:
+            with open(f) as fp:
+                data = yaml.safe_load(fp) or {}
+                results.append(data)
+        except Exception:
+            continue
+    return results