Code Insight

Para uma explicação sem detalhes técnicos, leia o guia do Code Insight: o que faz e como usar.

Extensão para Visual Studio Code que acompanha migrações estruturais Angular e padrões de interface em HTML e templates Angular, com relatórios em Excel e JSON. Em desenvolvimento — MVP 0.1.0, ainda não publicado no Marketplace.

Identifica componentes Standalone, padrões antigos e destinos presentes no código, indicando os arquivos que precisam de revisão. Os percentuais descrevem o código encontrado; não comprovam substituições históricas. A análise é estática: não modifica código nem executa scripts do projeto.

Escolha o fluxo de análise

O comando codeInsight.analyzeProject executa o fluxo completo. Os fluxos estrutural e completo exigem Angular; quando não o identificam, orientam a usar UI Migration. As exportações Excel e JSON funcionam para o último relatório de qualquer fluxo.

Para acompanhar a migração: comece por Resumo → Rotas → Pendências. A coluna Standalone responde sobre o componente; Status final considera também dependências locais, templates e UI. Uma rota pode ter Standalone = Sim e continuar Parcial. Detalhes Rotas preserva arquivos, posições, regras, guards e metadados. Veja o contrato da auditoria e exemplos.

Complete e Route Analysis executam as três análises novamente. Rodar Rotas depois de Complete não esvazia Estrutural/UI nem mistura dados antigos. Complete sem rotas informa 0 rotas analisadas. Nos fluxos individuais estrutural/UI, rotas ficam Não analisado.

Suporte atual de UI: arquivos .html e templates Angular inline/externos. Todos os HTML dentro do escopo são analisados, mesmo sem referência de um componente. Templates externos compartilhados contam uma vez. O motor de regras é independente de framework, mas os adaptadores JSX/TSX (React), Vue e Svelte ainda não estão implementados. Esses arquivos são sinalizados como não analisados. Folhas CSS e DOM em execução também não são analisados.

Os percentuais têm significados diferentes: estrutural mede componentes Standalone; UI mede destinos encontrados sobre origens + destinos. O indicador geral pondera ambos pelas quantidades dos fluxos executados. Nenhum deles comprova a correção funcional da migração; módulos encontrados não são classificados como módulos pendentes de remoção.

Funcionalidades

• Quatro fluxos de análise, com progresso e cancelamento.
• Mapa de rotas Angular por AST, incluindo routing.ts com extensões de menu, loadChildren para rotas ou módulos e relação componente → rotas. Veja o guia de Angular Route Analysis.
• Detecção por package.json, angular.json ou decorators importados de @angular/core.
• Standalone explícito e defaults por versão: antes do Angular 19, false; a partir do 19, true.
• Inventário de NgModules e componentes associados por símbolos, incluindo imports relativos, aliases, barrels e arrays simples.
• Motor extensível de regras por elemento, classe, atributo e valor de atributo em templates inline e arquivos referenciados por templateUrl.
• Detecção de origens e destinos, prioridade de regras e métricas por arquivo.
• Relatório em Output → Code Insight e Code Insight: Export Report, com Excel recomendado e JSON para integrações.
• IDs, schema versionado e data UTC para análise histórica.
• Seleção de pasta em workspaces com múltiplas raízes; alterações não salvas em documentos abertos entram no snapshot.

Instalação

Para usar a extensão, você precisa do VS Code 1.96+ para desktop ou com host remoto compatível. VS Code Web não é suportado neste MVP.

1. Abra no VS Code a pasta do projeto que deseja analisar.
2. Para analisar UI, crie .code-insight.json nessa pasta com suas regras de migração.
3. Abra a paleta de comandos (Ctrl+Shift+P) e escolha um dos quatro fluxos de análise.
4. Confira o resultado em Output / Saída → Code Insight, incluindo os avisos.
5. Execute Code Insight: Export Report, escolha Excel ou JSON e selecione onde salvar.

Para obter estrutura e UI juntas em Angular, use Code Insight: Analyze Project — Complete (Angular only). Para HTML sem Angular, use Code Insight: UI Migration (HTML / Angular templates). Depois de alterar o código ou as regras, execute a análise novamente.

