words-highlight-c

Documentação da Extensão - Análise de Erros em Arquivos de Quest e Missões

Visão Geral

Esta extensão foi desenvolvida para analisar arquivos de quests e mission, identificando padrões de erros e inconsistências com base em uma lista de tokens e palavras reservadas. Ela utiliza o módulo do Visual Studio Code (VS Code) para prover diagnóstico, descrição de funções e sugestão de palavras, ajudando o time de produto a criar scripts de quest e mission.

Estrutura do Projeto

Arquivo Principal: extension.ts - Contém o código central da extensão, incluindo as funções de análise e o provedor de tokens.

A função Activate define tudo o que será executado pela extensão quando for iniciada. 
1. Ler todos os arquivos e instanciar todas as quests.
2. Analisar cada documento usando o Quest.provideDocumentSemanticTokens().
3. Definir na variável "context" quais são as funções que estarão disponiveis na extensão.

Neste arquivo estão os códigos de cada provider da extensão.

Utilitários: Localizados em utils/, contêm listas de métodos, palavras reservadas e regex para análise. itemnames.ts -> Arquivo utilizado pelo hoverprovider para exibir o nome de um item

messages.ts -> Menssagens utilizadas em diversos lugares diferentes mas que devem ser sempre iguais.

methodsParams.ts -> Arquivo muito importante, alterações devem ser feitas com cuidado para não gerar inconsistências. A intenção deste arquivo é guardar a documentação de cada função existente em https://docs.google.com/spreadsheets/d/16DQ0zBoRJSLQBn_7pBddWh8pqc4U6BK9DaVkHOI3ex0/edit?gid=0#gid=0. 

MissionNpcList -> Contém o id e nome de cada npc, utilizado principalmente pelo hoverprovider.

Regex -> Arquivo que guarda as regex que são usadas para classificar cada token. Guarda tambem listas dos tipos de funções. A extensão faz uso extensivo de expressões regulares para identificar diferentes tipos de erros, como formatação incorreta de métodos, uso indevido de parâmetros e condições não válidas.

utils -> Contem principalmente as funções que são utilizadas para checar os parâmetros de cada palavra reservada classificada como um método de presente nos scripts, por exemplo, "SPEECH", "ITEM" e etc.

Interfaces -> Guarda as interfaces utilizadas no projeto, a principal delas é o Token, que armazena a palavra, as coordenadas da palavra, o documento, o tipo e todos os diagnósticos que devem ser exibidos em suas coordenadas. 

Classes de Suporte: Localizadas em class/, definem estruturas como Quest e utilitários de análise lexical.

Principais Componentes

mySemanticProviderQuest: Implementa DocumentSemanticTokensProvider para fornecer tokens semânticos baseados em padrões específicos de quests.
Condition: Classe que armazena a função e o indice de cada condition em uma quest para ajudar a checar repetições, também guarda os metodos utilizados naquela função.
Rewards: Classe utilizada para registras todas as rewards presentes em uma quest. O bjetivo é facilitar a checagem de repetiçoes.
Quest: Classe principal utilizada para armazenar todas as informações de uma quest. Facilitando a checagem das regras em cada uma. Há uma variável chamada quests que é um objeto do tipos {key:Quest}, em que a key vai ser sempre o nome da quest("QUEST003" ou  "QUEST50"), funciona em um escopo global e cada alteração em um documento deve ser registrado na quest correta dentro de quests.

Masters: Principais "classes" utilizadas pelo provider semântico de quest.

Lexer: Tem o código que classifica cada token em um tipo
Parser: Tem o código que verifica se uma linha esta formada da maneira correta que pode ser:
1 - QUEST questMethod Params
2 - QUEST CONDITION conditionMethod Params
3 - QUEST REWARD Porcent Porcent rewardMethod Params
O parser tenta descobrir se a linha está em um desses formatos e aplica diagnosticos de erro em tokens que não estejam em conformidade. 
Após passar pelo Lexer e Parser, se o token não estiver classificado em um tipo receberá um diagnóstico de erro.

checkLine    (Parser): Função que checa se uma linha está "bem formada"
checkTypes   (Parser): Checa se há algum token com tipo não identificado e em caso positivo infere um erro.
classifyToken (Lexer): Classifica tokens individuais com base nos padrões e palavras reservadas.

Regras para execução: No arquivo package.json estao as configurações de todos os tipos aceitos e as regras para que a extensão funcione. As analises da extensão só serão aplicadas em arquivos .c dentro de uma pasta chamada "Quest", seguindo a seguinte expressão regular -> Quest/*.c

Configuração e Execução Pré-requisitos Node.js instalado. VS Code instalado com o módulo TypeScript. Dependências listadas em package.json. Passos para Configurar o Projeto Clone o repositório. Execute npm install para instalar as dependências. Compile e execute a extensão no VS Code.

Como executar/debugar:

1. Abra o arquivo extension e tecle F5, a extensão será buildada e uma nova janela do vscode será aberta rodando a versão atual da extensão. Caso o F5 não funcione, na aba de degub do vscode você pode usar a opção Run Extension.
2. Ao abrir uma nova janela, abra o um arquivo com extensão .c dentro de uma pasta chamda "Quest".

Como publicar:

1. Para buildar uma nova versão da extensão é fundamental alterar no arquivo package.json o campo version.
2. Após fazer as alterações que desejava e testa-las, você pode utilizar o comando vsce package para gerar o arquivo com a nova versão.
3. Para publicar a extensão é preciso logar na conta da raidhut em https://marketplace.visualstudio.com/manage selecionar a extensão e fazer um update.
4. Se for preciso, você pode instalar a versão localmente antes de publica-lá usando o seguinte comando: code --install-extension words-highlight-c-0.0.0.vsix