forge-dev 0.1.0__py3-none-any.whl

forge_core/__init__.py

@@ -0,0 +1,3 @@
+"""Forge — AI-Native Development Workflow Engine."""
+
+__version__ = "0.1.0"

forge_core/agents/__init__.py

@@ -0,0 +1 @@
+"""Forge audit agents."""

forge_core/auditor.py

@@ -0,0 +1,330 @@
+"""Forge Audit Engine — validates code against governance rules.
+
+The auditor doesn't just find problems — it explains them, references
+the specific standard violated, and provides the fix. It generates
+prompts that the AI editor can use to self-correct.
+
+Audit categories:
+- Pattern compliance: Does code follow established patterns?
+- Security: Auth, input validation, secrets, SQL injection
+- API design: OpenAPI, versioning, error format, MCP-readiness
+- Observability: Instrumentation, logging, metrics
+- Type safety: Types, validation, no 'any'
+- Duplication: Similar code that should be consolidated
+- Regulatory: HIPAA/FERPA/GDPR-specific checks
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+from forge_core.models import ProjectContext, Regulatory
+
+
+@dataclass
+class AuditFinding:
+    """A single audit finding."""
+    severity: str  # critical, warning, info, suggestion
+    category: str  # security, api, observability, type-safety, duplication, pattern, regulatory
+    standard: str  # Which standard this violates
+    rule: str  # Specific rule within the standard
+    file: str  # File where the issue was found (or "project-wide")
+    line: int | None  # Line number if applicable
+    description: str  # What's wrong
+    fix: str  # How to fix it
+    code_example: str = ""  # Example of correct code
+
+
+@dataclass
+class AuditReport:
+    """Complete audit report for a project."""
+    project: str
+    timestamp: str
+    forge_version: str
+    total_files_scanned: int = 0
+    findings: list[AuditFinding] = field(default_factory=list)
+    summary: dict[str, int] = field(default_factory=dict)
+
+    @property
+    def critical_count(self) -> int:
+        return sum(1 for f in self.findings if f.severity == "critical")
+
+    @property
+    def warning_count(self) -> int:
+        return sum(1 for f in self.findings if f.severity == "warning")
+
+    @property
+    def passed(self) -> bool:
+        return self.critical_count == 0
+
+    def to_markdown(self) -> str:
+        """Generate a markdown audit report."""
+        lines = [
+            f"# Forge Audit Report — {self.project}",
+            f"**Date:** {self.timestamp}",
+            f"**Files scanned:** {self.total_files_scanned}",
+            f"**Findings:** {len(self.findings)} "
+            f"({self.critical_count} critical, {self.warning_count} warnings)",
+            f"**Status:** {'PASSED' if self.passed else 'FAILED'}",
+            "",
+        ]
+
+        if not self.findings:
+            lines.append("No issues found. Code is compliant with all standards.")
+            return "\n".join(lines)
+
+        # Group by category
+        by_category: dict[str, list[AuditFinding]] = {}
+        for f in self.findings:
+            by_category.setdefault(f.category, []).append(f)
+
+        for category, findings in sorted(by_category.items()):
+            lines.append(f"## {category.replace('-', ' ').title()}")
+            lines.append("")
+            for f in findings:
+                icon = {"critical": "🔴", "warning": "🟡", "info": "🔵", "suggestion": "💡"}
+                lines.append(
+                    f"{icon.get(f.severity, '•')} **[{f.severity.upper()}]** {f.description}"
+                )
+                if f.file != "project-wide":
+                    loc = f"{f.file}" + (f":{f.line}" if f.line else "")
+                    lines.append(f"  *File:* `{loc}`")
+                lines.append(f"  *Standard:* {f.standard} — {f.rule}")
+                lines.append(f"  *Fix:* {f.fix}")
+                if f.code_example:
+                    lines.append(f"  ```\n  {f.code_example}\n  ```")
+                lines.append("")
+
+        return "\n".join(lines)
+
+
+def build_audit_prompt(
+    project_path: Path,
+    context: ProjectContext,
+    standards: list[dict],
+    target_files: list[str] | None = None,
+) -> str:
+    """Build the prompt for LLM-powered code auditing.
+    
+    This prompt is designed to be sent to Claude or any LLM to perform
+    a deep audit of the code against Forge standards.
+    
+    Args:
+        project_path: Root of the project
+        context: Project context with stack and config
+        standards: All applicable standards
+        target_files: Specific files to audit (None = full project)
+    """
+    # Build standards section
+    standards_text = ""
+    for std in standards:
+        standards_text += f"\n### {std.get('name', 'unnamed')} ({std.get('area', 'general')})\n"
+        standards_text += f"{std.get('description', '')}\n"
+        rules = std.get("rules", [])
+        for i, rule in enumerate(rules, 1):
+            standards_text += f"  {i}. {rule}\n"
+
+    # Build regulatory section
+    regulatory_text = ""
+    for reg in context.regulatory:
+        if reg == Regulatory.HIPAA:
+            regulatory_text += """
+### HIPAA Requirements
+- All PHI encrypted at rest (AES-256) and in transit (TLS 1.2+)
+- Audit logging of ALL PHI access
+- Minimum necessary access via RBAC
+- Session timeouts <= 15 minutes
+- Never log PHI in application logs
+"""
+        elif reg == Regulatory.FERPA:
+            regulatory_text += """
+### FERPA Requirements
+- Student records must have restricted access controls
+- Consent tracking for data sharing
+- Audit trail for all record access
+"""
+
+    # Build file targets
+    if target_files:
+        files_instruction = f"Audit ONLY these files:\n" + "\n".join(f"- {f}" for f in target_files)
+    else:
+        files_instruction = "Audit ALL code files in the project."
+
+    return f"""You are Forge, an AI development governance engine. Perform a thorough code audit.
+
+## Project Context
+- Name: {context.name}
+- Type: {context.type.value}
+- Backend: {context.backend.value}
+- Frontend: {context.frontend.value}
+- Cloud: {context.cloud.value}
+- Auth: {context.auth.value}
+- Database: {context.database.value}
+- AI Enabled: {context.ai.enabled}
+- Regulatory: {', '.join(r.value for r in context.regulatory) or 'None'}
+
+## Standards to Enforce
+{standards_text}
+
+{regulatory_text}
+
+## Scope
+{files_instruction}
+
+## Audit Instructions
+
+For each file, check:
+
+1. **Pattern Compliance**: Does the code follow established patterns? Is there code that should be reusing existing utilities but isn't?
+
+2. **Security**: 
+   - Input validation at API boundaries
+   - No hardcoded secrets
+   - Parameterized SQL queries
+   - Auth/RBAC on all endpoints
+   - Security headers
+
+3. **API Design**:
+   - OpenAPI documentation present
+   - Correct versioning ({context.api.versioning})
+   - RFC 7807 error responses
+   - Rate limiting configured
+   - MCP-ready design (clear inputs/outputs)
+
+4. **Observability**:
+   - APM instrumentation ({context.observability.apm})
+   - Structured JSON logging with correlation IDs
+   - Custom metrics for business events
+   - No print() or console.log() in production code
+
+5. **Type Safety**:
+   - All functions have type annotations
+   - No 'any' types (TypeScript) or untyped parameters (Python)
+   - Pydantic/Zod validation at boundaries
+
+6. **Duplication**:
+   - Similar logic that should be consolidated
+   - Copy-pasted code blocks
+   - Services that overlap in responsibility
+
+7. **Regulatory** (if applicable):
+   - PHI/PII handling (HIPAA)
+   - Access controls (FERPA/GDPR)
+   - Audit logging completeness
+
+## Output Format
+
+Respond with a JSON array of findings:
+
+```json
+[
+  {{
+    "severity": "critical|warning|info|suggestion",
+    "category": "security|api|observability|type-safety|duplication|pattern|regulatory",
+    "standard": "name of the standard violated",
+    "rule": "specific rule text",
+    "file": "path/to/file.py",
+    "line": 42,
+    "description": "What is wrong",
+    "fix": "How to fix it — be specific and actionable",
+    "code_example": "Optional: example of correct code"
+  }}
+]
+```
+
+Be thorough but practical. Focus on findings that actually matter for production quality.
+Do NOT flag stylistic preferences — only standard violations and real issues."""
+
+
+def build_file_audit_prompt(
+    file_content: str,
+    file_path: str,
+    context: ProjectContext,
+    standards: list[dict],
+) -> str:
+    """Build an audit prompt for a single file.
+    
+    Used when the editor wants to audit code it just generated
+    before presenting it to the user.
+    """
+    # Compact standards for single-file context
+    rules_summary = []
+    for std in standards:
+        name = std.get("name", "unnamed")
+        for rule in std.get("rules", []):
+            rules_summary.append(f"[{name}] {rule}")
+
+    rules_text = "\n".join(f"- {r}" for r in rules_summary)
+
+    return f"""Audit this code against the project standards. Be specific and actionable.
+
+## Project: {context.name}
+Stack: {context.backend.value} + {context.frontend.value} | Auth: {context.auth.value}
+Regulatory: {', '.join(r.value for r in context.regulatory) or 'None'}
+
+## Standards
+{rules_text}
+
+## File: {file_path}
+```
+{file_content}
+```
+
+## Response Format
+Return ONLY a JSON array of findings (empty array if compliant):
+[{{"severity":"...", "category":"...", "standard":"...", "rule":"...", "line":N, "description":"...", "fix":"...", "code_example":"..."}}]"""
+
+
+def save_audit_report(report: AuditReport, project_path: Path) -> Path:
+    """Save an audit report to the project's .forge/audit/ directory."""
+    audit_dir = project_path / ".forge" / "audit"
+    audit_dir.mkdir(parents=True, exist_ok=True)
+
+    timestamp = datetime.now(timezone.utc).strftime("%Y%m%d_%H%M%S")
+
+    # Save markdown report
+    md_path = audit_dir / f"audit_{timestamp}.md"
+    md_path.write_text(report.to_markdown())
+
+    # Save structured data
+    data_path = audit_dir / f"audit_{timestamp}.yaml"
+    data = {
+        "project": report.project,
+        "timestamp": report.timestamp,
+        "forge_version": report.forge_version,
+        "total_files_scanned": report.total_files_scanned,
+        "passed": report.passed,
+        "summary": {
+            "critical": report.critical_count,
+            "warning": report.warning_count,
+            "total": len(report.findings),
+        },
+        "findings": [
+            {
+                "severity": f.severity,
+                "category": f.category,
+                "standard": f.standard,
+                "rule": f.rule,
+                "file": f.file,
+                "line": f.line,
+                "description": f.description,
+                "fix": f.fix,
+            }
+            for f in report.findings
+        ],
+    }
+    with open(data_path, "w") as fp:
+        yaml.dump(data, fp, default_flow_style=False, sort_keys=False)
+
+    # Update latest symlink
+    latest_md = audit_dir / "latest.md"
+    if latest_md.exists() or latest_md.is_symlink():
+        latest_md.unlink()
+    latest_md.symlink_to(md_path.name)
+
+    return md_path