Configuração de regras

Projetos em Angular 15

A análise estrutural atende projetos Angular 15. Nessa versão, standalone: true identifica um componente Standalone; standalone: false ou a ausência do campo identificam um componente não Standalone. Valores dinâmicos que não podem ser determinados ficam inconclusivos. O percentual acompanha quantos componentes encontrados são Standalone, não a atualização da versão do Angular nem toda a migração da aplicação.

O padrão implícito só muda para true no Angular 19. Veja a documentação oficial de componentes.

Arquivo de configuração UI

Crie .code-insight.json na raiz da pasta analisada para os fluxos UI, completo e rotas. Nenhuma regra ou destino corporativo é habilitado por padrão. Sem regras habilitadas, a auditoria não declara o layout concluído. Os destinos abaixo são exemplos: substitua target por qualquer destino desejado, sem alterar o código da extensão.

{
  "migrationRules": [
    { "id": "input", "type": "element", "source": "input", "target": "meu-input", "enabled": true },
    { "id": "material-icon", "type": "class", "source": "material-icon", "target": "sisbr-icon", "enabled": true },
    { "id": "mat-input", "type": "attribute", "source": "matInput", "target": "outro-input", "targetType": "element", "enabled": true },
    { "id": "legacy-icon", "type": "attribute-value", "attribute": "data-component", "source": "legacy-icon", "target": "componente-x", "enabled": true }
  ]
}

Entendendo uma regra, campo por campo

migrationRules é a lista de regras que você deseja executar. Os colchetes [] contêm essa lista, e cada objeto entre chaves {} representa uma regra. Você pode adicionar várias regras, separadas por vírgulas.

Considere este objeto da lista:

{
  "id": "input",
  "type": "element",
  "source": "input",
  "target": "meu-input",
  "enabled": true
}

Essa regra significa: “Procure elementos <input> como origens restantes e <meu-input> como destinos encontrados.” A extensão apenas identifica e relata; ela não substitui o código.

id e source têm funções diferentes, mesmo quando usam o mesmo texto. Por exemplo, "id": "migrar-campos-texto" com "source": "input" continua procurando <input>. O identificador da regra também não procura o atributo HTML id.

Para este template:

<input type="text">
<input type="email">
<meu-input></meu-input>

A regra encontra 3 ocorrências: 2 restantes e 1 migrada, resultando em 33,33% de progresso UI. Migrada significa presença do destino, não comprovação de uma substituição acompanhada historicamente.

Como escolher type e source

No último caso, a regra completa seria:

{
  "id": "migrar-icone-antigo",
  "type": "attribute-value",
  "attribute": "data-component",
  "source": "legacy-icon",
  "target": "meu-icone",
  "enabled": true
}

Leia assim: “Procure o atributo data-component com o valor legacy-icon como origem e meu-icone como destino.” Ela encontra <div data-component="legacy-icon"> como pendente e <div data-component="meu-icone"> como migrado. Não corresponde a <div data-component="outro-valor"> nem a <div title="legacy-icon">.

Como escrever o arquivo corretamente

• Coloque os objetos dentro de migrationRules, como no exemplo completo no início desta seção. Um objeto de regra sozinho não é uma configuração completa.
• Use aspas duplas nos nomes dos campos e nos valores de texto: "source": "input".
• Escreva true e false sem aspas: "enabled": false. O texto "false" não é aceito como booleano.
• Separe regras por vírgula, sem vírgula após a última regra. JSON não aceita comentários.
• Não repita o id. Para desativar todas as regras, use {"migrationRules": []}.
• Depois de editar, execute novamente Code Insight: UI Migration (HTML / Angular templates) ou, em Angular, Code Insight: Analyze Project — Complete (Angular only) para gerar um relatório com a configuração atualizada.

Detalhes da correspondência e da contagem

