diff --git a/.archgate/adrs/GEN-001-documentation-site.md b/.archgate/adrs/GEN-001-documentation-site.md index e969af6c..e91f7b2b 100644 --- a/.archgate/adrs/GEN-001-documentation-site.md +++ b/.archgate/adrs/GEN-001-documentation-site.md @@ -215,6 +215,7 @@ No automated rules are defined for this ADR (`rules: false`). Future opportuniti - A rule verifying that every MDX file in `docs/src/content/docs/` has a corresponding sidebar entry in `astro.config.mjs` - A rule checking that `docs/package.json` does not contain CLI source dependencies +- i18n page parity checks are enforced by [GEN-002](./GEN-002-docs-i18n.md) ### Manual Enforcement @@ -241,4 +242,5 @@ The `deploy-docs.yml` GitHub Actions workflow handles deployment: - [Astro documentation](https://docs.astro.build) — Framework reference - [Starlight documentation](https://starlight.astro.build) — Documentation integration reference - [ARCH-006 — Dependency Policy](./ARCH-006-dependency-policy.md) — Bun-first toolchain philosophy that extends to the docs build +- [GEN-002 — Documentation Internationalization](./GEN-002-docs-i18n.md) — i18n governance and 1:1 page parity rules - [deploy-docs.yml](../../.github/workflows/deploy-docs.yml) — GitHub Actions deployment workflow diff --git a/.archgate/adrs/GEN-002-docs-i18n.md b/.archgate/adrs/GEN-002-docs-i18n.md new file mode 100644 index 00000000..d0a2c576 --- /dev/null +++ b/.archgate/adrs/GEN-002-docs-i18n.md @@ -0,0 +1,132 @@ +--- +id: GEN-002 +title: Documentation Internationalization +domain: general +rules: true +files: ["docs/**"] +--- + +## Context + +Archgate targets a global developer audience, but the documentation site ([GEN-001](./GEN-001-documentation-site.md)) is English-only. Without internationalization: + +1. **Non-English speakers are excluded** -- Developers who are more comfortable in other languages cannot fully benefit from guides, reference pages, and examples +2. **Community growth is limited** -- Open-source adoption in non-English markets depends on accessible documentation +3. **Translation efforts lack governance** -- Without structure, translations drift from the source language, pages get added without corresponding translations, and stale translations mislead users + +Brazilian Portuguese is the first translation target. The Starlight documentation framework already provides built-in i18n support with locale-based routing, automatic language switching, and fallback behavior. + +**Alternatives considered:** + +- **No i18n** -- Keeps maintenance simple but excludes non-English speakers entirely. As Archgate grows internationally, this becomes a significant barrier to adoption. +- **External translation platform (Crowdin, Weblate)** -- Provides a translation management workflow with contributor UI, change detection, and automated PR creation. However, it adds an external service dependency, requires account setup, and is overkill when the team can manage translations directly in the repository. +- **Runtime translation (i18next / Paraglide)** -- Key-based translation systems designed for application strings. Poor fit for long-form MDX documentation where content is authored as prose, not message keys. Would require a complete rewrite of the content authoring approach. +- **Starlight built-in i18n** -- Uses file-based locale directories under `docs/src/content/docs//`. Starlight automatically handles routing (`/pt-br/guides/...`), language switching, sidebar resolution, and fallback to the default locale for untranslated pages. No additional dependencies required. + +Starlight's built-in i18n is the natural choice: zero new dependencies, file-based workflow that fits the existing PR review process, and automatic UI features (language switcher, locale-aware routing) with minimal configuration. + +## Decision + +The documentation site MUST use Starlight's built-in i18n with English as the root locale and additional languages in subdirectories under `docs/src/content/docs//`. The `docs/astro.config.mjs` MUST declare `defaultLocale: "root"` with a `locales` configuration object. + +**Root locale pattern:** + +English content stays at `docs/src/content/docs/` (no subdirectory) and serves URLs without a language prefix (e.g., `/getting-started/installation/`). This preserves all existing English URLs with zero breaking changes. Each additional locale gets a subdirectory (e.g., `docs/src/content/docs/pt-br/`) and a URL prefix (e.g., `/pt-br/getting-started/installation/`). + +**1:1 page parity:** + +Every MDX file in the root content directory MUST have a corresponding translation file in each configured locale directory, with the same relative path and filename. Conversely, every locale file MUST correspond to an existing root file -- orphan translations are violations. This ensures complete coverage and prevents stale or dangling pages. + +**Same-PR updates:** + +When adding or modifying English content, the corresponding locale files MUST be updated in the same pull request. This prevents translation drift at the source. + +**Translation scope:** + +- **Translate:** Page titles, descriptions, hero taglines, prose, headings, list items, table descriptions, admonition content, and user-visible text props in Starlight components (``, ``) +- **Keep in English:** Code blocks, CLI commands, file paths, TypeScript identifiers, technical terms (ADR, CLI, MCP, CI/CD, glob, frontmatter), import statements, component names, `link`/`href`/`slug` attribute values + +**Sidebar configuration:** + +The sidebar in `docs/astro.config.mjs` does NOT need per-locale duplication. Starlight resolves sidebar `slug` entries to the appropriate locale automatically. A single sidebar configuration serves all languages. + +**Configured locales:** + +| Locale key | Label | BCP 47 tag | URL prefix | +| ---------- | ------------------ | ---------- | ---------- | +| `root` | English | `en` | _(none)_ | +| `pt-br` | Portugues (Brasil) | `pt-BR` | `/pt-br/` | + +## Do's and Don'ts + +### Do + +- **DO** use Starlight's `defaultLocale: "root"` pattern so English URLs have no language prefix +- **DO** create translated files with the exact same relative path and filename as the English source (e.g., `pt-br/guides/writing-adrs.mdx` for `guides/writing-adrs.mdx`) +- **DO** translate all user-facing prose: titles, descriptions, headings, paragraphs, list items, table text, and admonition content +- **DO** translate text props in Starlight components (`title`, `description` in `` and ``) +- **DO** keep code blocks, CLI commands, file paths, and technical identifiers in English +- **DO** keep internal link paths unchanged -- Starlight handles locale-aware routing automatically (e.g., `/getting-started/installation/` resolves correctly in both English and Portuguese) +- **DO** preserve MDX curly-brace escaping (`\{\}`) in translations, following [GEN-001](./GEN-001-documentation-site.md) +- **DO** preserve Starlight component import statements identically in translated files +- **DO** update translations in the same PR that modifies the English source content +- **DO** update the `LOCALES` constant in the companion rules file when adding a new language + +### Don't + +- **DON'T** leave pages untranslated without a tracking issue explaining when the translation will be added +- **DON'T** use machine translation without human review for technical accuracy +- **DON'T** translate code examples, TypeScript identifiers, CLI command names, or file paths +- **DON'T** create locale-specific sidebar configurations -- Starlight handles sidebar resolution per locale automatically +- **DON'T** add locale prefixes in internal links (e.g., don't use `/pt-br/guides/...` -- use `/guides/...` and let Starlight resolve it) +- **DON'T** modify the root locale content directory structure to accommodate translations -- translations mirror the root structure +- **DON'T** add translation-only dependencies to `docs/package.json` -- Starlight's built-in i18n requires no additional packages + +## Consequences + +### Positive + +- **Broader international audience** -- Brazilian Portuguese speakers can read documentation in their language, lowering the barrier to adoption +- **Zero breaking changes** -- The root locale pattern preserves all existing English URLs; no redirects or link updates needed +- **Automatic language switching** -- Starlight renders a language switcher in the navigation with no custom code +- **Automated parity enforcement** -- The companion rule catches missing translations and orphan files before they reach production +- **Extensible to more languages** -- Adding a new locale requires only a config entry, a constant update in the rules file, and the translated content files + +### Negative + +- **Doubled content maintenance** -- Every content PR must update both English and Portuguese files, increasing review scope +- **Translation quality depends on reviewers** -- The automated rule only checks file existence, not translation accuracy or completeness +- **Contributor friction** -- Contributors who only speak English must still account for the Portuguese translation (even if they only add a placeholder file) + +### Risks + +- **Translation drift** -- Portuguese content may fall behind after significant English rewrites. + - **Mitigation:** The same-PR policy catches most drift at review time. The 1:1 parity rule catches structural drift (added/removed pages). Periodic manual audits can catch semantic drift within existing files. +- **Stale technical content** -- Reference pages (CLI Commands, Rule API, MCP Tools) change frequently and translations may lag. + - **Mitigation:** Reference pages contain mostly code blocks and tables with technical values that remain in English. Only surrounding prose needs translation, reducing the update surface. +- **Incorrect translations misleading users** -- Machine-translated or poorly reviewed content may contain errors. + - **Mitigation:** The ADR explicitly requires human review for all translations. Code blocks stay in English, eliminating the highest-risk translation errors (wrong commands, wrong API calls). + +## Compliance and Enforcement + +### Automated Enforcement + +The companion rules file (`GEN-002-docs-i18n.rules.ts`) defines one rule: + +- **`i18n-page-parity`** (severity: `error`) -- Verifies that every root MDX file has a corresponding translation in each configured locale directory, and that no orphan translations exist without a root source file. Runs as part of `archgate check`. + +### Manual Enforcement + +Code reviewers MUST verify during docs PRs: + +1. Translated prose is accurate and reads naturally in the target language +2. Code blocks, CLI commands, and technical identifiers remain in English +3. Starlight component imports and structural MDX elements are preserved identically +4. Internal links do not include locale prefixes +5. New English pages include corresponding translations (or a tracking issue is linked) + +## References + +- [Starlight Internationalization Guide](https://starlight.astro.build/guides/i18n/) -- Official Starlight i18n documentation +- [GEN-001 -- Documentation Site](./GEN-001-documentation-site.md) -- Docs site structure, tooling, and content organization +- [ARCH-006 -- Dependency Policy](./ARCH-006-dependency-policy.md) -- No additional dependencies for i18n (Starlight built-in) diff --git a/.archgate/adrs/GEN-002-docs-i18n.rules.ts b/.archgate/adrs/GEN-002-docs-i18n.rules.ts new file mode 100644 index 00000000..16e2f759 --- /dev/null +++ b/.archgate/adrs/GEN-002-docs-i18n.rules.ts @@ -0,0 +1,74 @@ +import { defineRules } from "../../src/formats/rules"; + +/** + * Configured documentation locales. + * When adding a new language, add its directory name here AND in + * docs/astro.config.mjs under the `locales` key. + */ +const LOCALES = ["pt-br"]; + +const CONTENT_ROOT = "docs/src/content/docs"; + +export default defineRules({ + "i18n-page-parity": { + description: + "Every root MDX file must have a corresponding translation in each locale, and vice versa", + severity: "error", + async check(ctx) { + const allMdxFiles = await ctx.glob(`${CONTENT_ROOT}/**/*.mdx`); + + // Separate root files from locale files + const rootFiles: string[] = []; + const localeFiles = new Map(); + + for (const locale of LOCALES) { + localeFiles.set(locale, []); + } + + for (const file of allMdxFiles) { + const matchedLocale = LOCALES.find((l) => + file.startsWith(`${CONTENT_ROOT}/${l}/`) + ); + if (matchedLocale) { + localeFiles.get(matchedLocale)!.push(file); + } else { + rootFiles.push(file); + } + } + + const rootRelativePaths = rootFiles.map((f) => + f.replace(`${CONTENT_ROOT}/`, "") + ); + const rootRelativeSet = new Set(rootRelativePaths); + + for (const locale of LOCALES) { + const localePrefix = `${CONTENT_ROOT}/${locale}/`; + const existingLocaleRelatives = new Set( + localeFiles.get(locale)!.map((f) => f.replace(localePrefix, "")) + ); + + // Root -> locale: missing translations + for (const relativePath of rootRelativePaths) { + if (!existingLocaleRelatives.has(relativePath)) { + ctx.report.violation({ + message: `Missing ${locale} translation for "${relativePath}"`, + file: `${CONTENT_ROOT}/${relativePath}`, + fix: `Create translated file at ${localePrefix}${relativePath}`, + }); + } + } + + // Locale -> root: orphan translations + for (const localeRelative of existingLocaleRelatives) { + if (!rootRelativeSet.has(localeRelative)) { + ctx.report.violation({ + message: `Orphan ${locale} translation "${localeRelative}" has no corresponding root file`, + file: `${localePrefix}${localeRelative}`, + fix: `Either create the root file at ${CONTENT_ROOT}/${localeRelative} or remove the orphan translation`, + }); + } + } + } + }, + }, +}); diff --git a/docs/astro.config.mjs b/docs/astro.config.mjs index b31d7d60..2a8c1676 100644 --- a/docs/astro.config.mjs +++ b/docs/astro.config.mjs @@ -6,6 +6,11 @@ export default defineConfig({ integrations: [ starlight({ title: "Archgate", + defaultLocale: "root", + locales: { + root: { label: "English", lang: "en" }, + "pt-br": { label: "Português (Brasil)", lang: "pt-BR" }, + }, description: "Enforce Architecture Decision Records as executable rules — for both humans and AI agents.", social: [ diff --git a/docs/src/content/docs/pt-br/concepts/adrs.mdx b/docs/src/content/docs/pt-br/concepts/adrs.mdx new file mode 100644 index 00000000..c9ebb742 --- /dev/null +++ b/docs/src/content/docs/pt-br/concepts/adrs.mdx @@ -0,0 +1,180 @@ +--- +title: Registros de Decisão Arquitetural +description: Entenda como o Archgate usa ADRs como documentos e regras executáveis. +--- + +Um Architecture Decision Record (ADR) é um documento curto que captura uma única decisão arquitetural junto com seu contexto e consequências. ADRs respondem à pergunta: _por que_ essa decisão foi tomada, e _quais_ são seus trade-offs? + +O Archgate expande o conceito de ADR dando a cada decisão duas expressões: um **documento** que humanos e agentes de IA leem, e um **arquivo de regras** opcional que máquinas executam. + +## Duas Expressões de um ADR + +### ADR como Documento + +O documento é um arquivo Markdown com frontmatter YAML armazenado em `.archgate/adrs/`. Ele descreve a decisão em linguagem simples: qual problema resolve, quais alternativas foram consideradas, o que a equipe decidiu, e quais consequências seguem. + +Tanto humanos quanto agentes de IA consomem esse documento. Quando um agente de IA de codificação está prestes a escrever código, ele lê os ADRs relevantes para entender as restrições antes de gerar qualquer coisa. + +:::tip[Automatize isso com plugins de editor] +Com o plugin do [Claude Code](/guides/claude-code-plugin/) ou [Cursor](/guides/cursor-integration/), seu agente de IA lê os ADRs aplicáveis automaticamente antes de cada tarefa de codificação -- sem necessidade de copiar e colar manualmente nos prompts. [Inscreva-se para acesso beta](https://plugins.archgate.dev). +::: + +### ADR como Regras + +O arquivo de regras é um arquivo `.rules.ts` complementar que exporta verificações automatizadas via `defineRules()`. Quando você executa `archgate check`, a CLI carrega cada ADR que tem `rules: true` em seu frontmatter, executa o arquivo de regras complementar contra seu codebase, e reporta quaisquer violações com caminhos de arquivo e números de linha. + +Nem todo ADR precisa de regras. Algumas decisões são melhor aplicadas apenas por revisão de código. Defina `rules: false` quando nenhuma verificação automatizada for prática. + +## Convenção de Nomenclatura de Arquivos + +Os arquivos de ADR seguem uma convenção de nomenclatura estrita que codifica o prefixo do domínio, número de sequência e um slug legível: + +``` +{PREFIX}-{NNN}-{slug}.md # The document +{PREFIX}-{NNN}-{slug}.rules.ts # The companion rules file (optional) +``` + +Por exemplo, um ADR do domínio de arquitetura sobre estrutura de comandos produziria: + +``` +ARCH-001-command-structure.md +ARCH-001-command-structure.rules.ts +``` + +O prefixo vem do domínio do ADR (veja [Domínios](/concepts/domains/)). O número de sequência é preenchido com zeros até três dígitos e auto-incrementado por `archgate adr create`. + +## Frontmatter YAML + +Todo documento ADR começa com um bloco de frontmatter YAML entre delimitadores `---`. O frontmatter é o metadado legível por máquina que o Archgate usa para carregar, filtrar e definir o escopo das regras. + +| Campo | Tipo | Obrigatório | Descrição | +| -------- | ------------ | ----------- | --------------------------------------------------------------- | +| `id` | string | Sim | Identificador único como `ARCH-001` ou `BE-003` | +| `title` | string | Sim | Título legível da decisão | +| `domain` | enum | Sim | Um de: `backend`, `frontend`, `data`, `architecture`, `general` | +| `rules` | boolean | Sim | Se este ADR tem um arquivo `.rules.ts` complementar | +| `files` | string array | Não | Padrões glob que definem quais arquivos as regras verificam | + +O campo `files` é opcional. Quando presente, restringe a execução das regras apenas aos arquivos que correspondem aos globs fornecidos. Quando ausente, as regras são executadas contra todos os arquivos do projeto. Por exemplo, `files: ["src/commands/**/*.ts"]` limita as verificações apenas aos arquivos de comando. + +## Seções do Corpo do ADR + +Após o frontmatter, o corpo do ADR segue uma estrutura de seções padrão: + +### Context + +Descreve o problema ou situação que motivou a decisão. Inclua alternativas que foram consideradas e por que foram rejeitadas. + +### Decision + +Declara a decisão em si e suas restrições principais. Esta é a seção que os agentes de IA mais observam ao decidir como escrever código. + +### Do's and Don'ts + +Orientação concreta e acionável dividida em duas subseções. Funcionam como uma lista de verificação rápida para desenvolvedores e agentes de IA. + +### Consequences + +Dividida em três subseções: + +- **Positive** -- benefícios que a decisão proporciona +- **Negative** -- trade-offs aceitos +- **Risks** -- coisas que podem dar errado e como mitigá-las + +### Compliance and Enforcement + +Descreve como a decisão é aplicada, tanto por regras automatizadas (com IDs de regra e severidades) quanto por checklists de revisão manual. + +### References + +Links para ADRs relacionados, documentação externa ou documentos de design. + +## Exemplo Completo + +Abaixo está um ADR completo com frontmatter e todas as seções preenchidas. + +```markdown +--- +id: BE-001 +title: API Response Envelope +domain: backend +rules: true +files: ["src/api/**/*.ts"] +--- + +## Context + +The API returns data in inconsistent shapes across endpoints. Some endpoints +wrap responses in `{ data, error }`, others return raw arrays, and error +responses vary between plain strings and structured objects. + +**Alternatives considered:** + +- **No envelope** -- Return raw data and rely on HTTP status codes alone. + Simple, but clients cannot distinguish between "the endpoint returned an + empty array" and "the endpoint errored." +- **GraphQL-style errors array** -- Use `{ data, errors: [] }`. Flexible + but adds complexity for simple REST endpoints. + +The chosen envelope balances consistency with simplicity. + +## Decision + +All API endpoints MUST return responses in a standard envelope: + +- Success: `{ data: T }` +- Error: `{ error: { code: string, message: string } }` + +HTTP status codes remain the primary success/failure signal. The envelope +provides a predictable structure for clients to parse. + +## Do's and Don'ts + +### Do + +- Wrap all API responses in the `{ data }` or `{ error }` envelope +- Use specific error codes (e.g., `VALIDATION_FAILED`, `NOT_FOUND`) +- Include the HTTP status code that matches the error semantics + +### Don't + +- Don't return raw arrays or primitives from API endpoints +- Don't nest envelopes (no `{ data: { data: ... } }`) +- Don't put stack traces in the error message field + +## Consequences + +### Positive + +- Clients can parse every response with the same logic +- Error responses always have a machine-readable code for programmatic handling + +### Negative + +- Adds a small amount of boilerplate to every endpoint handler +- Slightly larger payloads due to the wrapper object + +### Risks + +- Developers may forget the envelope on new endpoints. Mitigated by + the automated rule that scans for non-conforming return statements. + +## Compliance and Enforcement + +### Automated Enforcement + +- **Archgate rule** BE-001/response-envelope: Scans API handler files for + return statements and verifies they use the envelope helper. Severity: error. + +### Manual Enforcement + +Code reviewers MUST verify: + +1. New API endpoints use the response envelope +2. Error responses include a specific error code, not a generic message + +## References + +- [Microsoft REST API Guidelines](https://github.com/microsoft/api-guidelines) +- [ARCH-002 -- Error Handling](./ARCH-002-error-handling.md) +``` diff --git a/docs/src/content/docs/pt-br/concepts/domains.mdx b/docs/src/content/docs/pt-br/concepts/domains.mdx new file mode 100644 index 00000000..95d1ff7c --- /dev/null +++ b/docs/src/content/docs/pt-br/concepts/domains.mdx @@ -0,0 +1,96 @@ +--- +title: Domínios +description: Categorize ADRs por domínio para uma governança organizada. +--- + +Domínios são categorias que agrupam ADRs relacionados. Cada ADR pertence a exatamente um domínio, e o domínio determina o prefixo usado no identificador do ADR. + +## Domínios Integrados + +O Archgate vem com cinco domínios integrados. Cada um tem um prefixo curto que aparece no início de cada ID de ADR naquele domínio. + +| Domínio | Prefixo | Uso para | +| -------------- | ------- | ------------------------------------------------------------------ | +| `backend` | `BE` | Lógica server-side, APIs, bancos de dados, serviços | +| `frontend` | `FE` | Componentes de UI, lógica client-side, padrões de estilo | +| `data` | `DATA` | Modelos de dados, schemas, pipelines, estratégias de armazenamento | +| `architecture` | `ARCH` | Decisões arquiteturais transversais | +| `general` | `GEN` | Convenções gerais do projeto e workflows | + +Por exemplo, o terceiro ADR de backend teria o ID `BE-003`, e o primeiro ADR de frontend seria `FE-001`. + +## Como os Domínios São Usados + +### Identificação de ADR + +O prefixo do domínio é incorporado ao campo `id` de cada ADR. Quando você executa `archgate adr create` e seleciona um domínio, a CLI determina automaticamente o próximo número de sequência disponível para o prefixo daquele domínio. Um domínio de arquitetura com dois ADRs existentes (`ARCH-001`, `ARCH-002`) atribuiria `ARCH-003` ao próximo. + +O nome do arquivo espelha o ID: + +``` +ARCH-003-dependency-policy.md +ARCH-003-dependency-policy.rules.ts +``` + +### Filtragem + +O comando `archgate adr list` suporta a flag `--domain` para mostrar apenas ADRs de um domínio específico: + +```bash +archgate adr list --domain backend +archgate adr list --domain architecture +``` + +Isso é útil em projetos grandes onde dezenas de ADRs abrangem múltiplas preocupações. Filtrar por domínio permite que você foque nas decisões relevantes para seu trabalho atual. + +### Contexto para Agentes de IA + +A ferramenta `review_context` do servidor MCP agrupa arquivos alterados por domínio ao fornecer contexto para agentes de IA. Quando um agente está prestes a escrever código, ele recebe apenas os resumos de ADR relevantes para os domínios que suas alterações afetam, em vez do conjunto completo de todos os ADRs. Esse escopo reduz o ruído e ajuda os agentes a focar nas restrições que realmente se aplicam. + +### Validação com Escopo + +Embora os domínios em si não restrinjam quais arquivos uma regra pode verificar (esse é o trabalho do glob `files` no frontmatter do ADR), os domínios fornecem um agrupamento lógico que ajuda as equipes a organizar sua governança. Uma equipe de backend pode revisar todos os ADRs `BE-*` para entender suas restrições, enquanto a equipe de frontend foca nos `FE-*`. + +## Quando Usar Qual Domínio + +### backend + +Use para decisões sobre código server-side: padrões de design de API, convenções de acesso a banco de dados, fluxos de autenticação, comunicação entre serviços, tratamento de filas e padrões de jobs em background. + +**Exemplos de ADRs:** Formato de envelope de resposta de API, estratégia de migração de banco de dados, taxonomia de códigos de erro. + +### frontend + +Use para decisões sobre código client-side: estrutura de componentes, padrões de gerenciamento de estado, abordagens de estilização, requisitos de acessibilidade e escolhas de ferramentas de build. + +**Exemplos de ADRs:** Estrutura de arquivo de componente, metodologia CSS, padrão de validação de formulário. + +### data + +Use para decisões sobre dados: design de schema, convenções de pipeline de dados, escolhas de engine de armazenamento, formatos de serialização e estratégias de validação de dados. + +**Exemplos de ADRs:** Versionamento de schema de eventos, convenções de nomenclatura de banco de dados, política de retenção de dados. + +### architecture + +Use para decisões transversais que abrangem múltiplos domínios ou afetam a estrutura geral do projeto. São decisões que equipes de backend, frontend e dados precisam seguir. + +**Exemplos de ADRs:** Estrutura de comandos, convenções de tratamento de erros, política de gerenciamento de dependências, padrões de teste. + +### general + +Use para convenções de projeto que não se encaixam perfeitamente em um domínio técnico: processos de revisão de código, formatos de mensagem de commit, padrões de documentação e práticas de onboarding. + +**Exemplos de ADRs:** Formato de mensagem de commit, template de descrição de PR, requisitos de documentação. + +## Escolhendo o Domínio Certo + +Ao decidir a qual domínio um ADR pertence, considere quem precisa segui-lo: + +- Se apenas desenvolvedores de backend precisam segui-lo, use `backend`. +- Se apenas desenvolvedores de frontend precisam segui-lo, use `frontend`. +- Se diz respeito especificamente a modelagem de dados ou pipelines, use `data`. +- Se se aplica a múltiplos domínios técnicos, use `architecture`. +- Se é um processo ou convenção em vez de uma decisão técnica, use `general`. + +Em caso de dúvida entre `architecture` e um domínio específico, prefira o domínio mais específico. Reserve `architecture` para decisões que genuinamente cruzam fronteiras. diff --git a/docs/src/content/docs/pt-br/concepts/rules.mdx b/docs/src/content/docs/pt-br/concepts/rules.mdx new file mode 100644 index 00000000..0abc6c1a --- /dev/null +++ b/docs/src/content/docs/pt-br/concepts/rules.mdx @@ -0,0 +1,166 @@ +--- +title: Regras +description: Como o sistema de regras do Archgate transforma decisões de ADR em verificações automatizadas. +--- + +Regras são o lado executável de um ADR. Elas vivem em arquivos `.rules.ts` complementares ao lado do documento ADR e exportam verificações automatizadas via a função `defineRules()`. Quando você executa `archgate check`, a CLI carrega cada ADR que tem `rules: true`, importa seu arquivo de regras complementar e executa cada verificação contra seu codebase. + +## Definindo Regras + +Um arquivo de regras é um módulo TypeScript que exporta por padrão o resultado de `defineRules()`. Importe a função do pacote `archgate/rules`: + +```typescript +import { defineRules } from "archgate/rules"; + +export default defineRules({ + "rule-key": { + description: "What this rule checks", + severity: "error", + async check(ctx) { + // Inspect files and report violations + }, + }, +}); +``` + +Cada chave no objeto passado para `defineRules()` se torna o ID da regra. O identificador completo da regra mostrado na saída do check combina o ID do ADR e a chave da regra, por exemplo `ARCH-004/no-barrel-files`. + +## Estrutura da Regra + +Toda regra tem três partes: + +| Propriedade | Tipo | Obrigatório | Descrição | +| ------------- | -------- | ----------- | --------------------------------------------- | +| `description` | string | Sim | Um resumo curto do que a regra verifica | +| `severity` | string | Não | `"error"` (padrão), `"warning"`, ou `"info"` | +| `check` | function | Sim | Função assíncrona que recebe um `RuleContext` | + +### Níveis de Severidade + +A severidade determina o que acontece quando uma regra encontra um problema: + +| Severidade | Exit Code | Efeito | +| ---------- | --------- | -------------------------------------------- | +| `error` | 1 | A violação é reportada e a verificação falha | +| `warning` | 0 | O aviso é registrado mas a verificação passa | +| `info` | 0 | Mensagem informativa, a verificação passa | + +Quando `archgate check` é executado, exit code 1 significa que pelo menos uma violação de severidade `error` foi encontrada. Exit code 0 significa que não houve erros (avisos e mensagens informativas são registrados mas não bloqueiam). + +## O RuleContext + +A função `check` recebe um objeto `RuleContext` que fornece tudo que uma regra precisa para inspecionar o codebase e reportar descobertas. + +### Informações do Projeto + +| Propriedade | Tipo | Descrição | +| ------------------ | ---------- | ------------------------------------------------------------------------------------------------------ | +| `ctx.projectRoot` | `string` | Caminho absoluto para o diretório raiz do projeto | +| `ctx.scopedFiles` | `string[]` | Arquivos que correspondem aos globs `files` do ADR, ou todos os arquivos se não houver globs definidos | +| `ctx.changedFiles` | `string[]` | Arquivos alterados no git (preenchido ao executar com `--staged`) | + +### Operações de Arquivo + +| Método | Retorno | Descrição | +| -------------------- | ------------------- | --------------------------------------------------- | +| `ctx.glob(pattern)` | `Promise` | Encontra arquivos que correspondem a um padrão glob | +| `ctx.readFile(path)` | `Promise` | Lê o conteúdo de um arquivo como string | +| `ctx.readJSON(path)` | `Promise` | Lê e faz parse de um arquivo JSON | + +### Operações de Busca + +| Método | Retorno | Descrição | +| ---------------------------------- | ---------------------- | ------------------------------------------------------ | +| `ctx.grep(file, pattern)` | `Promise` | Busca em um único arquivo com um padrão regex | +| `ctx.grepFiles(pattern, fileGlob)` | `Promise` | Busca em múltiplos arquivos que correspondem a um glob | + +Tanto `grep` quanto `grepFiles` retornam um array de objetos `GrepMatch`: + +```typescript +interface GrepMatch { + file: string; // Relative path from project root + line: number; // 1-based line number + column: number; // 1-based column number + content: string; // The full line content +} +``` + +### Relatórios + +O objeto `ctx.report` fornece três métodos para reportar descobertas: + +```typescript +ctx.report.violation({ message, file?, line?, fix? }); +ctx.report.warning({ message, file?, line?, fix? }); +ctx.report.info({ message, file?, line?, fix? }); +``` + +Cada método aceita um objeto com: + +| Propriedade | Tipo | Obrigatório | Descrição | +| ----------- | ------ | ----------- | ---------------------------------------- | +| `message` | string | Sim | Qual é o problema | +| `file` | string | Não | Caminho relativo do arquivo com problema | +| `line` | number | Não | Número da linha onde o problema ocorre | +| `fix` | string | Não | Sugestão de correção para a violação | + +Use `ctx.report.violation()` para problemas que devem bloquear merges. Use `ctx.report.warning()` para questões que valem ser sinalizadas mas não bloqueiam. Use `ctx.report.info()` para saída puramente informativa. + +## Timeout de Regra + +Cada regra tem um timeout de execução de 30 segundos. Se a função `check` de uma regra não completar dentro de 30 segundos, ela é terminada e reportada como erro. Isso impede que regras descontroladas bloqueiem o pipeline indefinidamente. + +## Exemplo Completo + +Aqui está um arquivo de regras completo que verifica um padrão de import proibido. Ele garante que nenhum arquivo fonte importe diretamente de `node:fs` (o projeto requer o uso de um wrapper). + +```typescript +import { defineRules } from "archgate/rules"; + +export default defineRules({ + "no-direct-fs-import": { + description: + "Source files must not import directly from node:fs; use the fs wrapper", + severity: "error", + async check(ctx) { + const sourceFiles = ctx.scopedFiles.filter( + (f) => f.endsWith(".ts") && !f.endsWith(".test.ts") + ); + + for (const file of sourceFiles) { + const matches = await ctx.grep(file, /from ["']node:fs["']/); + + for (const match of matches) { + ctx.report.violation({ + message: `Direct import from "node:fs" is not allowed. Use the fs wrapper from "src/helpers/fs" instead.`, + file: match.file, + line: match.line, + fix: 'Replace the import with: import { readFile, writeFile } from "../helpers/fs"', + }); + } + } + }, + }, +}); +``` + +Quando essa regra é executada contra um arquivo contendo `import { readFileSync } from "node:fs"`, a saída se parece com: + +``` +ARCH-007/no-direct-fs-import ERROR + src/services/config.ts:3 — Direct import from "node:fs" is not allowed. Use the fs wrapper from "src/helpers/fs" instead. + Fix: Replace the import with: import { readFile, writeFile } from "../helpers/fs" +``` + +## Modelo de Execução + +As regras são executadas com as seguintes garantias: + +- **Paralelo entre ADRs** -- Regras de diferentes ADRs são executadas concorrentemente para maior velocidade. +- **Sequencial dentro de um ADR** -- Regras pertencentes ao mesmo ADR são executadas uma após a outra, para que regras anteriores possam estabelecer contexto para as posteriores. +- **Arquivos no escopo são pré-resolvidos** -- O array `ctx.scopedFiles` é preenchido antes que sua função `check` seja chamada, com base nos globs `files` do ADR. +- **Arquivos alterados para modo staged** -- Ao executar `archgate check --staged`, `ctx.changedFiles` contém apenas os arquivos staged no git, permitindo que regras pulem arquivos não alterados para feedback mais rápido. + +:::tip[Execute verificações automaticamente com plugins de editor] +Os plugins de editor para [Claude Code](/guides/claude-code-plugin/) e [Cursor](/guides/cursor-integration/) executam `archgate check` automaticamente após cada alteração de código. O agente lê os ADRs aplicáveis, escreve código em conformidade e valida -- sem necessidade de executar comandos de verificação manualmente. [Inscreva-se para acesso beta](https://plugins.archgate.dev). +::: diff --git a/docs/src/content/docs/pt-br/examples/common-rule-patterns.mdx b/docs/src/content/docs/pt-br/examples/common-rule-patterns.mdx new file mode 100644 index 00000000..f07aeb93 --- /dev/null +++ b/docs/src/content/docs/pt-br/examples/common-rule-patterns.mdx @@ -0,0 +1,273 @@ +--- +title: Padrões Comuns de Regras +description: Padrões de regras prontos para uso em necessidades comuns de governança. +--- + +Esta página fornece exemplos completos de regras, prontos para copiar e colar, para cenários comuns de governança. Cada padrão inclui o código completo da regra, uma explicação de como funciona e orientações sobre quando utilizá-lo. + +## Padrão 1: Lista de Dependências Permitidas + +**Quando usar:** Restringir dependências de produção a uma lista curada para evitar inchaços de dependências e riscos na cadeia de suprimentos. + +```typescript +import { defineRules } from "archgate/rules"; + +const APPROVED_DEPS = [ + "@commander-js/extra-typings", + "inquirer", + "@modelcontextprotocol/sdk", + "zod", +]; + +export default defineRules({ + "no-unapproved-deps": { + description: "Production dependencies must be on the approved list", + async check(ctx) { + let pkg: { dependencies?: Record }; + try { + pkg = (await ctx.readJSON("package.json")) as typeof pkg; + } catch { + return; // No package.json — nothing to check + } + + const deps = Object.keys(pkg.dependencies ?? {}); + for (const dep of deps) { + if (!APPROVED_DEPS.includes(dep)) { + ctx.report.violation({ + message: `Unapproved production dependency: "${dep}". Approved: ${APPROVED_DEPS.join(", ")}`, + file: "package.json", + fix: `Either add "${dep}" to the approved list in the ADR or move it to devDependencies`, + }); + } + } + }, + }, +}); +``` + +**Como funciona:** Lê o `package.json`, itera sobre as `dependencies` de produção e reporta uma violação para qualquer pacote que não esteja no array `APPROVED_DEPS`. Dependências em `devDependencies` não são verificadas. A mensagem de correção orienta o desenvolvedor a obter a aprovação da dependência ou reclassificá-la. + +--- + +## Padrão 2: Padrão de Exportação Obrigatória + +**Quando usar:** Garantir que arquivos em um diretório específico exportem uma assinatura de função obrigatória, como o padrão `register*Command` para arquivos de comandos CLI. + +```typescript +import { defineRules } from "archgate/rules"; + +export default defineRules({ + "register-function-export": { + description: "Command files must export a register*Command function", + async check(ctx) { + const files = ctx.scopedFiles.filter((f) => !f.endsWith("index.ts")); + const checks = files.map(async (file) => { + const content = await ctx.readFile(file); + if (!/export\s+function\s+register\w+Command/.test(content)) { + ctx.report.violation({ + message: "Command file must export a register*Command function", + file, + }); + } + }); + await Promise.all(checks); + }, + }, +}); +``` + +**Como funciona:** Filtra arquivos `index.ts` (barrel files), e então verifica cada arquivo no escopo em busca de uma função exportada que corresponda ao padrão de nomenclatura `register*Command`. A regex procura por `export function register` seguido de quaisquer caracteres alfanuméricos e `Command`. Arquivos que não correspondem recebem uma violação. + +Para adaptar este padrão, altere a regex para corresponder à convenção de exportação exigida pelo seu projeto. Por exemplo, para exigir uma exportação default de um componente React: + +```typescript +if (!/export\s+default\s+function\s+\w+/.test(content)) { +``` + +--- + +## Padrão 3: Importação Banida + +**Quando usar:** Impedir o uso de uma biblioteca ou módulo específico em toda a base de código. Casos de uso comuns incluem banir bibliotecas pesadas como `lodash` ou `moment` em favor de alternativas nativas, ou impedir importações de módulos internos que estão sendo descontinuados. + +```typescript +import { defineRules } from "archgate/rules"; + +const BANNED_IMPORTS = [ + { + pattern: /from\s+['"]lodash['"]/, + name: "lodash", + alternative: "native array methods", + }, + { + pattern: /from\s+['"]moment['"]/, + name: "moment", + alternative: "Temporal API or date-fns", + }, + { + pattern: /from\s+['"]axios['"]/, + name: "axios", + alternative: "native fetch()", + }, +]; + +export default defineRules({ + "no-banned-imports": { + description: "Prevent usage of banned libraries", + async check(ctx) { + for (const banned of BANNED_IMPORTS) { + const matches = await ctx.grepFiles(banned.pattern, "src/**/*.ts"); + for (const match of matches) { + ctx.report.violation({ + message: `Banned import: "${banned.name}" is not allowed. Use ${banned.alternative} instead.`, + file: match.file, + line: match.line, + fix: `Replace ${banned.name} with ${banned.alternative}`, + }); + } + } + }, + }, +}); +``` + +**Como funciona:** Define uma lista de importações banidas com o padrão regex para detectá-las, o nome da biblioteca para a mensagem de erro e a alternativa recomendada. Usa `ctx.grepFiles` para escanear todos os arquivos TypeScript em busca de cada padrão banido e reporta uma violação para cada correspondência. + +Para adicionar mais importações banidas, adicione entradas ao array `BANNED_IMPORTS`. O padrão deve corresponder à parte `from "..."` da instrução de importação. + +--- + +## Padrão 4: Convenção de Nomenclatura de Arquivos + +**Quando usar:** Impor nomenclatura consistente de arquivos em um diretório, como exigir kebab-case para todos os arquivos fonte. + +```typescript +import { defineRules } from "archgate/rules"; +import { basename } from "node:path"; + +const KEBAB_CASE = /^[a-z][a-z0-9]*(-[a-z0-9]+)*\.(ts|tsx|js|jsx)$/; + +export default defineRules({ + "kebab-case-filenames": { + description: "Source files must use kebab-case naming", + async check(ctx) { + for (const file of ctx.scopedFiles) { + const name = basename(file); + + // Skip test files and type declaration files + if (name.endsWith(".test.ts") || name.endsWith(".d.ts")) continue; + + if (!KEBAB_CASE.test(name)) { + ctx.report.violation({ + message: `File "${name}" does not follow kebab-case naming convention`, + file, + fix: `Rename to ${name.replace(/([a-z])([A-Z])/g, "$1-$2").toLowerCase()}`, + }); + } + } + }, + }, +}); +``` + +**Como funciona:** Extrai o basename de cada arquivo no escopo e o testa contra uma regex de kebab-case. A regex exige letras minúsculas e dígitos separados por hífens, com uma extensão de arquivo válida. Arquivos de teste e declarações de tipo são excluídos. A sugestão de correção converte automaticamente camelCase para kebab-case. + +Para alterar a convenção de nomenclatura, substitua a regex. Por exemplo, para camelCase: + +```typescript +const CAMEL_CASE = /^[a-z][a-zA-Z0-9]*\.(ts|tsx|js|jsx)$/; +``` + +--- + +## Padrão 5: Sem Comentários TODO em Produção + +**Quando usar:** Sinalizar comentários TODO, FIXME, HACK e XXX para que sejam resolvidos antes do merge. Usa severidade `warning` para não bloquear o CI, mas torna os comentários visíveis na saída da verificação. + +```typescript +import { defineRules } from "archgate/rules"; + +export default defineRules({ + "no-todo-comments": { + description: "TODO and FIXME comments should be resolved before merging", + severity: "warning", + async check(ctx) { + const matches = await ctx.grepFiles( + /\/\/\s*(TODO|FIXME|HACK|XXX):/i, + "src/**/*.ts" + ); + for (const match of matches) { + ctx.report.warning({ + message: `${match.content.trim()} -- resolve before merging`, + file: match.file, + line: match.line, + }); + } + }, + }, +}); +``` + +**Como funciona:** Usa `ctx.grepFiles` para escanear todos os arquivos TypeScript em `src/` em busca de comentários que comecem com `TODO:`, `FIXME:`, `HACK:` ou `XXX:` (sem distinção de maiúsculas/minúsculas). Cada correspondência é reportada como um aviso com o texto original do comentário. Como a severidade é `"warning"`, a verificação termina com código 0 mesmo quando correspondências são encontradas -- ela exibe os comentários sem bloquear merges. + +Para tornar isso um bloqueio definitivo, altere a severidade para `"error"` e use `ctx.report.violation()` em vez de `ctx.report.warning()`. + +--- + +## Padrão 6: Cobertura de Arquivos de Teste + +**Quando usar:** Garantir que todo arquivo fonte tenha um arquivo de teste correspondente, impedindo que código sem testes seja mergeado. + +```typescript +import { defineRules } from "archgate/rules"; +import { relative } from "node:path"; + +export default defineRules({ + "test-file-exists": { + description: "Every source file should have a corresponding test file", + severity: "warning", + async check(ctx) { + for (const file of ctx.scopedFiles) { + const rel = relative(ctx.projectRoot, file); + const testPath = rel + .replace(/^src\//, "tests/") + .replace(/\.ts$/, ".test.ts"); + const testFiles = await ctx.glob(testPath); + if (testFiles.length === 0) { + ctx.report.warning({ + message: `No test file found at ${testPath}`, + file, + fix: `Create a test file at ${testPath}`, + }); + } + } + }, + }, +}); +``` + +**Como funciona:** Para cada arquivo fonte no escopo, converte o caminho de `src/` para `tests/` e adiciona `.test.ts`. Em seguida, usa `ctx.glob` para verificar se o arquivo de teste existe. Caso não exista, reporta um aviso com uma correção sugerindo o caminho esperado do arquivo de teste. + +Isso pressupõe uma estrutura de diretório de testes que espelha `src/`: + +``` +src/ + helpers/ + log.ts + paths.ts +tests/ + helpers/ + log.test.ts + paths.test.ts +``` + +Para adaptar em projetos que colocam testes ao lado dos arquivos fonte, altere a transformação do caminho: + +```typescript +const testPath = rel.replace(/\.ts$/, ".test.ts"); +// src/helpers/log.ts -> src/helpers/log.test.ts +``` + +:::tip[Deixe agentes de IA escreverem regras para você] +Os plugins de editor para [Claude Code](/guides/claude-code-plugin/) e [Cursor](/guides/cursor-integration/) incluem uma skill de Quality Manager que identifica padrões recorrentes na sua base de código e propõe novas regras para aplicá-los. [Cadastre-se para acesso beta](https://plugins.archgate.dev). +::: diff --git a/docs/src/content/docs/pt-br/getting-started/installation.mdx b/docs/src/content/docs/pt-br/getting-started/installation.mdx new file mode 100644 index 00000000..5ae9f58d --- /dev/null +++ b/docs/src/content/docs/pt-br/getting-started/installation.mdx @@ -0,0 +1,118 @@ +--- +title: Instalação +description: Instale a CLI do Archgate no macOS, Linux ou Windows. +--- + +## Instalar globalmente + +Instale o Archgate globalmente usando seu gerenciador de pacotes preferido: + +```bash +# npm +npm install -g archgate + +# Bun +bun install -g archgate + +# Yarn +yarn global add archgate + +# pnpm +pnpm add -g archgate +``` + +Isso instala um wrapper leve que delega para um binário específico da plataforma. A CLI em si é um binário standalone compilado com Bun — o Node.js é necessário apenas para o wrapper do npm/yarn/pnpm. + +## Instalar como dependência de desenvolvimento + +Você também pode adicionar o Archgate como dependência de desenvolvimento no seu projeto e executá-lo através do script runner do seu gerenciador de pacotes. Isso é útil para fixar uma versão específica por projeto ou executar verificações no CI sem uma instalação global. + +```bash +# npm +npm install -D archgate + +# Bun +bun add -d archgate + +# Yarn +yarn add -D archgate + +# pnpm +pnpm add -D archgate +``` + +Depois execute o Archgate pelo seu gerenciador de pacotes: + +```bash +# npm / Yarn / pnpm +npx archgate check + +# Bun +bun run archgate check +``` + +Ou adicione um script ao seu `package.json`: + +```json +{ + "scripts": { + "check:adrs": "archgate check" + } +} +``` + +```bash +# Works with any package manager +npm run check:adrs +bun run check:adrs +yarn check:adrs +pnpm check:adrs +``` + +## Suporte a plataformas + +O Archgate disponibiliza binários pré-compilados para as seguintes plataformas: + +| Plataforma | Arquitetura | Pacote | +| ---------- | ----------- | ----------------------- | +| macOS | arm64 | `archgate-darwin-arm64` | +| Linux | x86_64 | `archgate-linux-x64` | +| Windows | x86_64 | `archgate-win32-x64` | + +O binário correto é instalado automaticamente como `optionalDependency` quando você instala o `archgate`. + +## Verificar a instalação + +```bash +archgate --version +``` + +Você deverá ver a versão instalada impressa no stdout. + +## Usuários do Proto toolchain + +Se você gerencia o Node.js com o [proto](https://moonrepo.dev/proto) (gerenciador de toolchain do moonrepo), binários npm instalados globalmente requerem um passo adicional de configuração. + +Adicione à sua configuração do proto: + +```toml +# ~/.proto/config.toml +[tools.npm] +shared-globals-dir = true +``` + +Depois adicione o diretório de globais ao perfil do seu shell (`.bashrc`, `.zshrc` ou equivalente): + +```bash +export PATH="$HOME/.proto/tools/node/globals/bin:$PATH" +``` + +Reinicie seu shell e execute `npm install -g archgate` novamente. O comando `archgate` agora deverá estar disponível globalmente. + +## Próximos passos + +Após a instalação, execute `archgate init` no seu projeto para configurar a governança. Veja o guia de [Início Rápido](/getting-started/quick-start/) para um passo a passo. + +:::tip[Plugins para editores (beta)] +Quer que seu agente de IA leia ADRs antes de programar e valide depois? Os plugins para editores do [Claude Code](/guides/claude-code-plugin/) e [Cursor](/guides/cursor-integration/) adicionam um fluxo completo de governança sobre a CLI. [Cadastre-se para acesso beta](https://plugins.archgate.dev). +::: diff --git a/docs/src/content/docs/pt-br/getting-started/quick-start.mdx b/docs/src/content/docs/pt-br/getting-started/quick-start.mdx new file mode 100644 index 00000000..e76f3936 --- /dev/null +++ b/docs/src/content/docs/pt-br/getting-started/quick-start.mdx @@ -0,0 +1,140 @@ +--- +title: Início Rápido +description: Comece a usar o Archgate em menos de 5 minutos. +--- + +## 1. Instalar o Archgate + +Se você ainda não instalou a CLI, instale-a globalmente via npm: + +```bash +npm install -g archgate +``` + +Veja a página de [Instalação](/getting-started/installation/) para detalhes de plataforma e solução de problemas. + +## 2. Inicializar seu projeto + +Navegue até a raiz do seu projeto e execute o comando `init`: + +```bash +cd my-project +archgate init +``` + +Isso cria o diretório `.archgate/` com a seguinte estrutura: + +``` +.archgate/ + adrs/ + ARCH-001-example.md # Example ADR + ARCH-001-example.rules.ts # Example rules file + lint/ + archgate.config.ts # Archgate configuration +``` + +Os arquivos gerados fornecem um exemplo funcional para você construir a partir dele. + +## 3. Editar o ADR de exemplo + +Abra `.archgate/adrs/ARCH-001-example.md`. Todo ADR começa com um frontmatter YAML que define sua identidade: + +```yaml +--- +id: ARCH-001 +title: Example Decision +domain: architecture +rules: true +files: ["src/**/*.ts"] +--- +``` + +- **id** — Identificador único. A convenção é `ARCH-NNN`, mas qualquer string funciona. +- **title** — Nome legível para a decisão. +- **domain** — Agrupa ADRs relacionados (`architecture`, `backend`, `frontend`, `data` ou `general`). +- **rules** — Defina como `true` se este ADR possui um arquivo complementar `.rules.ts` com verificações automatizadas. +- **files** — Padrões glob opcionais que definem o escopo de quais arquivos as regras se aplicam. + +Abaixo do frontmatter, escreva a decisão em markdown. O Archgate não impõe uma estrutura específica de seções, mas as seções recomendadas são: Context, Decision, Do's and Don'ts, Consequences, Compliance e References. + +## 4. Adicionar um arquivo de regras complementar + +Crie um arquivo `.rules.ts` ao lado do seu ADR com o mesmo prefixo de nome. As regras são escritas em TypeScript usando a função `defineRules`: + +```typescript +import { defineRules } from "archgate/rules"; + +export default defineRules({ + "no-console-error": { + description: "Use logError() instead of console.error()", + async check(ctx) { + for (const file of ctx.scopedFiles) { + const matches = await ctx.grep(file, /console\.error\(/); + for (const match of matches) { + ctx.report.violation({ + message: "Use logError() instead of console.error()", + file: match.file, + line: match.line, + fix: "Import logError from your helpers and use it instead", + }); + } + } + }, + }, +}); +``` + +Cada regra possui uma chave única, uma descrição e uma função assíncrona `check`. Dentro de `check`, você tem acesso a: + +- **`ctx.scopedFiles`** — Arquivos que correspondem aos padrões glob do campo `files` do ADR. +- **`ctx.grep(file, pattern)`** — Pesquisa um arquivo por correspondências de regex, retornando caminhos de arquivos e números de linha. +- **`ctx.report.violation()`** — Reporta uma violação com mensagem, caminho do arquivo, número da linha e sugestão opcional de correção. + +## 5. Executar verificações + +Execute o verificador de conformidade contra sua base de código: + +```bash +archgate check +``` + +O Archgate carrega cada ADR com `rules: true`, executa seu arquivo de regras complementar e imprime os resultados. O código de saída indica o resultado: + +| Código de saída | Significado | +| --------------- | ------------------------------------------------------ | +| 0 | Todas as regras passaram. Nenhuma violação encontrada. | +| 1 | Uma ou mais violações detectadas. | +| 2 | Erro interno (ex.: ADR ou regra malformada). | + +Para verificar apenas arquivos staged (útil em pre-commit hooks ou CI): + +```bash +archgate check --staged +``` + +## E agora? + +Agora que você tem uma configuração funcionando, aprofunde-se: + +**Entenda os conceitos:** + +- [ADRs](/concepts/adrs/) — O que são Architecture Decision Records e como o Archgate os utiliza. +- [Regras](/concepts/rules/) — Como arquivos complementares `.rules.ts` transformam decisões em verificações automatizadas. +- [Domínios](/concepts/domains/) — Como domínios agrupam ADRs relacionados e definem o escopo de correspondência de arquivos. + +**Escreva os seus:** + +- [Escrevendo ADRs](/guides/writing-adrs/) — Aprenda o formato completo de ADR e as melhores práticas para escrever decisões eficazes. +- [Escrevendo Regras](/guides/writing-rules/) — Explore a API de regras, padrões avançados e como testar suas regras. +- [Padrões Comuns de Regras](/examples/common-rule-patterns/) — Padrões prontos para copiar e colar para verificações de dependências, convenções de nomenclatura e mais. + +**Integre ao seu fluxo de trabalho:** + +- [Integração com CI](/guides/ci-integration/) — Conecte `archgate check` ao GitHub Actions, GitLab CI ou qualquer pipeline. +- [Pre-commit Hooks](/guides/pre-commit-hooks/) — Execute verificações localmente antes de cada commit. +- [Plugin Claude Code](/guides/claude-code-plugin/) — Dê aos agentes de IA um fluxo completo de governança com habilidades baseadas em papéis. +- [Integração com Cursor](/guides/cursor-integration/) — Use o Archgate com o Cursor IDE para desenvolvimento assistido por IA. + +:::tip[Plugins para editores (beta)] +Quer agentes de IA que leiam automaticamente seus ADRs antes de programar? Cadastre-se para o beta dos plugins para editores em [plugins.archgate.dev](https://plugins.archgate.dev), depois execute `archgate login` e `archgate init --install-plugin`. +::: diff --git a/docs/src/content/docs/pt-br/guides/ci-integration.mdx b/docs/src/content/docs/pt-br/guides/ci-integration.mdx new file mode 100644 index 00000000..f2b54d72 --- /dev/null +++ b/docs/src/content/docs/pt-br/guides/ci-integration.mdx @@ -0,0 +1,208 @@ +--- +title: Integração com CI +description: Adicione verificações do Archgate ao seu pipeline de CI/CD. +--- + +As verificações do Archgate funcionam em qualquer sistema de CI que respeite códigos de saída. Adicione um único passo ao seu pipeline e as violações bloquearão merges automaticamente. + +## GitHub Actions + +A configuração mais simples é um job dedicado que instala o Archgate e executa `archgate check`: + +```yaml +name: ADR Compliance +on: [push, pull_request] + +jobs: + check: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - run: npm install -g archgate + - run: archgate check +``` + +Isso instala o CLI globalmente e executa todas as regras de ADR. Se qualquer regra reportar uma violação com severidade `error`, o passo termina com código 1 e o job falha. + +## Anotações do GitHub Actions + +Use `--ci` para exibir violações como anotações de workflow do GitHub Actions. Elas aparecem inline na aba "Files changed" do pull request, apontando diretamente para o arquivo e a linha com o problema. + +```yaml +- run: archgate check --ci +``` + +A flag `--ci` produz anotações `::error` e `::warning` no formato esperado pelo GitHub Actions. Cada anotação inclui o ID do ADR, o ID da regra, o caminho do arquivo e o número da linha. + +## Saída legível por máquina + +Use `--json` para saída estruturada que outras ferramentas podem processar: + +```yaml +- run: archgate check --json > results.json +``` + +A saída JSON inclui: + +```json +{ + "pass": false, + "total": 6, + "passed": 5, + "failed": 1, + "warnings": 0, + "errors": 1, + "infos": 0, + "ruleErrors": 0, + "truncated": false, + "results": [ + { + "adrId": "ARCH-006", + "ruleId": "no-unapproved-deps", + "description": "Production dependencies must be on the approved list", + "status": "fail", + "totalViolations": 1, + "shownViolations": 1, + "violations": [ + { + "message": "Unapproved production dependency: \"chalk\"", + "file": "package.json", + "severity": "error" + } + ], + "durationMs": 18 + } + ], + "durationMs": 142 +} +``` + +## Códigos de saída + +| Código | Significado | Comportamento no CI | +| ------ | ------------------------------ | ------------------- | +| 0 | Todas as verificações passaram | Job bem-sucedido | +| 1 | Violações encontradas | Job falha | +| 2 | Erro interno | Job falha | + +Avisos (severidade `warning`) são registrados, mas não afetam o código de saída. Apenas violações com severidade `error` causam o código de saída 1. + +## Reduzindo o escopo + +### Verificar apenas arquivos staged + +Use `--staged` para limitar a verificação aos arquivos staged no git. Isso é útil em hooks de pre-commit ou quando você deseja validar apenas o que está prestes a ser commitado: + +```yaml +- run: archgate check --staged +``` + +### Verificar um ADR específico + +Use `--adr ` para executar regras de um único ADR: + +```yaml +- run: archgate check --adr ARCH-006 +``` + +Isso é útil quando um PR altera apenas arquivos governados por um ADR e você deseja feedback mais rápido. + +## Adicionando a um pipeline existente + +Se você já tem uma configuração de CI, adicione o Archgate como um único passo após o checkout: + +```yaml +# Existing pipeline +steps: + - uses: actions/checkout@v4 + - uses: actions/setup-node@v4 + with: + node-version: "22" + - run: npm ci + - run: npm test + + # Add Archgate check + - run: npm install -g archgate + - run: archgate check --ci +``` + +Nenhuma dependência adicional ou arquivo de configuração é necessário além do diretório `.archgate/` que já está no seu repositório. + +## Cache da instalação + +Faça cache do diretório `~/.archgate` para acelerar instalações repetidas: + +```yaml +jobs: + check: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + + - name: Cache Archgate + uses: actions/cache@v4 + with: + path: ~/.archgate + key: archgate-${{ runner.os }} + + - run: npm install -g archgate + - run: archgate check --ci +``` + +## GitLab CI + +```yaml +adr-compliance: + image: node:22 + script: + - npm install -g archgate + - archgate check +``` + +## CI baseado em Bun + +Se seu CI já usa Bun, instale o Archgate com `bun` ao invés de `npm`: + +```yaml +jobs: + check: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: oven-sh/setup-bun@v2 + - run: bun install -g archgate + - run: archgate check --ci +``` + +## Outros sistemas de CI + +O Archgate funciona com qualquer sistema de CI que consiga executar comandos shell. O padrão é sempre o mesmo: + +1. Instalar: `npm install -g archgate` (ou `bun install -g archgate`) +2. Executar: `archgate check` +3. Verificar o código de saída (0 = aprovado, 1 = violações, 2 = erro) + +Para sistemas que suportam anotações (Azure DevOps, Buildkite, etc.), use `--json` para processar a saída e emitir anotações no formato esperado pelo seu CI. + +## Hooks de pre-commit + +Você também pode executar o Archgate como um hook de pre-commit local. Adicione isso a `.git/hooks/pre-commit` (ou use um gerenciador de hooks como Husky ou Lefthook): + +```bash +#!/bin/sh +archgate check --staged +``` + +A flag `--staged` garante que apenas os arquivos prestes a serem commitados sejam verificados, mantendo o hook rápido. + +## Saída detalhada + +Use `--verbose` para ver as regras aprovadas e informações de tempo junto com as falhas. Isso é útil para debugar verificações lentas ou confirmar que as regras estão rodando como esperado: + +```yaml +- run: archgate check --verbose +``` + +:::tip[Adicione governança de IA ao seu fluxo de trabalho] +O CI detecta violações no momento do merge. Plugins de editor detectam no momento da codificação. Com o plugin [Claude Code](/guides/claude-code-plugin/) ou [Cursor](/guides/cursor-integration/), seu agente de IA lê os ADRs antes de escrever código e valida a conformidade antes mesmo de você commitar. [Inscreva-se para acesso beta](https://plugins.archgate.dev). +::: diff --git a/docs/src/content/docs/pt-br/guides/claude-code-plugin.mdx b/docs/src/content/docs/pt-br/guides/claude-code-plugin.mdx new file mode 100644 index 00000000..54b2fd5e --- /dev/null +++ b/docs/src/content/docs/pt-br/guides/claude-code-plugin.mdx @@ -0,0 +1,129 @@ +--- +title: Plugin para Claude Code +description: Dê aos agentes de IA um fluxo de governança completo com o plugin Archgate para Claude Code. +--- + +O plugin Archgate para Claude Code oferece aos agentes de IA que trabalham no [Claude Code](https://claude.ai/code) um fluxo de governança estruturado. Em vez de depender de instruções em prompts que se deterioram com o tempo, os agentes leem seus ADRs diretamente pelo servidor MCP e validam o próprio código contra suas regras. + +## O que o plugin oferece + +O plugin adiciona skills baseadas em papéis ao Claude Code. Cada skill encapsula uma parte específica do fluxo de governança, garantindo que os agentes sigam o mesmo processo todas as vezes -- ler as decisões antes de codificar, validar depois e capturar novos padrões para a equipe. + +### Skills incluídas + +| Skill | Propósito | +| -------------------------- | ------------------------------------------------------------------------------------------ | +| `archgate:developer` | Agente de desenvolvimento geral que lê ADRs antes de codificar e valida depois | +| `archgate:architect` | Valida alterações de código contra todos os ADRs do projeto para conformidade estrutural | +| `archgate:quality-manager` | Revisa a cobertura de regras e propõe novos ADRs quando padrões emergem | +| `archgate:adr-author` | Cria e edita ADRs seguindo as convenções do projeto | +| `archgate:onboard` | Configuração única: explora o codebase, entrevista o desenvolvedor e cria os ADRs iniciais | + +## Instalação + +:::note[Acesso beta necessário] +O plugin para Claude Code está atualmente em beta. [Cadastre-se em plugins.archgate.dev](https://plugins.archgate.dev) para obter acesso antes de seguir os passos abaixo. +::: + +### 1. Faça login com o GitHub + +Autentique-se com sua conta do GitHub para obter um token do plugin: + +```bash +archgate login +``` + +Isso inicia um GitHub Device Flow. O CLI exibe um código único e uma URL -- abra a URL no seu navegador, insira o código e autorize. Ao concluir, as credenciais são armazenadas em `~/.archgate/credentials`. + +### 2. Inicialize seu projeto com o plugin + +Execute `archgate init` no seu projeto. Se você já estiver logado, o plugin é instalado automaticamente: + +```bash +archgate init +``` + +Para solicitar explicitamente a instalação do plugin: + +```bash +archgate init --install-plugin +``` + +Se o CLI `claude` estiver no seu PATH, o plugin é instalado automaticamente via: + +1. `claude plugin marketplace add` (registra o marketplace do Archgate) +2. `claude plugin install archgate@archgate` (instala o plugin) + +Se o CLI `claude` não for encontrado, o comando exibe os comandos manuais para você executar. + +## Configuração inicial com onboard + +Após a instalação, execute a skill `archgate:onboard` no seu projeto uma vez. Essa skill: + +1. Explora a estrutura do seu codebase (diretórios, arquivos-chave, configuração de pacotes) +2. Entrevista você sobre as convenções, restrições e decisões arquiteturais da sua equipe +3. Cria um conjunto inicial de ADRs com base nas suas respostas +4. Configura o diretório `.archgate/` com suas primeiras regras + +A skill de onboard foi projetada para ser executada uma vez por projeto. Após o onboarding, as outras skills cuidam do desenvolvimento no dia a dia. + +## Como funciona na prática + +O plugin segue um fluxo estruturado para cada tarefa de codificação: + +### 1. Ler os ADRs aplicáveis + +Quando o desenvolvedor atribui uma tarefa de codificação, o agente lê todos os ADRs que se aplicam aos arquivos sendo alterados. O servidor MCP fornece um resumo condensado com as seções **Decision** e **Do's and Don'ts** de cada ADR relevante. + +O agente não escreve código até ter lido os ADRs aplicáveis. Isso é garantido pela skill `archgate:developer`. + +### 2. Escrever código seguindo as restrições dos ADRs + +O agente escreve código que cumpre as restrições dos ADRs. As seções Do's and Don'ts servem como guardrails concretos -- o agente as consulta enquanto codifica. + +### 3. Validar as alterações + +Após escrever o código, o agente executa `archgate check` para rodar as regras automatizadas contra as alterações. Qualquer violação é corrigida antes de prosseguir. + +### 4. Revisão do arquiteto + +O agente invoca `archgate:architect` para validar a conformidade estrutural com os ADRs além do que as regras automatizadas capturam. A skill de arquiteto revisa o contexto completo das alterações contra todos os ADRs aplicáveis. + +### 5. Capturar aprendizados + +O agente invoca `archgate:quality-manager` para revisar o trabalho e identificar padrões que valem ser capturados. O quality manager pode propor novos ADRs ou atualizações em existentes quando convenções recorrentes surgem. + +## Recusa orientada por ADRs + +Quando o agente encontra uma tarefa que exigiria violar um ADR, ele recusa e explica qual ADR seria violado. Em seguida, sugere como alcançar o mesmo objetivo mantendo a conformidade. + +Por exemplo, se um desenvolvedor pedir ao agente para adicionar `chalk` como dependência em um projeto governado pelo ARCH-006 (política de dependências), o agente irá: + +1. Recusar, citando o ARCH-006 e a lista de dependências aprovadas +2. Sugerir o uso de `styleText()` do `node:util` como alternativa +3. Oferecer-se para implementar a tarefa usando a alternativa em conformidade + +Esse comportamento é consistente independentemente de como o desenvolvedor formula a solicitação. ADRs são tratados como restrições obrigatórias, não sugestões. + +## Integração com o servidor MCP + +O plugin se comunica com os ADRs do seu projeto por meio do servidor MCP do Archgate. O servidor fornece: + +- **Conteúdo de ADRs** -- texto completo de qualquer ADR, acessível por ID +- **Contexto de revisão** -- resumos condensados de todos os ADRs aplicáveis a um conjunto de arquivos alterados +- **Verificação de regras** -- execução de regras automatizadas com relatório de violações +- **Listagem de ADRs** -- inventário de todos os ADRs do projeto com metadados + +O servidor MCP roda localmente e lê diretamente do seu diretório `.archgate/adrs/`. Nenhum dado sai da sua máquina. + +## Quando usar cada skill + +| Cenário | Skill a usar | +| ------------------------------------------------------- | -------------------------- | +| Iniciando um novo projeto com Archgate | `archgate:onboard` | +| Tarefas de codificação do dia a dia | `archgate:developer` | +| Revisando um PR para conformidade com ADRs | `archgate:architect` | +| Percebendo um padrão recorrente que vale ser codificado | `archgate:quality-manager` | +| Criando ou editando um ADR | `archgate:adr-author` | + +A skill `archgate:developer` orquestra as outras automaticamente -- ela invoca `archgate:architect` e `archgate:quality-manager` como parte do seu fluxo. Na maioria das vezes, você só precisa interagir diretamente com a skill de developer. diff --git a/docs/src/content/docs/pt-br/guides/cursor-integration.mdx b/docs/src/content/docs/pt-br/guides/cursor-integration.mdx new file mode 100644 index 00000000..1225a4a9 --- /dev/null +++ b/docs/src/content/docs/pt-br/guides/cursor-integration.mdx @@ -0,0 +1,167 @@ +--- +title: Integração com Cursor +description: Use o Archgate com o Cursor IDE para desenvolvimento assistido por IA com governança. +--- + +O Archgate se integra com o [Cursor](https://cursor.com) para oferecer aos agentes de IA um fluxo de governança estruturado. O agente lê seus ADRs antes de escrever código, valida depois e captura novos padrões para a equipe -- o mesmo fluxo disponível no [plugin para Claude Code](/guides/claude-code-plugin/). + +## Configuração + +Execute `archgate init` com a flag `--editor cursor` para configurar a integração com o Cursor no seu projeto: + +```bash +archgate init --editor cursor +``` + +### Com plugin (beta) + +:::note[Acesso beta necessário] +O plugin para Cursor está atualmente em beta. [Cadastre-se em plugins.archgate.dev](https://plugins.archgate.dev) para obter acesso. +::: + +Se você fez login via `archgate login`, o comando init também baixa e instala o plugin Archgate para o Cursor. O plugin fornece regras de agente pré-configuradas e skills que dão ao agente de IA do Cursor um fluxo de governança completo. + +Para instalar o plugin explicitamente: + +```bash +archgate login # configuração única +archgate init --editor cursor --install-plugin +``` + +O pacote do plugin é baixado de `plugins.archgate.dev` e extraído no diretório `.cursor/`. Ele inclui regras de agente, definições de skills e configuração MCP. + +### Sem plugin (gratuito) + +Sem o plugin, `archgate init --editor cursor` ainda configura a conexão com o servidor MCP e uma regra de governança básica. O agente de IA pode acessar seus ADRs e executar verificações, mas não recebe as skills baseadas em papéis descritas abaixo. + +### Arquivos gerados + +| Arquivo | Propósito | +| --------------------------------------- | --------------------------------------------------------------------------- | +| `.cursor/mcp.json` | Conexão com o servidor MCP para que o agente de IA do Cursor acesse os ADRs | +| `.cursor/rules/archgate-governance.mdc` | Regra sempre ativa do Cursor que instrui o agente a consultar os ADRs | + +Se `.cursor/mcp.json` já existir, o Archgate mescla sua configuração de forma aditiva -- entradas de servidor MCP existentes são preservadas. + +## O que o plugin oferece + +O plugin adiciona skills baseadas em papéis ao Cursor. Cada skill é invocada como um slash command com o prefixo `/ag-`. As skills encapsulam partes específicas do fluxo de governança para que o agente siga o mesmo processo todas as vezes. + +### Skills incluídas + +| Slash command | Skill | Propósito | +| --------------------- | --------------- | ------------------------------------------------------------------------------------------ | +| `/ag-developer` | Developer | Agente de desenvolvimento geral que lê ADRs antes de codificar e valida depois | +| `/ag-architect` | Architect | Valida alterações de código contra todos os ADRs do projeto para conformidade estrutural | +| `/ag-quality-manager` | Quality Manager | Revisa a cobertura de regras e propõe novos ADRs quando padrões emergem | +| `/ag-adr-author` | ADR Author | Cria e edita ADRs seguindo as convenções do projeto | +| `/ag-onboard` | Onboard | Configuração única: explora o codebase, entrevista o desenvolvedor e cria os ADRs iniciais | + +Essas são as mesmas skills disponíveis no plugin para Claude Code (`archgate:developer`, `archgate:architect`, etc.), adaptadas para a interface de slash commands do Cursor. + +## Configuração inicial com onboard + +Após instalar o plugin, execute `/ag-onboard` no seu projeto uma vez. Essa skill: + +1. Explora a estrutura do seu codebase (diretórios, arquivos-chave, configuração de pacotes) +2. Entrevista você sobre as convenções, restrições e decisões arquiteturais da sua equipe +3. Cria um conjunto inicial de ADRs com base nas suas respostas +4. Configura o diretório `.archgate/` com suas primeiras regras + +A skill de onboard foi projetada para ser executada uma vez por projeto. Após o onboarding, as outras skills cuidam do desenvolvimento no dia a dia. + +## Como funciona na prática + +### Com o plugin + +A skill `/ag-developer` segue um fluxo estruturado para cada tarefa de codificação: + +1. **Ler os ADRs aplicáveis** -- O agente chama `review_context` para ver quais ADRs se aplicam aos arquivos sendo alterados. Ele não escreve código até ter lido os ADRs aplicáveis. + +2. **Escrever código seguindo as restrições dos ADRs** -- O agente implementa as alterações seguindo as seções Do's and Don'ts dos ADRs aplicáveis. + +3. **Executar verificações de conformidade** -- O agente executa `archgate check` para rodar as regras automatizadas. Qualquer violação é corrigida antes de prosseguir. + +4. **Revisão do arquiteto** -- O agente invoca `/ag-architect` para validar a conformidade estrutural com os ADRs além do que as regras automatizadas capturam. + +5. **Capturar aprendizados** -- O agente invoca `/ag-quality-manager` para revisar o trabalho e identificar padrões que valem ser capturados como novos ADRs ou atualizações em existentes. + +### Sem o plugin + +O agente se conecta ao servidor MCP do Archgate e segue quatro passos manuais: + +1. **Revisar contexto** -- Chamar `review_context` para ver quais ADRs se aplicam aos arquivos sendo alterados. + +2. **Ler ADRs individuais** -- Para contexto completo sobre uma decisão específica, ler o recurso `adr://` (por exemplo, `adr://ARCH-001`). + +3. **Escrever código** -- Implementar as alterações seguindo as restrições dos ADRs aplicáveis. + +4. **Executar verificações de conformidade** -- Chamar `check` (opcionalmente com `staged: true`) para validar que o código está em conformidade com todas as regras dos ADRs. + +## Recusa orientada por ADRs + +Quando o agente encontra uma tarefa que exigiria violar um ADR, ele recusa e explica qual ADR seria violado. Em seguida, sugere como alcançar o mesmo objetivo mantendo a conformidade. + +Por exemplo, se um desenvolvedor pedir ao agente para adicionar `chalk` como dependência em um projeto governado por um ADR de política de dependências, o agente irá: + +1. Recusar, citando o ADR e a lista de dependências aprovadas +2. Sugerir o uso da alternativa aprovada +3. Oferecer-se para implementar a tarefa usando a abordagem em conformidade + +Esse comportamento é consistente independentemente de como o desenvolvedor formula a solicitação. ADRs são tratados como restrições obrigatórias, não sugestões. + +## Quando usar cada skill + +| Cenário | Slash command | +| ------------------------------------------------------- | --------------------- | +| Iniciando um novo projeto com Archgate | `/ag-onboard` | +| Tarefas de codificação do dia a dia | `/ag-developer` | +| Revisando um PR para conformidade com ADRs | `/ag-architect` | +| Percebendo um padrão recorrente que vale ser codificado | `/ag-quality-manager` | +| Criando ou editando um ADR | `/ag-adr-author` | + +A skill `/ag-developer` orquestra as outras automaticamente -- ela invoca `/ag-architect` e `/ag-quality-manager` como parte do seu fluxo. Na maioria das vezes, você só precisa usar `/ag-developer` diretamente. + +## Configuração do servidor MCP + +O arquivo `.cursor/mcp.json` gerado registra o servidor MCP do Archgate: + +```json +{ + "mcpServers": { + "archgate": { + "command": "archgate", + "args": ["mcp"] + } + } +} +``` + +A regra de governança em `.cursor/rules/archgate-governance.mdc` usa `alwaysApply: true`, o que significa que o agente do Cursor sempre tem o contexto de governança disponível sem ativação manual. + +O servidor MCP fornece: + +- **Conteúdo de ADRs** -- texto completo de qualquer ADR, acessível por ID via recursos `adr://` +- **Contexto de revisão** -- resumos condensados de todos os ADRs aplicáveis a um conjunto de arquivos alterados +- **Verificação de regras** -- execução de regras automatizadas com relatório de violações +- **Listagem de ADRs** -- inventário de todos os ADRs do projeto com metadados + +O servidor MCP roda localmente e lê diretamente do seu diretório `.archgate/adrs/`. Nenhum dado sai da sua máquina. + +## Acesso a transcrições de sessão + +A ferramenta MCP `cursor_session_context` lê transcrições de sessão do agente Cursor a partir do disco. Isso permite que as skills acessem o histórico da conversa atual, o que é útil para recuperar contexto que pode ter sido compactado ou truncado. + +A ferramenta aceita dois parâmetros opcionais: + +- `maxEntries` -- Número máximo de entradas a retornar (padrão: 200, entradas mais recentes). +- `sessionId` -- Um UUID de sessão específico para ler. Se omitido, a sessão mais recente é usada. + +## Dicas para uso eficaz + +- **Use `/ag-developer` para tarefas de codificação.** Ele orquestra todo o fluxo de leitura-validação-captura automaticamente. +- **Execute `/ag-onboard` uma vez por projeto.** Ele configura seus ADRs iniciais com base no seu codebase e convenções reais. +- **Use `/ag-architect` para revisões de PR.** Ele valida a conformidade estrutural além do que as regras automatizadas capturam. +- **Use `/ag-quality-manager` após resolver problemas complexos.** Ele captura aprendizados para que os mesmos erros não se repitam. +- **Faça commit do diretório `.cursor/`.** Isso garante que cada membro da equipe receba a mesma configuração de governança ao clonar o repositório. +- **Mantenha os arquivos de regras dos ADRs atualizados.** O agente aplica o que as regras verificam -- se uma regra estiver faltando, a violação não será detectada. diff --git a/docs/src/content/docs/pt-br/guides/mcp-server.mdx b/docs/src/content/docs/pt-br/guides/mcp-server.mdx new file mode 100644 index 00000000..98e7f1bf --- /dev/null +++ b/docs/src/content/docs/pt-br/guides/mcp-server.mdx @@ -0,0 +1,123 @@ +--- +title: Servidor MCP +description: Use o servidor MCP do Archgate para integração com agentes de IA. +--- + +O servidor MCP do Archgate expõe os ADRs e verificações de conformidade do seu projeto para agentes de IA por meio do [Model Context Protocol](https://modelcontextprotocol.io/). Qualquer cliente compatível com MCP -- Claude Code, Cursor ou ferramentas customizadas -- pode se conectar a ele. + +## Iniciando o servidor + +O servidor usa transporte stdio. Inicie-o com: + +```bash +archgate mcp +``` + +Normalmente você não executa esse comando manualmente. Em vez disso, configure sua ferramenta de IA para iniciá-lo automaticamente (veja abaixo). + +## Configurando no Claude Code + +Adicione o seguinte ao arquivo `.mcp.json` do seu projeto (crie-o se não existir): + +```json +{ + "mcpServers": { + "archgate": { + "command": "archgate", + "args": ["mcp"] + } + } +} +``` + +O Claude Code lê esse arquivo na inicialização e se conecta ao servidor MCP do Archgate automaticamente. Você também pode executar `archgate init` (que usa `--editor claude` por padrão) para gerar essa configuração junto com o diretório `.archgate/` completo. + +## Configurando no Cursor + +Execute `archgate init --editor cursor` para gerar `.cursor/mcp.json` com a mesma configuração de servidor. Consulte o guia de [Integração com Cursor](/guides/cursor-integration/) para mais detalhes. + +## Ferramentas MCP disponíveis + +O servidor registra cinco ferramentas que agentes de IA podem chamar. + +### `check` + +Executa verificações de conformidade com ADRs no codebase. + +| Parâmetro | Tipo | Descrição | +| --------- | ---------- | ----------------------------------------- | +| `adrId` | `string?` | Verificar apenas um ADR específico por ID | +| `staged` | `boolean?` | Verificar apenas arquivos staged no git | + +Retorna um resumo JSON com status de aprovação/reprovação, contagem de violações e resultados detalhados incluindo caminhos de arquivo e números de linha. + +### `list_adrs` + +Lista todos os ADRs do projeto com metadados. + +| Parâmetro | Tipo | Descrição | +| --------- | --------- | ------------------------------------------------------------------------------ | +| `domain` | `string?` | Filtrar por domínio (`backend`, `frontend`, `data`, `architecture`, `general`) | + +Retorna um array de objetos com os campos `id`, `title`, `domain` e `rules` para cada ADR. + +### `review_context` + +Obtém arquivos alterados agrupados por domínio com resumos dos ADRs aplicáveis. Este é o ponto de partida recomendado para um agente iniciando uma tarefa -- ele combina detecção de alterações em arquivos, agrupamento por domínio e sumarização de ADRs em uma única chamada. + +| Parâmetro | Tipo | Descrição | +| ----------- | ---------- | -------------------------------------------------------------------------------------- | +| `staged` | `boolean?` | Quando true, inclui apenas arquivos staged no git. Padrão: todos os arquivos alterados | +| `runChecks` | `boolean?` | Quando true, executa verificações de conformidade e inclui os resultados | +| `domain` | `string?` | Filtra os resultados para um único domínio | + +Retorna resumos contendo apenas as seções Decision e Do's/Don'ts de cada ADR aplicável, mantendo a resposta concisa. + +### `claude_code_session_context` + +Lê a transcrição da sessão atual do Claude Code para o projeto. Retorna entradas filtradas (mensagens do usuário e do assistente) do arquivo JSONL da sessão mais recente. + +| Parâmetro | Tipo | Descrição | +| ------------ | --------- | ---------------------------------------------------------------------------- | +| `maxEntries` | `number?` | Número máximo de entradas relevantes a retornar (padrão: 200, mais recentes) | + +### `cursor_session_context` + +Lê transcrições de sessão do agente Cursor para o projeto. Retorna entradas filtradas dos arquivos JSONL de agent-transcripts do Cursor. + +| Parâmetro | Tipo | Descrição | +| ------------ | --------- | ---------------------------------------------------------------------------- | +| `maxEntries` | `number?` | Número máximo de entradas relevantes a retornar (padrão: 200, mais recentes) | +| `sessionId` | `string?` | UUID de sessão específico para ler. Se omitido, lê a sessão mais recente | + +## Recursos MCP disponíveis + +### `adr://\{id\}` + +Lê o conteúdo completo de um ADR por ID. Substitua o placeholder `id` pelo identificador do ADR (por exemplo, `adr://ARCH-001`). + +Retorna o ADR completo em markdown incluindo frontmatter, justificativa, decisão, do's and don'ts, consequências, conformidade e seções de referências. + +## Comportamento sem projeto + +Se o servidor MCP iniciar em um diretório sem um diretório `.archgate/`, todas as ferramentas permanecem disponíveis mas retornam orientações instruindo o agente a executar `archgate init` para inicializar a governança. O servidor não trava nem se recusa a iniciar -- ele fornece feedback acionável para que o agente possa configurar o projeto. + +## Exemplo de fluxo de uso + +Uma sessão típica de agente de IA usando o servidor MCP segue este padrão: + +1. **O agente chama `review_context`** com `runChecks: false` para obter um resumo condensado de todos os ADRs que se aplicam ao conjunto atual de arquivos alterados. + +2. **O agente lê os resumos** e identifica quais restrições arquiteturais se aplicam à sua tarefa. + +3. **O agente lê um ADR completo** via `adr://ARCH-002` (por exemplo) quando precisa da justificativa completa ou exemplos de implementação além do resumo condensado. + +4. **O agente escreve código** seguindo as restrições dos ADRs aplicáveis. + +5. **O agente chama `check`** com `staged: true` para validar a conformidade. Se violações forem encontradas, a resposta inclui caminhos de arquivo e números de linha para que o agente possa corrigi-las. + +6. **O agente itera** até que `check` reporte zero violações. + +:::tip[Automatize todo esse fluxo] +Os plugins de editor para [Claude Code](/guides/claude-code-plugin/) e [Cursor](/guides/cursor-integration/) automatizam esse fluxo de ponta a ponta. O agente lê ADRs, escreve código em conformidade, executa verificações, valida com a skill de arquiteto e captura aprendizados -- tudo sem chamadas manuais de ferramentas MCP. [Cadastre-se para acesso beta](https://plugins.archgate.dev). +::: diff --git a/docs/src/content/docs/pt-br/guides/pre-commit-hooks.mdx b/docs/src/content/docs/pt-br/guides/pre-commit-hooks.mdx new file mode 100644 index 00000000..6ec969be --- /dev/null +++ b/docs/src/content/docs/pt-br/guides/pre-commit-hooks.mdx @@ -0,0 +1,92 @@ +--- +title: Hooks de Pre-commit +description: Execute verificações do Archgate automaticamente antes de cada commit. +--- + +## Visão geral + +O comando `archgate check --staged` verifica apenas os arquivos staged no git em relação às suas regras de ADR. Como ele ignora arquivos não-staged e não-rastreados, ele executa rápido o suficiente para ser usado como hook de pre-commit sem desacelerar seu fluxo de trabalho. + +Quando uma verificação falha, o commit é bloqueado. As violações são impressas em stderr com caminhos de arquivo e números de linha para que você possa localizá-las e corrigi-las imediatamente. + +## Lefthook + +[Lefthook](https://github.com/evilmartians/lefthook) é um gerenciador de hooks git rápido e multiplataforma. Adicione o seguinte ao seu `lefthook.yml`: + +```yaml +# lefthook.yml +pre-commit: + commands: + adr-check: + run: archgate check --staged +``` + +Instale o hook com: + +```bash +lefthook install +``` + +## Husky + +[Husky](https://typicode.github.io/husky/) é uma ferramenta popular de hooks git para projetos Node.js. Adicione a verificação ao seu hook de pre-commit: + +```bash +# .husky/pre-commit +archgate check --staged +``` + +Certifique-se de que o arquivo do hook é executável: + +```bash +chmod +x .husky/pre-commit +``` + +## O que acontece quando as verificações falham + +Quando `archgate check --staged` encontra violações, ele termina com código 1. Isso bloqueia o commit. A saída inclui: + +- O ID do ADR e o nome da regra que foi violada +- O caminho do arquivo onde a violação foi encontrada +- O número da linha (quando disponível) +- Uma descrição do que a regra espera + +Corrija as violações, re-stage os arquivos com `git add` e faça o commit novamente. + +## Performance + +A flag `--staged` restringe as verificações apenas aos arquivos na área de staging do git. Isso significa: + +- Um projeto com centenas de arquivos fonte mas apenas três arquivos staged verificará apenas esses três arquivos. +- Regras que não correspondem a nenhum arquivo staged são ignoradas completamente. +- Verificações típicas de pre-commit completam em menos de um segundo. + +Sem `--staged`, `archgate check` escaneia todos os arquivos correspondentes ao padrão glob `files` de cada ADR, o que é útil para CI mas mais lento para uso interativo. + +## Flags úteis + +| Flag | Finalidade | +| ------------ | -------------------------------------------------------------------------------------------------------------------------------------------- | +| `--staged` | Verifica apenas arquivos staged no git (obrigatório para pre-commit) | +| `--verbose` | Mostra regras aprovadas e informações de tempo -- útil para debugar por que uma verificação está lenta ou quais regras estão sendo avaliadas | +| `--json` | Exibe resultados como JSON -- útil para encaminhar a outras ferramentas ou scripts de relatório personalizados | +| `--adr ` | Verifica apenas regras de um ADR específico -- útil para isolar uma única regra durante o debug | +| `--ci` | Exibe anotações do GitHub Actions -- use em workflows de CI ao invés de hooks de pre-commit | + +## Combinando com outros hooks + +Hooks de pre-commit podem executar múltiplos comandos. Por exemplo, com Lefthook: + +```yaml +# lefthook.yml +pre-commit: + commands: + lint: + run: npm run lint + typecheck: + run: npm run typecheck + adr-check: + run: archgate check --staged +``` + +Cada comando executa independentemente. Se qualquer comando terminar com código diferente de zero, o commit é bloqueado. diff --git a/docs/src/content/docs/pt-br/guides/writing-adrs.mdx b/docs/src/content/docs/pt-br/guides/writing-adrs.mdx new file mode 100644 index 00000000..bcf561ed --- /dev/null +++ b/docs/src/content/docs/pt-br/guides/writing-adrs.mdx @@ -0,0 +1,310 @@ +--- +title: Escrevendo ADRs +description: Um guia completo para escrever Registros de Decisão Arquitetural eficazes. +--- + +## Criando um ADR + +Use `archgate adr create` para gerar um novo ADR com o template padrão. O comando suporta modos interativo e não-interativo. + +### Modo interativo + +Execute o comando sem argumentos para receber prompts guiados: + +```bash +archgate adr create +``` + +Você será solicitado a fornecer: + +1. **Domain** -- um entre `backend`, `frontend`, `data`, `architecture` ou `general` +2. **Title** -- um nome curto e descritivo para a decisão +3. **File patterns** -- globs opcionais separados por vírgula que delimitam o escopo da verificação de regras (ex.: `src/commands/**/*.ts`) + +O CLI atribui um ID sequencial baseado no prefixo do domínio (`ARCH-001`, `FE-002`, `BE-003`, etc.) e grava o arquivo em `.archgate/adrs/`. + +### Modo não-interativo + +Passe `--title` e `--domain` para pular os prompts: + +```bash +archgate adr create --title "API Response Format" --domain backend --files "src/api/**/*.ts" +``` + +Flags disponíveis: + +| Flag | Descrição | +| ----------------- | -------------------------------------------------------------- | +| `--title ` | Título do ADR (obrigatório no modo não-interativo) | +| `--domain <name>` | Domínio: backend, frontend, data, architecture, general | +| `--files <globs>` | Padrões de arquivo separados por vírgula para escopo de regras | +| `--rules` | Define `rules: true` no frontmatter | +| `--body <md>` | Corpo completo do ADR em markdown (pula o template) | +| `--json` | Exibe o resultado como JSON | + +## O template gerado + +Quando você cria um ADR sem `--body`, o CLI gera um template com todas as seções padrão: + +```markdown +--- +id: BE-001 +title: API Response Format +domain: backend +rules: false +files: ["src/api/**/*.ts"] +--- + +# API Response Format + +## Context + +Describe the context and problem statement. + +## Decision + +Describe the decision that was made. + +## Do's and Don'ts + +### Do + +- + +### Don't + +- + +## Consequences + +### Positive + +- + +### Negative + +- + +### Risks + +- + +## Compliance and Enforcement + +Describe how this decision will be enforced. + +## References + +- +``` + +## Orientações por seção + +### Context + +Explique por que essa decisão foi necessária. Qual problema a motivou? Quais alternativas foram consideradas e por que foram descartadas? + +Boas seções de contexto incluem: + +- O problema ou ponto de dor que motivou a decisão +- Alternativas avaliadas, com uma breve análise de trade-offs +- Quaisquer restrições que limitaram as opções (tamanho da equipe, runtime, compatibilidade) + +```markdown +## Context + +The CLI needs a consistent pattern for defining and registering commands. As the +command surface grows (init, check, adr, mcp, upgrade, clean), the registration +mechanism must scale without introducing hidden coupling or making the dependency +graph opaque. + +**Alternatives considered:** + +- **Auto-discovery via `executableDir()`** -- Commander.js supports automatic + command discovery by scanning a directory. This hides the dependency graph and + makes dead command detection impossible. +- **Single-file command map** -- Simple but creates a monolithic file that grows + with every command. +``` + +### Decision + +Declare o que foi decidido. Seja específico e concreto -- esta seção não deve deixar ambiguidade sobre o que os desenvolvedores devem fazer. + +Inclua restrições numeradas quando a decisão tem múltiplas facetas: + +```markdown +## Decision + +Commands live in src/commands/ and export a register\*Command(program) function. +The main entry point (src/cli.ts) explicitly imports and calls each register +function. + +**Key constraints:** + +1. **One command per file** -- Each .ts file defines exactly one command +2. **Explicit registration** -- Every command must be manually imported in src/cli.ts +3. **Thin commands** -- Command files handle I/O only; no business logic +``` + +### Do's and Don'ts + +Esta é a seção que desenvolvedores e agentes de IA consultam com mais frequência. Escreva exemplos concretos de padrões corretos e incorretos. Use código real sempre que possível. + +```markdown +## Do's and Don'ts + +### Do + +- Export a register\*Command function from each command module +- Keep commands thin: parse args, call helpers/engine, format output +- Use src/commands/<name>.ts for top-level commands + +### Don't + +- Don't put business logic in command files -- move it to src/engine/ or src/helpers/ +- Don't use executableDir() for command discovery +- Don't call .parse() in command files -- the entry point handles parsing +``` + +### Consequences + +Divida as consequências em três categorias: + +- **Positive** -- benefícios que a equipe ganha com esta decisão +- **Negative** -- trade-offs que a equipe aceita (toda decisão tem) +- **Risks** -- o que pode dar errado, e como você planeja mitigar + +```markdown +## Consequences + +### Positive + +- In-process execution enables testing without spawning subprocesses +- Explicit imports make all commands visible at a glance in src/cli.ts + +### Negative + +- Manual import bookkeeping -- each new command requires adding an import + +### Risks + +- Stale imports when commands are removed. Mitigation: TypeScript catches + missing modules at compile time. +``` + +### Compliance and Enforcement + +Descreva como esta decisão é aplicada. Existem dois mecanismos de aplicação: + +1. **Regras automatizadas** -- arquivos `.rules.ts` complementares que rodam durante `archgate check` +2. **Aplicação manual** -- o que revisores de código devem verificar + +```markdown +## Compliance and Enforcement + +### Automated Enforcement + +- **Archgate rule** ARCH-001/register-function-export: Scans all command files + and verifies each exports a register\*Command function. Severity: error. + +### Manual Enforcement + +Code reviewers MUST verify: + +1. New commands are imported and registered in src/cli.ts +2. Command files delegate to engine/helpers for business logic +``` + +### References + +Vincule ADRs relacionados, documentação externa ou discussões relevantes: + +```markdown +## References + +- [Commander.js documentation](https://github.com/tj/commander.js) +- [ARCH-004 -- No Barrel Files](./ARCH-004-no-barrel-files.md) +- [ARCH-002 -- Error Handling](./ARCH-002-error-handling.md) +``` + +## Delimitando regras com `files` + +O campo `files` no frontmatter é um array de padrões glob. Quando definido, `archgate check` passa apenas os arquivos correspondentes para o `ctx.scopedFiles` da regra. Isso mantém as regras focadas no código que elas governam. + +```yaml +--- +id: ARCH-001 +title: Command Structure +domain: architecture +rules: true +files: ["src/commands/**/*.ts"] +--- +``` + +Se `files` for omitido, `ctx.scopedFiles` inclui todos os arquivos do projeto. Isso é apropriado para regras que abrangem todo o projeto, como políticas de dependências. + +Padrões comuns: + +| Padrão | Corresponde a | +| ---------------------- | -------------------------------------------- | +| `src/commands/**/*.ts` | Todos os arquivos TypeScript em commands | +| `src/**/*.ts` | Todos os arquivos TypeScript do código-fonte | +| `package.json` | Apenas o package.json raiz | +| `src/api/**/*.ts` | Arquivos da camada de API | +| `tests/**/*.test.ts` | Arquivos de teste | + +## Quando definir `rules: true` vs `rules: false` + +Defina `rules: true` quando você tiver um arquivo `.rules.ts` complementar com verificações automatizadas. O arquivo deve ter o mesmo nome do arquivo markdown do ADR, mas com a extensão `.rules.ts`: + +``` +.archgate/adrs/ + ARCH-001-command-structure.md # rules: true + ARCH-001-command-structure.rules.ts # companion rules file + ARCH-002-error-handling.md # rules: true + ARCH-002-error-handling.rules.ts # companion rules file + GEN-001-code-review-process.md # rules: false (no automated checks) +``` + +Defina `rules: false` para decisões que são aplicadas apenas por revisão de código -- decisões de processo, acordos de equipe ou diretrizes difíceis de verificar programaticamente. + +## Atualizando ADRs + +Use `archgate adr update` para modificar um ADR existente: + +```bash +archgate adr update --id ARCH-001 --body "## Context\n\nUpdated context..." --title "New Title" +``` + +As flags `--id` e `--body` são obrigatórias. Todos os outros campos do frontmatter (`--title`, `--domain`, `--files`, `--rules`) são opcionais e preservam seus valores existentes quando omitidos. + +| Flag | Descrição | +| ----------------- | ------------------------------------------------------------ | +| `--id <id>` | ID do ADR a ser atualizado (obrigatório) | +| `--body <md>` | Corpo markdown de substituição completa (obrigatório) | +| `--title <title>` | Novo título (preserva o existente se omitido) | +| `--domain <name>` | Novo domínio (preserva o existente se omitido) | +| `--files <globs>` | Novos padrões de arquivo (preserva os existentes se omitido) | +| `--rules` | Define `rules: true` | +| `--json` | Exibe o resultado como JSON | + +## Dicas para ADRs eficazes + +1. **Mantenha cada ADR focado em uma única decisão.** Se você perceber que está escrevendo sobre dois assuntos não relacionados, divida-os em ADRs separados. + +2. **Seja específico nos Do's and Don'ts.** Diretrizes vagas como "escreva código limpo" não são acionáveis. Mostre padrões de código concretos. + +3. **Inclua exemplos de código reais.** A seção Do's and Don'ts é onde desenvolvedores e agentes de IA olham primeiro. Exemplos de código anotados tornam a decisão inequívoca. + +4. **Documente as alternativas que você rejeitou.** Futuros colaboradores perguntarão "por que não usamos X?" A seção Context deve responder a essa pergunta. + +5. **Declare os trade-offs honestamente.** Toda decisão tem consequências negativas. Documentá-las gera confiança e ajuda a equipe a entender o que foi sacrificado. + +6. **Escreva regras para decisões que podem ser verificadas automaticamente.** Se uma regra consegue detectar uma violação antes da revisão de código, defina `rules: true` e escreva um arquivo `.rules.ts` complementar. Veja o guia [Escrevendo Regras](/pt-br/guides/writing-rules/). + +7. **Use prefixos de domínio para organizar.** O campo domain (`backend`, `frontend`, `data`, `architecture`, `general`) determina o prefixo do ID e ajuda a filtrar ADRs por área. + +:::tip[Deixe agentes de IA escreverem ADRs para você] +Os plugins de editor para [Claude Code](/guides/claude-code-plugin/) e [Cursor](/guides/cursor-integration/) incluem uma skill de ADR Author que cria e atualiza ADRs seguindo as convenções do seu projeto. A skill Quality Manager também propõe novos ADRs quando detecta padrões recorrentes. [Inscreva-se para acesso beta](https://plugins.archgate.dev). +::: diff --git a/docs/src/content/docs/pt-br/guides/writing-rules.mdx b/docs/src/content/docs/pt-br/guides/writing-rules.mdx new file mode 100644 index 00000000..1b3bd773 --- /dev/null +++ b/docs/src/content/docs/pt-br/guides/writing-rules.mdx @@ -0,0 +1,453 @@ +--- +title: Escrevendo Regras +description: Aprenda a escrever regras automatizadas que aplicam suas decisões de ADR. +--- + +Regras são funções TypeScript que verificam seu codebase quanto à conformidade com ADRs. Elas ficam em arquivos `.rules.ts` complementares ao lado dos arquivos markdown dos ADRs e são executadas quando você roda `archgate check`. + +``` +.archgate/adrs/ + ARCH-001-command-structure.md # The decision + ARCH-001-command-structure.rules.ts # The automated checks +``` + +## Configuração básica + +Todo arquivo de regras exporta uma chamada `defineRules()` por padrão. Cada chave se torna um ID de regra, e cada regra tem uma `description` e uma função async `check` que recebe um objeto de contexto. + +```typescript +import { defineRules } from "archgate/rules"; + +export default defineRules({ + "my-rule-id": { + description: "What this rule checks", + async check(ctx) { + // Your check logic here + }, + }, +}); +``` + +Um único arquivo de regras pode definir múltiplas regras: + +```typescript +import { defineRules } from "archgate/rules"; + +export default defineRules({ + "first-rule": { + description: "Checks one thing", + async check(ctx) { + // ... + }, + }, + "second-rule": { + description: "Checks another thing", + async check(ctx) { + // ... + }, + }, +}); +``` + +## A API de Contexto + +O objeto `ctx` passado para toda função `check` fornece capacidades de leitura de arquivos, busca e relatório. Aqui está uma referência detalhada com exemplos. + +### ctx.scopedFiles + +Um array de caminhos de arquivo que correspondem ao glob `files` do frontmatter do ADR. Se o ADR não tiver o campo `files`, isso inclui todos os arquivos do projeto. + +```typescript +for (const file of ctx.scopedFiles) { + const content = await ctx.readFile(file); + // Check content... +} +``` + +Use `ctx.scopedFiles` quando sua regra deve se aplicar apenas aos arquivos que o ADR governa. Por exemplo, uma regra de estrutura de comandos com escopo `src/commands/**/*.ts` receberá apenas arquivos de comandos. + +### ctx.changedFiles + +Um array de caminhos de arquivo que foram modificados (staged ou alterados no git). Útil para verificação incremental -- valide apenas os arquivos que foram efetivamente alterados. + +```typescript +const filesToCheck = ctx.scopedFiles.filter((f) => + ctx.changedFiles.includes(f) +); +for (const file of filesToCheck) { + // Only check changed files +} +``` + +### ctx.readFile(path) + +Lê o conteúdo de um arquivo como string. O caminho é relativo à raiz do projeto. + +```typescript +const content = await ctx.readFile("src/cli.ts"); +``` + +### ctx.readJSON(path) + +Lê e faz o parse de um arquivo JSON. Retorna `unknown` -- faça cast para o formato esperado. + +```typescript +const pkg = (await ctx.readJSON("package.json")) as { + dependencies?: Record<string, string>; +}; +``` + +### ctx.grep(file, pattern) + +Busca em um único arquivo com uma expressão regular. Retorna um array de objetos `GrepMatch`, cada um com as propriedades `file`, `line`, `column` e `content`. + +```typescript +const matches = await ctx.grep(file, /console\.error\(/); +for (const match of matches) { + ctx.report.violation({ + message: "Use logError() instead of console.error()", + file: match.file, + line: match.line, + }); +} +``` + +### ctx.grepFiles(pattern, fileGlob) + +Busca em múltiplos arquivos que correspondem a um padrão glob. Retorna um array plano de objetos `GrepMatch` de todos os arquivos correspondentes. + +```typescript +const matches = await ctx.grepFiles(/TODO:/, "src/**/*.ts"); +for (const match of matches) { + ctx.report.warning({ + message: "TODO comment found", + file: match.file, + line: match.line, + }); +} +``` + +### ctx.glob(pattern) + +Encontra arquivos por padrão glob. Retorna um array de caminhos de arquivo relativos à raiz do projeto. + +```typescript +const testFiles = await ctx.glob("tests/**/*.test.ts"); +``` + +### ctx.report + +A interface de relatório com três métodos de severidade: + +- `ctx.report.violation(detail)` -- severidade error (código de saída 1, bloqueia CI) +- `ctx.report.warning(detail)` -- severidade warning (registrado, mas não bloqueia) +- `ctx.report.info(detail)` -- informacional (registrado para visibilidade) + +Cada método aceita um objeto com: + +| Campo | Tipo | Obrigatório | Descrição | +| --------- | -------- | ----------- | -------------------------------------------- | +| `message` | `string` | Sim | Qual é a violação | +| `file` | `string` | Não | Caminho do arquivo com a violação | +| `line` | `number` | Não | Número da linha da violação | +| `fix` | `string` | Não | Correção sugerida (exibida ao desenvolvedor) | + +```typescript +ctx.report.violation({ + message: "Command file must export a register*Command function", + file: "src/commands/check.ts", + line: 5, + fix: "Add: export function registerCheckCommand(program: Command) { ... }", +}); +``` + +### ctx.projectRoot + +O caminho absoluto para o diretório raiz do projeto. Útil quando você precisa construir caminhos absolutos. + +## Exemplos completos + +### Exemplo 1: Lista de dependências permitidas + +Verifica se todas as dependências de produção estão em uma lista aprovada. Esta é a regra que o Archgate usa para sua própria política de dependências ARCH-006. + +```typescript +import { defineRules } from "archgate/rules"; + +const APPROVED_DEPS = [ + "@commander-js/extra-typings", + "inquirer", + "@modelcontextprotocol/sdk", + "zod", +]; + +export default defineRules({ + "no-unapproved-deps": { + description: "Production dependencies must be on the approved list", + async check(ctx) { + let pkg: { dependencies?: Record<string, string> }; + try { + pkg = (await ctx.readJSON("package.json")) as typeof pkg; + } catch { + return; + } + + const deps = Object.keys(pkg.dependencies ?? {}); + for (const dep of deps) { + if (!APPROVED_DEPS.includes(dep)) { + ctx.report.violation({ + message: `Unapproved production dependency: "${dep}". Approved: ${APPROVED_DEPS.join(", ")}`, + file: "package.json", + fix: `Either add "${dep}" to the approved list in the ADR or move it to devDependencies`, + }); + } + } + }, + }, +}); +``` + +### Exemplo 2: Padrão de export obrigatório + +Verifica se todo arquivo de comando exporta uma função `register*Command`. Esta é a regra que o Archgate usa para sua própria estrutura de comandos ARCH-001. + +```typescript +import { defineRules } from "archgate/rules"; + +export default defineRules({ + "register-function-export": { + description: "Command files must export a register*Command function", + async check(ctx) { + const files = ctx.scopedFiles.filter((f) => !f.endsWith("index.ts")); + const checks = files.map(async (file) => { + const content = await ctx.readFile(file); + if (!/export\s+function\s+register\w+Command/.test(content)) { + ctx.report.violation({ + message: "Command file must export a register*Command function", + file, + }); + } + }); + await Promise.all(checks); + }, + }, +}); +``` + +### Exemplo 3: Padrão de import proibido + +Impede a importação de uma biblioteca específica quando alternativas nativas existem. + +```typescript +import { defineRules } from "archgate/rules"; + +export default defineRules({ + "no-lodash": { + description: "Do not use lodash -- use native array methods instead", + async check(ctx) { + const matches = await ctx.grepFiles( + /import\s+.*from\s+['"]lodash/, + "src/**/*.ts" + ); + for (const match of matches) { + ctx.report.violation({ + message: "Do not import lodash. Use native array methods instead.", + file: match.file, + line: match.line, + fix: "Replace lodash usage with native Array.prototype methods", + }); + } + }, + }, +}); +``` + +### Exemplo 4: Convenção de nomenclatura de arquivos + +Aplica nomenclatura kebab-case para arquivos fonte. + +```typescript +import { defineRules } from "archgate/rules"; +import { basename } from "node:path"; + +export default defineRules({ + "kebab-case-files": { + description: "Source files must use kebab-case naming", + async check(ctx) { + for (const file of ctx.scopedFiles) { + const name = basename(file).replace(/\.(ts|tsx|js|jsx)$/, ""); + if (name !== name.toLowerCase() || name.includes("_")) { + ctx.report.violation({ + message: `File name "${basename(file)}" must be kebab-case (lowercase with hyphens)`, + file, + fix: `Rename to ${name.toLowerCase().replace(/_/g, "-")}`, + }); + } + } + }, + }, +}); +``` + +### Exemplo 5: Tamanho máximo de arquivo + +Emite um aviso quando arquivos excedem um limite de linhas. + +```typescript +import { defineRules } from "archgate/rules"; + +const MAX_LINES = 300; + +export default defineRules({ + "max-file-length": { + description: `Source files should not exceed ${MAX_LINES} lines`, + async check(ctx) { + const checks = ctx.scopedFiles.map(async (file) => { + const content = await ctx.readFile(file); + const lineCount = content.split("\n").length; + if (lineCount > MAX_LINES) { + ctx.report.warning({ + message: `File has ${lineCount} lines (max: ${MAX_LINES}). Consider splitting it.`, + file, + fix: "Extract related functions into separate modules", + }); + } + }); + await Promise.all(checks); + }, + }, +}); +``` + +### Exemplo 6: Cobertura de testes obrigatória + +Verifica se todo arquivo fonte possui um arquivo de teste correspondente. + +```typescript +import { defineRules } from "archgate/rules"; +import { basename } from "node:path"; + +export default defineRules({ + "test-file-exists": { + description: "Every source module must have a corresponding test file", + async check(ctx) { + const testFiles = await ctx.glob("tests/**/*.test.ts"); + const testBaseNames = new Set( + testFiles.map((f) => basename(f).replace(".test.ts", "")) + ); + + for (const file of ctx.scopedFiles) { + const name = basename(file).replace(/\.ts$/, ""); + if (!testBaseNames.has(name)) { + ctx.report.warning({ + message: `No test file found for ${basename(file)}`, + file, + fix: `Create tests/${name}.test.ts`, + }); + } + } + }, + }, +}); +``` + +## Níveis de severidade + +Cada regra pode definir uma severidade padrão em sua configuração. A severidade determina como as violações são tratadas: + +| Severidade | Código de saída | Comportamento | +| ---------- | --------------- | ------------------------------------------- | +| `error` | 1 | Bloqueia CI, deve ser corrigido | +| `warning` | 0 | Registrado, mas não bloqueia | +| `info` | 0 | Informacional, registrado para visibilidade | + +Defina a severidade na definição da regra: + +```typescript +export default defineRules({ + "my-rule": { + description: "...", + severity: "warning", + async check(ctx) { + // Violations from this rule are warnings, not errors + ctx.report.violation({ message: "..." }); + }, + }, +}); +``` + +Se `severity` for omitido, o padrão é `error`. + +Você também pode reportar com diferentes severidades dentro da mesma regra usando `ctx.report.violation()`, `ctx.report.warning()` e `ctx.report.info()` diretamente. + +## Timeout de regras + +Cada regra tem um timeout de execução de 30 segundos. Se uma regra exceder esse limite, ela é tratada como erro. Isso impede que verificações descontroladas bloqueiem o pipeline. + +Mantenha as regras rápidas: + +- Usando `ctx.grepFiles()` ao invés de ler cada arquivo manualmente +- Usando `Promise.all()` para verificar arquivos em paralelo +- Delimitando regras com o campo `files` do frontmatter para limitar o número de arquivos processados + +## O campo `fix` + +O campo `fix` é uma string opcional exibida ao desenvolvedor junto com a mensagem de violação. Ele descreve qual ação tomar para resolver o problema. Correções não são aplicadas automaticamente -- são orientações. + +```typescript +ctx.report.violation({ + message: `Unapproved dependency: "chalk"`, + file: "package.json", + fix: "Use styleText() from node:util instead of chalk", +}); +``` + +Quando exibido, o fix aparece abaixo da mensagem de violação: + +``` +ARCH-006/no-unapproved-deps + package.json + Unapproved dependency: "chalk" + Fix: Use styleText() from node:util instead of chalk +``` + +## Dicas para escrever regras + +1. **Use `Promise.all()` para verificações de arquivo em paralelo.** Ao verificar múltiplos arquivos independentes, processe-os em paralelo ao invés de sequencialmente. + + ```typescript + // Good: parallel + const checks = files.map(async (file) => { + const content = await ctx.readFile(file); + // ... + }); + await Promise.all(checks); + + // Avoid: sequential + for (const file of files) { + const content = await ctx.readFile(file); + // ... + } + ``` + +2. **Use `ctx.changedFiles` para verificação incremental.** Ao executar `archgate check --staged`, `ctx.changedFiles` contém apenas os arquivos staged no git. Filtre `ctx.scopedFiles` com ele para verificar apenas o que mudou. + +3. **Mantenha as regras focadas em uma única preocupação.** Uma regra que verifica tanto convenções de nomenclatura quanto padrões de import deve ser dividida em duas regras com IDs separados. + +4. **Use `ctx.grepFiles()` ao invés de iteração manual.** Ao buscar um padrão em muitos arquivos, `ctx.grepFiles()` é mais eficiente do que ler cada arquivo e executar uma regex. + +5. **Forneça mensagens de `fix` acionáveis.** Um fix como "Não faça isso" não é útil. Diga ao desenvolvedor exatamente o que fazer. + +6. **Filtre arquivos não-aplicáveis cedo.** Se sua regra se aplica apenas a certos arquivos dentro do escopo, filtre `ctx.scopedFiles` antes de processar: + + ```typescript + const commandFiles = ctx.scopedFiles.filter((f) => !f.endsWith("index.ts")); + ``` + +7. **Trate arquivos ausentes com elegância.** Se sua regra lê um arquivo específico como `package.json`, envolva a leitura em um try/catch e retorne antecipadamente se o arquivo não existir. + +## Próximos passos + +- [Common Rule Patterns](/examples/common-rule-patterns/) — Padrões prontos para copiar e colar para verificações de dependências, convenções de nomenclatura, restrições de import e mais. +- [Rule API Reference](/reference/rule-api/) — Referência completa de todos os tipos e funções da API de regras. +- [Integração com CI](/pt-br/guides/ci-integration/) — Integre `archgate check` ao seu pipeline para aplicar regras em cada PR. diff --git a/docs/src/content/docs/pt-br/index.mdx b/docs/src/content/docs/pt-br/index.mdx new file mode 100644 index 00000000..349d8a06 --- /dev/null +++ b/docs/src/content/docs/pt-br/index.mdx @@ -0,0 +1,123 @@ +--- +title: Archgate +description: Aplique Architecture Decision Records como regras executáveis — para humanos e agentes de IA. +template: splash +hero: + tagline: Escreva um ADR uma vez. Aplique em todo lugar. Alimente agentes de IA automaticamente. + actions: + - text: Primeiros Passos + link: /getting-started/installation/ + icon: right-arrow + variant: primary + - text: Ver no GitHub + link: https://github.com/archgate/cli + icon: external + variant: minimal +--- + +import { Card, CardGrid, LinkCard } from "@astrojs/starlight/components"; + +## Como funciona + +O Archgate possui duas camadas que trabalham juntas: + +1. **ADRs como documentos** — Arquivos Markdown com frontmatter YAML que descrevem decisões arquiteturais em linguagem natural. Humanos os leem. Agentes de IA os leem. Todos ficam alinhados. + +2. **ADRs como regras** — Arquivos complementares `.rules.ts` com verificações automatizadas escritas em TypeScript. Eles são executados contra sua base de código e reportam violações com caminhos de arquivos e números de linha. + +``` +.archgate/ + adrs/ + ARCH-001-command-structure.md # The decision (human + AI readable) + ARCH-001-command-structure.rules.ts # The checks (machine executable) + ARCH-002-error-handling.md + ARCH-002-error-handling.rules.ts + lint/ + archgate.config.ts # Archgate configuration +``` + +Quando você executa `archgate check`, a CLI carrega cada ADR que possui `rules: true` em seu frontmatter, executa o arquivo de regras complementar e reporta quaisquer violações. Código de saída 0 significa que seu código está em conformidade. Código de saída 1 significa que não está. + +## Funcionalidades Principais + +<CardGrid> + <Card title="Regras Executáveis" icon="seti:typescript"> + Escreva regras em TypeScript. O Archgate as executa contra sua base de + código e reporta violações com caminhos de arquivos e números de linha. As + regras ficam ao lado das decisões que elas aplicam. + </Card> + <Card title="Integração com CI" icon="seti:pipeline"> + Conecte `archgate check` ao seu pipeline. Código de saída 1 bloqueia merges + quando regras são violadas. Funciona com GitHub Actions, GitLab CI ou + qualquer sistema de CI que respeite códigos de saída. + </Card> + <Card title="Governança com IA" icon="star"> + O servidor MCP dá aos agentes de IA acesso em tempo real aos seus ADRs. Eles + leem as decisões antes de escrever código e validam depois. Sem copiar e + colar regras nos prompts. + </Card> + <Card title="Auto-Governança" icon="approve-check-circle"> + O Archgate governa seu próprio desenvolvimento. A mesma ferramenta que + verifica seu código verifica o nosso. Seis ADRs aplicam estrutura de + comandos, tratamento de erros, formatação de saída, testes e mais. + </Card> +</CardGrid> + +## Plugins para editores + +A CLI do Archgate funciona de forma independente, mas os **plugins para editores** habilitam um fluxo completo de governança com IA. Os plugins dão aos agentes de IA habilidades baseadas em papéis para que leiam seus ADRs antes de programar, validem depois e capturem novos padrões para sua equipe -- automaticamente. + +<CardGrid> + <Card title="Claude Code" icon="star"> + O plugin para Claude Code adiciona cinco habilidades: developer, architect, + quality-manager, adr-author e onboard. Os agentes seguem um ciclo + estruturado de leitura-validação-captura em cada tarefa. + </Card> + <Card title="Cursor" icon="pencil"> + O plugin para Cursor fornece regras e habilidades pré-configuradas para + agentes, dando ao agente de IA do Cursor o mesmo fluxo de governança do + Claude Code. + </Card> +</CardGrid> + +:::tip[Acesso beta] +Os plugins para editores estão atualmente em beta. Cadastre-se em [plugins.archgate.dev](https://plugins.archgate.dev) para obter acesso, depois instale com `archgate login` e `archgate init --install-plugin`. +::: + +<CardGrid> + <LinkCard + title="Guia do plugin Claude Code" + href="/guides/claude-code-plugin/" + description="Guia completo de configuração e uso do plugin Claude Code." + /> + <LinkCard + title="Guia de integração com Cursor" + href="/guides/cursor-integration/" + description="Configure o Archgate com o Cursor IDE." + /> +</CardGrid> + +## Saiba mais + +<CardGrid> + <LinkCard + title="O que são ADRs?" + href="/concepts/adrs/" + description="Entenda os Architecture Decision Records e como o Archgate os utiliza." + /> + <LinkCard + title="Escrevendo Regras" + href="/guides/writing-rules/" + description="Escreva regras em TypeScript que aplicam suas decisões automaticamente." + /> + <LinkCard + title="Integração com CI" + href="/guides/ci-integration/" + description="Bloqueie merges quando regras forem violadas no GitHub Actions, GitLab CI ou qualquer pipeline." + /> + <LinkCard + title="Comandos da CLI" + href="/reference/cli-commands/" + description="Referência completa de todos os comandos e opções da CLI do Archgate." + /> +</CardGrid> diff --git a/docs/src/content/docs/pt-br/reference/adr-schema.mdx b/docs/src/content/docs/pt-br/reference/adr-schema.mdx new file mode 100644 index 00000000..19b48c60 --- /dev/null +++ b/docs/src/content/docs/pt-br/reference/adr-schema.mdx @@ -0,0 +1,281 @@ +--- +title: Esquema de ADR +description: Esquema de frontmatter YAML e estrutura markdown para ADRs do Archgate. +--- + +Todo ADR do Archgate é um arquivo Markdown armazenado em `.archgate/adrs/` com frontmatter YAML que define a identidade e o escopo da decisão. Esta página documenta o esquema do frontmatter, a estrutura das seções markdown e o comportamento de validação. + +## Esquema do Frontmatter + +O bloco de frontmatter YAML fica entre delimitadores `---` no topo do arquivo. + +```yaml +--- +id: ARCH-001 +title: Command Structure +domain: architecture +rules: true +files: ["src/commands/**/*.ts"] +--- +``` + +### Campos + +| Campo | Tipo | Obrigatório | Descrição | +| -------- | ---------- | ----------- | -------------------------------------------------------------------------------------- | +| `id` | `string` | Sim | Identificador único. Não pode ser vazio. Convenção: `PREFIX-NNN` (ex.: `ARCH-001`). | +| `title` | `string` | Sim | Título legível da decisão. Não pode ser vazio. | +| `domain` | `enum` | Sim | Categoria de domínio. Um de: `backend`, `frontend`, `data`, `architecture`, `general`. | +| `rules` | `boolean` | Sim | Se este ADR possui um arquivo `.rules.ts` complementar com verificações automatizadas. | +| `files` | `string[]` | Não | Padrões glob que definem o escopo de quais arquivos as regras se aplicam. | + +### id + +O identificador do ADR. Por convenção, usa o prefixo do domínio seguido de um número de sequência com preenchimento de zeros (ex.: `ARCH-001`, `BE-003`). O comando `archgate adr create` gera IDs automaticamente. + +Qualquer string não vazia é válida, mas seguir a convenção de prefixo mantém os ADRs organizados e ordenáveis. + +### title + +Um nome curto e descritivo para a decisão arquitetural. Exibido na saída de `archgate adr list` e usado como cabeçalho quando agentes de IA referenciam o ADR. + +### domain + +Agrupa ADRs relacionados. O domínio também determina o prefixo do ID usado por `archgate adr create`. + +### rules + +Defina como `true` quando este ADR tem um arquivo `.rules.ts` complementar. Quando `archgate check` é executado, ele pula ADRs onde `rules` é `false`. + +### files + +Um array opcional de padrões glob que definem o escopo de cobertura de arquivos da regra. Quando presente, `ctx.scopedFiles` no arquivo de regras contém apenas arquivos que correspondem a esses padrões. Quando ausente, todos os arquivos do projeto estão no escopo. + +```yaml +files: ["src/commands/**/*.ts"] +``` + +Múltiplos padrões podem ser especificados: + +```yaml +files: ["src/api/**/*.ts", "src/middleware/**/*.ts"] +``` + +--- + +## Prefixos de Domínio + +Cada domínio mapeia para um prefixo usado na convenção de ID do ADR. + +| Domínio | Prefixo | ID de Exemplo | +| -------------- | ------- | ------------- | +| `backend` | `BE` | `BE-001` | +| `frontend` | `FE` | `FE-001` | +| `data` | `DATA` | `DATA-001` | +| `architecture` | `ARCH` | `ARCH-001` | +| `general` | `GEN` | `GEN-001` | + +O comando `archgate adr create` usa esse mapeamento para gerar IDs automaticamente. + +--- + +## Convenção de Nomenclatura de Arquivos + +Os arquivos de ADR seguem uma convenção de nomenclatura que codifica o ID e um slug legível: + +``` +{ID}-{slug}.md # The document +{ID}-{slug}.rules.ts # The companion rules file (optional) +``` + +Por exemplo: + +``` +ARCH-001-command-structure.md +ARCH-001-command-structure.rules.ts +``` + +O slug é uma versão kebab-case do título, gerada automaticamente por `archgate adr create`. + +--- + +## Seções Markdown + +Após o frontmatter, o corpo do ADR segue uma estrutura de seções padrão. Embora o Archgate não imponha seções específicas, a estrutura a seguir é recomendada para consistência. + +### Context + +Descreve o problema ou situação que motivou a decisão. Inclua alternativas que foram consideradas e por que foram rejeitadas. + +```markdown +## Context + +The CLI returns errors in inconsistent formats. Some commands print raw +stack traces, others print nothing, and a few use `console.error()` with +custom formatting. + +**Alternatives considered:** + +- **No standard** -- Let each command handle errors its own way. Simple + but leads to an inconsistent user experience. +- **Try/catch wrapper** -- A global try/catch at the CLI entry point. + Loses context about which command failed. +``` + +### Decision + +Declara a decisão em si e suas principais restrições. Esta é a seção principal que os agentes de IA leem antes de escrever código. + +```markdown +## Decision + +All commands MUST use `logError()` from `src/helpers/log.ts` for error +output. Commands MUST NOT call `console.error()` directly. +``` + +### Do's and Don'ts + +Orientação concreta e acionável dividida em duas subseções. Funciona como um checklist de referência rápida para desenvolvedores e agentes de IA. + +```markdown +## Do's and Don'ts + +### Do + +- Use `logError(message, detail?)` for all error output +- Include a suggested fix in the detail parameter when possible +- Exit with code 1 for user errors, code 2 for internal errors + +### Don't + +- Don't call `console.error()` directly in command files +- Don't print stack traces to users +- Don't exit without printing an error message first +``` + +### Consequences + +Dividida em três subseções que documentam os tradeoffs. + +```markdown +## Consequences + +### Positive + +- Consistent error formatting across all commands +- Machine-parseable error output when combined with `--json` + +### Negative + +- Requires importing `logError` in every command file +- Cannot use built-in error formatting from libraries + +### Risks + +- New contributors may use `console.error()` by habit. Mitigated by the + automated rule that scans for direct `console.error()` calls. +``` + +### Compliance and Enforcement + +Descreve como a decisão é aplicada por meio de regras automatizadas e revisão manual. + +```markdown +## Compliance and Enforcement + +### Automated Enforcement + +- **Archgate rule** ARCH-002/no-console-error: Scans command files for + `console.error()` calls. Severity: error. + +### Manual Enforcement + +Code reviewers MUST verify: + +1. Error messages are actionable and include context +2. Exit codes match the error type (1 for user, 2 for internal) +``` + +### References + +Links para ADRs relacionados, documentação externa ou documentos de design. + +```markdown +## References + +- [ARCH-001 -- Command Structure](./ARCH-001-command-structure.md) +- [Node.js process.exit documentation](https://nodejs.org/api/process.html#processexitcode) +``` + +--- + +## Arquivo de Regras Complementar + +Quando `rules: true`, o Archgate procura um arquivo complementar com o mesmo nome mas extensão `.rules.ts`. + +``` +ARCH-002-error-handling.md # rules: true in frontmatter +ARCH-002-error-handling.rules.ts # companion rules file +``` + +O arquivo de regras deve exportar um `RuleSet` padrão criado via `defineRules()`: + +```typescript +import { defineRules } from "archgate/rules"; + +export default defineRules({ + "no-console-error": { + description: "Use logError() instead of console.error()", + async check(ctx) { + for (const file of ctx.scopedFiles) { + const matches = await ctx.grep(file, /console\.error\(/); + for (const match of matches) { + ctx.report.violation({ + message: "Use logError() instead of console.error()", + file: match.file, + line: match.line, + fix: "Import logError from src/helpers/log and use it instead", + }); + } + } + }, + }, +}); +``` + +Consulte a [API de Regras](/pt-br/reference/rule-api/) para a referência completa da API TypeScript. + +--- + +## Validação + +O frontmatter YAML é validado no momento do parse usando um esquema Zod. Frontmatter inválido causa um erro de parse com uma mensagem descritiva. + +### Campos obrigatórios + +Se um campo obrigatório estiver ausente, o ADR falha no parse: + +``` +Invalid ADR frontmatter in ARCH-001-example.md: + - domain: Required +``` + +### Valores de enum inválidos + +Se `domain` não for um dos valores válidos: + +``` +Invalid ADR frontmatter in ARCH-001-example.md: + - domain: Invalid enum value. Expected 'backend' | 'frontend' | 'data' | 'architecture' | 'general', received 'security' +``` + +### Incompatibilidade de tipos + +Se `rules` for uma string em vez de um booleano: + +``` +Invalid ADR frontmatter in ARCH-001-example.md: + - rules: Expected boolean, received string +``` + +ADRs que falham na validação são ignorados por `archgate check` e reportados como erros. diff --git a/docs/src/content/docs/pt-br/reference/cli-commands.mdx b/docs/src/content/docs/pt-br/reference/cli-commands.mdx new file mode 100644 index 00000000..0db6b86a --- /dev/null +++ b/docs/src/content/docs/pt-br/reference/cli-commands.mdx @@ -0,0 +1,461 @@ +--- +title: Comandos da CLI +description: Referência completa de todos os comandos da CLI do Archgate. +--- + +## Opções globais + +Estas opções estão disponíveis em todos os comandos: + +| Opção | Descrição | +| ----------------- | ---------------------------------- | +| `--version`, `-V` | Exibe a versão do Archgate | +| `--help`, `-h` | Mostra ajuda para qualquer comando | + +```bash +archgate --version +archgate check --help +``` + +--- + +## archgate login + +Autentique-se com o GitHub para acessar os plugins de editor do Archgate. + +```bash +archgate login +``` + +Inicia um GitHub Device Flow (OAuth). A CLI exibe um código de uso único e uma URL. Abra a URL no seu navegador, insira o código e autorize o Archgate GitHub OAuth App. Após a autorização, a CLI troca sua identidade do GitHub por um token de plugin do Archgate e armazena ambos em `~/.archgate/credentials`. + +As credenciais são necessárias para instalar plugins de editor via `archgate init --install-plugin`. A CLI em si (check, init, mcp, etc.) funciona sem login. + +:::tip[Plugin em beta] +Os plugins de editor estão atualmente em beta. Cadastre-se em [plugins.archgate.dev](https://plugins.archgate.dev) para obter acesso. +::: + +### Subcomandos + +| Subcomando | Descrição | +| ------------------------ | -------------------------------------- | +| `archgate login` | Autenticar (pula se já estiver logado) | +| `archgate login status` | Mostrar o status atual de autenticação | +| `archgate login logout` | Remover credenciais armazenadas | +| `archgate login refresh` | Reautenticar e solicitar um novo token | + +### Exemplos + +Fazer login pela primeira vez: + +```bash +archgate login +``` + +``` +Authenticating with GitHub... + +Open https://github.com/login/device in your browser +and enter the code: ABCD-1234 + +Waiting for authorization... +GitHub user: yourname +Claiming archgate plugin token... + +Authenticated as yourname. Plugin access is now available. +Run `archgate init` to set up a project with the archgate plugin. +``` + +Verificar o status do login: + +```bash +archgate login status +``` + +``` +Logged in as yourname (since 2026-02-28) +``` + +Fazer logout: + +```bash +archgate login logout +``` + +Reautenticar: + +```bash +archgate login refresh +``` + +--- + +## archgate init + +Inicializa a governança do Archgate no projeto atual. + +```bash +archgate init [options] +``` + +Cria o diretório `.archgate/` com um ADR de exemplo, arquivo de regras complementar e configuração do linter. Opcionalmente configura a integração com o editor para fluxos de trabalho com agentes de IA e instala o plugin de editor do Archgate. + +### Opções + +| Opção | Padrão | Descrição | +| ------------------- | -------- | ------------------------------------------------------------------------ | +| `--editor <editor>` | `claude` | Integração de editor a configurar (`claude`, `cursor`) | +| `--install-plugin` | auto | Instalar o plugin de editor do Archgate (requer `archgate login` prévio) | + +Quando `--install-plugin` é passado, a CLI instala o plugin do Archgate para o editor selecionado. Se a flag for omitida, a CLI faz detecção automática: instala o plugin quando existem credenciais válidas (de um `archgate login` anterior) e pula caso contrário. + +### Comportamento de instalação do plugin + +**Claude Code:** Se a CLI `claude` estiver no seu PATH, o plugin é instalado automaticamente via `claude plugin marketplace add` e `claude plugin install`. Se a CLI `claude` não for encontrada, o comando exibe os comandos de instalação manual. + +**Cursor:** O pacote do plugin é baixado de `plugins.archgate.dev` e extraído no diretório `.cursor/`. + +### Saída + +``` +Initialized Archgate governance in /path/to/project + adrs/ - architecture decision records + lint/ - linter-specific rules + .claude/ - Claude Code settings configured + +Archgate plugin installed for Claude Code. +``` + +Quando `--editor cursor` é usado, a saída mostra `.cursor/` em vez de `.claude/`. + +### Estrutura gerada + +``` +.archgate/ + adrs/ + ARCH-001-example.md # Example ADR + ARCH-001-example.rules.ts # Example rules file + lint/ + archgate.config.ts # Archgate configuration +``` + +--- + +## archgate check + +Executa todas as verificações automatizadas de conformidade com ADRs no codebase. + +```bash +archgate check [options] +``` + +Carrega cada ADR com `rules: true` no frontmatter, executa o arquivo `.rules.ts` complementar e reporta violações com caminhos de arquivo e números de linha. + +### Opções + +| Opção | Descrição | +| ------------ | ---------------------------------------------------------------------- | +| `--staged` | Verificar apenas arquivos no git stage (útil para hooks de pre-commit) | +| `--json` | Saída JSON legível por máquina | +| `--ci` | Formato de anotação do GitHub Actions | +| `--adr <id>` | Verificar apenas regras de um ADR específico | +| `--verbose` | Mostrar regras aprovadas e informações de tempo | + +### Códigos de saída + +| Código | Significado | +| ------ | ------------------------------------------------------ | +| 0 | Todas as regras passaram. Nenhuma violação encontrada. | +| 1 | Uma ou mais violações detectadas. | +| 2 | Erro interno (ex.: ADR ou regra malformada). | + +### Exemplos + +Verificar o projeto inteiro: + +```bash +archgate check +``` + +Verificar apenas arquivos no stage antes de commitar: + +```bash +archgate check --staged +``` + +Verificar um único ADR: + +```bash +archgate check --adr ARCH-001 +``` + +Obter saída JSON para integração com CI: + +```bash +archgate check --json +``` + +Obter anotações do GitHub Actions: + +```bash +archgate check --ci +``` + +### Formato da saída JSON + +Quando `--json` é usado, a saída é um único objeto JSON: + +```json +{ + "pass": false, + "total": 4, + "passed": 3, + "failed": 1, + "warnings": 0, + "errors": 1, + "infos": 0, + "ruleErrors": 0, + "truncated": false, + "results": [ + { + "adrId": "ARCH-001", + "ruleId": "register-function-export", + "description": "Command file must export a register*Command function", + "status": "fail", + "totalViolations": 1, + "shownViolations": 1, + "violations": [ + { + "message": "Command file must export a register*Command function", + "file": "src/commands/broken.ts", + "severity": "error" + } + ], + "durationMs": 12 + } + ], + "durationMs": 42 +} +``` + +--- + +## archgate adr create + +Cria um novo ADR interativamente ou via flags. + +```bash +archgate adr create [options] +``` + +Quando executado sem `--title` e `--domain`, o comando solicita interativamente o domínio, título e padrões de arquivo opcionais. Quando ambos `--title` e `--domain` são fornecidos, ele executa de forma não interativa. + +O ID do ADR é gerado automaticamente com o prefixo do domínio e o próximo número de sequência disponível (ex.: `ARCH-002`, `BE-001`). + +### Opções + +| Opção | Descrição | +| -------------------- | ------------------------------------------------------------------------- | +| `--title <title>` | Título do ADR (pula o prompt interativo) | +| `--domain <domain>` | Domínio do ADR (`backend`, `frontend`, `data`, `architecture`, `general`) | +| `--files <patterns>` | Padrões de arquivo, separados por vírgula | +| `--body <markdown>` | Corpo completo do ADR em markdown (pula o template) | +| `--rules` | Define `rules: true` no frontmatter | +| `--json` | Saída como JSON | + +### Exemplos + +Modo interativo: + +```bash +archgate adr create +``` + +Modo não interativo: + +```bash +archgate adr create \ + --title "API Response Envelope" \ + --domain backend \ + --files "src/api/**/*.ts" \ + --rules +``` + +--- + +## archgate adr list + +Lista todos os ADRs do projeto. + +```bash +archgate adr list [options] +``` + +### Opções + +| Opção | Descrição | +| ------------------- | ------------------- | +| `--json` | Saída como JSON | +| `--domain <domain>` | Filtrar por domínio | + +### Exemplos + +Listar todos os ADRs em formato de tabela: + +```bash +archgate adr list +``` + +``` +ID Domain Rules Title +──────────────────────────────────────────────────────── +ARCH-001 architecture true Command Structure +ARCH-002 architecture true Error Handling +BE-001 backend true API Response Envelope +``` + +Listar ADRs como JSON: + +```bash +archgate adr list --json +``` + +Filtrar por domínio: + +```bash +archgate adr list --domain backend +``` + +--- + +## archgate adr show + +Exibe um ADR específico pelo ID. + +```bash +archgate adr show <id> +``` + +Imprime o conteúdo completo do ADR (frontmatter e corpo) na saída padrão. + +### Argumentos + +| Argumento | Descrição | +| --------- | ------------------------------------- | +| `<id>` | ID do ADR (ex.: `ARCH-001`, `BE-003`) | + +### Exemplo + +```bash +archgate adr show ARCH-001 +``` + +--- + +## archgate adr update + +Atualiza um ADR existente pelo ID. + +```bash +archgate adr update --id <id> --body <markdown> [options] +``` + +Substitui o corpo do ADR pelo markdown fornecido. Campos do frontmatter (`--title`, `--domain`, `--files`, `--rules`) são atualizados apenas quando passados explicitamente; caso contrário, os valores existentes são preservados. + +### Opções + +| Opção | Obrigatório | Descrição | +| -------------------- | ----------- | ------------------------------------------------------------------------------- | +| `--id <id>` | Sim | ID do ADR a atualizar (ex.: `ARCH-001`) | +| `--body <markdown>` | Sim | Corpo completo do ADR em markdown (substitui o existente) | +| `--title <title>` | Não | Novo título do ADR (preserva o existente se omitido) | +| `--domain <domain>` | Não | Novo domínio (`backend`, `frontend`, `data`, `architecture`, `general`) | +| `--files <patterns>` | Não | Novos padrões de arquivo, separados por vírgula (preserva existente se omitido) | +| `--rules` | Não | Define `rules: true` no frontmatter | +| `--json` | Não | Saída como JSON | + +### Exemplo + +```bash +archgate adr update \ + --id ARCH-001 \ + --title "Updated Command Structure" \ + --body "## Context\n\nUpdated context..." +``` + +--- + +## archgate mcp + +Inicia o servidor MCP para integração com agentes de IA. + +```bash +archgate mcp +``` + +Executa um servidor MCP usando transporte stdio. O servidor expõe ferramentas para verificar conformidade com ADRs, listar ADRs e obter contexto de revisão. Consulte a referência de [Ferramentas MCP](/pt-br/reference/mcp-tools/) para a lista completa de ferramentas e recursos disponíveis. + +O servidor inicia mesmo quando nenhum diretório `.archgate/` é encontrado. Nesse caso, as ferramentas retornam orientações direcionando o agente a inicializar a governança primeiro. + +### Configuração + +Adicione a configuração MCP do seu projeto (`.mcp.json` na raiz do projeto): + +```json +{ + "mcpServers": { + "archgate": { + "command": "archgate", + "args": ["mcp"] + } + } +} +``` + +Executar `archgate init` cria essa configuração automaticamente para o seu editor. + +--- + +## archgate upgrade + +Atualiza o Archgate para a versão mais recente via npm. + +```bash +archgate upgrade +``` + +Verifica o registro npm para a versão mais recente publicada. Se uma versão mais nova estiver disponível, executa `npm install -g archgate@latest` para atualizar. Se já estiver atualizado, exibe uma mensagem e encerra. + +### Exemplo + +```bash +archgate upgrade +``` + +``` +Checking for latest Archgate release... +Upgrading 0.3.0 -> 0.4.0... +Archgate upgraded to 0.4.0 successfully. +``` + +--- + +## archgate clean + +Remove o diretório de cache da CLI. + +```bash +archgate clean +``` + +Remove `~/.archgate/`, que armazena dados em cache como timestamps de verificação de atualização. Seguro para executar a qualquer momento -- o diretório é recriado automaticamente quando necessário. + +### Exemplo + +```bash +archgate clean +``` + +``` +/home/user/.archgate cleaned up +``` diff --git a/docs/src/content/docs/pt-br/reference/mcp-tools.mdx b/docs/src/content/docs/pt-br/reference/mcp-tools.mdx new file mode 100644 index 00000000..15a4c24d --- /dev/null +++ b/docs/src/content/docs/pt-br/reference/mcp-tools.mdx @@ -0,0 +1,226 @@ +--- +title: Ferramentas MCP +description: Referência de todas as ferramentas e recursos MCP expostos pelo servidor Archgate. +--- + +O servidor MCP do Archgate expõe ferramentas e recursos que agentes de IA utilizam para ler ADRs, validar código contra regras e acessar o contexto de revisão. Inicie o servidor com `archgate mcp`. + +## Ferramentas + +### check + +Executa verificações de conformidade com ADRs no codebase. + +**Parâmetros:** + +| Nome | Tipo | Obrigatório | Descrição | +| -------- | ------- | ----------- | ----------------------------------------- | +| `adrId` | string | Não | Verificar apenas um ADR específico por ID | +| `staged` | boolean | Não | Verificar apenas arquivos no git stage | + +**Retorna** um objeto JSON com os resultados da verificação: + +```json +{ + "pass": false, + "total": 4, + "passed": 3, + "failed": 1, + "warnings": 0, + "errors": 1, + "infos": 0, + "ruleErrors": 0, + "truncated": false, + "results": [ + { + "adrId": "ARCH-001", + "ruleId": "register-function-export", + "description": "Command file must export a register*Command function", + "status": "fail", + "totalViolations": 1, + "shownViolations": 1, + "violations": [ + { + "message": "Command file must export a register*Command function", + "file": "src/commands/broken.ts", + "severity": "error" + } + ], + "durationMs": 12 + } + ], + "durationMs": 42 +} +``` + +Quando nenhuma regra é encontrada, retorna `{ "pass": true, "total": 0, "results": [], "message": "No rules to check" }`. + +As violações são limitadas a 20 por regra para manter as respostas concisas. Quando uma regra tem mais violações do que o limite, `totalViolations` reflete a contagem real enquanto `shownViolations` e o array `violations` incluem apenas as 20 primeiras. O campo `truncated` no nível superior é definido como `true` quando alguma regra foi limitada. + +--- + +### list_adrs + +Lista todos os ADRs do projeto com seus metadados. + +**Parâmetros:** + +| Nome | Tipo | Obrigatório | Descrição | +| -------- | ------ | ----------- | ------------------------------------------------------------------------------ | +| `domain` | string | Não | Filtrar por domínio (`backend`, `frontend`, `data`, `architecture`, `general`) | + +**Retorna** um array JSON de objetos ADR: + +```json +[ + { + "id": "ARCH-001", + "title": "Command Structure", + "domain": "architecture", + "rules": true + }, + { + "id": "BE-001", + "title": "API Response Envelope", + "domain": "backend", + "rules": true + } +] +``` + +--- + +### review_context + +Obtém arquivos alterados agrupados por domínio com resumos dos ADRs aplicáveis. Esta é a ferramenta principal que os agentes usam antes de escrever código -- ela fornece uma visão condensada de todas as decisões e restrições de ADR relevantes sem precisar ler cada arquivo de ADR individualmente. + +**Parâmetros:** + +| Nome | Tipo | Obrigatório | Descrição | +| ----------- | ------- | ----------- | -------------------------------------------------------------------------------------------- | +| `staged` | boolean | Não | Quando `true`, inclui apenas arquivos no git stage. Padrão: `false` (todos os alterados). | +| `runChecks` | boolean | Não | Quando `true`, executa verificações de conformidade e inclui os resultados. Padrão: `false`. | +| `domain` | string | Não | Filtrar por um único domínio (`backend`, `frontend`, `data`, `architecture`, `general`). | + +**Retorna** um objeto JSON com resumos agrupados por domínio: + +```json +{ + "allChangedFiles": ["src/commands/init.ts", "src/helpers/log.ts"], + "truncatedFiles": false, + "domains": [ + { + "domain": "architecture", + "changedFiles": ["src/commands/init.ts", "src/helpers/log.ts"], + "adrs": [ + { + "id": "ARCH-001", + "title": "Command Structure", + "domain": "architecture", + "files": ["src/commands/**/*.ts"], + "rules": true, + "decision": "Commands export register*Command(program)...", + "dosAndDonts": "### Do's\n- Export a register function..." + } + ] + } + ], + "checkSummary": null +} +``` + +Cada grupo de domínio inclui os arquivos alterados que correspondem aos seus ADRs, e resumos condensados dos ADRs com apenas as seções **Decision** e **Do's and Don'ts**. + +Quando `runChecks` é `true`, `checkSummary` contém os resultados completos da verificação (mesmo formato da resposta da ferramenta `check`). Quando `false` ou omitido, `checkSummary` é `null`. + +--- + +### claude_code_session_context + +Lê a transcrição da sessão atual do Claude Code para o projeto. Útil para recuperar contexto da sessão que pode ter sido compactado da conversa. + +**Parâmetros:** + +| Nome | Tipo | Obrigatório | Padrão | Descrição | +| ------------ | ------ | ----------- | ------ | ----------------------------------------------------------------------------------- | +| `maxEntries` | number | Não | 200 | Número máximo de entradas relevantes a retornar. Retorna as entradas mais recentes. | + +**Retorna** um objeto JSON com metadados da sessão e transcrição filtrada: + +```json +{ + "sessionFile": "abc123.jsonl", + "totalEntries": 450, + "relevantEntries": 180, + "transcript": [ + { + "type": "user", + "role": "user", + "contentPreview": "Add a dark mode toggle..." + }, + { + "type": "assistant", + "role": "assistant", + "contentPreview": "[tool_use: edit_file] | Updated styles..." + } + ] +} +``` + +Apenas tipos de mensagem `user` e `assistant` são incluídos. As prévias de conteúdo são truncadas para 500 caracteres para mensagens de usuário e 300 caracteres por bloco de conteúdo para mensagens do assistente. + +--- + +### cursor_session_context + +Lê as transcrições de sessão do agente Cursor para o projeto. Funciona da mesma forma que `claude_code_session_context`, mas lê do diretório `agent-transcripts` do Cursor. + +**Parâmetros:** + +| Nome | Tipo | Obrigatório | Padrão | Descrição | +| ------------ | ------ | ----------- | ------ | ------------------------------------------------------------------------- | +| `maxEntries` | number | Não | 200 | Número máximo de entradas relevantes a retornar. | +| `sessionId` | string | Não | -- | UUID de sessão específico para ler. Se omitido, lê a sessão mais recente. | + +**Retorna** um objeto JSON com metadados da sessão e transcrição filtrada: + +```json +{ + "sessionId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "sessionFile": "a1b2c3d4-e5f6-7890-abcd-ef1234567890.jsonl", + "totalEntries": 320, + "relevantEntries": 140, + "transcript": [ + { + "role": "user", + "contentPreview": "Fix the build error..." + }, + { + "role": "assistant", + "contentPreview": "The error is caused by..." + } + ] +} +``` + +Se o `sessionId` especificado não for encontrado, a resposta inclui uma lista de IDs de sessão disponíveis. + +--- + +## Recursos + +### adr://\{id\} + +Lê o conteúdo completo de um ADR pelo seu ID. Retorna o markdown completo incluindo frontmatter YAML e corpo. + +**Formato da URI:** `adr://\{id\}` onde `\{id\}` é o identificador do ADR (ex.: `ARCH-001`, `BE-003`). + +**Exemplo:** + +Solicitar `adr://ARCH-001` retorna o conteúdo markdown completo do arquivo ADR ARCH-001 com tipo MIME `text/markdown`. + +Se o ADR solicitado não for encontrado, o recurso retorna uma mensagem em texto simples: `ADR ARCH-001 not found`. + +:::tip[Pule chamadas MCP manuais com plugins de editor] +Os plugins de editor para [Claude Code](/guides/claude-code-plugin/) e [Cursor](/guides/cursor-integration/) chamam essas ferramentas MCP automaticamente como parte de um fluxo de trabalho estruturado de governança. Seu agente lê ADRs, valida conformidade e captura aprendizados sem você invocar nenhuma ferramenta manualmente. [Cadastre-se para acesso beta](https://plugins.archgate.dev). +::: diff --git a/docs/src/content/docs/pt-br/reference/rule-api.mdx b/docs/src/content/docs/pt-br/reference/rule-api.mdx new file mode 100644 index 00000000..18511af9 --- /dev/null +++ b/docs/src/content/docs/pt-br/reference/rule-api.mdx @@ -0,0 +1,300 @@ +--- +title: API de Regras +description: Referência da API TypeScript para escrever regras do Archgate. +--- + +As regras do Archgate são arquivos TypeScript que exportam verificações automatizadas via `defineRules()`. Cada regra recebe um `RuleContext` com utilitários para buscar arquivos, ler conteúdo e reportar violações. + +## defineRules + +```typescript +import { defineRules } from "archgate/rules"; + +export default defineRules({ + "my-rule-id": { + description: "Human-readable description of what this rule checks", + severity: "error", // optional, defaults to "error" + async check(ctx) { + // Rule logic here + }, + }, +}); +``` + +A função `defineRules` recebe um registro de configurações de regras indexadas 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 função retorna um objeto `RuleSet`. + +```typescript +function defineRules(rules: Record<string, RuleConfig>): RuleSet; +``` + +--- + +## RuleConfig + +Cada regra no registro deve estar em conformidade com a interface `RuleConfig`. + +```typescript +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. + +```typescript +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 + +```typescript +projectRoot: string; +``` + +Caminho absoluto para o diretório raiz do projeto (onde `.archgate/` está localizado). + +#### scopedFiles + +```typescript +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 + +```typescript +changedFiles: string[]; +``` + +Arquivos que foram modificados de acordo com o git. Quando `--staged` é usado, contém apenas arquivos no stage. Quando executado sem `--staged`, contém todos os arquivos alterados (staged e unstaged). Vazio quando nenhuma alteração git é detectada. + +#### report + +```typescript +report: RuleReport; +``` + +A interface de relatório para registrar violações, avisos e mensagens informativas. Veja [RuleReport](#rulereport) abaixo. + +### Métodos + +#### glob + +```typescript +glob(pattern: string): Promise<string[]>; +``` + +Encontra arquivos correspondentes a um padrão glob relativo à raiz do projeto. Retorna um array de caminhos absolutos de arquivo. + +```typescript +const testFiles = await ctx.glob("tests/**/*.test.ts"); +``` + +#### grep + +```typescript +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. + +```typescript +const matches = await ctx.grep(file, /console\.error\(/); +``` + +#### grepFiles + +```typescript +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. + +```typescript +const matches = await ctx.grepFiles(/TODO:/i, "src/**/*.ts"); +``` + +#### readFile + +```typescript +readFile(path: string): Promise<string>; +``` + +Lê o conteúdo de um arquivo como string. O caminho é relativo à raiz do projeto. + +```typescript +const content = await ctx.readFile("src/config.ts"); +``` + +#### readJSON + +```typescript +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. + +```typescript +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. + +```typescript +interface RuleReport { + violation(detail: ReportDetail): void; + warning(detail: ReportDetail): void; + info(detail: ReportDetail): void; +} +``` + +#### violation + +```typescript +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 + +```typescript +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 + +```typescript +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`. + +```typescript +interface ReportDetail { + message: string; + file?: string; + line?: 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 no arquivo | +| `fix` | `string` | Não | Sugestão de correção ou ação de remediação | + +--- + +## GrepMatch + +Retornado por `ctx.grep()` e `ctx.grepFiles()`. + +```typescript +interface GrepMatch { + file: string; + line: number; + column: number; + content: string; +} +``` + +| Campo | Tipo | Descrição | +| --------- | -------- | -------------------------------------------- | +| `file` | `string` | Caminho absoluto 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 + +```typescript +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. + +```typescript +interface ViolationDetail { + ruleId: string; + adrId: string; + message: string; + file?: string; + line?: number; + fix?: string; + severity: Severity; +} +``` + +| Campo | Tipo | Descrição | +| ---------- | ---------- | ------------------------------------------------- | +| `ruleId` | `string` | ID da regra da chave de `defineRules` | +| `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 no arquivo | +| `fix` | `string?` | Sugestão de correção | +| `severity` | `Severity` | Severidade efetiva desta violação | + +--- + +## RuleSet + +O tipo de retorno de `defineRules`. Você não constrói isso diretamente. + +```typescript +type RuleSet = { + rules: Record<string, RuleConfig>; +}; +```