Commitlint

O que Commitlint faz?

Valida mensagens de commit no formato Conventional Commits usando a configuração e regras do commitlint.

Quando Usar Este Skill

Use este skill quando:

• Configurando o commitlint para um repositório
• Configurando regras do commitlint e configurações compartilháveis
• Integrando o commitlint com hooks de pre-commit ou pipelines CI/CD
• Extraindo regras da configuração do commitlint para gerar prompts de LLM para geração de mensagens de commit
• Validando mensagens de commit programaticamente
• Resolvendo problemas de configuração ou validação do commitlint
• Entendendo a sintaxe das regras do commitlint e níveis de severidade
• Detectando arquivos de configuração do commitlint em um repositório

Capacidades Principais

Detecção de Configuração

O commitlint usa o cosmiconfig para encontrar arquivos de configuração nesta ordem de prioridade:

Arquivos de configuração dedicados:

.commitlintrc
.commitlintrc.json
.commitlintrc.yaml
.commitlintrc.yml
.commitlintrc.js
.commitlintrc.cjs
.commitlintrc.mjs
.commitlintrc.ts
.commitlintrc.cts
commitlint.config.js
commitlint.config.cjs
commitlint.config.mjs
commitlint.config.ts
commitlint.config.cts

Arquivos de pacote:

• package.json com o campo commitlint
• package.yaml (PNPM) com o campo commitlint

Formatos de Configuração

JavaScript ES Modules (Recomendado):

// commitlint.config.js ou commitlint.config.mjs
export default {
  extends: ['@commitlint/config-conventional'],
};

TypeScript:

// commitlint.config.ts
import type { UserConfig } from '@commitlint/types';
import { RuleConfigSeverity } from '@commitlint/types';

const config: UserConfig = {
  extends: ['@commitlint/config-conventional'],
  rules: {
    'type-enum': [RuleConfigSeverity.Error, 'always', ['feat', 'fix', 'docs']],
  },
};

export default config;

JSON:

{
  "extends": ["@commitlint/config-conventional"]
}

YAML:

extends:
  - "@commitlint/config-conventional"

Configuração de Regras

As regras são configuradas como arrays: [nivel, aplicabilidade, valor]

Níveis de Severidade:

Nível	Significado	Enum TypeScript
0	Desabilitado	RuleConfigSeverity.Disabled
1	Aviso	RuleConfigSeverity.Warning
2	Erro	RuleConfigSeverity.Error

Aplicabilidade:

• 'always' - A regra deve corresponder
• 'never' - A regra não deve corresponder

Exemplos de regras:

rules: {
  // Erro se o tipo não estiver no enum
  'type-enum': [2, 'always', ['feat', 'fix', 'docs', 'style', 'refactor', 'perf', 'test', 'build', 'ci', 'chore', 'revert']],

  // Erro se o tipo estiver vazio
  'type-empty': [2, 'never'],

  // Erro se o assunto estiver vazio
  'subject-empty': [2, 'never'],

  // Erro se o cabeçalho exceder 100 caracteres
  'header-max-length': [2, 'always', 100],

  // Erro se o assunto terminar com ponto final
  'subject-full-stop': [2, 'never', '.'],

  // Aviso se o corpo não tiver linha em branco inicial
  'body-leading-blank': [1, 'always'],
}

Configurações Comuns

@commitlint/config-conventional

A configuração compartilhável mais utilizada. Regras de nível de erro padrão:

Regra	Configuração	Exemplo de Sucesso	Exemplo de Falha
type-enum	['build', 'chore', 'ci', 'docs', 'feat', 'fix', 'perf', 'refactor', 'revert', 'style', 'test']	fix: mensagem	foo: mensagem
type-case	'lowerCase'	fix: mensagem	FIX: mensagem
type-empty	never	fix: mensagem	: mensagem
subject-case	never + ['sentence-case', 'start-case', 'pascal-case', 'upper-case']	fix: alguma mensagem	fix: Alguma Mensagem
subject-empty	never	fix: mensagem	fix:
subject-full-stop	never, '.'	fix: mensagem	fix: mensagem.
header-max-length	100	Cabeçalho curto	Cabeçalho > 100 caracteres
body-leading-blank	always (aviso)	Linha em branco antes do corpo	Sem linha em branco
body-max-line-length	100	Linhas <= 100 caracteres	Linha > 100 caracteres
footer-leading-blank	always (aviso)	Linha em branco antes do rodapé	Sem linha em branco
footer-max-line-length	100	Linhas <= 100 caracteres	Linha > 100 caracteres

Esquema de Configuração Completo

// commitlint.config.js
export default {
  // Estende configurações compartilháveis (resolvidas via resolução de node)
  extends: ['@commitlint/config-conventional'],

  // Configuração do parser para analisar mensagens de commit
  parserPreset: 'conventional-changelog-atom',

  // Formatador de saída
  formatter: '@commitlint/format',

  // Regras personalizadas (substituem regras herdadas)
  rules: {
    'type-enum': [2, 'always', ['feat', 'fix', 'docs', 'style', 'refactor', 'test', 'chore']],
  },

  // Funções que retornam true para ignorar commits específicos
  // Mesclado com ignores padrão (commits de merge, reverts, tags semver)
  ignores: [(commit) => commit.includes('WIP')],

  // Se deve usar padrões de ignore padrão
  // Padrões padrão: 'Merge pull request', 'Revert X', 'v1.2.3', etc.
  defaultIgnores: true,

  // URL de ajuda personalizada exibida em caso de falha
  helpUrl: 'https://exemplo.com/diretrizes-commit',

  // Configuração de prompt (para @commitlint/cz-commitlint)
  prompt: {
    messages: {},
    questions: {
      type: {
        description: 'Selecione o tipo de mudança:',
      },
    },
  },
};