IDs devem ser únicos. source e target devem ser strings não vazias e representar padrões diferentes. enabled é opcional (padrão true); regras desabilitadas não entram no relatório. Classes, nomes de atributos e valores distinguem maiúsculas/minúsculas. Classes devem conter apenas um token; seletores CSS/regex não são interpretados.

Cada elemento é atribuído a uma única regra. Templates externos compartilhados contam uma vez; HTML não referenciado por componentes também entra nas regras de UI. Uma ocorrência de origem tem status pending; uma de destino tem status migrated. A regra fica completed somente quando há destinos encontrados e nenhuma origem atribuída; com zero total, permanece pending.

Destino, prioridade e regras específicas

Primeiro, uma origem tem preferência sobre um destino no mesmo elemento (para não declarar migrado algo que ainda contém o padrão antigo). Entre candidatos do mesmo estado, vence a maior priority; depois a maior especificidade: restrição element, seguida por attribute-value, attribute, class, element. Empates finais são resolvidos pelo id em ordem alfabética, independentemente da ordem da configuração.

Destinos compartilhados por várias regras também pertencem a uma única regra conforme essa ordem. Isso evita inflar o total, mas não permite recuperar a origem histórica daquele destino. Mantenha regras, prioridades e escopo consistentes ao comparar execuções.

{
  "migrationRules": [
    { "id": "input-generico", "type": "element", "source": "input", "target": "meu-input" },
    { "id": "input-material", "type": "attribute", "element": "input", "source": "matInput", "target": "meu-input-material", "targetType": "element", "priority": 10 }
  ]
}

O progresso UI é resolvedOccurrences / totalOccurrences × 100, arredondado a duas casas. Zero total retorna 0%. Com 3 origens e 2 destinos, total = 5 e progresso = 40%. O progresso geral é (Standalone + destinos UI) / (componentes encontrados + ocorrências UI) × 100, considerando somente fluxos executados. Trata-se de uma ponderação por itens heterogêneos, não de média simples nem estimativa de esforço restante.

O scanner ignora comentários, interpolação e markup dentro de valores de atributos ou conteúdo script/style/textarea/title. Não avalia [ngClass], [class], [class.nome] ou expressões Angular; nomes de bindings só correspondem se configurados literalmente (por exemplo [matInput]). Valores interpolados não são tratados como valores estáticos. Entidades HTML não são decodificadas nesta versão.

O arquivo é lido a cada análise, incluindo alterações não salvas em documento aberto. Em workspaces com várias raízes, usa-se somente a configuração da pasta selecionada. JSON inválido, IDs duplicados, tipos desconhecidos e campos inválidos interrompem a análise com mensagem de erro.

Compatibilidade: quando .code-insight.json não existe, codeInsight.componentMappings no settings.json continua funcionando como regras element. Quando o arquivo existe, ele substitui os mapeamentos por completo, inclusive com {"migrationRules":[]}. Veja configuração de exemplo.

Exemplo de relatório

Trecho ilustrativo do fluxo completo, com dados fictícios:

CODE INSIGHT
Projeto: meu-projeto
Fluxo: Análise completa — exclusivo Angular

MIGRAÇÃO ESTRUTURAL — ANGULAR

Componentes encontrados: 120
Standalone: 75
Não Standalone: 45
Inconclusivos: 0
Progresso estrutural: 62,5%

Modules encontrados: 18
Componentes declarados em NgModules: 45

MIGRAÇÃO DE INTERFACE — UI
[element] input → meu-input: total 5, migrados 2, restantes 3, progresso 40%
  src/app/form.html:1:1 — Pendente
  src/app/form.html:2:1 — Pendente
  src/app/form.html:3:1 — Pendente
  src/app/form.html:4:1 — Migrado
  src/app/form.html:5:1 — Migrado
Total de ocorrências de regras: 5
Progresso UI: 40% (destinos encontrados / total; não é comprovação histórica).

Progresso geral: 61.6% (ponderado por componentes e ocorrências dos fluxos executados).

Como interpretar o relatório

