API de Regras

As regras do Archgate são arquivos TypeScript que exportam um objeto simples tipado com satisfies RuleSet. Cada regra recebe um RuleContext com utilitários para buscar arquivos, ler conteúdo e reportar violações.

RuleSet

/// <reference path="../rules.d.ts" />

export default {
  rules: {
    "my-rule-id": {
      description: "Human-readable description of what this rule checks",
      severity: "error", // optional, defaults to "error"
      async check(ctx) {
        // Rule logic here
      },
    },
  },
} satisfies RuleSet;

Um arquivo de regras exporta por padrão um objeto simples com um registro rules indexado por ID de regra. As chaves se tornam os IDs das regras que aparecem na saída de verificação e nos relatórios de violação. A anotação satisfies RuleSet fornece verificação de tipos sem envolver em uma chamada de função.

type RuleSet = { rules: Record<string, RuleConfig> };

---

RuleConfig

Cada regra no registro deve estar em conformidade com a interface RuleConfig.

interface RuleConfig {
  description: string;
  severity?: Severity;
  check: (ctx: RuleContext) => Promise<void>;
}

Campo	Tipo	Obrigatório	Descrição
description	string	Sim	Descrição legível exibida na saída de verificação
severity	Severity	Não	Severidade padrão para violações. Padrão: "error"
check	(ctx: RuleContext) => Promise<void>	Sim	Função assíncrona contendo a lógica da regra

---

RuleContext

A função check recebe um objeto RuleContext com o estado do projeto e métodos utilitários.

interface RuleContext {
  projectRoot: string;
  scopedFiles: string[];
  changedFiles: string[];
  glob(pattern: string): Promise<string[]>;
  grep(file: string, pattern: RegExp): Promise<GrepMatch[]>;
  grepFiles(pattern: RegExp, fileGlob: string): Promise<GrepMatch[]>;
  readFile(path: string): Promise<string>;
  readJSON(path: string): Promise<unknown>;
  report: RuleReport;
}

Propriedades

projectRoot

projectRoot: string;

Caminho absoluto para o diretório raiz do projeto (onde .archgate/ está localizado).

scopedFiles

scopedFiles: string[];

Arquivos que correspondem aos padrões glob de files do frontmatter do ADR. Se o ADR não tiver o campo files, contém todos os arquivos do projeto. Use esta lista como a lista principal de arquivos para suas verificações de regra.

changedFiles

changedFiles: string[];

Arquivos modificados conforme o Git. Por padrão, é autopreenchido com o diff da branch em relação à branch base detectada (ex.: origin/main) mais quaisquer alterações não commitadas da árvore de trabalho (arquivos staged, não staged e não rastreados que não sejam ignorados). Quando --staged é usado, contém apenas arquivos staged. Quando --base <ref> é usado, contém todos os arquivos alterados desde essa ref mais as alterações não commitadas da árvore de trabalho. Fica vazio quando a detecção falha ou nenhuma alteração é encontrada. Use para construir regras de dependência entre arquivos (ex.: “se o arquivo A mudou, o arquivo B também deve mudar”).

report

report: RuleReport;

A interface de relatório para registrar violações, avisos e mensagens informativas. Veja RuleReport abaixo.

Métodos

glob

glob(pattern: string): Promise<string[]>;

Encontra arquivos correspondentes a um padrão glob relativo à raiz do projeto. Retorna um array de caminhos de arquivo. Arquivos ignorados pelo .gitignore são excluídos por padrão. Defina respectGitignore: false no frontmatter do ADR para incluí-los.

const testFiles = await ctx.glob("tests/**/*.test.ts");

grep

grep(file: string, pattern: RegExp): Promise<GrepMatch[]>;

Busca em um único arquivo por linhas correspondentes a uma expressão regular. Retorna um array de objetos GrepMatch com caminho do arquivo, número da linha, coluna e conteúdo correspondente.

