docforge-api / backend /services /formatter.py
Shivoo29's picture
fix: set PLAYWRIGHT_BROWSERS_PATH so chromium is found at runtime by user
6ca8e48
Raw History Blame Contribute Delete
3.11 kB
"""
Formatter: converts structured JSON → .context.md
The output format is specifically designed to:
1. Be readable by humans reviewing what was generated
2. Maximize signal density for AI context windows (no fluff)
3. Prominently feature gotchas — the main reason this tool exists
"""
from datetime import date
def format_context_md(data: dict) -> str:
"""Convert a structured library dict to a .context.md string."""
library = data.get("library", "unknown")
version = data.get("version", "unknown")
description = data.get("description", "")
components = data.get("components", [])
today = date.today().isoformat()
lines: list[str] = []
# Header
lines.append(f"# {library}@{version} — DocForge Context File")
lines.append(f"> Generated by DocForge | Last verified: {today}")
lines.append("> Drop this file into your project and reference it with @context.md in Cursor/Claude")
if description:
lines.append(f"\n{description}")
lines.append("")
# Component sections
for comp in components:
lines.append(f"---\n\n## {comp.get('name', 'Unknown')}")
# Install command
install = comp.get("install_command")
if install:
lines.append("\n**Install:**")
lines.append("```bash")
lines.append(install)
lines.append("```")
# Import path
import_path = comp.get("import_path")
if import_path:
lines.append("\n**Import:**")
lines.append("```typescript")
lines.append(import_path)
lines.append("```")
# Peer dependencies
peer_deps = comp.get("peer_dependencies", [])
if peer_deps:
lines.append("\n**Peer Dependencies:**")
for dep in peer_deps:
lines.append(f"- `{dep}`")
# Props table
props = comp.get("props", [])
if props:
lines.append("\n**Props:**")
lines.append("| Prop | Type | Required | Default |")
lines.append("|------|------|----------|---------|")
for prop in props:
name = prop.get("name", "")
ptype = prop.get("type", "")
required = "✓" if prop.get("required") else "—"
default = prop.get("default") or "—"
lines.append(f"| {name} | {ptype} | {required} | {default} |")
# Gotchas — the most important section
gotchas = comp.get("gotchas", [])
if gotchas:
lines.append("\n**⚠️ Gotchas (Common AI Codegen Errors):**")
for gotcha in gotchas:
lines.append(f"- {gotcha}")
# Usage example
usage = comp.get("usage_example")
if usage:
lines.append("\n**Usage:**")
# Detect language hint from content
lang = "tsx" if ("<" in usage and ">" in usage) else "typescript"
lines.append(f"```{lang}")
lines.append(usage.strip())
lines.append("```")
lines.append("")
return "\n".join(lines)