Os quatro comandos exportam schemaVersion 5, preservando structural, ui e a árvore routes dos schemas anteriores. audit.items reúne os itens únicos e cada nó de rota contém audit com referências aos itens, dependências e status final. Complete e Rotas incluem structural, ui e routes, inclusive quando a árvore está vazia. Veja modelo e compatibilidade.

• structural: análise Angular, ou null quando não executada. Métricas em structural.angular, detalhes em structural.components e structural.modules, avisos em structural.warnings.
• ui: análise de interface, ou null quando não executada. Contém supportedFormats, analyzedTemplates, totalRules, migrationRules, totalOccurrences, resolvedOccurrences, remainingOccurrences, progressPercentage, files (métricas por arquivo/regra) e warnings.

null significa não executado, não zero problemas. O objeto estrutural preserva o formato interno anterior (schema 1); sua lista migrationRules fica vazia, pois as regras executadas estão em ui.migrationRules. As tabelas abaixo descrevem os campos dentro dessas seções. Ao importar relatórios antigos, adapte os caminhos conforme a versão do documento. Compare apenas execuções com fluxo, regras e escopo equivalentes.

Comece pelos avisos, confira os componentes inconclusivos e depois interprete o percentual. Os números representam o que o analisador conseguiu identificar no escopo escolhido; não são uma validação de que a aplicação compila ou de que a migração está concluída.

Métricas de componentes e módulos

Os campos abaixo ficam dentro de structural.angular no JSON atual:

totalComponents = standaloneComponents + moduleComponents + unknownComponents. Já declaredModuleComponents é uma contagem separada: não deve ser somada às outras. Ela pode diferir de moduleComponents por declarações não resolvidas, componentes sem associação identificada ou inconsistências no projeto.

O que significa unknownComponents?

Significa classificação inconclusiva, não necessariamente erro no componente. Exemplos:

@Component({ standalone: algumaVariavel }) // O valor não é um booleano literal.
class ExemploA {}

@Component(configuracao) // Os metadados estão em outro objeto.
class ExemploB {}

@Component({ template: '<p>Olá</p>' }) // Sem standalone explícito:
class ExemploC {}                     // depende da versão Angular identificada.

No último exemplo, o componente só fica inconclusivo se a versão necessária para inferir o padrão não puder ser identificada. Spreads como @Component({ ...configuracao }) também podem impedir a classificação.

Para investigar, procure standalone: null em structural.components e leia os avisos em structural.warnings. Confira a declaração de @angular/core no package.json e os metadados do componente indicado. Se o código estiver correto, o resultado pode refletir uma limitação da análise estática; não altere standalone apenas para eliminar o aviso.

Como o percentual é calculado?

Fórmula: standaloneComponents / totalComponents * 100, arredondada a duas casas decimais. Com zero componentes, retorna 0%.

Exemplo: 10 componentes encontrados, sendo 6 Standalone, 3 não Standalone e 1 inconclusivo, resultam em 60%. O inconclusivo permanece no total, mas não conta como migrado. Os outros 40% incluem tanto componentes não Standalone quanto componentes ainda sem classificação.

100% significa que todos os componentes encontrados foram classificados como Standalone. Ainda podem existir NgModules, regras com ocorrências e dependências de módulos: um componente Standalone pode importar NgModules. Arquivos ou padrões fora do alcance do analisador também não são cobertos por essa conclusão.

Detalhes de componentes e módulos

Resultados das regras de migração

Zero total significa que a regra não recebeu correspondências no escopo e prioridades atuais. Não comprova conclusão: status permanece pending.

O total soma ocorrências atribuídas sem repetir elementos. Por exemplo, <input matInput> é atribuído à regra específica de atributo, a menos que uma prioridade explícita favoreça outra regra. Regras desabilitadas não aparecem no relatório.

Avisos e próximos passos

structural.warnings e ui.warnings contêm situações que merecem revisão em cada fluxo executado. O campo warnings na raiz do JSON reúne os avisos dos dois fluxos, sem mensagens idênticas repetidas; as listas por área são preservadas. Um aviso não significa automaticamente que o código esteja errado, mas pode indicar que parte do relatório está incompleta.

