#!/usr/bin/env python3 """Gera doc/godot/api.md: o resumo das peças (godot/kits/) e das cenas da biblioteca (godot/library/). Para o agente que constrói cenas ler ~100 linhas de assinaturas em vez de ~1.700 de GDScript. Extrai de cada .gd o cabeçalho "##" do topo e as funções públicas (sem "_") com os "##" logo acima; de cada manifest.json, o rótulo, a descrição e os parâmetros. Uso (na raiz do repositório): python .claude/skills/cenaforge/scripts/godot_api.py Rode de novo sempre que uma peça ou cena mudar (o agente da tarefa "Cena no Godot" também roda). """ from __future__ import annotations import json import re import sys from pathlib import Path ROOT = Path(__file__).resolve().parents[4] OUT = ROOT / "doc" / "godot" / "api.md" FUNC = re.compile(r"^(static\s+)?func\s+([A-Za-z]\w*)\s*\((.*?)\)\s*(->\s*[\w\[\], ]+)?\s*:") def summarize_gd(path: Path) -> list[str]: lines = path.read_text(encoding="utf-8").splitlines() out: list[str] = [] # Cabeçalho: os "##" do topo (depois de extends/class_name). header: list[str] = [] for line in lines[:40]: s = line.strip() if s.startswith("##"): header.append(s[2:].strip()) elif header and not s: break elif s and not s.startswith(("extends", "class_name", "@")): if header: break if header: out.append("> " + "\n> ".join(h for h in header if h)) funcs: list[str] = [] for i, line in enumerate(lines): m = FUNC.match(line) if not m or m.group(2).startswith("_"): continue doc: list[str] = [] j = i - 1 while j >= 0 and lines[j].strip().startswith("##"): doc.insert(0, lines[j].strip()[2:].strip()) j -= 1 sig = f"{'static ' if m.group(1) else ''}{m.group(2)}({m.group(3)}){(' ' + m.group(4).strip()) if m.group(4) else ''}" funcs.append(f"- `{sig}`" + (f": {' '.join(doc)}" if doc else "")) if funcs: out.append("") out.extend(funcs) return out def summarize_manifest(path: Path) -> list[str]: try: m = json.loads(path.read_text(encoding="utf-8")) except (OSError, json.JSONDecodeError) as e: return [f"- manifest.json ilegível: {e}"] out = [f"**{m.get('label', path.parent.name)}** ({m.get('kind', 'doc3d')}): {m.get('description', '')}"] for p in m.get("params", []): if p.get("type") == "select": opts = ", ".join(str(o.get("value")) for o in p.get("options", [])) out.append(f"- param `{p.get('name')}` (select: {opts}; padrão {p.get('default')!r})") else: out.append(f"- param `{p.get('name')}` ({p.get('type')}; padrão {p.get('default')!r})") return out def main() -> int: parts = [ "# API das peças e cenas do Godot (gerado)", "", "Gerado por `python .claude/skills/cenaforge/scripts/godot_api.py`. Não edite à mão: rode de novo", "quando uma peça ou cena mudar. Use estas funções sem abrir os .gd inteiros.", "", "## Peças (`godot/kits/`, use com `preload(\"res://kits/.gd\")`)", ] for gd in sorted((ROOT / "godot" / "kits").glob("*.gd")): parts += ["", f"### `{gd.relative_to(ROOT).as_posix()}`", *summarize_gd(gd)] parts += ["", "## Cenas da biblioteca (`godot/library//`)"] for scene in sorted(p for p in (ROOT / "godot" / "library").iterdir() if p.is_dir()): parts += ["", f"### `{scene.name}`"] manifest = scene / "manifest.json" if manifest.exists(): parts += summarize_manifest(manifest) for gd in sorted(scene.glob("*.gd")): summary = summarize_gd(gd) if summary: parts += ["", f"`{gd.relative_to(ROOT).as_posix()}`", *summary] OUT.parent.mkdir(parents=True, exist_ok=True) OUT.write_text("\n".join(parts) + "\n", encoding="utf-8") print(f"{OUT.relative_to(ROOT).as_posix()}: {len(parts)} linhas") return 0 if __name__ == "__main__": sys.exit(main())