Pular para conteúdo

v0.11.0 — GitHub Analyzer 2.0

Objetivo

A v0.11.0 implementa a base do GitHub Analyzer 2.0: um módulo backend para análise mais profunda de repositórios públicos, inspirado no nível de pipeline do REPOLOGS, mas adaptado ao objetivo do SotuHire: carreira, currículo, vaga e evidência profissional.

A extensão continua sem carregar toda a inteligência. Ela funciona como ponte e sinaliza quando o backend local deve tentar a análise por GitHub API.

Estado implementado

  • modules/github_analyzer/github_client.py: parse de URL, metadados, linguagens, árvore, raw files e GITHUB_TOKEN opcional.
  • modules/github_analyzer/tree_builder.py: árvore textual, marcadores e sinais de README, testes, CI, Docker, docs, licença, manifests e segurança.
  • modules/github_analyzer/file_filters.py e file_sampler.py: filtros de ruído/binários e seleção priorizada de README, manifests, workflows, source, tests e docs.
  • modules/github_analyzer/dependency_graph.py: imports Python e JS/TS heurísticos para detectar arquivos centrais.
  • modules/github_analyzer/context_builder.py: payload para provider/Prompt Registry com metadata, sinais, árvore, arquivos e contexto de vaga/carreira.
  • modules/github_analyzer/evidence_index.py: claims com fonte, tipo e confidence, incluindo possível segredo exposto.
  • modules/github_analyzer/scoring.py: scores finais calculados por código, com caps de segurança e testes.
  • modules/github_analyzer/analyzer_service.py: pipeline orquestrado com fallback para sinais capturados pela extensão.
  • Local Companion API: usa o Analyzer 2 quando analysis_result.use_github_api vem no payload, mantendo fallback legado.

Problema atual

A análise de GitHub da v0.9.0 é útil, mas ainda pode ser simples demais se depender principalmente de:

  • DOM visível;
  • README;
  • commits visíveis;
  • topics;
  • linguagens;
  • heurísticas locais;
  • prompt curto de refinamento.

Isso ajuda como fallback, mas não avalia o repositório em profundidade.

Direção correta

Extensão captura owner/repo -> backend busca via GitHub API -> sampler seleciona arquivos -> IA analisa JSON -> código calcula scores -> SotuHire salva evidências.

Arquitetura proposta

modules/github_analyzer/
  github_client.py
  tree_builder.py
  sampler.py
  dependency_graph.py
  context_builder.py
  schemas.py
  prompts.py
  scoring.py
  service.py

Fluxo

flowchart TD
    A[URL do GitHub] --> B[Extract owner/repo]
    B --> C[GitHub API metadata]
    C --> D[Full repository tree]
    D --> E[Directory tree filtered]
    E --> F[Priority file sampler]
    F --> G[Raw file reader]
    G --> H[Dependency graph]
    H --> I[Context builder]
    I --> J[Structured AI prompt]
    J --> K[Pydantic validation]
    K --> L[Scoring engine]
    L --> M[Career evidence]
    M --> N[Memory + Tracker + UI]

GitHub Client

Responsável por:

  • buscar metadados do repositório;
  • buscar branch padrão;
  • buscar árvore completa pelo SHA;
  • buscar conteúdo raw de arquivos selecionados;
  • respeitar limites;
  • aplicar cache por commit SHA;
  • tratar repo inexistente ou privado sem permissão.

Tree Builder

Deve gerar:

  • árvore completa filtrada;
  • contagem por tipo de arquivo;
  • presença de testes;
  • presença de docs;
  • presença de CI;
  • presença de Docker;
  • presença de manifests;
  • presença de arquivos de segurança;
  • presença de exemplos.

File Sampler

