Metadata-Version: 2.4
Name: pyinspect-code
Version: 0.2.0
Summary: Understand Python code without reading every line
Author: PyInspect Contributors
License: MIT
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.10
Description-Content-Type: text/markdown

# PyInspect

> **PyInspect — Understand Python code without reading every line.**

PyInspect é uma biblioteca e CLI open source para compreender rapidamente projetos Python por meio de análise estática baseada em AST. Ela descobre módulos, funções, classes, imports, chamadas, heranças, ciclos de importação e possíveis pontos de complexidade sem executar o código analisado por padrão.

## Instalação

```bash
pip install .
```

## Uso rápido

A interface visível da CLI — resumo, ajuda, avisos, erros amigáveis, exportações e mensagens do servidor local — está disponível em **português do Brasil**. Os nomes técnicos dos comandos e opções permanecem em inglês para preservar a compatibilidade, como `scan`, `analyze`, `tree`, `graph`, `export` e `serve`.

```bash
pyinspect ./meu_projeto
pyinspect scan ./meu_projeto
pyinspect analyze ./meu_projeto
# análise profunda: complexidade, dependências, qualidade, estrutura e grafo
pyinspect verify ./meu_projeto/arquivo.py
# explica o comportamento provável do arquivo por análise AST, sem executá-lo
pyinspect graph ./meu_projeto
pyinspect dead-code ./meu_projeto
pyinspect export ./meu_projeto --format json --output report.json
```

### Verificação sem execução

`verify` pode receber um arquivo ou um diretório. Em arquivos Python e Python stub, usa AST para explicar propósito provável, dependências, entradas, saídas, efeitos observáveis, fluxo, funções, classes, chamadas importantes, sinais de atenção e limitações. Em diretórios, reúne uma visão geral dos módulos e componentes encontrados.

```bash
pyinspect verify arquivo.py
pyinspect verify ./meu_projeto
pyinspect verify pyproject.toml
pyinspect verify config.json
```

A extensão determina o analisador: `.py`/`.pyi` usam Python/AST; `.toml`, `.json`, `.yaml` e `.yml` são tratados como dados estruturados; JavaScript, TypeScript, Java, C/C++, Rust, Go, PHP, Ruby, Shell, SQL, HTML e CSS recebem análise textual/estrutural quando não houver parser semântico específico. O arquivo nunca é executado. Possíveis tokens, senhas e chaves são detectados como sinais e mascarados, sem exibição integral.

Para abrir o relatório localmente:

```bash
pyinspect serve ./meu_projeto
```

## API Python

```python
from pyinspect import Project

project = Project("./meu_projeto")
result = project.scan()
print(project.files)
print(project.functions)
print(project.classes)
print(project.graph)
print(project.callers("process_payment"))
print(project.callees("process_payment"))
```

## Configuração

Opcionalmente, crie `.pyinspect.json` na raiz do projeto analisado para adicionar diretórios ignorados:

```json
{"ignore": ["generated", "vendor"]}
```

A versão 0.2.0 também gera um relatório HTML local com busca de entidades, filtragem por tipo de relação, resumo de problemas e visualização textual do grafo. O comando `verify` explica o comportamento provável de qualquer arquivo Python: propósito inferido, fluxo de dados, entradas, saídas, efeitos observáveis, chamadas, funções, classes, dependências e decisões. A explicação usa evidências genéricas do AST, não depende de `print`, Discord ou de um framework específico, e sempre informa suas limitações. O arquivo não é executado.

O comando `analyze` apresenta uma análise aprofundada com linhas de código, complexidade por função e arquivo, dependências internas e externas, ciclos, código possivelmente não utilizado, estrutura, heurísticas de qualidade, grafo e possíveis pontos de entrada. Diretórios de build e distribuição, incluindo `dist_pimcord`, `.dist_pimcord` e variantes `dist_*`, são ignorados por padrão; regras adicionais podem ser definidas em `.pyinspect.json`.

## Limitações

A análise é estática e deliberadamente conservadora. Imports dinâmicos, reflexão, `getattr`, decorators, plugins e convenções específicas de frameworks podem impedir que o uso real de uma função ou classe seja determinado. Por isso, os diagnósticos de código não utilizado são sempre apresentados como possibilidades, e não como provas definitivas.

## Roadmap

A V1 concentra AST, projeto, grafo, CLI, exportação, cache básico e relatório web local. A versão atual do pacote é 0.2.0 e mantém a análise offline como núcleo. Evoluções futuras podem incluir tracing opcional em runtime, integração com Git, comparação entre versões, plugins e integração opcional com LLM.

## Desenvolvimento

```bash
pip install -e .
python -m unittest discover -s tests -v
```

Licença MIT.
