Skill Map 🧭

O Skill Map transforma sinais públicos de repositórios do GitHub em um mapa explicável das tecnologias praticadas por um desenvolvedor.

A aplicação não tenta adivinhar senioridade. Ela mostra evidências: linguagens, recorrência entre projetos, topics, atividade, estrelas, forks e variedade.

Funcionalidades

• Análise de um usuário público do GitHub.
• Coleta de repositórios que não sejam forks nem arquivados.
• Pontuação de linguagens e tecnologias.
• Radar visual com as principais habilidades.
• Evidências por skill.
• Ranking dos repositórios mais fortes.
• Histórico local das análises.
• API REST.
• Testes, Docker e CI.

Stack

• Python 3.11+
• FastAPI
• SQLAlchemy 2
• SQLite
• HTTPX
• Jinja2
• JavaScript e SVG puros
• Pytest
• Ruff
• Docker

Como executar

git clone <url-do-seu-repositorio>
cd skill-map

python -m venv .venv

Ative o ambiente virtual:

# Linux ou macOS
source .venv/bin/activate

# Windows PowerShell
.venv\Scripts\Activate.ps1

Instale e inicie:

pip install -r requirements-dev.txt
uvicorn app.main:app --reload

Abra:

• Aplicação: http://127.0.0.1:8000
• Swagger: http://127.0.0.1:8000/docs
• Health check: http://127.0.0.1:8000/health

Token do GitHub

Sem token, a aplicação ainda pode consultar dados públicos, mas fica sujeita a um limite menor de requisições.

Crie um arquivo .env baseado em .env.example ou defina a variável:

export GITHUB_TOKEN="seu_token"

No PowerShell:

$env:GITHUB_TOKEN="seu_token"

O MVP não precisa de permissões para repositórios privados.

Dados de demonstração

python seed.py

Testes e lint

pytest
ruff check .

Docker

docker compose up --build

Para usar um token com Docker:

GITHUB_TOKEN="seu_token" docker compose up --build

API

Método	Endpoint	Ação
POST	/api/analyses	Criar análise
GET	/api/analyses/{id}	Consultar análise
GET	/api/users/{username}/latest	Última análise do usuário
GET	/health	Verificar disponibilidade

Exemplo:

curl -X POST http://127.0.0.1:8000/api/analyses \
  -H "Content-Type: application/json" \
  -d '{"username":"octocat"}'

Como a pontuação funciona

A pontuação é uma heurística explicável. Ela combina:

• Quantidade relativa de código por linguagem.
• Presença da tecnologia em vários repositórios.
• Variedade de linguagens.
• Atividade recente.
• Topics declarados.
• Estrelas, forks, tamanho e licença do projeto.

Uma nota alta significa que foram encontrados mais sinais públicos, não que o desenvolvedor recebeu um selo mágico de domínio absoluto.

Próximas evoluções

• Login com GitHub.
• Análise de repositórios privados autorizados.
• Comparação entre duas análises.
• Linha do tempo de evolução.
• Detecção de testes e CI pela árvore de arquivos.
• Exportação do mapa como imagem ou PDF.
• Página pública compartilhável.
• Recomendações de próximos projetos.
• Integração com README de perfil.

Licença

MIT.