collect
Gerada por tools/gerar_documentacao.py. Definição: tools/documentacao/analise.py:617.
Coleta fontes, símbolos, referências, casos, modos e exemplos do repositório.
Tipo: função Python · Visibilidade: pública · Arquivo: tools/documentacao/analise.py.
Assinatura e expansão
def collect(root: Path) -> Inventory:
Parâmetros formais: root: Path.
Como funciona
Coleta fontes, símbolos, referências, casos, modos e exemplos do repositório.
Implementação completa · 100 linhas
def collect(root: Path) -> Inventory:
"""Coleta fontes, símbolos, referências, casos, modos e exemplos do repositório."""
root = root.resolve()
inv = Inventory(root)
parser = Parser(Language(tree_sitter_c.language()))
paths = []
for top in ("include", "src", "tools", "tests"):
base = root / top
if base.exists():
paths.extend(p for p in base.rglob("*") if p.is_file()
and not any(part in SKIP_DIRS or part.startswith("build-") for part in p.relative_to(root).parts))
for path in sorted(set(paths)):
relative = path.relative_to(root).as_posix()
if path.suffix not in CODE_SUFFIXES:
continue
try:
text = path.read_text(encoding="utf-8")
except UnicodeDecodeError:
inv.warnings.append(f"Arquivo de código não UTF-8 ignorado: {relative}")
continue
language = {".py": "python", ".sh": "shell", ".cpp": "cpp", ".cc": "cpp"}.get(path.suffix, "c")
source = Source(relative, text, language)
if language in {"c", "cpp"}:
# O atributo de diagnóstico é um protocolo do projeto, não sintaxe C.
# Só a cópia analisada omite essa anotação; posições e fonte permanecem.
parse_text = re.sub(r"(BG_FORMATO\([^)]*\)|BG_NORETURN(?=\s+void))",
lambda m: " " * len(m.group()), text)
source.tree = parser.parse(parse_text.encode("utf-8"))
inv.sources[relative] = source
production = relative.startswith(("include/", "src/", "tools/"))
if language in {"c", "cpp"}:
extract_c(inv, source, production)
if relative == "tests/test_biblioteca.c":
extract_modes(inv, source)
elif language == "python":
extract_python(inv, source)
elif language == "shell":
extract_shell(inv, source)
extract_heredocs(inv, source, parser)
# Funções primeiro: a resolução de contexto não deve escolher o caso inteiro
# quando existe uma função de teste mais específica.
inv.finish()
names = set(inv.by_name)
for source in list(inv.sources.values()):
if not source.path.startswith("tests/"):
continue
spans = identifier_spans(source)
if source.language == "shell" and not source.parent:
# Heredocs já têm fonte e linhas próprias; não contar duas vezes.
masked = mask_code(source.text, "shell")
for match in re.finditer(r"<<-?\s*['\"]?([A-Za-z_][A-Za-z_0-9]*)['\"]?", masked):
line_start = masked.rfind("\n", 0, match.start()) + 1
if masked[line_start:match.start()].lstrip().startswith("#"):
continue
delimiter = match.group(1)
end = masked.find("\n" + delimiter, match.end())
if end >= 0:
stop = masked.find("\n", end + 1)
stop = len(masked) if stop < 0 else stop
masked = masked[:match.end()] + " " * (stop - match.end()) + masked[stop:]
spans = [(m.group(), masked.count("\n", 0, m.start()) + 1)
for m in IDENT.finditer(masked)]
for name, line in spans:
if name not in names:
continue
if not source.parent:
definition = next((s for s in inv.by_name[name] if s.path == source.path
and line == s.line), None)
if definition:
continue
kind = "condicional" if source.language in {"c", "cpp"} and re.match(
r"\s*#\s*(if|ifdef|ifndef|elif|else|endif)", source.lines[line - 1]) else "código"
inv.references.append(Reference(name, source.path, line + source.offset,
container_for(source, line, inv), kind,
source.parent, source.offset if source.parent else 0))
expansions = root / "tests" / "expansoes.txt"
if expansions.exists():
for line, text in enumerate(expansions.read_text(encoding="utf-8").splitlines(), 1):
match = re.match(r"([A-Za-z_]\w*)\|", text)
if match and match.group(1) in names:
inv.references.append(Reference(match.group(1), "tests/expansoes.txt", line,
"expansão esperada após cc -E -dM", "tabela de expansão"))
example_dir = root / "docs" / "exemplos"
if example_dir.exists():
for path in sorted(example_dir.glob("*.c")):
relative = path.relative_to(root).as_posix()
text = path.read_text(encoding="utf-8")
source = Source(relative, text, "c")
source.tree = parser.parse(source.data)
inv.sources[relative] = source
names = sorted({name for name, _ in identifier_spans(source) if name in names})
inv.examples.append({"name": path.stem, "path": relative, "symbols": names,
"files": {p.name: p.relative_to(root).as_posix()
for p in sorted(example_dir.glob(path.stem + ".*"))}})
discover_cases(inv)
for case in inv.cases:
case["symbols"] = sorted({r.symbol for r in inv.references if r.path.startswith(case["path"] + "/")})
discover_make(inv)
inv.finish()
return inv
Nomes internos referenciados: container_for, discover_cases, discover_make, extract_c, extract_heredocs, extract_modes, extract_python, extract_shell, identifier_spans, mask_code.
Como este símbolo aparece nos testes
3 ocorrência(s) em 1 arquivo(s) de teste. Os links apontam para linhas exatas; os trechos mostram o contexto local. Uma menção não prova que todos os ramos foi executado.
tests/documentacao/test_gerador.py
Contexto: GeradorTest.setUpClass, GeradorTest.test_funcao_e_caso_novos_aparecem_sem_lista_manual, test_gerador.py. Linhas: 8, 19, 151. Tipo de evidência: código; via collect.
Linhas 6–10 · abrir contexto
from pathlib import Path
from tools.documentacao.analise import collect
from tools.documentacao.render import Renderer, protect
from tools.gerar_documentacao import check_outputs, clean_managed_output, tree_digest
Linhas 17–21 · abrir contexto
def setUpClass(cls) -> None:
"""Extrai o repositório real uma vez para os testes de integração."""
cls.inv = collect(ROOT)
def test_funcoes_publicas_tem_corpo_e_prototipo(self) -> None:
Linhas 149–153 · abrir contexto
(case / "programa.c").write_text("int main(void) { return NOVO(0); }\n", encoding="utf-8")
(case / "esperado.txt").write_text("1\n", encoding="utf-8")
inv = collect(root)
self.assertIn("novo", inv.by_name)
self.assertIn("BG_NOVO", inv.by_name)
Evidência indireta
Estes símbolos chamam/encaminham para este nome. As referências deles ajudam a rastrear o caminho, mas não substituem um teste específico deste símbolo.
Compiladores, padrão C e sistema operacional
Nenhum ramo condicional externo foi detectado para este símbolo. A implementação é compartilhada no fonte; isso não certifica compiladores ou sistemas não executados.
- Script Python: usa a biblioteca padrão e pathlib/subprocess quando aplicável; caminhos não devem depender do separador de um único OS.
A matriz histórica distingue executado, compilado, avaliado e não testado. Consulte a matriz, os compiladores e os logs atuais dos workflows antes de chamar um alvo de suportado.
Perguntas frequentes
Perguntas reunidas a partir da definição, do contrato editorial e dos testes de collect. As respostas repetem apenas o que o repositório mostra; quando não há evidência, isso é dito.
Em uma frase, o que collect faz?
Coleta fontes, símbolos, referências, casos, modos e exemplos do repositório.
Qual é a assinatura e o tipo de retorno de collect?
Assinatura extraída de tools/documentacao/analise.py; visibilidade pública.
def collect(root: Path) -> Inventory:
Como collect aparece em código real deste repositório?
Uso extraído de tests/documentacao/test_gerador.py:6, com as linhas vizinhas preservadas:
from pathlib import Path
from tools.documentacao.analise import collect
from tools.documentacao.render import Renderer, protect
from tools.gerar_documentacao import check_outputs, clean_managed_output, tree_digest
Onde collect é exercitado nos testes?
Há 3 ocorrência(s) em 1 arquivo(s): tests/documentacao/test_gerador.py. Os links da seção de evidência apontam para a linha exata; uma menção não prova que todos os ramos foram executados.
collect depende de compilador, padrão C ou sistema operacional?
collect é uma função Python: requer Python 3.10+ e biblioteca padrão, sem compilador C.
O que acontece em caso de falha ou uso inválido?
Não há ressalva editorial específica para este nome. O comportamento em falha é o do corpo/expansão mostrado acima; não invente validação que o fonte não faz.