eslint-plugin-furnas v2.0.1

eslint-plugin-furnas

Este projeto é um plugin que implementa regras arquiteturais customizadas desenvolvidas pela equipe de inspeção de código de Furnas.

Data: 20/05/2022 Versão: 2.0.0

Instruções e pré-requisitos para instalação e execução

• Pré-requisitos
  • Node - Baixar a versão LTS
  • NPM - Baixar a versão LTS
  • Mocha - Será usado para testes locais
    • $ npm install mocha

Estrutura de pastas da aplicação

sonarregrasreact
└───eslint-plugin-furnas
    ├───.vscode
    ├───docs
    │   └───rules
    ├───helpers
    ├───lib
    │   ├───processors
    │   ├───rules
    │   └───utils
    └───tests
        └───lib
            ├───processors
            └───rules

• O plugin deverá estar previamente instalado antes de qualquer análise estática ou implementação. Portanto, execute o comando $ npm install na pasta eslint-plugin-furnas. Uma pasta nomeada .\node_modules será criada após esse passo.

• Dentro da pasta eslint-plugin-furnas você deverá executar o comando npm link, isso fará que ela fique disponível para instalação em outros projetos. Saiba mais sobre Npm Link

  Vale ressaltar que esse passo deverá ser repetido caso algo seja atualizado no código

Lista de regras implementadas

✔: Disponível com a configuração recomendada

Criação de novas regras

Para criar uma nova regra, é necessária a instalação da biblioteca Yeoman, portanto, execute em seu terminal npm install -g yo.

Após isso, será apenas necessário executar yo eslint:rule e responder às perguntas para criação de uma nova regra

Obs: Durante o desenvolvimento deste projeto, percebemos que as regras devem seguir o padrão de nomenclatura kebab-case

• Documentação das regras EsLint

Testagem local de regras

Para executar os testes do plugin, basta digitar: $ npm test

• Documentação RuleTester
• Documentação de Unit Tests ESLint

Implementação de regras

Para expor as discrepâncias relacionadas no SonarQube de forma apropriada, paralelo ao código .NET

• Documentação SonarScanner for .NET

Habilitando modo debug do Node.js

Caso o modo Debug não esteja funcionando, deleta o diretório ./.vscode Considerando que estamos usando o VSCode como plataforma de desenvolvimento, é possível habilitar o modo debug do Node.js, de maneira interativa seguindo os seguintes passos:

• Instale Mocha no seu ambiente de desenvolvimento: $ npm install mocha
• Na toolbar da esquerda do VSCode, clique em Run and Debug, ou digite Ctrl + Shift + D
• Clique na opção de criar launch.json (será o arquivo que será usado para configurar o debug)
• Adicione a configuração Node.js: Mocha Tests para o debug:
  • Uma configuração será adicionada ao launch.json, basta alterar o caminho dos testes para "${workspaceFolder}/tests/lib/rules"
• Insira o breakpoint.
• No menu de Run and Debug, executar Mocha Tests. O menu de debug será aberto automaticamente.

Execução da análise estática de um projeto

Preparando o projeto para análise

Na pasta raiz do projeto front-end a ser analisado, execute os seguintes comandos no terminal:

• $ npm install eslint --save-dev

  (Este comando instalará o EsLint como dependência de desenvolvimento)

• $ npm install eslint-plugin-furnas

  (Este comando será responsável por instalar o plugin previamente disponibilizado)