Uso via CLI

Instalação

# npm
npm install -D @commitlint/cli @commitlint/config-conventional

# yarn
yarn add -D @commitlint/cli @commitlint/config-conventional

# pnpm
pnpm add -D @commitlint/cli @commitlint/config-conventional

Comandos Comuns

# Valida o último commit
npx commitlint --last

# Valida um intervalo de commits
npx commitlint --from HEAD~5

# Valida a partir de um commit específico
npx commitlint --from abc1234

# Valida mensagem via stdin
echo "feat: adicionar funcionalidade" | npx commitlint

# Valida mensagem de arquivo
npx commitlint < .git/COMMIT_EDITMSG

# Valida com flag edit (lê .git/COMMIT_EDITMSG)
npx commitlint --edit

# Valida com caminho de configuração personalizado
npx commitlint --config ./custom-commitlint.config.js

# Imprime a configuração resolvida
npx commitlint --print-config

# Modo estrito (avisos se tornam código de saída 2)
npx commitlint --last --strict

Códigos de Saída

Código	Significado
0	Sucesso (sem erros)
1	Erros de lint encontrados
2	Avisos encontrados (apenas modo estrito)
3	Erros encontrados (modo estrito)
9	Arquivo de configuração ausente (com flag -g)

Referência de Regras

Regras de Tipo

Regra	Condição	Aplicabilidade Padrão
type-enum	type é encontrado no valor	always
type-case	type está no caso value	always, 'lower-case'
type-empty	type está vazio	never
type-max-length	type tem value ou menos caracteres	always, Infinity
type-min-length	type tem value ou mais caracteres	always, 0

Regras de Assunto

Regra	Condição	Aplicabilidade Padrão
subject-case	subject está no caso value	always
subject-empty	subject está vazio	never
subject-full-stop	subject termina com value	never, '.'
subject-max-length	subject tem value ou menos caracteres	always, Infinity
subject-min-length	subject tem value ou mais caracteres	always, 0
subject-exclamation-mark	subject tem exclamação antes de :	never

Regras de Escopo

Regra	Condição	Aplicabilidade Padrão
scope-enum	scope é encontrado no valor	always, []
scope-case	scope está no caso value	always, 'lower-case'
scope-empty	scope está vazio	never
scope-max-length	scope tem value ou menos caracteres	always, Infinity
scope-min-length	scope tem value ou mais caracteres	always, 0

Regras de Cabeçalho

Regra	Condição	Aplicabilidade Padrão
header-case	header está no caso value	always, 'lower-case'
header-full-stop	header termina com value	never, '.'
header-max-length	header tem value ou menos caracteres	always, 72
header-min-length	header tem value ou mais caracteres	always, 0
header-trim	header não tem espaços no início/fim	always

Regras de Corpo

Regra	Condição	Aplicabilidade Padrão
body-leading-blank	body começa com linha em branco	always
body-empty	body está vazio	never
body-max-length	body tem value ou menos caracteres	always, Infinity
body-max-line-length	Linhas de body têm value ou menos caracteres (URLs excluídas)	always, Infinity
body-min-length	body tem value ou mais caracteres	always, 0
body-case	body está no caso value	always, 'lower-case'
body-full-stop	body termina com value	never, '.'

Regras de Rodapé

Regra	Condição	Aplicabilidade Padrão
footer-leading-blank	footer começa com linha em branco	always
footer-empty	footer está vazio	never
footer-max-length	footer tem value ou menos caracteres	always, Infinity
footer-max-line-length	Linhas de footer têm value ou menos caracteres	always, Infinity
footer-min-length	footer tem value ou mais caracteres	always, 0

Valores de Caso

Para regras que verificam caso (*-case):

[
  'lower-case',    // letras minúsculas
  'upper-case',    // LETRAS MAIÚSCULAS
  'camel-case',    // camelCase
  'kebab-case',    // kebab-case
  'pascal-case',   // PascalCase
  'sentence-case', // Sentence case
  'snake-case',    // snake_case
  'start-case',    // Start Case
]

Uso Programático

Carregar Configuração

import load from '@commitlint/load';

async function getCommitlintConfig() {
  const config = await load();
  console.log(config.rules);
  return config;
}

Validar Mensagem

import load from '@commitlint/load';
import lint from '@commitlint/lint';

async function validateMessage(message) {
  const config = await load();
  const result = await lint(message, config.rules);

  return {
    valid: result.valid,
    errors: result.errors,
    warnings: result.warnings,
  };
}

Padrões de Integração com LLM

Extrair Regras para Geração de Prompts

Gere restrições amigáveis para LLM a partir da configuração do commitlint:

def extract_rules_for_prompt(config: dict) -> str:
    """Extrai regras do commitlint para um formato amigável ao LLM."""
    rules = config.get("rules", {})
    prompt_parts = []

    # Extrai type-enum se presente
    if "type-enum" in rules:
        level, applicability, types = rules["type-enum"]
        if level > 0 and applicability == "always":
            prompt_parts.append(f"Tipos de commit permitidos: {', '.join(types)}")

    # Extrai scope-enum se presente
    if "scope-enum" in rules:
        level, applicability, scopes = rules["scope-enum"]