const matches = await ctx.grep(file, /console\.error\(/);

grepFiles

grepFiles(pattern: RegExp, fileGlob: string): Promise<GrepMatch[]>;

Busca em múltiplos arquivos correspondentes a um padrão glob por linhas que correspondam a uma expressão regular. Combina glob e grep em uma única chamada. Arquivos ignorados pelo .gitignore são excluídos por padrão. Defina respectGitignore: false no frontmatter do ADR para incluí-los.

const matches = await ctx.grepFiles(/TODO:/i, "src/**/*.ts");

readFile

readFile(path: string): Promise<string>;

Lê o conteúdo de um arquivo como string. O caminho é relativo à raiz do projeto.

const content = await ctx.readFile("src/config.ts");

readJSON

readJSON(path: string): Promise<unknown>;

Lê e faz o parse de um arquivo JSON. O caminho é relativo à raiz do projeto. Retorna o valor parseado como unknown — faça o cast para o tipo esperado na sua regra.

const pkg = (await ctx.readJSON("package.json")) as {
  dependencies?: Record<string, string>;
};

---

RuleReport

A interface de relatório para registrar resultados de verificação. Cada método aceita um objeto de detalhe descrevendo o problema.

interface RuleReport {
  violation(detail: ReportDetail): void;
  warning(detail: ReportDetail): void;
  info(detail: ReportDetail): void;
}

violation

report.violation(detail: ReportDetail): void;

Reporta uma violação de regra. Violações fazem a verificação falhar com código de saída 1. Use para restrições rígidas que não devem ser mergeadas.

warning

report.warning(detail: ReportDetail): void;

Reporta um aviso. Avisos aparecem na saída de verificação mas não fazem a verificação falhar. Use para orientações não bloqueantes.

info

report.info(detail: ReportDetail): void;

Reporta uma mensagem informativa. Não afeta o código de saída da verificação. Use para sugestões ou notas.

ReportDetail

O objeto de detalhe passado para violation, warning e info.

interface ReportDetail {
  message: string;
  file?: string;
  line?: number;
  endLine?: number;
  endColumn?: number;
  fix?: string;
}

Campo	Tipo	Obrigatório	Descrição
message	string	Sim	Descrição legível do problema
file	string	Não	Caminho do arquivo onde o problema foi encontrado
line	number	Não	Número da linha inicial (base 1)
endLine	number	Não	Número da linha final (base 1), para destaque preciso no editor
endColumn	number	Não	Número da coluna final (base 0), para destaque preciso no editor
fix	string	Não	Sugestão de correção ou ação de remediação

Quando endLine e endColumn são fornecidos, editores (VS Code, Cursor) podem destacar a expressão exata que viola a regra, em vez da linha inteira. Se omitidos, a linha completa em line é destacada.

---

GrepMatch

Retornado por ctx.grep() e ctx.grepFiles().

interface GrepMatch {
  file: string;
  line: number;
  column: number;
  content: string;
}

Campo	Tipo	Descrição
file	string	Caminho relativo ao projeto do arquivo correspondente
line	number	Número da linha da correspondência (base 1)
column	number	Número da coluna da correspondência (base 1)
content	string	Conteúdo completo da linha correspondente

---

Severity

type Severity = "error" | "warning" | "info";

Valor	Impacto no código de saída	Descrição
"error"	Causa saída 1	Restrição rígida, bloqueia merges
"warning"	Sem impacto	Orientação não bloqueante
"info"	Sem impacto	Informativo, apenas sugestões

---

ViolationDetail

A representação interna de um problema reportado, usada na saída de verificação e nos resultados JSON.

interface ViolationDetail {
  ruleId: string;
  adrId: string;
  message: string;
  file?: string;
  line?: number;
  endLine?: number;
  endColumn?: number;
  fix?: string;
  severity: Severity;
}

Campo	Tipo	Descrição
ruleId	string	ID da regra da chave do objeto rules
adrId	string	ID do ADR do frontmatter
message	string	Descrição legível
file	string?	Caminho do arquivo onde o problema foi encontrado
line	number?	Número da linha inicial (base 1)
endLine	number?	Linha final (base 1), para destaque preciso no editor
endColumn	number?	Coluna final (base 0), para destaque preciso no editor
fix	string?	Sugestão de correção
severity	Severity	Severidade efetiva desta violação

---

Supressão inline

Violações podem ser suprimidas no código-fonte usando comentários archgate-ignore. O engine lida com isso automaticamente. As regras não precisam de nenhuma lógica especial.

// archgate-ignore ARCH-006/no-unapproved-deps dep legada, migração planejada
import chalk from "chalk";

Um motivo é obrigatório. A supressão no nível do arquivo usa archgate-ignore-file. Empilhe múltiplos comentários para suprimir mais de uma regra na mesma linha. Veja Diretivas de opt-out para detalhes completos e padrões de diretivas customizadas.