Prioridade máxima:

  • README;
  • pyproject.toml;
  • package.json;
  • requirements.txt;
  • go.mod;
  • Cargo.toml;
  • pom.xml;
  • build.gradle;
  • tsconfig.json;
  • Dockerfile;
  • docker-compose.yml;
  • .github/workflows/*;
  • arquivos principais de entrada;
  • arquivos centrais importados por muitos outros.

Ignorar:

  • node_modules;
  • dist;
  • build;
  • .venv;
  • pycache;
  • arquivos binários;
  • imagens;
  • arquivos compactados;
  • lock files grandes;
  • outputs gerados;
  • dumps;
  • arquivos acima do limite configurado.

Dependency Graph

O grafo deve detectar sinais simples:

  • imports Python;
  • imports JS/TS;
  • require;
  • exports;
  • módulos centrais;
  • arquivos com alto in-degree;
  • entrypoints.

Não precisa ser perfeito. Ele serve para priorizar arquivos, não para compilar o projeto.

Prompt estruturado

Usar github_repo_analysis_v2 no catálogo de prompts.

A IA deve retornar:

  • resumo executivo;
  • project type;
  • stack detectada;
  • dimension scores;
  • reasoning por dimensão;
  • segurança;
  • documentação;
  • testes;
  • arquitetura;
  • manutenibilidade;
  • valor de portfólio;
  • evidências para currículo;
  • bullets seguros;
  • alinhamento com vaga;
  • inconsistências;
  • recomendações priorizadas;
  • índice de evidências.

Scores

Separar pelo menos:

  • Technical Quality Score;
  • Portfolio Value Score;
  • Resume Evidence Score;
  • Recruiter Readiness Score;
  • Job Alignment Score;
  • Security Risk Level;
  • Documentation Score;
  • Test Signal Score.

O score final não deve ser decidido apenas pela IA.

Regra:

A IA retorna dimension_scores e reasoning.
O código calcula scores finais e aplica travas de calibração.

Evidências

Toda afirmação importante deve ter fonte.

Exemplo:

{
  "claim": "Demonstra uso de CI/CD",
  "source_file": ".github/workflows/ci.yml",
  "evidence_type": "workflow",
  "confidence": 0.91
}

Comparação com vaga

Modo especial:

Repo + currículo + vaga -> quais requisitos esse projeto comprova?

Saída esperada:

  • requisitos atendidos pelo repo;
  • requisitos não comprovados;
  • bullets seguros para currículo;
  • pontos para entrevista;
  • melhorias no README para recrutador;
  • gaps técnicos do projeto.

UI no site

Criar página:

Portfólio / GitHub Analyzer

Ações:

  • analisar repo por URL;
  • analisar perfil GitHub;
  • comparar repo com vaga;
  • comparar GitHub com currículo;
  • gerar bullets para currículo;
  • salvar evidência no perfil;
  • abrir relatório completo.

Extensão

A extensão deve:

  • extrair URL;
  • detectar owner/repo;
  • chamar Local Companion API;
  • mostrar resumo;
  • abrir relatório no site.

Ela não precisa implementar o pipeline inteiro.

TypeScript

Migrar a extensão para TypeScript é uma melhoria de manutenção, não requisito funcional.

Benefícios:

  • contratos de payload mais claros;
  • menos erro em content scripts;
  • melhor build;
  • integração com schemas compartilhados;
  • melhor organização.

Mas a prioridade é o backend Python fazer a análise profunda.

Critério de pronto

A v0.11.0 está pronta quando:

  • repo por URL é analisado pelo backend;
  • árvore completa é coletada pela GitHub API quando disponível;
  • sampler seleciona arquivos relevantes;
  • Prompt Registry registra github_repo_analysis_v2 e o JSON Guard valida sua saída;
  • score final é calculado por código;
  • evidências por arquivo aparecem no relatório;
  • análise pode ser salva na Career Memory pelo fluxo existente de projeto/portfólio;
  • contexto de vaga/cargo pode entrar no context builder para job alignment;
  • extensão continua funcionando como ponte.

Pendências naturais para v0.12+

  • UI dedicada para comparar repo com vaga/currículo diretamente no site.
  • Pipeline profundo para perfil GitHub completo, além do fallback heurístico atual.
  • Portfolio Gap Analysis consolidando vários repositórios e objetivo profissional.