File size: 3,112 Bytes
6ca8e48
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
"""
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)