Uma lista warnings vazia não elimina as limitações descritas mais abaixo. Já uma configuração de regras inválida ou uma falha de leitura que interrompa a execução impede a geração de um novo relatório: corrija a mensagem apresentada e execute a análise novamente.

Informações gerais da análise

Exportação Excel e JSON

Execute Code Insight: Export Report após qualquer análise. Selecione Excel (.xlsx) para leitura humana ou JSON (.json) para integrações. O Excel aparece primeiro, como opção recomendada. Escolha o local no diálogo; se o arquivo existir, a extensão confirma a substituição. Cancelar a escolha ou a geração não grava um novo arquivo.

Os nomes sugeridos são Code-Insight-Report.xlsx e Code-Insight-Report.json. O comando Code Insight: Export JSON Report continua disponível como atalho direto.

O Excel é um .xlsx real, gerado com ExcelJS em uma worker. Possui títulos, linhas alternadas, bordas discretas, colunas ajustadas ao conteúdo com limite de largura, filtros, cabeçalhos congelados, números/percentuais formatados e barras de progresso. Textos provenientes do projeto são gravados como texto, sem fórmulas executáveis.

Sem análise estrutural/UI, os indicadores correspondentes mostram “Não executado” ou “Não analisado”; abas detalhadas permanecem com cabeçalhos e explicação. Zero ocorrências é diferente de um fluxo não executado. Não há importação ou persistência automática de histórico nesta fase. O campo opcional history do modelo aceita snapshots com projeto, ID, data, fluxo e percentuais; o Excel inclui apenas snapshots do mesmo projeto e a execução atual. Para preservar análises manualmente, salve arquivos com nomes diferentes.

O exportador rejeita dados que excedam limites de linhas ou texto por célula do Excel em vez de truncar silenciosamente; nesses casos, use JSON.

JSON e histórico

Execute Code Insight: Export JSON Report depois da análise. O diálogo sugere Code-Insight-Report.json. Para preservar histórico, escolha nomes diferentes, por exemplo Code-Insight-Report-2026-09-10.json. Não há gravação automática.

O JSON inclui schemaVersion, analysisId, projectId, projectName, analyzedAt, angularVersions, métricas, componentes, módulos, regras e avisos. Cada execução recebe um novo ID. projectId é um hash da URI da pasta, estável na mesma localização; ao mover/clonar o projeto, normalize esse identificador na ferramenta que consolida o histórico. Caminhos são relativos; conteúdo de código/templates não é exportado.

overallPercentage contém o indicador geral ponderado. history, quando fornecido, contém snapshots anteriores; o comando atual não os persiste nem importa automaticamente. Informações estruturais como angularVersions ficam dentro de structural.

Cada resultado de regra mantém occurrences (contagem) e files, e acrescenta type, attribute quando aplicável e matches com as ocorrências detalhadas:

{
  "ruleId": "mat-input",
  "type": "attribute",
  "source": "matInput",
  "target": "outro-input",
  "file": "src/app/app.component.html",
  "line": 3,
  "column": 1,
  "status": "pending"
}

Linha e coluna começam em 1 e apontam para o início da tag. Em templates inline, apontam para o TypeScript original, inclusive quando há escapes na string. Os detalhes estão em ui.migrationRules[].matches. O schema 3 acrescenta status por ocorrência, detecção de destinos, prioridade e métricas por arquivo; consumidores dos schemas 1/2 devem revisar caminhos e semântica das contagens antes de comparar dados.

Snapshots podem alimentar dashboards/Power BI sem integração direta. Para comparar datas, mantenha escopo e regras consistentes e revise os avisos.

Arquitetura

src/
  analyzers/          Contrato ProjectAnalyzer e implementação Angular
    angular/         Detecção, componentes, módulos e standalone
    rules/           Tipos, configuração, scanner e registro de matchers
  ui-migration/      Analisador UI e adaptadores HTML/Angular independentes
  routes/            Descoberta AST, resolução e árvore de rotas Angular
  commands/          Quatro fluxos de análise, VS Code e exportação
  reports/           Tipos, métricas e renderização texto/JSON/Excel
  export/            Contrato ReportExporter e implementações JSON/Excel
  utils/             AST, leitura assíncrona e controle da worker
  workers/           Análise fora do extension host
  extension.ts       Registro e descarte de recursos
