@digdigital/eslint-plugin-rules

Plugin interno do ESLint com regras específicas para os projetos da Dig. A primeira regra disponível evita que o objeto inteiro process.env seja exposto acidentalmente no código.

Requisitos

• Node.js compatível com o projeto consumidor;
• ESLint 7 ou 8.

Instalação

Instale o plugin como dependência de desenvolvimento:

yarn add --dev @digdigital/eslint-plugin-rules

ou:

npm install --save-dev @digdigital/eslint-plugin-rules

Configuração

ESLint flat config

No eslint.config.js, importe o plugin e registre a regra:

const interRules = require('@digdigital/eslint-plugin-rules')

module.exports = [
  {
    files: ['**/*.js'],
    plugins: {
      '@digdigital': interRules,
    },
    rules: {
      '@digdigital/no-process-env-exposure': 'error',
    },
  },
]

Se o projeto utilizar módulos ES, a mesma configuração pode ser escrita com import e export default.

Configuração legada

Em projetos que ainda utilizam .eslintrc, registre o plugin e ative a regra:

{
  "plugins": ["@digdigital/rules"],
  "rules": {
    "@digdigital/rules/no-process-env-exposure": "error"
  }
}

Para configurações novas, prefira o formato flat.

Regras

no-process-env-exposure

Impede o uso direto de process.env, que pode expor todas as variáveis de ambiente quando o objeto é passado para outra função ou incluído em uma estrutura de dados.

Inválido

const config = {
  env: process.env,
}

sendToLogger(process.env)

Válido

Informe explicitamente a variável necessária:

const config = {
  env: process.env.NODE_ENV,
}

const apiKey = process.env.API_KEY

Também são permitidos os usos destinados a percorrer as chaves do ambiente:

Object.keys(process.env)
Object.entries(process.env)

A regra não possui opções de configuração. O nível recomendado é error.

Correção automática

A regra declara um fixer e pode ser executada com:

npx eslint . --fix

Revise o diff após a correção automática e confirme que o resultado continua semanticamente correto.

Desenvolvimento

Clone o repositório e instale as dependências:

git clone [email protected]:digdigital/eslint-plugin-rules.git
cd eslint-plugin-rules
yarn install

Para validar a regra no arquivo de exemplo:

yarn dev

A configuração usada nesse comando está em sample/eslint.config.sample.js, e o código analisado está em sample/example-code.js.

Criando uma regra

1. Crie uma pasta em rules/ com o nome da regra.
2. Exporte o objeto da regra em rules/<nome-da-regra>/index.js.
3. Registre a regra em index.js, no objeto plugin.rules.
4. Adicione os testes em rules/<nome-da-regra>/test.js.
5. Execute a suíte de testes.

Estrutura mínima:

rules/
└── minha-regra/
    ├── index.js
    └── test.js

Uma regra deve definir, no mínimo, meta e create:

module.exports = {
  meta: {
    type: 'problem',
    docs: {
      description: 'Descreve o problema identificado pela regra.',
    },
    schema: [],
  },
  create(context) {
    return {
      Identifier(node) {
        // Analise o nó e use context.report(...) quando necessário.
      },
    }
  },
}

Consulte a documentação de regras customizadas do ESLint e a lista de visitor keys para escolher os nós da AST que a regra deve observar.

Testes

Os testes utilizam o RuleTester do ESLint, compartilhado por ruleTester/index.js. Execute todos os testes com:

yarn test

Exemplo de teste:

const { ruleTester } = require('../../ruleTester')
const rule = require('.')

ruleTester.run('minha-regra', rule, {
  valid: [{ code: 'const value = 1' }],
  invalid: [
    {
      code: 'const value = 0',
      errors: 1,
    },
  ],
})

Scripts disponíveis

| Comando | Finalidade | | --- | --- | | yarn dev | Executa o ESLint sobre o exemplo em sample/. | | yarn test | Executa os testes com Jest. | | yarn lint | Mantido para compatibilidade do pacote. | | yarn build | Mantido para compatibilidade; não há etapa de compilação. |

Nova publicação no npm

A publicação é feita automaticamente pelo GitHub Actions, por meio do workflow Create release tag. Antes de iniciar uma publicação, confirme que:

• as alterações já foram revisadas e estão na branch master;
• o secret NPM_TOKEN está configurado no repositório e possui permissão para publicar o pacote;
• o token tem acesso à organização @digdigital.

Para publicar uma nova versão:

1. Acesse a aba Actions do repositório.
2. Selecione Create release tag e clique em Run workflow.
3. Confirme a branch master e escolha o tipo de versão:
   • patch: correções compatíveis, por exemplo, 1.0.0 → 1.0.1;
   • minor: novas funcionalidades compatíveis, por exemplo, 1.0.0 → 1.1.0;
   • major: alterações incompatíveis, por exemplo, 1.0.0 → 2.0.0.
4. Aguarde a conclusão do workflow.

O workflow calcula a próxima versão a partir das tags vMAJOR.MINOR.PATCH, atualiza o package.json, executa o build, gera o pacote com yarn pack, publica com yarn publish --access public, cria o commit de release e envia a nova tag para o repositório.

Após a execução, confirme a versão publicada na página do pacote ou com:

yarn info @digdigital/eslint-plugin-rules version

Não é necessário executar yarn publish localmente.

Licença

MIT