""" 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)