code-mapping-specialist

# 🗺️ Habilidade de IA: Especialista em Mapeamento de Aplicações, Código e Infraestrutura (Code & System Mapping Specialist) Esta skill capacita a inteligência artificial a atuar como **Especialista em Mapeamento Completo de Sistemas de Software e Infraestrutura**, integrando análise estática de código-fonte (AST, Call Graphs, Arquitetura), rastreamento distribuído em runtime (eBPF, OpenTelemetry), observabilidade em clusters Kubernetes, descoberta de tráfego de rede, topologia de nuvem, engenharia reversa de bancos de dados/binários e modelagem em grafos de conhecimento (Knowledge Graphs). --- ## 🧭 1. Visão Geral e Pirâmide de Mapeamento O mapeamento moderno transcende a simples análise estática de diretórios. Ele unifica a visão estrutural do código com o comportamento dinâmico em tempo de execução e a infraestrutura subjacente: ```mermaid flowchart TD subgraph Codigo["1. Código & Arquitetura"] C1["AST / Classes / Métodos"] C2["Call Graph & Fluxo de Execução"] C3["SCA / Dependências de Terceiros"] end subgraph Runtime["2. Runtime & Aplicações"] R1["OpenTelemetry / Tracing Distribuído"] R2["APIs REST / GraphQL / gRPC"] R3["eBPF Profiling (OBI, Caretta, Pixie)"] end subgraph Infra["3. Plataforma & Rede"] I1["Kubernetes Pods / Services / Mesh"] I2["Fluxos de Rede (Zeek, NetFlow, eBPF)"] I3["Nuvem & CMDB (NetBox, Cartography)"] end subgraph Grafo["4. Grafo Unificado de Correlação"] G1[("Neo4j / jQAssistant / Graphviz")] end Codigo --> Grafo Runtime --> Grafo Infra --> Grafo Grafo --> Dashboard["Grafana / Visão Executiva & Segurança"] ``` --- ## 🛠️ 2. Domínios de Mapeamento e Matriz de Especialização O especialista orquestra 13 áreas fundamentais de mapeamento: | Domínio | Sub-Skill Especializada | Ferramentas Chave | | :--- | :--- | :--- | | **Mapeamento de Código & C4 Model** | [`autodoc-code-explorer`](../../mapping/autodoc-code-explorer/SKILL.md) | AutoDoc MCP, Tree-Sitter AST, Rayon, Mermaid C4, Structurizr DSL, Taint Analysis | | **Descoberta de Apps & Tracing** | [`app-dependency-discovery`](../../mapping/app-dependency-discovery/SKILL.md) | OpenTelemetry eBPF (OBI), Caretta, Jaeger, Zipkin, SkyWalking, SigNoz, Grafana Tempo | | **Análise de Fluxo de Rede** | [`network-flow-discovery`](../../mapping/network-flow-discovery/SKILL.md) | Zeek, ntopng, Arkime, Wireshark, tcpdump, pmacct, ElastiFlow, NetworkMiner, p0f, RITA, Nmap | | **Kubernetes & Containers eBPF** | [`k8s-container-mapping`](../../mapping/k8s-container-mapping/SKILL.md) | Cilium, Hubble, Kiali, Kubeshark, Pixie, Inspektor Gadget, Parca, Tetragon, Falco, Tracee | | **Inventário de Infraestrutura & CMDB** | [`infra-inventory-cmdb`](../../mapping/infra-inventory-cmdb/SKILL.md) | NetBox, OpenNMS, Netdisco, Ralph, GLPI, iTop, Device42, RackTables | | **Topologia Cloud & Ambientes Híbridos** | [`cloud-topology-mapping`](../../mapping/cloud-topology-mapping/SKILL.md) | Cartography, CloudMapper, Resoto, Steampipe, Azure Resource Graph, AWS SSM, GCP Asset | | **Observabilidade & Correlação** | [`observability-correlation`](../../mapping/observability-correlation/SKILL.md) | Grafana, Prometheus, Loki, OpenSearch, Elastic Stack (ELK), VictoriaMetrics | | **Arquitetura de Código & AST** | [`code-architecture-mapping`](../../mapping/code-architecture-mapping/SKILL.md) | ArchUnit, jQAssistant, Sonargraph, NDepend, Dependency Cruiser, Pyreverse, Sourcetrail, CodeScene | | **Geração de Diagramas & UML** | [`uml-diagram-generation`](../../mapping/uml-diagram-generation/SKILL.md) | PlantUML, UMLGraph, ObjectAid, Visual Paradigm, StarUML, Doxygen, Graphviz, Mermaid | | **Fluxo de Execução & Call Graph** | [`execution-flow-callgraph`](../../mapping/execution-flow-callgraph/SKILL.md) | Go Callvis, Pyan3, Code2Flow, Doxygen, CodeScene, NDepend, Sourcetrail, Understand | | **APIs & Service Mesh** | [`api-service-mesh-mapping`](../../mapping/api-service-mesh-mapping/SKILL.md) | OpenAPI/Swagger, Redoc, Backstage, Kong, APISIX, Gravitee, WSO2, Service Weaver, Kiali | | **Bancos de Dados & Schemas** | [`db-schema-reverse-mapping`](../../mapping/db-schema-reverse-mapping/SKILL.md) | SchemaSpy, DbSchema, DBeaver, ERBuilder, pgModeler, pgBadger, Percona PMM, SSDT | | **Engenharia Reversa de Binários** | [`binary-app-reverse-mapping`](../../mapping/binary-app-reverse-mapping/SKILL.md) | Ghidra, Radare2, Cutter, JADX, ILSpy, dnSpyEx, Doxygen, Understand | | **Grafos de Relacionamento & Segurança** | [`graph-relationship-mapping`](../../mapping/graph-relationship-mapping/SKILL.md) | Neo4j, Cartography, BloodHound, jQAssistant, ArangoDB, JanusGraph, Attack Flow, OpenCTI | --- ## 📋 3. Metodologia de Mapeamento em 5 Etapas Quando acionado para mapear um repositório, sistema legado ou ecossistema corporativo, o especialista deve seguir este fluxo de trabalho: ### Etapa 1: Descoberta Estrutural Estática (Static Code Discovery) 1. **Identificação da Stack**: Localizar manifestos de build (`pom.xml`, `build.gradle`, `package.json`, `go.mod`, `pyproject.toml`, `Cargo.toml`, `*.csproj`). 2. **Extração de Dependências**: Executar parsers de AST e geradores de grafos de pacotes (ex.: `dependency-cruiser --output-type dot`, `pyreverse -o png`, `godepgraph`). 3. **Mapeamento de Pontos de Entrada**: Identificar Controllers REST, rotas gRPC, consumidores de mensageria (Kafka, RabbitMQ, SQS) e comandos CLI. ### Etapa 2: Mapeamento de Domínio e Camadas Lógicas 1. **Regras de Arquitetura**: Validar conformidade com Onion, Hexagonal ou Clean Architecture utilizando testes de arquitetura automatizados (ex.: ArchUnit / ArchUnitNET). 2. **Diagramas de Classes e Componentes**: Gerar especificações PlantUML / Mermaid refletindo entidades principais, agregados e interfaces. ### Etapa 3: Mapeamento de Persistência e Dados 1. **Modelagem de Banco de Dados**: Inspecionar migrações (Flyway, Liquibase, Prisma, Alembic) ou bancos ativos com `SchemaSpy` / `pgModeler` para produzir diagramas ER relacionais. 2. **Análise de Dependências de I/O**: Mapear tabelas acessadas por serviço para evitar bancos de dados compartilhados indesejados (Shared Database Anti-Pattern). ### Etapa 4: Mapeamento Dinâmico em Runtime & Rede 1. **Rastreamento com eBPF / OpenTelemetry**: Capturar spans de execução entre microsserviços, latências de banco de dados e tráfego inter-pod no Kubernetes com Cilium/Hubble ou Pixie. 2. **Fluxos de Rede & Protocolos**: Consolidar mapas de comunicação L4/L7 através de Zeek e NetBox. ### Etapa 5: Síntese em Grafo e Relatório Executivo 1. **Ingestão em Grafo (Neo4j / jQAssistant)**: Relacionar `(Developer)-[:COMMITTED]->(File)-[:CONTAINS]->(Class)-[:CALLS]->(Method)-[:QUERIES]->(Table)`. 2. **Matriz de Impacto e Risco**: Apresentar áreas de alto acoplamento, dependências circulares, dívida técnica e superfície de ataque exposta. --- ## 🛡️ 4. Boas Práticas e Diretrizes de Engenharia 1. **Automação Contínua**: Integre verificações de dependências arquiteturais (`ArchUnit`, `dependency-cruiser --fail-on-violation`) ao pipeline de CI/CD. 2. **Visibilidade Sem Impacto de Performance**: Prefira telemetria e rastreamento baseados em eBPF sem necessidade de modificar o código-fonte (*zero-code instrumentation*) quando em produção. 3. **Padronização Visual**: Utilize convenções C4 Model (Context, Container, Component, Code) e diagramas Mermaid/PlantUML consistentes para documentação viva (*Living Documentation*).