• $ npm init @eslint/config

  (Este comando abrirá uma janela de perguntas

  • As respostas a serem marcadas serão: * To check syntax and find problems * JavaScript modules (import/export) * React * No (Por enquanto os projetos de Furnas não fazem uso de TypeScript, caso isso mude, atualize essa documentação) * Browser * JSON * Yes
  • Será criado um arquivo chamado .eslintrc.json (Arquivo de configuração do EsLint)
  • Neste arquivo existe uma chave chamada plugins, Adicione furnas à lista de plugins: Exemplo de um arquivo .eslintrc.json

      ```JSON
      {
          "env": {
              "browser": true,
              "es2021": true
          },
          "extends": [
          ],
          "parserOptions": {
              "ecmaFeatures": {
                  "jsx": true
              },
              "ecmaVersion": "latest",
              "sourceType": "module"
          },
          "plugins": [
              "furnas"
          ],
          "rules": {
          }
      }
      ```

  • A chave "rules" tem o propósito de adicionar as regras que serão utilizadas para a análise.

• Por fim, você deverá produzir o arquivo report.json que será lido pelo SonarScanner, no terminal, execute:

  $ npx eslint -f json -o report.json .

  Caso o arquivo criado contenha apenas uma array vazia, um dos passos não foi executado corretamente.

Integração com o SonarScanner.MSBuild

No momento da análise do projeto, é necessário mover a pasta do front-end do projeto para o diretório raiz do back-end do projeto: ~/Furnas.Projeto.

Devido à uma configuração do SonarScanner, o front-end deve estar, mesmo que só no momento da análise, no mesmo caminho da solução do projeto backend (.sln).

Após isso, é vital que no momento da preparação da análise, sejam usados os seguintes argumentos para o SonarScanner: 1. /d:sonar.eslint.reportPaths 2. /d:sonar.sources

Conforme a documentação do SonarScanner.MSBuild, a integração das análises ocorrerá dessa maneira.

Exemplo de uma análise do SonarScanner.MSBuild com /report.json incluso:

    cd %CAMINHO_DO_PROJETO%

    dotnet %CAMINHO_MS_BUILD% begin                         \
            /k:%NOME_PROJETO%                               \
            /n:%NOME_PROJETO%                               \
            /d:sonar.eslint.reportPaths=%REPORT_PATH%       \
            /d:sonar.sources=%CAMINHO_REACT%                \

    dotnet build %SLN_PROJETO% 

    dotnet %CAMINHO_MS_BUILD% end

    pause

Considerando:

• REPORT_PATH : Caminho absoluto do arquivo report.json gerado pelo eslint
• CAMINHO_REACT : Caminho absoluto do front-end do projeto, relativo ao caminho do backend.
  • %CAMINHO_DO_PROJETO%/Furnas.Projeto.Visao.React

Instalação Antiga

DISCLAIMER - Esse método não é mais suportado e pode não funcionar, devido à mudanças no procedimento de instalação de dependências.

Rode o comando no projeto eslint-plugin-furnas para poder adicionar suas dependências e ter a pasta node_modules:

$ npm install 

Passos na pasta do frontend do projeto a ser analisado:

É necessário realizar a instalação do ESLint ESLint:

$ npm i eslint babel-eslint --save-dev

Exemplo de arquivo .eslint:

module.exports = {
    "env": {
        "browser": true,
        "es2020": true
    },
    "extends": [ ],
    "parser": "babel-eslint",
    "parserOptions": {
        "ecmaVersion": 11,
        "sourceType": "module",
        "ecmaFeatures": {
            "jsx": true,
            "modules": true,
            "experimentalObjectRestSpread": true
        }
    },
    "plugins": [ "furnas" ],
    "rules": {
        "furnas/nomenclatura-de-actions": 2
    }
};

Após a edição do arquivo .eslint. Adicione a pasta eslint-plugin-furnas dentro de uma pasta @furnas, na raiz do projeto a ser analisado. Após, vamos no package.json e adicionamos "eslint-plugin-furnas": "@furnas/eslint-plugin-furnas" dentro do devDependencies.

Usando

Podemos modificar os nomes das regras, mas percebi que elas seguiam um padrao de dividir as palavras com hífen.

Podemos adicionar regras específicas no arquivo de configuração do eslint no projeto frontend. Exemplo das regras utilizadas até agora:

module.exports = {
    "env": {
        "browser": true,
        "es2020": true
    },
    "extends": [
    ],
    "parser": "babel-eslint",
    "parserOptions": {
        "ecmaVersion": 11,
        "sourceType": "module",
        "ecmaFeatures": {
            "jsx": true,
            "modules": true,
            "experimentalObjectRestSpread": true
        }
    },
    "plugins": [
        "furnas"
    ],
    "rules": {
        "furnas/acesso-a-actions": 2,
        "furnas/acesso-a-dispatcher": 2,
        "furnas/acesso-a-furnasrequest": 2,
        "furnas/acesso-a-servicos": 2,
        "furnas/acesso-a-store": 2,
        "furnas/diretorio-actions": 2,
        "furnas/diretorio-componentes": 2,
        "furnas/diretorio-servicos": 2,
        "furnas/diretorio-store": 2,
        "furnas/documentacao-em-classes-e-funcoes": "error",
        "furnas/input-sem-disabled": 2,
        "furnas/nomenclatura-de-actions": 2,
        "furnas/nomenclatura-de-arquivos": "error",
        "furnas/nomenclatura-de-classes": 2,
        "furnas/nomenclatura-de-constantes": 2,
		"furnas/nomenclatura-de-funcoes-e-variaveis": "error",
        "furnas/nomenclatura-de-paginas": 2,
        "furnas/nomenclatura-de-servico": 2,
        "furnas/nomenclatura-de-store": 2,
		"furnas/paginas-extends-component": "warn",
		"furnas/store-extends-eventemitter": "warn",
        "furnas/uso-do-alert": 2,
        "furnas/uso-do-dispatcher": 2,
    }
};

SonarQube

Dentro da pasta do frontend, rodamos um comando para gerar um arquivo report.json:

$ eslint -f json -o report.json .

Após a geração do arquivo report.json, vamos até a raiz do projeto (onde temos todas as pastas com Dominio, Visao, Serviços, etc) e rodamos o comando para o sonar analizar o projeto:

sonar-scanner -D"sonar.projectKey=PROJECT_KEY_AQUI" -D"sonar.projectName=NOME_DO_PROJETO" -D"sonar.projectVersion=1.0" -D"sonar.eslint.reportPaths=NOME_DO_PROJETO.Visao.React/report.json" -D"sonar.host.url=http://localhost:9000/" -D"sonar.sourceEncoding=UTF-8" -D"sonar.javascript.file.suffixes=.vue" -D"sonar.html.file.suffixes=.shtml" -D"sonar.css.file.suffixes=.less"

O SonarWay do JavaScript só irá analisar os arquivos .vue; HTML só irá analisar os arquivos .shtml; CSS só irá analisar os arquivos .less.