test/                Cenários isolados com node:test

A API do compilador TypeScript fornece AST e símbolos; ExcelJS gera XLSX reais com formatação, recurso ausente nas APIs nativas de Node/VS Code. Node fornece workers, testes e JSON; VS Code fornece busca, leitura, progresso e exportação. ESLint, tipos e @vscode/vsce são ferramentas de desenvolvimento. O override de uuid do ExcelJS usa a versão 11 com correção de segurança e API CommonJS v4 compatível, validada pela geração e reabertura de planilhas com formatação condicional.

As métricas são calculadas no analisador e em migration-metrics.ts, não no Excel. migration-audit.ts correlaciona componentes, imports locais, templates e ocorrências já produzidas pela UI; calcula os status e as referências a itens únicos. route-migration.ts mantém os campos antigos como uma projeção dessa auditoria, sem executar regras novamente. ReportExporter recebe o relatório e retorna bytes; o comando cuida da escolha de destino e gravação pela API VS Code. O Excel apenas apresenta os campos do relatório, sem inspecionar código Angular ou aplicar regras.

RuleEngine coordena matchers por tipo sem depender de Angular ou HTML. Os quatro matchers atuais compartilham o scanner de templates, executado uma vez por template. Para um novo tipo, estenda os tipos/validação e registre um RuleMatcher; o analisador Angular e a agregação dos resultados permanecem os mesmos. Novos domínios, como imports TypeScript, podem ampliar RuleContext e fornecer seu próprio parser. Configurações são dados: não executam plugins ou código do usuário.

Leitura em lotes de 16 arquivos; análise em worker thread. Cancelar encerra a worker. Arquivo acima de 5 MB ou snapshot acima de 100 MB interrompe a análise com erro, sem publicar métricas truncadas. A configuração .code-insight.json tem limite de 1 MB. Os limites também se aplicam ao conteúdo não salvo dos documentos abertos.

Limitações

• Exclui node_modules, dist, out, build, coverage, .git, .vscode, .angular, .code-insight, .d.ts, .spec.ts e .test.ts. Analisa a pasta, não o grafo de um tsconfig. A política de exclusão está isolada para configuração futura.
• Estrutural, rotas e auditoria resolvem aliases locais simples de paths/baseUrl. Não resolvem wrappers/reexports de decorators, chamadas arbitrárias ou templates calculados. Imports locais transitivos são auditados; imports não resolvidos ficam inconclusivos. O escopo de um NgModule inclui suas declarações/exports, sem inferir quais seletores são usados em runtime. CSS, serviços, directives, pipes e pacotes externos não têm auditoria de migração completa.
• Versão vem do package.json mais próximo que declara @angular/core. Versões simples, ^ e ~ com major conhecido são aceitas; intervalos amplos/tags são inconclusivos. Não consulta lockfile/instalação efetiva: verifique a correspondência com a versão usada pelo projeto.
• Scanner HTML é lexical, não o compilador Angular. Sintaxe malformada/construções dinâmicas complexas podem gerar contagens incompletas.
• Erros sintáticos, declarações não resolvidas e templates ausentes geram avisos. A análise não prova que o projeto compila ou que a migração está correta.

Roadmap

• CSV e evolução histórica.
• Regras adicionais para componentes corporativos/Angular Material.
• Directives, pipes, serviços, imports e dependências.
• Dashboard e ações para abrir arquivos/ignorar ocorrências.
• Outros frameworks pelo contrato de analisadores.
• Correções assistidas apenas em etapa futura autorizada.

Contribuição

Para relatar um problema, abra uma issue com um exemplo que permita reproduzi-lo. Para contribuir com o código, consulte o guia de desenvolvimento.

Referências e licença

• Angular: Component
• Angular: migração Standalone
• VS Code: manifesto

Licença MIT, preservada do repositório original.