From cfcc1de0163e6b0beae6a546a86af210e3e8c181 Mon Sep 17 00:00:00 2001 From: Rhuan Barreto Date: Sat, 28 Feb 2026 19:52:00 +0100 Subject: [PATCH 1/2] feat(docs): add Brazilian Portuguese i18n and GEN-002 ADR Configure Starlight built-in i18n with root locale pattern (English at current URLs, Portuguese at /pt-br/). Translate all 18 documentation pages to Brazilian Portuguese. Create GEN-002 ADR with automated i18n-page-parity rule enforcing 1:1 translation coverage. Co-Authored-By: Claude Opus 4.6 --- .archgate/adrs/GEN-001-documentation-site.md | 2 + .archgate/adrs/GEN-002-docs-i18n.md | 132 +++++ .archgate/adrs/GEN-002-docs-i18n.rules.ts | 74 +++ docs/astro.config.mjs | 5 + docs/src/content/docs/pt-br/concepts/adrs.mdx | 180 +++++++ .../content/docs/pt-br/concepts/domains.mdx | 96 ++++ .../src/content/docs/pt-br/concepts/rules.mdx | 166 +++++++ .../pt-br/examples/common-rule-patterns.mdx | 273 +++++++++++ .../pt-br/getting-started/installation.mdx | 118 +++++ .../pt-br/getting-started/quick-start.mdx | 140 ++++++ .../docs/pt-br/guides/ci-integration.mdx | 208 ++++++++ .../docs/pt-br/guides/claude-code-plugin.mdx | 129 +++++ .../docs/pt-br/guides/cursor-integration.mdx | 167 +++++++ .../content/docs/pt-br/guides/mcp-server.mdx | 123 +++++ .../docs/pt-br/guides/pre-commit-hooks.mdx | 92 ++++ .../docs/pt-br/guides/writing-adrs.mdx | 310 ++++++++++++ .../docs/pt-br/guides/writing-rules.mdx | 453 +++++++++++++++++ docs/src/content/docs/pt-br/index.mdx | 123 +++++ .../docs/pt-br/reference/adr-schema.mdx | 281 +++++++++++ .../docs/pt-br/reference/cli-commands.mdx | 461 ++++++++++++++++++ .../docs/pt-br/reference/mcp-tools.mdx | 226 +++++++++ .../content/docs/pt-br/reference/rule-api.mdx | 300 ++++++++++++ 22 files changed, 4059 insertions(+) create mode 100644 .archgate/adrs/GEN-002-docs-i18n.md create mode 100644 .archgate/adrs/GEN-002-docs-i18n.rules.ts create mode 100644 docs/src/content/docs/pt-br/concepts/adrs.mdx create mode 100644 docs/src/content/docs/pt-br/concepts/domains.mdx create mode 100644 docs/src/content/docs/pt-br/concepts/rules.mdx create mode 100644 docs/src/content/docs/pt-br/examples/common-rule-patterns.mdx create mode 100644 docs/src/content/docs/pt-br/getting-started/installation.mdx create mode 100644 docs/src/content/docs/pt-br/getting-started/quick-start.mdx create mode 100644 docs/src/content/docs/pt-br/guides/ci-integration.mdx create mode 100644 docs/src/content/docs/pt-br/guides/claude-code-plugin.mdx create mode 100644 docs/src/content/docs/pt-br/guides/cursor-integration.mdx create mode 100644 docs/src/content/docs/pt-br/guides/mcp-server.mdx create mode 100644 docs/src/content/docs/pt-br/guides/pre-commit-hooks.mdx create mode 100644 docs/src/content/docs/pt-br/guides/writing-adrs.mdx create mode 100644 docs/src/content/docs/pt-br/guides/writing-rules.mdx create mode 100644 docs/src/content/docs/pt-br/index.mdx create mode 100644 docs/src/content/docs/pt-br/reference/adr-schema.mdx create mode 100644 docs/src/content/docs/pt-br/reference/cli-commands.mdx create mode 100644 docs/src/content/docs/pt-br/reference/mcp-tools.mdx create mode 100644 docs/src/content/docs/pt-br/reference/rule-api.mdx 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..b1e9969f --- /dev/null +++ b/docs/src/content/docs/pt-br/concepts/adrs.mdx @@ -0,0 +1,180 @@ +--- +title: Registros de Decisao Arquitetural +description: Entenda como o Archgate usa ADRs como documentos e regras executaveis. +--- + +Um Architecture Decision Record (ADR) e um documento curto que captura uma unica decisao arquitetural junto com seu contexto e consequencias. ADRs respondem a pergunta: _por que_ essa decisao foi tomada, e _quais_ sao seus trade-offs? + +O Archgate expande o conceito de ADR dando a cada decisao duas expressoes: um **documento** que humanos e agentes de IA leem, e um **arquivo de regras** opcional que maquinas executam. + +## Duas Expressoes de um ADR + +### ADR como Documento + +O documento e um arquivo Markdown com frontmatter YAML armazenado em `.archgate/adrs/`. Ele descreve a decisao em linguagem simples: qual problema resolve, quais alternativas foram consideradas, o que a equipe decidiu, e quais consequencias seguem. + +Tanto humanos quanto agentes de IA consomem esse documento. Quando um agente de IA de codificacao esta prestes a escrever codigo, ele le os ADRs relevantes para entender as restricoes 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 le os ADRs aplicaveis automaticamente antes de cada tarefa de codificacao -- 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 e um arquivo `.rules.ts` complementar que exporta verificacoes automatizadas via `defineRules()`. Quando voce 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 violacoes com caminhos de arquivo e numeros de linha. + +Nem todo ADR precisa de regras. Algumas decisoes sao melhor aplicadas apenas por revisao de codigo. Defina `rules: false` quando nenhuma verificacao automatizada for pratica. + +## Convencao de Nomenclatura de Arquivos + +Os arquivos de ADR seguem uma convencao de nomenclatura estrita que codifica o prefixo do dominio, numero de sequencia e um slug legivel: + +``` +{PREFIX}-{NNN}-{slug}.md # The document +{PREFIX}-{NNN}-{slug}.rules.ts # The companion rules file (optional) +``` + +Por exemplo, um ADR do dominio de arquitetura sobre estrutura de comandos produziria: + +``` +ARCH-001-command-structure.md +ARCH-001-command-structure.rules.ts +``` + +O prefixo vem do dominio do ADR (veja [Dominios](/concepts/domains/)). O numero de sequencia e preenchido com zeros ate tres digitos e auto-incrementado por `archgate adr create`. + +## Frontmatter YAML + +Todo documento ADR comeca com um bloco de frontmatter YAML entre delimitadores `---`. O frontmatter e o metadado legivel por maquina que o Archgate usa para carregar, filtrar e definir o escopo das regras. + +| Campo | Tipo | Obrigatorio | Descricao | +| -------- | ------------ | ----------- | --------------------------------------------------------------- | +| `id` | string | Sim | Identificador unico como `ARCH-001` ou `BE-003` | +| `title` | string | Sim | Titulo legivel da decisao | +| `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 | Nao | Padroes glob que definem quais arquivos as regras verificam | + +O campo `files` e opcional. Quando presente, restringe a execucao das regras apenas aos arquivos que correspondem aos globs fornecidos. Quando ausente, as regras sao executadas contra todos os arquivos do projeto. Por exemplo, `files: ["src/commands/**/*.ts"]` limita as verificacoes apenas aos arquivos de comando. + +## Secoes do Corpo do ADR + +Apos o frontmatter, o corpo do ADR segue uma estrutura de secoes padrao: + +### Context + +Descreve o problema ou situacao que motivou a decisao. Inclua alternativas que foram consideradas e por que foram rejeitadas. + +### Decision + +Declara a decisao em si e suas restricoes principais. Esta e a secao que os agentes de IA mais observam ao decidir como escrever codigo. + +### Do's and Don'ts + +Orientacao concreta e acionavel dividida em duas subsecoes. Funcionam como uma lista de verificacao rapida para desenvolvedores e agentes de IA. + +### Consequences + +Dividida em tres subsecoes: + +- **Positive** -- beneficios que a decisao proporciona +- **Negative** -- trade-offs aceitos +- **Risks** -- coisas que podem dar errado e como mitiga-las + +### Compliance and Enforcement + +Descreve como a decisao e aplicada, tanto por regras automatizadas (com IDs de regra e severidades) quanto por checklists de revisao manual. + +### References + +Links para ADRs relacionados, documentacao externa ou documentos de design. + +## Exemplo Completo + +Abaixo esta um ADR completo com frontmatter e todas as secoes 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..bb2d8893 --- /dev/null +++ b/docs/src/content/docs/pt-br/concepts/domains.mdx @@ -0,0 +1,96 @@ +--- +title: Dominios +description: Categorize ADRs por dominio para uma governanca organizada. +--- + +Dominios sao categorias que agrupam ADRs relacionados. Cada ADR pertence a exatamente um dominio, e o dominio determina o prefixo usado no identificador do ADR. + +## Dominios Integrados + +O Archgate vem com cinco dominios integrados. Cada um tem um prefixo curto que aparece no inicio de cada ID de ADR naquele dominio. + +| Dominio | Prefixo | Uso para | +| -------------- | ------- | ------------------------------------------------------------------ | +| `backend` | `BE` | Logica server-side, APIs, bancos de dados, servicos | +| `frontend` | `FE` | Componentes de UI, logica client-side, padroes de estilo | +| `data` | `DATA` | Modelos de dados, schemas, pipelines, estrategias de armazenamento | +| `architecture` | `ARCH` | Decisoes arquiteturais transversais | +| `general` | `GEN` | Convencoes 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 Dominios Sao Usados + +### Identificacao de ADR + +O prefixo do dominio e incorporado ao campo `id` de cada ADR. Quando voce executa `archgate adr create` e seleciona um dominio, a CLI determina automaticamente o proximo numero de sequencia disponivel para o prefixo daquele dominio. Um dominio de arquitetura com dois ADRs existentes (`ARCH-001`, `ARCH-002`) atribuiria `ARCH-003` ao proximo. + +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 dominio especifico: + +```bash +archgate adr list --domain backend +archgate adr list --domain architecture +``` + +Isso e util em projetos grandes onde dezenas de ADRs abrangem multiplas preocupacoes. Filtrar por dominio permite que voce foque nas decisoes relevantes para seu trabalho atual. + +### Contexto para Agentes de IA + +A ferramenta `review_context` do servidor MCP agrupa arquivos alterados por dominio ao fornecer contexto para agentes de IA. Quando um agente esta prestes a escrever codigo, ele recebe apenas os resumos de ADR relevantes para os dominios que suas alteracoes afetam, em vez do conjunto completo de todos os ADRs. Esse escopo reduz o ruido e ajuda os agentes a focar nas restricoes que realmente se aplicam. + +### Validacao com Escopo + +Embora os dominios em si nao restrinjam quais arquivos uma regra pode verificar (esse e o trabalho do glob `files` no frontmatter do ADR), os dominios fornecem um agrupamento logico que ajuda as equipes a organizar sua governanca. Uma equipe de backend pode revisar todos os ADRs `BE-*` para entender suas restricoes, enquanto a equipe de frontend foca nos `FE-*`. + +## Quando Usar Qual Dominio + +### backend + +Use para decisoes sobre codigo server-side: padroes de design de API, convencoes de acesso a banco de dados, fluxos de autenticacao, comunicacao entre servicos, tratamento de filas e padroes de jobs em background. + +**Exemplos de ADRs:** Formato de envelope de resposta de API, estrategia de migracao de banco de dados, taxonomia de codigos de erro. + +### frontend + +Use para decisoes sobre codigo client-side: estrutura de componentes, padroes de gerenciamento de estado, abordagens de estilizacao, requisitos de acessibilidade e escolhas de ferramentas de build. + +**Exemplos de ADRs:** Estrutura de arquivo de componente, metodologia CSS, padrao de validacao de formulario. + +### data + +Use para decisoes sobre dados: design de schema, convencoes de pipeline de dados, escolhas de engine de armazenamento, formatos de serializacao e estrategias de validacao de dados. + +**Exemplos de ADRs:** Versionamento de schema de eventos, convencoes de nomenclatura de banco de dados, politica de retencao de dados. + +### architecture + +Use para decisoes transversais que abrangem multiplos dominios ou afetam a estrutura geral do projeto. Sao decisoes que equipes de backend, frontend e dados precisam seguir. + +**Exemplos de ADRs:** Estrutura de comandos, convencoes de tratamento de erros, politica de gerenciamento de dependencias, padroes de teste. + +### general + +Use para convencoes de projeto que nao se encaixam perfeitamente em um dominio tecnico: processos de revisao de codigo, formatos de mensagem de commit, padroes de documentacao e praticas de onboarding. + +**Exemplos de ADRs:** Formato de mensagem de commit, template de descricao de PR, requisitos de documentacao. + +## Escolhendo o Dominio Certo + +Ao decidir a qual dominio 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 multiplos dominios tecnicos, use `architecture`. +- Se e um processo ou convencao em vez de uma decisao tecnica, use `general`. + +Em caso de duvida entre `architecture` e um dominio especifico, prefira o dominio mais especifico. Reserve `architecture` para decisoes 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..4af0aae4 --- /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 decisoes de ADR em verificacoes automatizadas. +--- + +Regras sao o lado executavel de um ADR. Elas vivem em arquivos `.rules.ts` complementares ao lado do documento ADR e exportam verificacoes automatizadas via a funcao `defineRules()`. Quando voce executa `archgate check`, a CLI carrega cada ADR que tem `rules: true`, importa seu arquivo de regras complementar e executa cada verificacao contra seu codebase. + +## Definindo Regras + +Um arquivo de regras e um modulo TypeScript que exporta por padrao o resultado de `defineRules()`. Importe a funcao 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 saida 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 tres partes: + +| Propriedade | Tipo | Obrigatorio | Descricao | +| ------------- | -------- | ----------- | --------------------------------------------- | +| `description` | string | Sim | Um resumo curto do que a regra verifica | +| `severity` | string | Nao | `"error"` (padrao), `"warning"`, ou `"info"` | +| `check` | function | Sim | Funcao assincrona que recebe um `RuleContext` | + +### Niveis de Severidade + +A severidade determina o que acontece quando uma regra encontra um problema: + +| Severidade | Exit Code | Efeito | +| ---------- | --------- | -------------------------------------------- | +| `error` | 1 | A violacao e reportada e a verificacao falha | +| `warning` | 0 | O aviso e registrado mas a verificacao passa | +| `info` | 0 | Mensagem informativa, a verificacao passa | + +Quando `archgate check` e executado, exit code 1 significa que pelo menos uma violacao de severidade `error` foi encontrada. Exit code 0 significa que nao houve erros (avisos e mensagens informativas sao registrados mas nao bloqueiam). + +## O RuleContext + +A funcao `check` recebe um objeto `RuleContext` que fornece tudo que uma regra precisa para inspecionar o codebase e reportar descobertas. + +### Informacoes do Projeto + +| Propriedade | Tipo | Descricao | +| ------------------ | ---------- | ------------------------------------------------------------------------------------------------------ | +| `ctx.projectRoot` | `string` | Caminho absoluto para o diretorio raiz do projeto | +| `ctx.scopedFiles` | `string[]` | Arquivos que correspondem aos globs `files` do ADR, ou todos os arquivos se nao houver globs definidos | +| `ctx.changedFiles` | `string[]` | Arquivos alterados no git (preenchido ao executar com `--staged`) | + +### Operacoes de Arquivo + +| Metodo | Retorno | Descricao | +| -------------------- | ------------------- | --------------------------------------------------- | +| `ctx.glob(pattern)` | `Promise` | Encontra arquivos que correspondem a um padrao glob | +| `ctx.readFile(path)` | `Promise` | Le o conteudo de um arquivo como string | +| `ctx.readJSON(path)` | `Promise` | Le e faz parse de um arquivo JSON | + +### Operacoes de Busca + +| Metodo | Retorno | Descricao | +| ---------------------------------- | ---------------------- | ------------------------------------------------------ | +| `ctx.grep(file, pattern)` | `Promise` | Busca em um unico arquivo com um padrao regex | +| `ctx.grepFiles(pattern, fileGlob)` | `Promise` | Busca em multiplos 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 +} +``` + +### Relatorios + +O objeto `ctx.report` fornece tres metodos 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 metodo aceita um objeto com: + +| Propriedade | Tipo | Obrigatorio | Descricao | +| ----------- | ------ | ----------- | ---------------------------------------- | +| `message` | string | Sim | Qual e o problema | +| `file` | string | Nao | Caminho relativo do arquivo com problema | +| `line` | number | Nao | Numero da linha onde o problema ocorre | +| `fix` | string | Nao | Sugestao de correcao para a violacao | + +Use `ctx.report.violation()` para problemas que devem bloquear merges. Use `ctx.report.warning()` para questoes que valem ser sinalizadas mas nao bloqueiam. Use `ctx.report.info()` para saida puramente informativa. + +## Timeout de Regra + +Cada regra tem um timeout de execucao de 30 segundos. Se a funcao `check` de uma regra nao completar dentro de 30 segundos, ela e terminada e reportada como erro. Isso impede que regras descontroladas bloqueiem o pipeline indefinidamente. + +## Exemplo Completo + +Aqui esta um arquivo de regras completo que verifica um padrao 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 e executada contra um arquivo contendo `import { readFileSync } from "node:fs"`, a saida 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 Execucao + +As regras sao executadas com as seguintes garantias: + +- **Paralelo entre ADRs** -- Regras de diferentes ADRs sao executadas concorrentemente para maior velocidade. +- **Sequencial dentro de um ADR** -- Regras pertencentes ao mesmo ADR sao executadas uma apos a outra, para que regras anteriores possam estabelecer contexto para as posteriores. +- **Arquivos no escopo sao pre-resolvidos** -- O array `ctx.scopedFiles` e preenchido antes que sua funcao `check` seja chamada, com base nos globs `files` do ADR. +- **Arquivos alterados para modo staged** -- Ao executar `archgate check --staged`, `ctx.changedFiles` contem apenas os arquivos staged no git, permitindo que regras pulem arquivos nao alterados para feedback mais rapido. + +:::tip[Execute verificacoes 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 apos cada alteracao de codigo. O agente le os ADRs aplicaveis, escreve codigo em conformidade e valida -- sem necessidade de executar comandos de verificacao 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..6e0fe066 --- /dev/null +++ b/docs/src/content/docs/pt-br/examples/common-rule-patterns.mdx @@ -0,0 +1,273 @@ +--- +title: Padroes Comuns de Regras +description: Padroes de regras prontos para uso em necessidades comuns de governanca. +--- + +Esta pagina fornece exemplos completos de regras, prontos para copiar e colar, para cenarios comuns de governanca. Cada padrao inclui o codigo completo da regra, uma explicacao de como funciona e orientacoes sobre quando utiliza-lo. + +## Padrao 1: Lista de Dependencias Permitidas + +**Quando usar:** Restringir dependencias de producao a uma lista curada para evitar inchacos de dependencias 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:** Le o `package.json`, itera sobre as `dependencies` de producao e reporta uma violacao para qualquer pacote que nao esteja no array `APPROVED_DEPS`. Dependencias em `devDependencies` nao sao verificadas. A mensagem de correcao orienta o desenvolvedor a obter a aprovacao da dependencia ou reclassifica-la. + +--- + +## Padrao 2: Padrao de Exportacao Obrigatoria + +**Quando usar:** Garantir que arquivos em um diretorio especifico exportem uma assinatura de funcao obrigatoria, como o padrao `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 entao verifica cada arquivo no escopo em busca de uma funcao exportada que corresponda ao padrao de nomenclatura `register*Command`. A regex procura por `export function register` seguido de quaisquer caracteres alfanumericos e `Command`. Arquivos que nao correspondem recebem uma violacao. + +Para adaptar este padrao, altere a regex para corresponder a convencao de exportacao exigida pelo seu projeto. Por exemplo, para exigir uma exportacao default de um componente React: + +```typescript +if (!/export\s+default\s+function\s+\w+/.test(content)) { +``` + +--- + +## Padrao 3: Importacao Banida + +**Quando usar:** Impedir o uso de uma biblioteca ou modulo especifico em toda a base de codigo. Casos de uso comuns incluem banir bibliotecas pesadas como `lodash` ou `moment` em favor de alternativas nativas, ou impedir importacoes de modulos internos que estao 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 importacoes banidas com o padrao regex para detecta-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 padrao banido e reporta uma violacao para cada correspondencia. + +Para adicionar mais importacoes banidas, adicione entradas ao array `BANNED_IMPORTS`. O padrao deve corresponder a parte `from "..."` da instrucao de importacao. + +--- + +## Padrao 4: Convencao de Nomenclatura de Arquivos + +**Quando usar:** Impor nomenclatura consistente de arquivos em um diretorio, 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 minusculas e digitos separados por hifens, com uma extensao de arquivo valida. Arquivos de teste e declaracoes de tipo sao excluidos. A sugestao de correcao converte automaticamente camelCase para kebab-case. + +Para alterar a convencao de nomenclatura, substitua a regex. Por exemplo, para camelCase: + +```typescript +const CAMEL_CASE = /^[a-z][a-zA-Z0-9]*\.(ts|tsx|js|jsx)$/; +``` + +--- + +## Padrao 5: Sem Comentarios TODO em Producao + +**Quando usar:** Sinalizar comentarios TODO, FIXME, HACK e XXX para que sejam resolvidos antes do merge. Usa severidade `warning` para nao bloquear o CI, mas torna os comentarios visiveis na saida da verificacao. + +```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 comentarios que comecem com `TODO:`, `FIXME:`, `HACK:` ou `XXX:` (sem distincao de maiusculas/minusculas). Cada correspondencia e reportada como um aviso com o texto original do comentario. Como a severidade e `"warning"`, a verificacao termina com codigo 0 mesmo quando correspondencias sao encontradas -- ela exibe os comentarios 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()`. + +--- + +## Padrao 6: Cobertura de Arquivos de Teste + +**Quando usar:** Garantir que todo arquivo fonte tenha um arquivo de teste correspondente, impedindo que codigo 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 nao exista, reporta um aviso com uma correcao sugerindo o caminho esperado do arquivo de teste. + +Isso pressupoe uma estrutura de diretorio 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 transformacao 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 voce] +Os plugins de editor para [Claude Code](/guides/claude-code-plugin/) e [Cursor](/guides/cursor-integration/) incluem uma skill de Quality Manager que identifica padroes recorrentes na sua base de codigo e propoe novas regras para aplica-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..9bbdb11e --- /dev/null +++ b/docs/src/content/docs/pt-br/getting-started/installation.mdx @@ -0,0 +1,118 @@ +--- +title: Instalacao +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 binario especifico da plataforma. A CLI em si e um binario standalone compilado com Bun — o Node.js e necessario apenas para o wrapper do npm/yarn/pnpm. + +## Instalar como dependencia de desenvolvimento + +Voce tambem pode adicionar o Archgate como dependencia de desenvolvimento no seu projeto e executa-lo atraves do script runner do seu gerenciador de pacotes. Isso e util para fixar uma versao especifica por projeto ou executar verificacoes no CI sem uma instalacao 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 binarios pre-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 binario correto e instalado automaticamente como `optionalDependency` quando voce instala o `archgate`. + +## Verificar a instalacao + +```bash +archgate --version +``` + +Voce devera ver a versao instalada impressa no stdout. + +## Usuarios do Proto toolchain + +Se voce gerencia o Node.js com o [proto](https://moonrepo.dev/proto) (gerenciador de toolchain do moonrepo), binarios npm instalados globalmente requerem um passo adicional de configuracao. + +Adicione a sua configuracao do proto: + +```toml +# ~/.proto/config.toml +[tools.npm] +shared-globals-dir = true +``` + +Depois adicione o diretorio 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 devera estar disponivel globalmente. + +## Proximos passos + +Apos a instalacao, execute `archgate init` no seu projeto para configurar a governanca. Veja o guia de [Inicio Rapido](/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 governanca 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..ca258337 --- /dev/null +++ b/docs/src/content/docs/pt-br/getting-started/quick-start.mdx @@ -0,0 +1,140 @@ +--- +title: Inicio Rapido +description: Comece a usar o Archgate em menos de 5 minutos. +--- + +## 1. Instalar o Archgate + +Se voce ainda nao instalou a CLI, instale-a globalmente via npm: + +```bash +npm install -g archgate +``` + +Veja a pagina de [Instalacao](/getting-started/installation/) para detalhes de plataforma e solucao de problemas. + +## 2. Inicializar seu projeto + +Navegue ate a raiz do seu projeto e execute o comando `init`: + +```bash +cd my-project +archgate init +``` + +Isso cria o diretorio `.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 voce construir a partir dele. + +## 3. Editar o ADR de exemplo + +Abra `.archgate/adrs/ARCH-001-example.md`. Todo ADR comeca com um frontmatter YAML que define sua identidade: + +```yaml +--- +id: ARCH-001 +title: Example Decision +domain: architecture +rules: true +files: ["src/**/*.ts"] +--- +``` + +- **id** — Identificador unico. A convencao e `ARCH-NNN`, mas qualquer string funciona. +- **title** — Nome legivel para a decisao. +- **domain** — Agrupa ADRs relacionados (`architecture`, `backend`, `frontend`, `data` ou `general`). +- **rules** — Defina como `true` se este ADR possui um arquivo complementar `.rules.ts` com verificacoes automatizadas. +- **files** — Padroes glob opcionais que definem o escopo de quais arquivos as regras se aplicam. + +Abaixo do frontmatter, escreva a decisao em markdown. O Archgate nao impoe uma estrutura especifica de secoes, mas as secoes recomendadas sao: 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 sao escritas em TypeScript usando a funcao `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 unica, uma descricao e uma funcao assincrona `check`. Dentro de `check`, voce tem acesso a: + +- **`ctx.scopedFiles`** — Arquivos que correspondem aos padroes glob do campo `files` do ADR. +- **`ctx.grep(file, pattern)`** — Pesquisa um arquivo por correspondencias de regex, retornando caminhos de arquivos e numeros de linha. +- **`ctx.report.violation()`** — Reporta uma violacao com mensagem, caminho do arquivo, numero da linha e sugestao opcional de correcao. + +## 5. Executar verificacoes + +Execute o verificador de conformidade contra sua base de codigo: + +```bash +archgate check +``` + +O Archgate carrega cada ADR com `rules: true`, executa seu arquivo de regras complementar e imprime os resultados. O codigo de saida indica o resultado: + +| Codigo de saida | Significado | +| --------------- | ------------------------------------------------------ | +| 0 | Todas as regras passaram. Nenhuma violacao encontrada. | +| 1 | Uma ou mais violacoes detectadas. | +| 2 | Erro interno (ex.: ADR ou regra malformada). | + +Para verificar apenas arquivos staged (util em pre-commit hooks ou CI): + +```bash +archgate check --staged +``` + +## E agora? + +Agora que voce tem uma configuracao funcionando, aprofunde-se: + +**Entenda os conceitos:** + +- [ADRs](/concepts/adrs/) — O que sao Architecture Decision Records e como o Archgate os utiliza. +- [Regras](/concepts/rules/) — Como arquivos complementares `.rules.ts` transformam decisoes em verificacoes automatizadas. +- [Dominios](/concepts/domains/) — Como dominios agrupam ADRs relacionados e definem o escopo de correspondencia de arquivos. + +**Escreva os seus:** + +- [Escrevendo ADRs](/guides/writing-adrs/) — Aprenda o formato completo de ADR e as melhores praticas para escrever decisoes eficazes. +- [Escrevendo Regras](/guides/writing-rules/) — Explore a API de regras, padroes avancados e como testar suas regras. +- [Padroes Comuns de Regras](/examples/common-rule-patterns/) — Padroes prontos para copiar e colar para verificacoes de dependencias, convencoes de nomenclatura e mais. + +**Integre ao seu fluxo de trabalho:** + +- [Integracao com CI](/guides/ci-integration/) — Conecte `archgate check` ao GitHub Actions, GitLab CI ou qualquer pipeline. +- [Pre-commit Hooks](/guides/pre-commit-hooks/) — Execute verificacoes localmente antes de cada commit. +- [Plugin Claude Code](/guides/claude-code-plugin/) — De aos agentes de IA um fluxo completo de governanca com habilidades baseadas em papeis. +- [Integracao 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..35b07a8a --- /dev/null +++ b/docs/src/content/docs/pt-br/guides/ci-integration.mdx @@ -0,0 +1,208 @@ +--- +title: Integracao com CI +description: Adicione verificacoes do Archgate ao seu pipeline de CI/CD. +--- + +As verificacoes do Archgate funcionam em qualquer sistema de CI que respeite codigos de saida. Adicione um unico passo ao seu pipeline e as violacoes bloqueiarao merges automaticamente. + +## GitHub Actions + +A configuracao mais simples e 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 violacao com severidade `error`, o passo termina com codigo 1 e o job falha. + +## Anotacoes do GitHub Actions + +Use `--ci` para exibir violacoes como anotacoes 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 anotacoes `::error` e `::warning` no formato esperado pelo GitHub Actions. Cada anotacao inclui o ID do ADR, o ID da regra, o caminho do arquivo e o numero da linha. + +## Saida legivel por maquina + +Use `--json` para saida estruturada que outras ferramentas podem processar: + +```yaml +- run: archgate check --json > results.json +``` + +A saida 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 +} +``` + +## Codigos de saida + +| Codigo | Significado | Comportamento no CI | +| ------ | ------------------------------ | ------------------- | +| 0 | Todas as verificacoes passaram | Job bem-sucedido | +| 1 | Violacoes encontradas | Job falha | +| 2 | Erro interno | Job falha | + +Avisos (severidade `warning`) sao registrados, mas nao afetam o codigo de saida. Apenas violacoes com severidade `error` causam o codigo de saida 1. + +## Reduzindo o escopo + +### Verificar apenas arquivos staged + +Use `--staged` para limitar a verificacao aos arquivos staged no git. Isso e util em hooks de pre-commit ou quando voce deseja validar apenas o que esta prestes a ser commitado: + +```yaml +- run: archgate check --staged +``` + +### Verificar um ADR especifico + +Use `--adr ` para executar regras de um unico ADR: + +```yaml +- run: archgate check --adr ARCH-006 +``` + +Isso e util quando um PR altera apenas arquivos governados por um ADR e voce deseja feedback mais rapido. + +## Adicionando a um pipeline existente + +Se voce ja tem uma configuracao de CI, adicione o Archgate como um unico passo apos 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 dependencia adicional ou arquivo de configuracao e necessario alem do diretorio `.archgate/` que ja esta no seu repositorio. + +## Cache da instalacao + +Faca cache do diretorio `~/.archgate` para acelerar instalacoes 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 ja usa Bun, instale o Archgate com `bun` ao inves 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 padrao e sempre o mesmo: + +1. Instalar: `npm install -g archgate` (ou `bun install -g archgate`) +2. Executar: `archgate check` +3. Verificar o codigo de saida (0 = aprovado, 1 = violacoes, 2 = erro) + +Para sistemas que suportam anotacoes (Azure DevOps, Buildkite, etc.), use `--json` para processar a saida e emitir anotacoes no formato esperado pelo seu CI. + +## Hooks de pre-commit + +Voce tambem 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 rapido. + +## Saida detalhada + +Use `--verbose` para ver as regras aprovadas e informacoes de tempo junto com as falhas. Isso e util para debugar verificacoes lentas ou confirmar que as regras estao rodando como esperado: + +```yaml +- run: archgate check --verbose +``` + +:::tip[Adicione governanca de IA ao seu fluxo de trabalho] +O CI detecta violacoes no momento do merge. Plugins de editor detectam no momento da codificacao. Com o plugin [Claude Code](/guides/claude-code-plugin/) ou [Cursor](/guides/cursor-integration/), seu agente de IA le os ADRs antes de escrever codigo e valida a conformidade antes mesmo de voce 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..8f601302 --- /dev/null +++ b/docs/src/content/docs/pt-br/guides/claude-code-plugin.mdx @@ -0,0 +1,129 @@ +--- +title: Plugin para Claude Code +description: De aos agentes de IA um fluxo de governanca 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 governanca estruturado. Em vez de depender de instrucoes em prompts que se deterioram com o tempo, os agentes leem seus ADRs diretamente pelo servidor MCP e validam o proprio codigo contra suas regras. + +## O que o plugin oferece + +O plugin adiciona skills baseadas em papeis ao Claude Code. Cada skill encapsula uma parte especifica do fluxo de governanca, garantindo que os agentes sigam o mesmo processo todas as vezes -- ler as decisoes antes de codificar, validar depois e capturar novos padroes para a equipe. + +### Skills incluidas + +| Skill | Proposito | +| -------------------------- | ------------------------------------------------------------------------------------------ | +| `archgate:developer` | Agente de desenvolvimento geral que le ADRs antes de codificar e valida depois | +| `archgate:architect` | Valida alteracoes de codigo contra todos os ADRs do projeto para conformidade estrutural | +| `archgate:quality-manager` | Revisa a cobertura de regras e propoe novos ADRs quando padroes emergem | +| `archgate:adr-author` | Cria e edita ADRs seguindo as convencoes do projeto | +| `archgate:onboard` | Configuracao unica: explora o codebase, entrevista o desenvolvedor e cria os ADRs iniciais | + +## Instalacao + +:::note[Acesso beta necessario] +O plugin para Claude Code esta atualmente em beta. [Cadastre-se em plugins.archgate.dev](https://plugins.archgate.dev) para obter acesso antes de seguir os passos abaixo. +::: + +### 1. Faca 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 codigo unico e uma URL -- abra a URL no seu navegador, insira o codigo e autorize. Ao concluir, as credenciais sao armazenadas em `~/.archgate/credentials`. + +### 2. Inicialize seu projeto com o plugin + +Execute `archgate init` no seu projeto. Se voce ja estiver logado, o plugin e instalado automaticamente: + +```bash +archgate init +``` + +Para solicitar explicitamente a instalacao do plugin: + +```bash +archgate init --install-plugin +``` + +Se o CLI `claude` estiver no seu PATH, o plugin e 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` nao for encontrado, o comando exibe os comandos manuais para voce executar. + +## Configuracao inicial com onboard + +Apos a instalacao, execute a skill `archgate:onboard` no seu projeto uma vez. Essa skill: + +1. Explora a estrutura do seu codebase (diretorios, arquivos-chave, configuracao de pacotes) +2. Entrevista voce sobre as convencoes, restricoes e decisoes arquiteturais da sua equipe +3. Cria um conjunto inicial de ADRs com base nas suas respostas +4. Configura o diretorio `.archgate/` com suas primeiras regras + +A skill de onboard foi projetada para ser executada uma vez por projeto. Apos o onboarding, as outras skills cuidam do desenvolvimento no dia a dia. + +## Como funciona na pratica + +O plugin segue um fluxo estruturado para cada tarefa de codificacao: + +### 1. Ler os ADRs aplicaveis + +Quando o desenvolvedor atribui uma tarefa de codificacao, o agente le todos os ADRs que se aplicam aos arquivos sendo alterados. O servidor MCP fornece um resumo condensado com as secoes **Decision** e **Do's and Don'ts** de cada ADR relevante. + +O agente nao escreve codigo ate ter lido os ADRs aplicaveis. Isso e garantido pela skill `archgate:developer`. + +### 2. Escrever codigo seguindo as restricoes dos ADRs + +O agente escreve codigo que cumpre as restricoes dos ADRs. As secoes Do's and Don'ts servem como guardrails concretos -- o agente as consulta enquanto codifica. + +### 3. Validar as alteracoes + +Apos escrever o codigo, o agente executa `archgate check` para rodar as regras automatizadas contra as alteracoes. Qualquer violacao e corrigida antes de prosseguir. + +### 4. Revisao do arquiteto + +O agente invoca `archgate:architect` para validar a conformidade estrutural com os ADRs alem do que as regras automatizadas capturam. A skill de arquiteto revisa o contexto completo das alteracoes contra todos os ADRs aplicaveis. + +### 5. Capturar aprendizados + +O agente invoca `archgate:quality-manager` para revisar o trabalho e identificar padroes que valem ser capturados. O quality manager pode propor novos ADRs ou atualizacoes em existentes quando convencoes 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 alcancar o mesmo objetivo mantendo a conformidade. + +Por exemplo, se um desenvolvedor pedir ao agente para adicionar `chalk` como dependencia em um projeto governado pelo ARCH-006 (politica de dependencias), o agente ira: + +1. Recusar, citando o ARCH-006 e a lista de dependencias 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 e consistente independentemente de como o desenvolvedor formula a solicitacao. ADRs sao tratados como restricoes obrigatorias, nao sugestoes. + +## Integracao com o servidor MCP + +O plugin se comunica com os ADRs do seu projeto por meio do servidor MCP do Archgate. O servidor fornece: + +- **Conteudo de ADRs** -- texto completo de qualquer ADR, acessivel por ID +- **Contexto de revisao** -- resumos condensados de todos os ADRs aplicaveis a um conjunto de arquivos alterados +- **Verificacao de regras** -- execucao de regras automatizadas com relatorio de violacoes +- **Listagem de ADRs** -- inventario de todos os ADRs do projeto com metadados + +O servidor MCP roda localmente e le diretamente do seu diretorio `.archgate/adrs/`. Nenhum dado sai da sua maquina. + +## Quando usar cada skill + +| Cenario | Skill a usar | +| ------------------------------------------------------- | -------------------------- | +| Iniciando um novo projeto com Archgate | `archgate:onboard` | +| Tarefas de codificacao do dia a dia | `archgate:developer` | +| Revisando um PR para conformidade com ADRs | `archgate:architect` | +| Percebendo um padrao 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, voce so 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..aefa22f1 --- /dev/null +++ b/docs/src/content/docs/pt-br/guides/cursor-integration.mdx @@ -0,0 +1,167 @@ +--- +title: Integracao com Cursor +description: Use o Archgate com o Cursor IDE para desenvolvimento assistido por IA com governanca. +--- + +O Archgate se integra com o [Cursor](https://cursor.com) para oferecer aos agentes de IA um fluxo de governanca estruturado. O agente le seus ADRs antes de escrever codigo, valida depois e captura novos padroes para a equipe -- o mesmo fluxo disponivel no [plugin para Claude Code](/guides/claude-code-plugin/). + +## Configuracao + +Execute `archgate init` com a flag `--editor cursor` para configurar a integracao com o Cursor no seu projeto: + +```bash +archgate init --editor cursor +``` + +### Com plugin (beta) + +:::note[Acesso beta necessario] +O plugin para Cursor esta atualmente em beta. [Cadastre-se em plugins.archgate.dev](https://plugins.archgate.dev) para obter acesso. +::: + +Se voce fez login via `archgate login`, o comando init tambem baixa e instala o plugin Archgate para o Cursor. O plugin fornece regras de agente pre-configuradas e skills que dao ao agente de IA do Cursor um fluxo de governanca completo. + +Para instalar o plugin explicitamente: + +```bash +archgate login # configuracao unica +archgate init --editor cursor --install-plugin +``` + +O pacote do plugin e baixado de `plugins.archgate.dev` e extraido no diretorio `.cursor/`. Ele inclui regras de agente, definicoes de skills e configuracao MCP. + +### Sem plugin (gratuito) + +Sem o plugin, `archgate init --editor cursor` ainda configura a conexao com o servidor MCP e uma regra de governanca basica. O agente de IA pode acessar seus ADRs e executar verificacoes, mas nao recebe as skills baseadas em papeis descritas abaixo. + +### Arquivos gerados + +| Arquivo | Proposito | +| --------------------------------------- | --------------------------------------------------------------------------- | +| `.cursor/mcp.json` | Conexao 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` ja existir, o Archgate mescla sua configuracao de forma aditiva -- entradas de servidor MCP existentes sao preservadas. + +## O que o plugin oferece + +O plugin adiciona skills baseadas em papeis ao Cursor. Cada skill e invocada como um slash command com o prefixo `/ag-`. As skills encapsulam partes especificas do fluxo de governanca para que o agente siga o mesmo processo todas as vezes. + +### Skills incluidas + +| Slash command | Skill | Proposito | +| --------------------- | --------------- | ------------------------------------------------------------------------------------------ | +| `/ag-developer` | Developer | Agente de desenvolvimento geral que le ADRs antes de codificar e valida depois | +| `/ag-architect` | Architect | Valida alteracoes de codigo contra todos os ADRs do projeto para conformidade estrutural | +| `/ag-quality-manager` | Quality Manager | Revisa a cobertura de regras e propoe novos ADRs quando padroes emergem | +| `/ag-adr-author` | ADR Author | Cria e edita ADRs seguindo as convencoes do projeto | +| `/ag-onboard` | Onboard | Configuracao unica: explora o codebase, entrevista o desenvolvedor e cria os ADRs iniciais | + +Essas sao as mesmas skills disponiveis no plugin para Claude Code (`archgate:developer`, `archgate:architect`, etc.), adaptadas para a interface de slash commands do Cursor. + +## Configuracao inicial com onboard + +Apos instalar o plugin, execute `/ag-onboard` no seu projeto uma vez. Essa skill: + +1. Explora a estrutura do seu codebase (diretorios, arquivos-chave, configuracao de pacotes) +2. Entrevista voce sobre as convencoes, restricoes e decisoes arquiteturais da sua equipe +3. Cria um conjunto inicial de ADRs com base nas suas respostas +4. Configura o diretorio `.archgate/` com suas primeiras regras + +A skill de onboard foi projetada para ser executada uma vez por projeto. Apos o onboarding, as outras skills cuidam do desenvolvimento no dia a dia. + +## Como funciona na pratica + +### Com o plugin + +A skill `/ag-developer` segue um fluxo estruturado para cada tarefa de codificacao: + +1. **Ler os ADRs aplicaveis** -- O agente chama `review_context` para ver quais ADRs se aplicam aos arquivos sendo alterados. Ele nao escreve codigo ate ter lido os ADRs aplicaveis. + +2. **Escrever codigo seguindo as restricoes dos ADRs** -- O agente implementa as alteracoes seguindo as secoes Do's and Don'ts dos ADRs aplicaveis. + +3. **Executar verificacoes de conformidade** -- O agente executa `archgate check` para rodar as regras automatizadas. Qualquer violacao e corrigida antes de prosseguir. + +4. **Revisao do arquiteto** -- O agente invoca `/ag-architect` para validar a conformidade estrutural com os ADRs alem do que as regras automatizadas capturam. + +5. **Capturar aprendizados** -- O agente invoca `/ag-quality-manager` para revisar o trabalho e identificar padroes que valem ser capturados como novos ADRs ou atualizacoes 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 decisao especifica, ler o recurso `adr://` (por exemplo, `adr://ARCH-001`). + +3. **Escrever codigo** -- Implementar as alteracoes seguindo as restricoes dos ADRs aplicaveis. + +4. **Executar verificacoes de conformidade** -- Chamar `check` (opcionalmente com `staged: true`) para validar que o codigo esta 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 alcancar o mesmo objetivo mantendo a conformidade. + +Por exemplo, se um desenvolvedor pedir ao agente para adicionar `chalk` como dependencia em um projeto governado por um ADR de politica de dependencias, o agente ira: + +1. Recusar, citando o ADR e a lista de dependencias aprovadas +2. Sugerir o uso da alternativa aprovada +3. Oferecer-se para implementar a tarefa usando a abordagem em conformidade + +Esse comportamento e consistente independentemente de como o desenvolvedor formula a solicitacao. ADRs sao tratados como restricoes obrigatorias, nao sugestoes. + +## Quando usar cada skill + +| Cenario | Slash command | +| ------------------------------------------------------- | --------------------- | +| Iniciando um novo projeto com Archgate | `/ag-onboard` | +| Tarefas de codificacao do dia a dia | `/ag-developer` | +| Revisando um PR para conformidade com ADRs | `/ag-architect` | +| Percebendo um padrao 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, voce so precisa usar `/ag-developer` diretamente. + +## Configuracao 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 governanca em `.cursor/rules/archgate-governance.mdc` usa `alwaysApply: true`, o que significa que o agente do Cursor sempre tem o contexto de governanca disponivel sem ativacao manual. + +O servidor MCP fornece: + +- **Conteudo de ADRs** -- texto completo de qualquer ADR, acessivel por ID via recursos `adr://` +- **Contexto de revisao** -- resumos condensados de todos os ADRs aplicaveis a um conjunto de arquivos alterados +- **Verificacao de regras** -- execucao de regras automatizadas com relatorio de violacoes +- **Listagem de ADRs** -- inventario de todos os ADRs do projeto com metadados + +O servidor MCP roda localmente e le diretamente do seu diretorio `.archgate/adrs/`. Nenhum dado sai da sua maquina. + +## Acesso a transcricoes de sessao + +A ferramenta MCP `cursor_session_context` le transcricoes de sessao do agente Cursor a partir do disco. Isso permite que as skills acessem o historico da conversa atual, o que e util para recuperar contexto que pode ter sido compactado ou truncado. + +A ferramenta aceita dois parametros opcionais: + +- `maxEntries` -- Numero maximo de entradas a retornar (padrao: 200, entradas mais recentes). +- `sessionId` -- Um UUID de sessao especifico para ler. Se omitido, a sessao mais recente e usada. + +## Dicas para uso eficaz + +- **Use `/ag-developer` para tarefas de codificacao.** Ele orquestra todo o fluxo de leitura-validacao-captura automaticamente. +- **Execute `/ag-onboard` uma vez por projeto.** Ele configura seus ADRs iniciais com base no seu codebase e convencoes reais. +- **Use `/ag-architect` para revisoes de PR.** Ele valida a conformidade estrutural alem do que as regras automatizadas capturam. +- **Use `/ag-quality-manager` apos resolver problemas complexos.** Ele captura aprendizados para que os mesmos erros nao se repitam. +- **Faca commit do diretorio `.cursor/`.** Isso garante que cada membro da equipe receba a mesma configuracao de governanca ao clonar o repositorio. +- **Mantenha os arquivos de regras dos ADRs atualizados.** O agente aplica o que as regras verificam -- se uma regra estiver faltando, a violacao nao sera 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..1580a242 --- /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 integracao com agentes de IA. +--- + +O servidor MCP do Archgate expoe os ADRs e verificacoes de conformidade do seu projeto para agentes de IA por meio do [Model Context Protocol](https://modelcontextprotocol.io/). Qualquer cliente compativel 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 voce nao executa esse comando manualmente. Em vez disso, configure sua ferramenta de IA para inicia-lo automaticamente (veja abaixo). + +## Configurando no Claude Code + +Adicione o seguinte ao arquivo `.mcp.json` do seu projeto (crie-o se nao existir): + +```json +{ + "mcpServers": { + "archgate": { + "command": "archgate", + "args": ["mcp"] + } + } +} +``` + +O Claude Code le esse arquivo na inicializacao e se conecta ao servidor MCP do Archgate automaticamente. Voce tambem pode executar `archgate init` (que usa `--editor claude` por padrao) para gerar essa configuracao junto com o diretorio `.archgate/` completo. + +## Configurando no Cursor + +Execute `archgate init --editor cursor` para gerar `.cursor/mcp.json` com a mesma configuracao de servidor. Consulte o guia de [Integracao com Cursor](/guides/cursor-integration/) para mais detalhes. + +## Ferramentas MCP disponiveis + +O servidor registra cinco ferramentas que agentes de IA podem chamar. + +### `check` + +Executa verificacoes de conformidade com ADRs no codebase. + +| Parametro | Tipo | Descricao | +| --------- | ---------- | ----------------------------------------- | +| `adrId` | `string?` | Verificar apenas um ADR especifico por ID | +| `staged` | `boolean?` | Verificar apenas arquivos staged no git | + +Retorna um resumo JSON com status de aprovacao/reprovacao, contagem de violacoes e resultados detalhados incluindo caminhos de arquivo e numeros de linha. + +### `list_adrs` + +Lista todos os ADRs do projeto com metadados. + +| Parametro | Tipo | Descricao | +| --------- | --------- | ------------------------------------------------------------------------------ | +| `domain` | `string?` | Filtrar por dominio (`backend`, `frontend`, `data`, `architecture`, `general`) | + +Retorna um array de objetos com os campos `id`, `title`, `domain` e `rules` para cada ADR. + +### `review_context` + +Obtem arquivos alterados agrupados por dominio com resumos dos ADRs aplicaveis. Este e o ponto de partida recomendado para um agente iniciando uma tarefa -- ele combina deteccao de alteracoes em arquivos, agrupamento por dominio e sumarizacao de ADRs em uma unica chamada. + +| Parametro | Tipo | Descricao | +| ----------- | ---------- | -------------------------------------------------------------------------------------- | +| `staged` | `boolean?` | Quando true, inclui apenas arquivos staged no git. Padrao: todos os arquivos alterados | +| `runChecks` | `boolean?` | Quando true, executa verificacoes de conformidade e inclui os resultados | +| `domain` | `string?` | Filtra os resultados para um unico dominio | + +Retorna resumos contendo apenas as secoes Decision e Do's/Don'ts de cada ADR aplicavel, mantendo a resposta concisa. + +### `claude_code_session_context` + +Le a transcricao da sessao atual do Claude Code para o projeto. Retorna entradas filtradas (mensagens do usuario e do assistente) do arquivo JSONL da sessao mais recente. + +| Parametro | Tipo | Descricao | +| ------------ | --------- | ---------------------------------------------------------------------------- | +| `maxEntries` | `number?` | Numero maximo de entradas relevantes a retornar (padrao: 200, mais recentes) | + +### `cursor_session_context` + +Le transcricoes de sessao do agente Cursor para o projeto. Retorna entradas filtradas dos arquivos JSONL de agent-transcripts do Cursor. + +| Parametro | Tipo | Descricao | +| ------------ | --------- | ---------------------------------------------------------------------------- | +| `maxEntries` | `number?` | Numero maximo de entradas relevantes a retornar (padrao: 200, mais recentes) | +| `sessionId` | `string?` | UUID de sessao especifico para ler. Se omitido, le a sessao mais recente | + +## Recursos MCP disponiveis + +### `adr://\{id\}` + +Le o conteudo 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, decisao, do's and don'ts, consequencias, conformidade e secoes de referencias. + +## Comportamento sem projeto + +Se o servidor MCP iniciar em um diretorio sem um diretorio `.archgate/`, todas as ferramentas permanecem disponiveis mas retornam orientacoes instruindo o agente a executar `archgate init` para inicializar a governanca. O servidor nao trava nem se recusa a iniciar -- ele fornece feedback acionavel para que o agente possa configurar o projeto. + +## Exemplo de fluxo de uso + +Uma sessao tipica de agente de IA usando o servidor MCP segue este padrao: + +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 le os resumos** e identifica quais restricoes arquiteturais se aplicam a sua tarefa. + +3. **O agente le um ADR completo** via `adr://ARCH-002` (por exemplo) quando precisa da justificativa completa ou exemplos de implementacao alem do resumo condensado. + +4. **O agente escreve codigo** seguindo as restricoes dos ADRs aplicaveis. + +5. **O agente chama `check`** com `staged: true` para validar a conformidade. Se violacoes forem encontradas, a resposta inclui caminhos de arquivo e numeros de linha para que o agente possa corrigi-las. + +6. **O agente itera** ate que `check` reporte zero violacoes. + +:::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 le ADRs, escreve codigo em conformidade, executa verificacoes, 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..4a509951 --- /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 verificacoes do Archgate automaticamente antes de cada commit. +--- + +## Visao geral + +O comando `archgate check --staged` verifica apenas os arquivos staged no git em relacao as suas regras de ADR. Como ele ignora arquivos nao-staged e nao-rastreados, ele executa rapido o suficiente para ser usado como hook de pre-commit sem desacelerar seu fluxo de trabalho. + +Quando uma verificacao falha, o commit e bloqueado. As violacoes sao impressas em stderr com caminhos de arquivo e numeros de linha para que voce possa localiza-las e corrigi-las imediatamente. + +## Lefthook + +[Lefthook](https://github.com/evilmartians/lefthook) e um gerenciador de hooks git rapido 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/) e uma ferramenta popular de hooks git para projetos Node.js. Adicione a verificacao ao seu hook de pre-commit: + +```bash +# .husky/pre-commit +archgate check --staged +``` + +Certifique-se de que o arquivo do hook e executavel: + +```bash +chmod +x .husky/pre-commit +``` + +## O que acontece quando as verificacoes falham + +Quando `archgate check --staged` encontra violacoes, ele termina com codigo 1. Isso bloqueia o commit. A saida inclui: + +- O ID do ADR e o nome da regra que foi violada +- O caminho do arquivo onde a violacao foi encontrada +- O numero da linha (quando disponivel) +- Uma descricao do que a regra espera + +Corrija as violacoes, re-stage os arquivos com `git add` e faca o commit novamente. + +## Performance + +A flag `--staged` restringe as verificacoes apenas aos arquivos na area de staging do git. Isso significa: + +- Um projeto com centenas de arquivos fonte mas apenas tres arquivos staged verificara apenas esses tres arquivos. +- Regras que nao correspondem a nenhum arquivo staged sao ignoradas completamente. +- Verificacoes tipicas de pre-commit completam em menos de um segundo. + +Sem `--staged`, `archgate check` escaneia todos os arquivos correspondentes ao padrao glob `files` de cada ADR, o que e util para CI mas mais lento para uso interativo. + +## Flags uteis + +| Flag | Finalidade | +| ------------ | -------------------------------------------------------------------------------------------------------------------------------------------- | +| `--staged` | Verifica apenas arquivos staged no git (obrigatorio para pre-commit) | +| `--verbose` | Mostra regras aprovadas e informacoes de tempo -- util para debugar por que uma verificacao esta lenta ou quais regras estao sendo avaliadas | +| `--json` | Exibe resultados como JSON -- util para encaminhar a outras ferramentas ou scripts de relatorio personalizados | +| `--adr ` | Verifica apenas regras de um ADR especifico -- util para isolar uma unica regra durante o debug | +| `--ci` | Exibe anotacoes do GitHub Actions -- use em workflows de CI ao inves de hooks de pre-commit | + +## Combinando com outros hooks + +Hooks de pre-commit podem executar multiplos 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 codigo diferente de zero, o commit e 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..599da6b7 --- /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 Decisao Arquitetural eficazes. +--- + +## Criando um ADR + +Use `archgate adr create` para gerar um novo ADR com o template padrao. O comando suporta modos interativo e nao-interativo. + +### Modo interativo + +Execute o comando sem argumentos para receber prompts guiados: + +```bash +archgate adr create +``` + +Voce sera solicitado a fornecer: + +1. **Domain** -- um entre `backend`, `frontend`, `data`, `architecture` ou `general` +2. **Title** -- um nome curto e descritivo para a decisao +3. **File patterns** -- globs opcionais separados por virgula que delimitam o escopo da verificacao de regras (ex.: `src/commands/**/*.ts`) + +O CLI atribui um ID sequencial baseado no prefixo do dominio (`ARCH-001`, `FE-002`, `BE-003`, etc.) e grava o arquivo em `.archgate/adrs/`. + +### Modo nao-interativo + +Passe `--title` e `--domain` para pular os prompts: + +```bash +archgate adr create --title "API Response Format" --domain backend --files "src/api/**/*.ts" +``` + +Flags disponiveis: + +| Flag | Descricao | +| ----------------- | -------------------------------------------------------------- | +| `--title ` | Titulo do ADR (obrigatorio no modo nao-interativo) | +| `--domain <name>` | Dominio: backend, frontend, data, architecture, general | +| `--files <globs>` | Padroes de arquivo separados por virgula 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 voce cria um ADR sem `--body`, o CLI gera um template com todas as secoes padrao: + +```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 + +- +``` + +## Orientacoes por secao + +### Context + +Explique por que essa decisao foi necessaria. Qual problema a motivou? Quais alternativas foram consideradas e por que foram descartadas? + +Boas secoes de contexto incluem: + +- O problema ou ponto de dor que motivou a decisao +- Alternativas avaliadas, com uma breve analise de trade-offs +- Quaisquer restricoes que limitaram as opcoes (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 especifico e concreto -- esta secao nao deve deixar ambiguidade sobre o que os desenvolvedores devem fazer. + +Inclua restricoes numeradas quando a decisao tem multiplas 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 e a secao que desenvolvedores e agentes de IA consultam com mais frequencia. Escreva exemplos concretos de padroes corretos e incorretos. Use codigo real sempre que possivel. + +```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 consequencias em tres categorias: + +- **Positive** -- beneficios que a equipe ganha com esta decisao +- **Negative** -- trade-offs que a equipe aceita (toda decisao tem) +- **Risks** -- o que pode dar errado, e como voce 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 decisao e aplicada. Existem dois mecanismos de aplicacao: + +1. **Regras automatizadas** -- arquivos `.rules.ts` complementares que rodam durante `archgate check` +2. **Aplicacao manual** -- o que revisores de codigo 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, documentacao externa ou discussoes 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 e um array de padroes glob. Quando definido, `archgate check` passa apenas os arquivos correspondentes para o `ctx.scopedFiles` da regra. Isso mantem as regras focadas no codigo 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 e apropriado para regras que abrangem todo o projeto, como politicas de dependencias. + +Padroes comuns: + +| Padrao | Corresponde a | +| ---------------------- | -------------------------------------------- | +| `src/commands/**/*.ts` | Todos os arquivos TypeScript em commands | +| `src/**/*.ts` | Todos os arquivos TypeScript do codigo-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 voce tiver um arquivo `.rules.ts` complementar com verificacoes automatizadas. O arquivo deve ter o mesmo nome do arquivo markdown do ADR, mas com a extensao `.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 decisoes que sao aplicadas apenas por revisao de codigo -- decisoes de processo, acordos de equipe ou diretrizes dificeis 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` sao obrigatorias. Todos os outros campos do frontmatter (`--title`, `--domain`, `--files`, `--rules`) sao opcionais e preservam seus valores existentes quando omitidos. + +| Flag | Descricao | +| ----------------- | ------------------------------------------------------------ | +| `--id <id>` | ID do ADR a ser atualizado (obrigatorio) | +| `--body <md>` | Corpo markdown de substituicao completa (obrigatorio) | +| `--title <title>` | Novo titulo (preserva o existente se omitido) | +| `--domain <name>` | Novo dominio (preserva o existente se omitido) | +| `--files <globs>` | Novos padroes 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 unica decisao.** Se voce perceber que esta escrevendo sobre dois assuntos nao relacionados, divida-os em ADRs separados. + +2. **Seja especifico nos Do's and Don'ts.** Diretrizes vagas como "escreva codigo limpo" nao sao acionaveis. Mostre padroes de codigo concretos. + +3. **Inclua exemplos de codigo reais.** A secao Do's and Don'ts e onde desenvolvedores e agentes de IA olham primeiro. Exemplos de codigo anotados tornam a decisao inequivoca. + +4. **Documente as alternativas que voce rejeitou.** Futuros colaboradores perguntarao "por que nao usamos X?" A secao Context deve responder a essa pergunta. + +5. **Declare os trade-offs honestamente.** Toda decisao tem consequencias negativas. Documenta-las gera confianca e ajuda a equipe a entender o que foi sacrificado. + +6. **Escreva regras para decisoes que podem ser verificadas automaticamente.** Se uma regra consegue detectar uma violacao antes da revisao de codigo, defina `rules: true` e escreva um arquivo `.rules.ts` complementar. Veja o guia [Escrevendo Regras](/pt-br/guides/writing-rules/). + +7. **Use prefixos de dominio para organizar.** O campo domain (`backend`, `frontend`, `data`, `architecture`, `general`) determina o prefixo do ID e ajuda a filtrar ADRs por area. + +:::tip[Deixe agentes de IA escreverem ADRs para voce] +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 convencoes do seu projeto. A skill Quality Manager tambem propoe novos ADRs quando detecta padroes 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..8c4deede --- /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 decisoes de ADR. +--- + +Regras sao funcoes TypeScript que verificam seu codebase quanto a conformidade com ADRs. Elas ficam em arquivos `.rules.ts` complementares ao lado dos arquivos markdown dos ADRs e sao executadas quando voce roda `archgate check`. + +``` +.archgate/adrs/ + ARCH-001-command-structure.md # The decision + ARCH-001-command-structure.rules.ts # The automated checks +``` + +## Configuracao basica + +Todo arquivo de regras exporta uma chamada `defineRules()` por padrao. Cada chave se torna um ID de regra, e cada regra tem uma `description` e uma funcao 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 unico arquivo de regras pode definir multiplas 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 funcao `check` fornece capacidades de leitura de arquivos, busca e relatorio. Aqui esta uma referencia detalhada com exemplos. + +### ctx.scopedFiles + +Um array de caminhos de arquivo que correspondem ao glob `files` do frontmatter do ADR. Se o ADR nao 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` recebera apenas arquivos de comandos. + +### ctx.changedFiles + +Um array de caminhos de arquivo que foram modificados (staged ou alterados no git). Util para verificacao 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) + +Le o conteudo de um arquivo como string. O caminho e relativo a raiz do projeto. + +```typescript +const content = await ctx.readFile("src/cli.ts"); +``` + +### ctx.readJSON(path) + +Le e faz o parse de um arquivo JSON. Retorna `unknown` -- faca 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 unico arquivo com uma expressao 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 multiplos arquivos que correspondem a um padrao 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 padrao glob. Retorna um array de caminhos de arquivo relativos a raiz do projeto. + +```typescript +const testFiles = await ctx.glob("tests/**/*.test.ts"); +``` + +### ctx.report + +A interface de relatorio com tres metodos de severidade: + +- `ctx.report.violation(detail)` -- severidade error (codigo de saida 1, bloqueia CI) +- `ctx.report.warning(detail)` -- severidade warning (registrado, mas nao bloqueia) +- `ctx.report.info(detail)` -- informacional (registrado para visibilidade) + +Cada metodo aceita um objeto com: + +| Campo | Tipo | Obrigatorio | Descricao | +| --------- | -------- | ----------- | -------------------------------------------- | +| `message` | `string` | Sim | Qual e a violacao | +| `file` | `string` | Nao | Caminho do arquivo com a violacao | +| `line` | `number` | Nao | Numero da linha da violacao | +| `fix` | `string` | Nao | Correcao 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 diretorio raiz do projeto. Util quando voce precisa construir caminhos absolutos. + +## Exemplos completos + +### Exemplo 1: Lista de dependencias permitidas + +Verifica se todas as dependencias de producao estao em uma lista aprovada. Esta e a regra que o Archgate usa para sua propria politica de dependencias 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: Padrao de export obrigatorio + +Verifica se todo arquivo de comando exporta uma funcao `register*Command`. Esta e a regra que o Archgate usa para sua propria 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: Padrao de import proibido + +Impede a importacao de uma biblioteca especifica 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: Convencao 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 maximo 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 obrigatoria + +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`, + }); + } + } + }, + }, +}); +``` + +## Niveis de severidade + +Cada regra pode definir uma severidade padrao em sua configuracao. A severidade determina como as violacoes sao tratadas: + +| Severidade | Codigo de saida | Comportamento | +| ---------- | --------------- | ------------------------------------------- | +| `error` | 1 | Bloqueia CI, deve ser corrigido | +| `warning` | 0 | Registrado, mas nao bloqueia | +| `info` | 0 | Informacional, registrado para visibilidade | + +Defina a severidade na definicao 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 padrao e `error`. + +Voce tambem 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 execucao de 30 segundos. Se uma regra exceder esse limite, ela e tratada como erro. Isso impede que verificacoes descontroladas bloqueiem o pipeline. + +Mantenha as regras rapidas: + +- Usando `ctx.grepFiles()` ao inves de ler cada arquivo manualmente +- Usando `Promise.all()` para verificar arquivos em paralelo +- Delimitando regras com o campo `files` do frontmatter para limitar o numero de arquivos processados + +## O campo `fix` + +O campo `fix` e uma string opcional exibida ao desenvolvedor junto com a mensagem de violacao. Ele descreve qual acao tomar para resolver o problema. Correcoes nao sao aplicadas automaticamente -- sao orientacoes. + +```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 violacao: + +``` +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 verificacoes de arquivo em paralelo.** Ao verificar multiplos arquivos independentes, processe-os em paralelo ao inves 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 verificacao incremental.** Ao executar `archgate check --staged`, `ctx.changedFiles` contem apenas os arquivos staged no git. Filtre `ctx.scopedFiles` com ele para verificar apenas o que mudou. + +3. **Mantenha as regras focadas em uma unica preocupacao.** Uma regra que verifica tanto convencoes de nomenclatura quanto padroes de import deve ser dividida em duas regras com IDs separados. + +4. **Use `ctx.grepFiles()` ao inves de iteracao manual.** Ao buscar um padrao em muitos arquivos, `ctx.grepFiles()` e mais eficiente do que ler cada arquivo e executar uma regex. + +5. **Forneca mensagens de `fix` acionaveis.** Um fix como "Nao faca isso" nao e util. Diga ao desenvolvedor exatamente o que fazer. + +6. **Filtre arquivos nao-aplicaveis 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 elegancia.** Se sua regra le um arquivo especifico como `package.json`, envolva a leitura em um try/catch e retorne antecipadamente se o arquivo nao existir. + +## Proximos passos + +- [Common Rule Patterns](/examples/common-rule-patterns/) — Padroes prontos para copiar e colar para verificacoes de dependencias, convencoes de nomenclatura, restricoes de import e mais. +- [Rule API Reference](/reference/rule-api/) — Referencia completa de todos os tipos e funcoes da API de regras. +- [Integracao 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..e31eeb72 --- /dev/null +++ b/docs/src/content/docs/pt-br/index.mdx @@ -0,0 +1,123 @@ +--- +title: Archgate +description: Aplique Architecture Decision Records como regras executaveis — 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 decisoes arquiteturais em linguagem natural. Humanos os leem. Agentes de IA os leem. Todos ficam alinhados. + +2. **ADRs como regras** — Arquivos complementares `.rules.ts` com verificacoes automatizadas escritas em TypeScript. Eles sao executados contra sua base de codigo e reportam violacoes com caminhos de arquivos e numeros 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 voce executa `archgate check`, a CLI carrega cada ADR que possui `rules: true` em seu frontmatter, executa o arquivo de regras complementar e reporta quaisquer violacoes. Codigo de saida 0 significa que seu codigo esta em conformidade. Codigo de saida 1 significa que nao esta. + +## Funcionalidades Principais + +<CardGrid> + <Card title="Regras Executaveis" icon="seti:typescript"> + Escreva regras em TypeScript. O Archgate as executa contra sua base de + codigo e reporta violacoes com caminhos de arquivos e numeros de linha. As + regras ficam ao lado das decisoes que elas aplicam. + </Card> + <Card title="Integracao com CI" icon="seti:pipeline"> + Conecte `archgate check` ao seu pipeline. Codigo de saida 1 bloqueia merges + quando regras sao violadas. Funciona com GitHub Actions, GitLab CI ou + qualquer sistema de CI que respeite codigos de saida. + </Card> + <Card title="Governanca com IA" icon="star"> + O servidor MCP da aos agentes de IA acesso em tempo real aos seus ADRs. Eles + leem as decisoes antes de escrever codigo e validam depois. Sem copiar e + colar regras nos prompts. + </Card> + <Card title="Auto-Governanca" icon="approve-check-circle"> + O Archgate governa seu proprio desenvolvimento. A mesma ferramenta que + verifica seu codigo verifica o nosso. Seis ADRs aplicam estrutura de + comandos, tratamento de erros, formatacao de saida, 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 governanca com IA. Os plugins dao aos agentes de IA habilidades baseadas em papeis para que leiam seus ADRs antes de programar, validem depois e capturem novos padroes 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-validacao-captura em cada tarefa. + </Card> + <Card title="Cursor" icon="pencil"> + O plugin para Cursor fornece regras e habilidades pre-configuradas para + agentes, dando ao agente de IA do Cursor o mesmo fluxo de governanca do + Claude Code. + </Card> +</CardGrid> + +:::tip[Acesso beta] +Os plugins para editores estao 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 configuracao e uso do plugin Claude Code." + /> + <LinkCard + title="Guia de integracao com Cursor" + href="/guides/cursor-integration/" + description="Configure o Archgate com o Cursor IDE." + /> +</CardGrid> + +## Saiba mais + +<CardGrid> + <LinkCard + title="O que sao 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 decisoes automaticamente." + /> + <LinkCard + title="Integracao 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="Referencia completa de todos os comandos e opcoes 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..393b91bb --- /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 e um arquivo Markdown armazenado em `.archgate/adrs/` com frontmatter YAML que define a identidade e o escopo da decisao. Esta pagina documenta o esquema do frontmatter, a estrutura das secoes markdown e o comportamento de validacao. + +## 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 | Obrigatorio | Descricao | +| -------- | ---------- | ----------- | -------------------------------------------------------------------------------------- | +| `id` | `string` | Sim | Identificador unico. Nao pode ser vazio. Convencao: `PREFIX-NNN` (ex.: `ARCH-001`). | +| `title` | `string` | Sim | Titulo legivel da decisao. Nao pode ser vazio. | +| `domain` | `enum` | Sim | Categoria de dominio. Um de: `backend`, `frontend`, `data`, `architecture`, `general`. | +| `rules` | `boolean` | Sim | Se este ADR possui um arquivo `.rules.ts` complementar com verificacoes automatizadas. | +| `files` | `string[]` | Nao | Padroes glob que definem o escopo de quais arquivos as regras se aplicam. | + +### id + +O identificador do ADR. Por convencao, usa o prefixo do dominio seguido de um numero de sequencia com preenchimento de zeros (ex.: `ARCH-001`, `BE-003`). O comando `archgate adr create` gera IDs automaticamente. + +Qualquer string nao vazia e valida, mas seguir a convencao de prefixo mantem os ADRs organizados e ordenaveis. + +### title + +Um nome curto e descritivo para a decisao arquitetural. Exibido na saida de `archgate adr list` e usado como cabecalho quando agentes de IA referenciam o ADR. + +### domain + +Agrupa ADRs relacionados. O dominio tambem 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` e executado, ele pula ADRs onde `rules` e `false`. + +### files + +Um array opcional de padroes glob que definem o escopo de cobertura de arquivos da regra. Quando presente, `ctx.scopedFiles` no arquivo de regras contem apenas arquivos que correspondem a esses padroes. Quando ausente, todos os arquivos do projeto estao no escopo. + +```yaml +files: ["src/commands/**/*.ts"] +``` + +Multiplos padroes podem ser especificados: + +```yaml +files: ["src/api/**/*.ts", "src/middleware/**/*.ts"] +``` + +--- + +## Prefixos de Dominio + +Cada dominio mapeia para um prefixo usado na convencao de ID do ADR. + +| Dominio | 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. + +--- + +## Convencao de Nomenclatura de Arquivos + +Os arquivos de ADR seguem uma convencao de nomenclatura que codifica o ID e um slug legivel: + +``` +{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 e uma versao kebab-case do titulo, gerada automaticamente por `archgate adr create`. + +--- + +## Secoes Markdown + +Apos o frontmatter, o corpo do ADR segue uma estrutura de secoes padrao. Embora o Archgate nao imponha secoes especificas, a estrutura a seguir e recomendada para consistencia. + +### Context + +Descreve o problema ou situacao que motivou a decisao. 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 decisao em si e suas principais restricoes. Esta e a secao principal que os agentes de IA leem antes de escrever codigo. + +```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 + +Orientacao concreta e acionavel dividida em duas subsecoes. Funciona como um checklist de referencia rapida 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 tres subsecoes 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 decisao e aplicada por meio de regras automatizadas e revisao 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, documentacao 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 extensao `.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` padrao 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 referencia completa da API TypeScript. + +--- + +## Validacao + +O frontmatter YAML e validado no momento do parse usando um esquema Zod. Frontmatter invalido causa um erro de parse com uma mensagem descritiva. + +### Campos obrigatorios + +Se um campo obrigatorio estiver ausente, o ADR falha no parse: + +``` +Invalid ADR frontmatter in ARCH-001-example.md: + - domain: Required +``` + +### Valores de enum invalidos + +Se `domain` nao for um dos valores validos: + +``` +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 validacao sao 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..d08d9232 --- /dev/null +++ b/docs/src/content/docs/pt-br/reference/cli-commands.mdx @@ -0,0 +1,461 @@ +--- +title: Comandos da CLI +description: Referencia completa de todos os comandos da CLI do Archgate. +--- + +## Opcoes globais + +Estas opcoes estao disponiveis em todos os comandos: + +| Opcao | Descricao | +| ----------------- | ---------------------------------- | +| `--version`, `-V` | Exibe a versao 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 codigo de uso unico e uma URL. Abra a URL no seu navegador, insira o codigo e autorize o Archgate GitHub OAuth App. Apos a autorizacao, a CLI troca sua identidade do GitHub por um token de plugin do Archgate e armazena ambos em `~/.archgate/credentials`. + +As credenciais sao necessarias 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 estao atualmente em beta. Cadastre-se em [plugins.archgate.dev](https://plugins.archgate.dev) para obter acesso. +::: + +### Subcomandos + +| Subcomando | Descricao | +| ------------------------ | -------------------------------------- | +| `archgate login` | Autenticar (pula se ja estiver logado) | +| `archgate login status` | Mostrar o status atual de autenticacao | +| `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 governanca do Archgate no projeto atual. + +```bash +archgate init [options] +``` + +Cria o diretorio `.archgate/` com um ADR de exemplo, arquivo de regras complementar e configuracao do linter. Opcionalmente configura a integracao com o editor para fluxos de trabalho com agentes de IA e instala o plugin de editor do Archgate. + +### Opcoes + +| Opcao | Padrao | Descricao | +| ------------------- | -------- | ------------------------------------------------------------------------ | +| `--editor <editor>` | `claude` | Integracao de editor a configurar (`claude`, `cursor`) | +| `--install-plugin` | auto | Instalar o plugin de editor do Archgate (requer `archgate login` previo) | + +Quando `--install-plugin` e passado, a CLI instala o plugin do Archgate para o editor selecionado. Se a flag for omitida, a CLI faz deteccao automatica: instala o plugin quando existem credenciais validas (de um `archgate login` anterior) e pula caso contrario. + +### Comportamento de instalacao do plugin + +**Claude Code:** Se a CLI `claude` estiver no seu PATH, o plugin e instalado automaticamente via `claude plugin marketplace add` e `claude plugin install`. Se a CLI `claude` nao for encontrada, o comando exibe os comandos de instalacao manual. + +**Cursor:** O pacote do plugin e baixado de `plugins.archgate.dev` e extraido no diretorio `.cursor/`. + +### Saida + +``` +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` e usado, a saida 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 verificacoes 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 violacoes com caminhos de arquivo e numeros de linha. + +### Opcoes + +| Opcao | Descricao | +| ------------ | ---------------------------------------------------------------------- | +| `--staged` | Verificar apenas arquivos no git stage (util para hooks de pre-commit) | +| `--json` | Saida JSON legivel por maquina | +| `--ci` | Formato de anotacao do GitHub Actions | +| `--adr <id>` | Verificar apenas regras de um ADR especifico | +| `--verbose` | Mostrar regras aprovadas e informacoes de tempo | + +### Codigos de saida + +| Codigo | Significado | +| ------ | ------------------------------------------------------ | +| 0 | Todas as regras passaram. Nenhuma violacao encontrada. | +| 1 | Uma ou mais violacoes 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 unico ADR: + +```bash +archgate check --adr ARCH-001 +``` + +Obter saida JSON para integracao com CI: + +```bash +archgate check --json +``` + +Obter anotacoes do GitHub Actions: + +```bash +archgate check --ci +``` + +### Formato da saida JSON + +Quando `--json` e usado, a saida e um unico 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 dominio, titulo e padroes de arquivo opcionais. Quando ambos `--title` e `--domain` sao fornecidos, ele executa de forma nao interativa. + +O ID do ADR e gerado automaticamente com o prefixo do dominio e o proximo numero de sequencia disponivel (ex.: `ARCH-002`, `BE-001`). + +### Opcoes + +| Opcao | Descricao | +| -------------------- | ------------------------------------------------------------------------- | +| `--title <title>` | Titulo do ADR (pula o prompt interativo) | +| `--domain <domain>` | Dominio do ADR (`backend`, `frontend`, `data`, `architecture`, `general`) | +| `--files <patterns>` | Padroes de arquivo, separados por virgula | +| `--body <markdown>` | Corpo completo do ADR em markdown (pula o template) | +| `--rules` | Define `rules: true` no frontmatter | +| `--json` | Saida como JSON | + +### Exemplos + +Modo interativo: + +```bash +archgate adr create +``` + +Modo nao 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] +``` + +### Opcoes + +| Opcao | Descricao | +| ------------------- | ------------------- | +| `--json` | Saida como JSON | +| `--domain <domain>` | Filtrar por dominio | + +### 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 dominio: + +```bash +archgate adr list --domain backend +``` + +--- + +## archgate adr show + +Exibe um ADR especifico pelo ID. + +```bash +archgate adr show <id> +``` + +Imprime o conteudo completo do ADR (frontmatter e corpo) na saida padrao. + +### Argumentos + +| Argumento | Descricao | +| --------- | ------------------------------------- | +| `<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`) sao atualizados apenas quando passados explicitamente; caso contrario, os valores existentes sao preservados. + +### Opcoes + +| Opcao | Obrigatorio | Descricao | +| -------------------- | ----------- | ------------------------------------------------------------------------------- | +| `--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>` | Nao | Novo titulo do ADR (preserva o existente se omitido) | +| `--domain <domain>` | Nao | Novo dominio (`backend`, `frontend`, `data`, `architecture`, `general`) | +| `--files <patterns>` | Nao | Novos padroes de arquivo, separados por virgula (preserva existente se omitido) | +| `--rules` | Nao | Define `rules: true` no frontmatter | +| `--json` | Nao | Saida 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 integracao com agentes de IA. + +```bash +archgate mcp +``` + +Executa um servidor MCP usando transporte stdio. O servidor expoe ferramentas para verificar conformidade com ADRs, listar ADRs e obter contexto de revisao. Consulte a referencia de [Ferramentas MCP](/pt-br/reference/mcp-tools/) para a lista completa de ferramentas e recursos disponiveis. + +O servidor inicia mesmo quando nenhum diretorio `.archgate/` e encontrado. Nesse caso, as ferramentas retornam orientacoes direcionando o agente a inicializar a governanca primeiro. + +### Configuracao + +Adicione a configuracao MCP do seu projeto (`.mcp.json` na raiz do projeto): + +```json +{ + "mcpServers": { + "archgate": { + "command": "archgate", + "args": ["mcp"] + } + } +} +``` + +Executar `archgate init` cria essa configuracao automaticamente para o seu editor. + +--- + +## archgate upgrade + +Atualiza o Archgate para a versao mais recente via npm. + +```bash +archgate upgrade +``` + +Verifica o registro npm para a versao mais recente publicada. Se uma versao mais nova estiver disponivel, executa `npm install -g archgate@latest` para atualizar. Se ja 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 diretorio de cache da CLI. + +```bash +archgate clean +``` + +Remove `~/.archgate/`, que armazena dados em cache como timestamps de verificacao de atualizacao. Seguro para executar a qualquer momento -- o diretorio e recriado automaticamente quando necessario. + +### 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..d6f8704b --- /dev/null +++ b/docs/src/content/docs/pt-br/reference/mcp-tools.mdx @@ -0,0 +1,226 @@ +--- +title: Ferramentas MCP +description: Referencia de todas as ferramentas e recursos MCP expostos pelo servidor Archgate. +--- + +O servidor MCP do Archgate expoe ferramentas e recursos que agentes de IA utilizam para ler ADRs, validar codigo contra regras e acessar o contexto de revisao. Inicie o servidor com `archgate mcp`. + +## Ferramentas + +### check + +Executa verificacoes de conformidade com ADRs no codebase. + +**Parametros:** + +| Nome | Tipo | Obrigatorio | Descricao | +| -------- | ------- | ----------- | ----------------------------------------- | +| `adrId` | string | Nao | Verificar apenas um ADR especifico por ID | +| `staged` | boolean | Nao | Verificar apenas arquivos no git stage | + +**Retorna** um objeto JSON com os resultados da verificacao: + +```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 e encontrada, retorna `{ "pass": true, "total": 0, "results": [], "message": "No rules to check" }`. + +As violacoes sao limitadas a 20 por regra para manter as respostas concisas. Quando uma regra tem mais violacoes do que o limite, `totalViolations` reflete a contagem real enquanto `shownViolations` e o array `violations` incluem apenas as 20 primeiras. O campo `truncated` no nivel superior e definido como `true` quando alguma regra foi limitada. + +--- + +### list_adrs + +Lista todos os ADRs do projeto com seus metadados. + +**Parametros:** + +| Nome | Tipo | Obrigatorio | Descricao | +| -------- | ------ | ----------- | ------------------------------------------------------------------------------ | +| `domain` | string | Nao | Filtrar por dominio (`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 + +Obtem arquivos alterados agrupados por dominio com resumos dos ADRs aplicaveis. Esta e a ferramenta principal que os agentes usam antes de escrever codigo -- ela fornece uma visao condensada de todas as decisoes e restricoes de ADR relevantes sem precisar ler cada arquivo de ADR individualmente. + +**Parametros:** + +| Nome | Tipo | Obrigatorio | Descricao | +| ----------- | ------- | ----------- | -------------------------------------------------------------------------------------------- | +| `staged` | boolean | Nao | Quando `true`, inclui apenas arquivos no git stage. Padrao: `false` (todos os alterados). | +| `runChecks` | boolean | Nao | Quando `true`, executa verificacoes de conformidade e inclui os resultados. Padrao: `false`. | +| `domain` | string | Nao | Filtrar por um unico dominio (`backend`, `frontend`, `data`, `architecture`, `general`). | + +**Retorna** um objeto JSON com resumos agrupados por dominio: + +```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 dominio inclui os arquivos alterados que correspondem aos seus ADRs, e resumos condensados dos ADRs com apenas as secoes **Decision** e **Do's and Don'ts**. + +Quando `runChecks` e `true`, `checkSummary` contem os resultados completos da verificacao (mesmo formato da resposta da ferramenta `check`). Quando `false` ou omitido, `checkSummary` e `null`. + +--- + +### claude_code_session_context + +Le a transcricao da sessao atual do Claude Code para o projeto. Util para recuperar contexto da sessao que pode ter sido compactado da conversa. + +**Parametros:** + +| Nome | Tipo | Obrigatorio | Padrao | Descricao | +| ------------ | ------ | ----------- | ------ | ----------------------------------------------------------------------------------- | +| `maxEntries` | number | Nao | 200 | Numero maximo de entradas relevantes a retornar. Retorna as entradas mais recentes. | + +**Retorna** um objeto JSON com metadados da sessao e transcricao 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` sao incluidos. As previas de conteudo sao truncadas para 500 caracteres para mensagens de usuario e 300 caracteres por bloco de conteudo para mensagens do assistente. + +--- + +### cursor_session_context + +Le as transcricoes de sessao do agente Cursor para o projeto. Funciona da mesma forma que `claude_code_session_context`, mas le do diretorio `agent-transcripts` do Cursor. + +**Parametros:** + +| Nome | Tipo | Obrigatorio | Padrao | Descricao | +| ------------ | ------ | ----------- | ------ | ------------------------------------------------------------------------- | +| `maxEntries` | number | Nao | 200 | Numero maximo de entradas relevantes a retornar. | +| `sessionId` | string | Nao | -- | UUID de sessao especifico para ler. Se omitido, le a sessao mais recente. | + +**Retorna** um objeto JSON com metadados da sessao e transcricao 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 nao for encontrado, a resposta inclui uma lista de IDs de sessao disponiveis. + +--- + +## Recursos + +### adr://\{id\} + +Le o conteudo completo de um ADR pelo seu ID. Retorna o markdown completo incluindo frontmatter YAML e corpo. + +**Formato da URI:** `adr://\{id\}` onde `\{id\}` e o identificador do ADR (ex.: `ARCH-001`, `BE-003`). + +**Exemplo:** + +Solicitar `adr://ARCH-001` retorna o conteudo markdown completo do arquivo ADR ARCH-001 com tipo MIME `text/markdown`. + +Se o ADR solicitado nao 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 governanca. Seu agente le ADRs, valida conformidade e captura aprendizados sem voce 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..45e1a0ec --- /dev/null +++ b/docs/src/content/docs/pt-br/reference/rule-api.mdx @@ -0,0 +1,300 @@ +--- +title: API de Regras +description: Referencia da API TypeScript para escrever regras do Archgate. +--- + +As regras do Archgate sao arquivos TypeScript que exportam verificacoes automatizadas via `defineRules()`. Cada regra recebe um `RuleContext` com utilitarios para buscar arquivos, ler conteudo e reportar violacoes. + +## 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 funcao `defineRules` recebe um registro de configuracoes de regras indexadas por ID de regra. As chaves se tornam os IDs das regras que aparecem na saida de verificacao e nos relatorios de violacao. A funcao 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 | Obrigatorio | Descricao | +| ------------- | ------------------------------------- | ----------- | --------------------------------------------------- | +| `description` | `string` | Sim | Descricao legivel exibida na saida de verificacao | +| `severity` | `Severity` | Nao | Severidade padrao para violacoes. Padrao: `"error"` | +| `check` | `(ctx: RuleContext) => Promise<void>` | Sim | Funcao assincrona contendo a logica da regra | + +--- + +## RuleContext + +A funcao `check` recebe um objeto `RuleContext` com o estado do projeto e metodos utilitarios. + +```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 diretorio raiz do projeto (onde `.archgate/` esta localizado). + +#### scopedFiles + +```typescript +scopedFiles: string[]; +``` + +Arquivos que correspondem aos padroes glob de `files` do frontmatter do ADR. Se o ADR nao tiver o campo `files`, contem todos os arquivos do projeto. Use esta lista como a lista principal de arquivos para suas verificacoes de regra. + +#### changedFiles + +```typescript +changedFiles: string[]; +``` + +Arquivos que foram modificados de acordo com o git. Quando `--staged` e usado, contem apenas arquivos no stage. Quando executado sem `--staged`, contem todos os arquivos alterados (staged e unstaged). Vazio quando nenhuma alteracao git e detectada. + +#### report + +```typescript +report: RuleReport; +``` + +A interface de relatorio para registrar violacoes, avisos e mensagens informativas. Veja [RuleReport](#rulereport) abaixo. + +### Metodos + +#### glob + +```typescript +glob(pattern: string): Promise<string[]>; +``` + +Encontra arquivos correspondentes a um padrao glob relativo a 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 unico arquivo por linhas correspondentes a uma expressao regular. Retorna um array de objetos `GrepMatch` com caminho do arquivo, numero da linha, coluna e conteudo correspondente. + +```typescript +const matches = await ctx.grep(file, /console\.error\(/); +``` + +#### grepFiles + +```typescript +grepFiles(pattern: RegExp, fileGlob: string): Promise<GrepMatch[]>; +``` + +Busca em multiplos arquivos correspondentes a um padrao glob por linhas que correspondam a uma expressao regular. Combina `glob` e `grep` em uma unica chamada. + +```typescript +const matches = await ctx.grepFiles(/TODO:/i, "src/**/*.ts"); +``` + +#### readFile + +```typescript +readFile(path: string): Promise<string>; +``` + +Le o conteudo de um arquivo como string. O caminho e relativo a raiz do projeto. + +```typescript +const content = await ctx.readFile("src/config.ts"); +``` + +#### readJSON + +```typescript +readJSON(path: string): Promise<unknown>; +``` + +Le e faz o parse de um arquivo JSON. O caminho e relativo a raiz do projeto. Retorna o valor parseado como `unknown` -- faca 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 relatorio para registrar resultados de verificacao. Cada metodo 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 violacao de regra. Violacoes fazem a verificacao falhar com codigo de saida 1. Use para restricoes rigidas que nao devem ser mergeadas. + +#### warning + +```typescript +report.warning(detail: ReportDetail): void; +``` + +Reporta um aviso. Avisos aparecem na saida de verificacao mas nao fazem a verificacao falhar. Use para orientacoes nao bloqueantes. + +#### info + +```typescript +report.info(detail: ReportDetail): void; +``` + +Reporta uma mensagem informativa. Nao afeta o codigo de saida da verificacao. Use para sugestoes 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 | Obrigatorio | Descricao | +| --------- | -------- | ----------- | ------------------------------------------------- | +| `message` | `string` | Sim | Descricao legivel do problema | +| `file` | `string` | Nao | Caminho do arquivo onde o problema foi encontrado | +| `line` | `number` | Nao | Numero da linha no arquivo | +| `fix` | `string` | Nao | Sugestao de correcao ou acao de remediacao | + +--- + +## GrepMatch + +Retornado por `ctx.grep()` e `ctx.grepFiles()`. + +```typescript +interface GrepMatch { + file: string; + line: number; + column: number; + content: string; +} +``` + +| Campo | Tipo | Descricao | +| --------- | -------- | -------------------------------------------- | +| `file` | `string` | Caminho absoluto do arquivo correspondente | +| `line` | `number` | Numero da linha da correspondencia (base 1) | +| `column` | `number` | Numero da coluna da correspondencia (base 1) | +| `content` | `string` | Conteudo completo da linha correspondente | + +--- + +## Severity + +```typescript +type Severity = "error" | "warning" | "info"; +``` + +| Valor | Impacto no codigo de saida | Descricao | +| ----------- | -------------------------- | --------------------------------- | +| `"error"` | Causa saida 1 | Restricao rigida, bloqueia merges | +| `"warning"` | Sem impacto | Orientacao nao bloqueante | +| `"info"` | Sem impacto | Informativo, apenas sugestoes | + +--- + +## ViolationDetail + +A representacao interna de um problema reportado, usada na saida de verificacao e nos resultados JSON. + +```typescript +interface ViolationDetail { + ruleId: string; + adrId: string; + message: string; + file?: string; + line?: number; + fix?: string; + severity: Severity; +} +``` + +| Campo | Tipo | Descricao | +| ---------- | ---------- | ------------------------------------------------- | +| `ruleId` | `string` | ID da regra da chave de `defineRules` | +| `adrId` | `string` | ID do ADR do frontmatter | +| `message` | `string` | Descricao legivel | +| `file` | `string?` | Caminho do arquivo onde o problema foi encontrado | +| `line` | `number?` | Numero da linha no arquivo | +| `fix` | `string?` | Sugestao de correcao | +| `severity` | `Severity` | Severidade efetiva desta violacao | + +--- + +## RuleSet + +O tipo de retorno de `defineRules`. Voce nao constroi isso diretamente. + +```typescript +type RuleSet = { + rules: Record<string, RuleConfig>; +}; +``` From 00100dd1fcddd205d8e5595f8bfb0620546aa85f Mon Sep 17 00:00:00 2001 From: Rhuan Barreto <rhuan@barreto.work> Date: Sat, 28 Feb 2026 20:04:00 +0100 Subject: [PATCH 2/2] fix(docs): add missing diacritical marks to pt-br translations MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit All 18 Portuguese translation files were missing accents (ã, é, í, ó, ú, ç, ê, ô, õ, á). Rewrote every file with proper diacritics while preserving code blocks, links, and technical terms unchanged. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> --- docs/src/content/docs/pt-br/concepts/adrs.mdx | 62 +++---- .../content/docs/pt-br/concepts/domains.mdx | 70 ++++---- .../src/content/docs/pt-br/concepts/rules.mdx | 94 +++++------ .../pt-br/examples/common-rule-patterns.mdx | 56 +++---- .../pt-br/getting-started/installation.mdx | 32 ++-- .../pt-br/getting-started/quick-start.mdx | 70 ++++---- .../docs/pt-br/guides/ci-integration.mdx | 68 ++++---- .../docs/pt-br/guides/claude-code-plugin.mdx | 102 ++++++------ .../docs/pt-br/guides/cursor-integration.mdx | 130 +++++++-------- .../content/docs/pt-br/guides/mcp-server.mdx | 74 ++++----- .../docs/pt-br/guides/pre-commit-hooks.mdx | 52 +++--- .../docs/pt-br/guides/writing-adrs.mdx | 104 ++++++------ .../docs/pt-br/guides/writing-rules.mdx | 114 ++++++------- docs/src/content/docs/pt-br/index.mdx | 58 +++---- .../docs/pt-br/reference/adr-schema.mdx | 76 ++++----- .../docs/pt-br/reference/cli-commands.mdx | 152 +++++++++--------- .../docs/pt-br/reference/mcp-tools.mdx | 80 ++++----- .../content/docs/pt-br/reference/rule-api.mdx | 84 +++++----- 18 files changed, 739 insertions(+), 739 deletions(-) diff --git a/docs/src/content/docs/pt-br/concepts/adrs.mdx b/docs/src/content/docs/pt-br/concepts/adrs.mdx index b1e9969f..c9ebb742 100644 --- a/docs/src/content/docs/pt-br/concepts/adrs.mdx +++ b/docs/src/content/docs/pt-br/concepts/adrs.mdx @@ -1,97 +1,97 @@ --- -title: Registros de Decisao Arquitetural -description: Entenda como o Archgate usa ADRs como documentos e regras executaveis. +title: Registros de Decisão Arquitetural +description: Entenda como o Archgate usa ADRs como documentos e regras executáveis. --- -Um Architecture Decision Record (ADR) e um documento curto que captura uma unica decisao arquitetural junto com seu contexto e consequencias. ADRs respondem a pergunta: _por que_ essa decisao foi tomada, e _quais_ sao seus trade-offs? +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 decisao duas expressoes: um **documento** que humanos e agentes de IA leem, e um **arquivo de regras** opcional que maquinas executam. +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 Expressoes de um ADR +## Duas Expressões de um ADR ### ADR como Documento -O documento e um arquivo Markdown com frontmatter YAML armazenado em `.archgate/adrs/`. Ele descreve a decisao em linguagem simples: qual problema resolve, quais alternativas foram consideradas, o que a equipe decidiu, e quais consequencias seguem. +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 codificacao esta prestes a escrever codigo, ele le os ADRs relevantes para entender as restricoes antes de gerar qualquer coisa. +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 le os ADRs aplicaveis automaticamente antes de cada tarefa de codificacao -- sem necessidade de copiar e colar manualmente nos prompts. [Inscreva-se para acesso beta](https://plugins.archgate.dev). +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 e um arquivo `.rules.ts` complementar que exporta verificacoes automatizadas via `defineRules()`. Quando voce 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 violacoes com caminhos de arquivo e numeros de linha. +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 decisoes sao melhor aplicadas apenas por revisao de codigo. Defina `rules: false` quando nenhuma verificacao automatizada for pratica. +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. -## Convencao de Nomenclatura de Arquivos +## Convenção de Nomenclatura de Arquivos -Os arquivos de ADR seguem uma convencao de nomenclatura estrita que codifica o prefixo do dominio, numero de sequencia e um slug legivel: +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 dominio de arquitetura sobre estrutura de comandos produziria: +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 dominio do ADR (veja [Dominios](/concepts/domains/)). O numero de sequencia e preenchido com zeros ate tres digitos e auto-incrementado por `archgate adr create`. +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 comeca com um bloco de frontmatter YAML entre delimitadores `---`. O frontmatter e o metadado legivel por maquina que o Archgate usa para carregar, filtrar e definir o escopo das regras. +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 | Obrigatorio | Descricao | +| Campo | Tipo | Obrigatório | Descrição | | -------- | ------------ | ----------- | --------------------------------------------------------------- | -| `id` | string | Sim | Identificador unico como `ARCH-001` ou `BE-003` | -| `title` | string | Sim | Titulo legivel da decisao | +| `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 | Nao | Padroes glob que definem quais arquivos as regras verificam | +| `files` | string array | Não | Padrões glob que definem quais arquivos as regras verificam | -O campo `files` e opcional. Quando presente, restringe a execucao das regras apenas aos arquivos que correspondem aos globs fornecidos. Quando ausente, as regras sao executadas contra todos os arquivos do projeto. Por exemplo, `files: ["src/commands/**/*.ts"]` limita as verificacoes apenas aos arquivos de comando. +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. -## Secoes do Corpo do ADR +## Seções do Corpo do ADR -Apos o frontmatter, o corpo do ADR segue uma estrutura de secoes padrao: +Após o frontmatter, o corpo do ADR segue uma estrutura de seções padrão: ### Context -Descreve o problema ou situacao que motivou a decisao. Inclua alternativas que foram consideradas e por que foram rejeitadas. +Descreve o problema ou situação que motivou a decisão. Inclua alternativas que foram consideradas e por que foram rejeitadas. ### Decision -Declara a decisao em si e suas restricoes principais. Esta e a secao que os agentes de IA mais observam ao decidir como escrever codigo. +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 -Orientacao concreta e acionavel dividida em duas subsecoes. Funcionam como uma lista de verificacao rapida para desenvolvedores e agentes de IA. +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 tres subsecoes: +Dividida em três subseções: -- **Positive** -- beneficios que a decisao proporciona +- **Positive** -- benefícios que a decisão proporciona - **Negative** -- trade-offs aceitos -- **Risks** -- coisas que podem dar errado e como mitiga-las +- **Risks** -- coisas que podem dar errado e como mitigá-las ### Compliance and Enforcement -Descreve como a decisao e aplicada, tanto por regras automatizadas (com IDs de regra e severidades) quanto por checklists de revisao manual. +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, documentacao externa ou documentos de design. +Links para ADRs relacionados, documentação externa ou documentos de design. ## Exemplo Completo -Abaixo esta um ADR completo com frontmatter e todas as secoes preenchidas. +Abaixo está um ADR completo com frontmatter e todas as seções preenchidas. ```markdown --- diff --git a/docs/src/content/docs/pt-br/concepts/domains.mdx b/docs/src/content/docs/pt-br/concepts/domains.mdx index bb2d8893..95d1ff7c 100644 --- a/docs/src/content/docs/pt-br/concepts/domains.mdx +++ b/docs/src/content/docs/pt-br/concepts/domains.mdx @@ -1,29 +1,29 @@ --- -title: Dominios -description: Categorize ADRs por dominio para uma governanca organizada. +title: Domínios +description: Categorize ADRs por domínio para uma governança organizada. --- -Dominios sao categorias que agrupam ADRs relacionados. Cada ADR pertence a exatamente um dominio, e o dominio determina o prefixo usado no identificador do ADR. +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. -## Dominios Integrados +## Domínios Integrados -O Archgate vem com cinco dominios integrados. Cada um tem um prefixo curto que aparece no inicio de cada ID de ADR naquele dominio. +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. -| Dominio | Prefixo | Uso para | +| Domínio | Prefixo | Uso para | | -------------- | ------- | ------------------------------------------------------------------ | -| `backend` | `BE` | Logica server-side, APIs, bancos de dados, servicos | -| `frontend` | `FE` | Componentes de UI, logica client-side, padroes de estilo | -| `data` | `DATA` | Modelos de dados, schemas, pipelines, estrategias de armazenamento | -| `architecture` | `ARCH` | Decisoes arquiteturais transversais | -| `general` | `GEN` | Convencoes gerais do projeto e workflows | +| `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 Dominios Sao Usados +## Como os Domínios São Usados -### Identificacao de ADR +### Identificação de ADR -O prefixo do dominio e incorporado ao campo `id` de cada ADR. Quando voce executa `archgate adr create` e seleciona um dominio, a CLI determina automaticamente o proximo numero de sequencia disponivel para o prefixo daquele dominio. Um dominio de arquitetura com dois ADRs existentes (`ARCH-001`, `ARCH-002`) atribuiria `ARCH-003` ao proximo. +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: @@ -34,63 +34,63 @@ ARCH-003-dependency-policy.rules.ts ### Filtragem -O comando `archgate adr list` suporta a flag `--domain` para mostrar apenas ADRs de um dominio especifico: +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 e util em projetos grandes onde dezenas de ADRs abrangem multiplas preocupacoes. Filtrar por dominio permite que voce foque nas decisoes relevantes para seu trabalho atual. +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 dominio ao fornecer contexto para agentes de IA. Quando um agente esta prestes a escrever codigo, ele recebe apenas os resumos de ADR relevantes para os dominios que suas alteracoes afetam, em vez do conjunto completo de todos os ADRs. Esse escopo reduz o ruido e ajuda os agentes a focar nas restricoes que realmente se aplicam. +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. -### Validacao com Escopo +### Validação com Escopo -Embora os dominios em si nao restrinjam quais arquivos uma regra pode verificar (esse e o trabalho do glob `files` no frontmatter do ADR), os dominios fornecem um agrupamento logico que ajuda as equipes a organizar sua governanca. Uma equipe de backend pode revisar todos os ADRs `BE-*` para entender suas restricoes, enquanto a equipe de frontend foca nos `FE-*`. +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 Dominio +## Quando Usar Qual Domínio ### backend -Use para decisoes sobre codigo server-side: padroes de design de API, convencoes de acesso a banco de dados, fluxos de autenticacao, comunicacao entre servicos, tratamento de filas e padroes de jobs em background. +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, estrategia de migracao de banco de dados, taxonomia de codigos de erro. +**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 decisoes sobre codigo client-side: estrutura de componentes, padroes de gerenciamento de estado, abordagens de estilizacao, requisitos de acessibilidade e escolhas de ferramentas de build. +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, padrao de validacao de formulario. +**Exemplos de ADRs:** Estrutura de arquivo de componente, metodologia CSS, padrão de validação de formulário. ### data -Use para decisoes sobre dados: design de schema, convencoes de pipeline de dados, escolhas de engine de armazenamento, formatos de serializacao e estrategias de validacao de dados. +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, convencoes de nomenclatura de banco de dados, politica de retencao 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 decisoes transversais que abrangem multiplos dominios ou afetam a estrutura geral do projeto. Sao decisoes que equipes de backend, frontend e dados precisam seguir. +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, convencoes de tratamento de erros, politica de gerenciamento de dependencias, padroes de teste. +**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 convencoes de projeto que nao se encaixam perfeitamente em um dominio tecnico: processos de revisao de codigo, formatos de mensagem de commit, padroes de documentacao e praticas de onboarding. +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 descricao de PR, requisitos de documentacao. +**Exemplos de ADRs:** Formato de mensagem de commit, template de descrição de PR, requisitos de documentação. -## Escolhendo o Dominio Certo +## Escolhendo o Domínio Certo -Ao decidir a qual dominio um ADR pertence, considere quem precisa segui-lo: +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 multiplos dominios tecnicos, use `architecture`. -- Se e um processo ou convencao em vez de uma decisao tecnica, use `general`. +- 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 duvida entre `architecture` e um dominio especifico, prefira o dominio mais especifico. Reserve `architecture` para decisoes que genuinamente cruzam fronteiras. +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 index 4af0aae4..0abc6c1a 100644 --- a/docs/src/content/docs/pt-br/concepts/rules.mdx +++ b/docs/src/content/docs/pt-br/concepts/rules.mdx @@ -1,13 +1,13 @@ --- title: Regras -description: Como o sistema de regras do Archgate transforma decisoes de ADR em verificacoes automatizadas. +description: Como o sistema de regras do Archgate transforma decisões de ADR em verificações automatizadas. --- -Regras sao o lado executavel de um ADR. Elas vivem em arquivos `.rules.ts` complementares ao lado do documento ADR e exportam verificacoes automatizadas via a funcao `defineRules()`. Quando voce executa `archgate check`, a CLI carrega cada ADR que tem `rules: true`, importa seu arquivo de regras complementar e executa cada verificacao contra seu codebase. +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 e um modulo TypeScript que exporta por padrao o resultado de `defineRules()`. Importe a funcao do pacote `archgate/rules`: +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"; @@ -23,56 +23,56 @@ export default defineRules({ }); ``` -Cada chave no objeto passado para `defineRules()` se torna o ID da regra. O identificador completo da regra mostrado na saida do check combina o ID do ADR e a chave da regra, por exemplo `ARCH-004/no-barrel-files`. +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 tres partes: +Toda regra tem três partes: -| Propriedade | Tipo | Obrigatorio | Descricao | +| Propriedade | Tipo | Obrigatório | Descrição | | ------------- | -------- | ----------- | --------------------------------------------- | | `description` | string | Sim | Um resumo curto do que a regra verifica | -| `severity` | string | Nao | `"error"` (padrao), `"warning"`, ou `"info"` | -| `check` | function | Sim | Funcao assincrona que recebe um `RuleContext` | +| `severity` | string | Não | `"error"` (padrão), `"warning"`, ou `"info"` | +| `check` | function | Sim | Função assíncrona que recebe um `RuleContext` | -### Niveis de Severidade +### Níveis de Severidade A severidade determina o que acontece quando uma regra encontra um problema: | Severidade | Exit Code | Efeito | | ---------- | --------- | -------------------------------------------- | -| `error` | 1 | A violacao e reportada e a verificacao falha | -| `warning` | 0 | O aviso e registrado mas a verificacao passa | -| `info` | 0 | Mensagem informativa, a verificacao passa | +| `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` e executado, exit code 1 significa que pelo menos uma violacao de severidade `error` foi encontrada. Exit code 0 significa que nao houve erros (avisos e mensagens informativas sao registrados mas nao bloqueiam). +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 funcao `check` recebe um objeto `RuleContext` que fornece tudo que uma regra precisa para inspecionar o codebase e reportar descobertas. +A função `check` recebe um objeto `RuleContext` que fornece tudo que uma regra precisa para inspecionar o codebase e reportar descobertas. -### Informacoes do Projeto +### Informações do Projeto -| Propriedade | Tipo | Descricao | +| Propriedade | Tipo | Descrição | | ------------------ | ---------- | ------------------------------------------------------------------------------------------------------ | -| `ctx.projectRoot` | `string` | Caminho absoluto para o diretorio raiz do projeto | -| `ctx.scopedFiles` | `string[]` | Arquivos que correspondem aos globs `files` do ADR, ou todos os arquivos se nao houver globs definidos | +| `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`) | -### Operacoes de Arquivo +### Operações de Arquivo -| Metodo | Retorno | Descricao | +| Método | Retorno | Descrição | | -------------------- | ------------------- | --------------------------------------------------- | -| `ctx.glob(pattern)` | `Promise<string[]>` | Encontra arquivos que correspondem a um padrao glob | -| `ctx.readFile(path)` | `Promise<string>` | Le o conteudo de um arquivo como string | -| `ctx.readJSON(path)` | `Promise<unknown>` | Le e faz parse de um arquivo JSON | +| `ctx.glob(pattern)` | `Promise<string[]>` | Encontra arquivos que correspondem a um padrão glob | +| `ctx.readFile(path)` | `Promise<string>` | Lê o conteúdo de um arquivo como string | +| `ctx.readJSON(path)` | `Promise<unknown>` | Lê e faz parse de um arquivo JSON | -### Operacoes de Busca +### Operações de Busca -| Metodo | Retorno | Descricao | +| Método | Retorno | Descrição | | ---------------------------------- | ---------------------- | ------------------------------------------------------ | -| `ctx.grep(file, pattern)` | `Promise<GrepMatch[]>` | Busca em um unico arquivo com um padrao regex | -| `ctx.grepFiles(pattern, fileGlob)` | `Promise<GrepMatch[]>` | Busca em multiplos arquivos que correspondem a um glob | +| `ctx.grep(file, pattern)` | `Promise<GrepMatch[]>` | Busca em um único arquivo com um padrão regex | +| `ctx.grepFiles(pattern, fileGlob)` | `Promise<GrepMatch[]>` | Busca em múltiplos arquivos que correspondem a um glob | Tanto `grep` quanto `grepFiles` retornam um array de objetos `GrepMatch`: @@ -85,9 +85,9 @@ interface GrepMatch { } ``` -### Relatorios +### Relatórios -O objeto `ctx.report` fornece tres metodos para reportar descobertas: +O objeto `ctx.report` fornece três métodos para reportar descobertas: ```typescript ctx.report.violation({ message, file?, line?, fix? }); @@ -95,24 +95,24 @@ ctx.report.warning({ message, file?, line?, fix? }); ctx.report.info({ message, file?, line?, fix? }); ``` -Cada metodo aceita um objeto com: +Cada método aceita um objeto com: -| Propriedade | Tipo | Obrigatorio | Descricao | +| Propriedade | Tipo | Obrigatório | Descrição | | ----------- | ------ | ----------- | ---------------------------------------- | -| `message` | string | Sim | Qual e o problema | -| `file` | string | Nao | Caminho relativo do arquivo com problema | -| `line` | number | Nao | Numero da linha onde o problema ocorre | -| `fix` | string | Nao | Sugestao de correcao para a violacao | +| `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 questoes que valem ser sinalizadas mas nao bloqueiam. Use `ctx.report.info()` para saida puramente informativa. +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 execucao de 30 segundos. Se a funcao `check` de uma regra nao completar dentro de 30 segundos, ela e terminada e reportada como erro. Isso impede que regras descontroladas bloqueiem o pipeline indefinidamente. +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 esta um arquivo de regras completo que verifica um padrao de import proibido. Ele garante que nenhum arquivo fonte importe diretamente de `node:fs` (o projeto requer o uso de um wrapper). +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"; @@ -144,7 +144,7 @@ export default defineRules({ }); ``` -Quando essa regra e executada contra um arquivo contendo `import { readFileSync } from "node:fs"`, a saida se parece com: +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 @@ -152,15 +152,15 @@ ARCH-007/no-direct-fs-import ERROR Fix: Replace the import with: import { readFile, writeFile } from "../helpers/fs" ``` -## Modelo de Execucao +## Modelo de Execução -As regras sao executadas com as seguintes garantias: +As regras são executadas com as seguintes garantias: -- **Paralelo entre ADRs** -- Regras de diferentes ADRs sao executadas concorrentemente para maior velocidade. -- **Sequencial dentro de um ADR** -- Regras pertencentes ao mesmo ADR sao executadas uma apos a outra, para que regras anteriores possam estabelecer contexto para as posteriores. -- **Arquivos no escopo sao pre-resolvidos** -- O array `ctx.scopedFiles` e preenchido antes que sua funcao `check` seja chamada, com base nos globs `files` do ADR. -- **Arquivos alterados para modo staged** -- Ao executar `archgate check --staged`, `ctx.changedFiles` contem apenas os arquivos staged no git, permitindo que regras pulem arquivos nao alterados para feedback mais rapido. +- **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 verificacoes 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 apos cada alteracao de codigo. O agente le os ADRs aplicaveis, escreve codigo em conformidade e valida -- sem necessidade de executar comandos de verificacao manualmente. [Inscreva-se para acesso beta](https://plugins.archgate.dev). +:::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 index 6e0fe066..f07aeb93 100644 --- a/docs/src/content/docs/pt-br/examples/common-rule-patterns.mdx +++ b/docs/src/content/docs/pt-br/examples/common-rule-patterns.mdx @@ -1,13 +1,13 @@ --- -title: Padroes Comuns de Regras -description: Padroes de regras prontos para uso em necessidades comuns de governanca. +title: Padrões Comuns de Regras +description: Padrões de regras prontos para uso em necessidades comuns de governança. --- -Esta pagina fornece exemplos completos de regras, prontos para copiar e colar, para cenarios comuns de governanca. Cada padrao inclui o codigo completo da regra, uma explicacao de como funciona e orientacoes sobre quando utiliza-lo. +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. -## Padrao 1: Lista de Dependencias Permitidas +## Padrão 1: Lista de Dependências Permitidas -**Quando usar:** Restringir dependencias de producao a uma lista curada para evitar inchacos de dependencias e riscos na cadeia de suprimentos. +**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"; @@ -45,13 +45,13 @@ export default defineRules({ }); ``` -**Como funciona:** Le o `package.json`, itera sobre as `dependencies` de producao e reporta uma violacao para qualquer pacote que nao esteja no array `APPROVED_DEPS`. Dependencias em `devDependencies` nao sao verificadas. A mensagem de correcao orienta o desenvolvedor a obter a aprovacao da dependencia ou reclassifica-la. +**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. --- -## Padrao 2: Padrao de Exportacao Obrigatoria +## Padrão 2: Padrão de Exportação Obrigatória -**Quando usar:** Garantir que arquivos em um diretorio especifico exportem uma assinatura de funcao obrigatoria, como o padrao `register*Command` para arquivos de comandos CLI. +**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"; @@ -76,9 +76,9 @@ export default defineRules({ }); ``` -**Como funciona:** Filtra arquivos `index.ts` (barrel files), e entao verifica cada arquivo no escopo em busca de uma funcao exportada que corresponda ao padrao de nomenclatura `register*Command`. A regex procura por `export function register` seguido de quaisquer caracteres alfanumericos e `Command`. Arquivos que nao correspondem recebem uma violacao. +**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 padrao, altere a regex para corresponder a convencao de exportacao exigida pelo seu projeto. Por exemplo, para exigir uma exportacao default de um componente React: +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)) { @@ -86,9 +86,9 @@ if (!/export\s+default\s+function\s+\w+/.test(content)) { --- -## Padrao 3: Importacao Banida +## Padrão 3: Importação Banida -**Quando usar:** Impedir o uso de uma biblioteca ou modulo especifico em toda a base de codigo. Casos de uso comuns incluem banir bibliotecas pesadas como `lodash` ou `moment` em favor de alternativas nativas, ou impedir importacoes de modulos internos que estao sendo descontinuados. +**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"; @@ -131,15 +131,15 @@ export default defineRules({ }); ``` -**Como funciona:** Define uma lista de importacoes banidas com o padrao regex para detecta-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 padrao banido e reporta uma violacao para cada correspondencia. +**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 importacoes banidas, adicione entradas ao array `BANNED_IMPORTS`. O padrao deve corresponder a parte `from "..."` da instrucao de importacao. +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. --- -## Padrao 4: Convencao de Nomenclatura de Arquivos +## Padrão 4: Convenção de Nomenclatura de Arquivos -**Quando usar:** Impor nomenclatura consistente de arquivos em um diretorio, como exigir kebab-case para todos os arquivos fonte. +**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"; @@ -170,9 +170,9 @@ export default defineRules({ }); ``` -**Como funciona:** Extrai o basename de cada arquivo no escopo e o testa contra uma regex de kebab-case. A regex exige letras minusculas e digitos separados por hifens, com uma extensao de arquivo valida. Arquivos de teste e declaracoes de tipo sao excluidos. A sugestao de correcao converte automaticamente camelCase para kebab-case. +**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 convencao de nomenclatura, substitua a regex. Por exemplo, para camelCase: +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)$/; @@ -180,9 +180,9 @@ const CAMEL_CASE = /^[a-z][a-zA-Z0-9]*\.(ts|tsx|js|jsx)$/; --- -## Padrao 5: Sem Comentarios TODO em Producao +## Padrão 5: Sem Comentários TODO em Produção -**Quando usar:** Sinalizar comentarios TODO, FIXME, HACK e XXX para que sejam resolvidos antes do merge. Usa severidade `warning` para nao bloquear o CI, mas torna os comentarios visiveis na saida da verificacao. +**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"; @@ -208,15 +208,15 @@ export default defineRules({ }); ``` -**Como funciona:** Usa `ctx.grepFiles` para escanear todos os arquivos TypeScript em `src/` em busca de comentarios que comecem com `TODO:`, `FIXME:`, `HACK:` ou `XXX:` (sem distincao de maiusculas/minusculas). Cada correspondencia e reportada como um aviso com o texto original do comentario. Como a severidade e `"warning"`, a verificacao termina com codigo 0 mesmo quando correspondencias sao encontradas -- ela exibe os comentarios sem bloquear merges. +**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()`. --- -## Padrao 6: Cobertura de Arquivos de Teste +## Padrão 6: Cobertura de Arquivos de Teste -**Quando usar:** Garantir que todo arquivo fonte tenha um arquivo de teste correspondente, impedindo que codigo sem testes seja mergeado. +**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"; @@ -246,9 +246,9 @@ export default defineRules({ }); ``` -**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 nao exista, reporta um aviso com uma correcao sugerindo o caminho esperado do arquivo de teste. +**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 pressupoe uma estrutura de diretorio de testes que espelha `src/`: +Isso pressupõe uma estrutura de diretório de testes que espelha `src/`: ``` src/ @@ -261,13 +261,13 @@ tests/ paths.test.ts ``` -Para adaptar em projetos que colocam testes ao lado dos arquivos fonte, altere a transformacao do caminho: +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 voce] -Os plugins de editor para [Claude Code](/guides/claude-code-plugin/) e [Cursor](/guides/cursor-integration/) incluem uma skill de Quality Manager que identifica padroes recorrentes na sua base de codigo e propoe novas regras para aplica-los. [Cadastre-se para acesso beta](https://plugins.archgate.dev). +:::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 index 9bbdb11e..5ae9f58d 100644 --- a/docs/src/content/docs/pt-br/getting-started/installation.mdx +++ b/docs/src/content/docs/pt-br/getting-started/installation.mdx @@ -1,5 +1,5 @@ --- -title: Instalacao +title: Instalação description: Instale a CLI do Archgate no macOS, Linux ou Windows. --- @@ -21,11 +21,11 @@ yarn global add archgate pnpm add -g archgate ``` -Isso instala um wrapper leve que delega para um binario especifico da plataforma. A CLI em si e um binario standalone compilado com Bun — o Node.js e necessario apenas para o wrapper do npm/yarn/pnpm. +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 dependencia de desenvolvimento +## Instalar como dependência de desenvolvimento -Voce tambem pode adicionar o Archgate como dependencia de desenvolvimento no seu projeto e executa-lo atraves do script runner do seu gerenciador de pacotes. Isso e util para fixar uma versao especifica por projeto ou executar verificacoes no CI sem uma instalacao global. +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 @@ -71,7 +71,7 @@ pnpm check:adrs ## Suporte a plataformas -O Archgate disponibiliza binarios pre-compilados para as seguintes plataformas: +O Archgate disponibiliza binários pré-compilados para as seguintes plataformas: | Plataforma | Arquitetura | Pacote | | ---------- | ----------- | ----------------------- | @@ -79,21 +79,21 @@ O Archgate disponibiliza binarios pre-compilados para as seguintes plataformas: | Linux | x86_64 | `archgate-linux-x64` | | Windows | x86_64 | `archgate-win32-x64` | -O binario correto e instalado automaticamente como `optionalDependency` quando voce instala o `archgate`. +O binário correto é instalado automaticamente como `optionalDependency` quando você instala o `archgate`. -## Verificar a instalacao +## Verificar a instalação ```bash archgate --version ``` -Voce devera ver a versao instalada impressa no stdout. +Você deverá ver a versão instalada impressa no stdout. -## Usuarios do Proto toolchain +## Usuários do Proto toolchain -Se voce gerencia o Node.js com o [proto](https://moonrepo.dev/proto) (gerenciador de toolchain do moonrepo), binarios npm instalados globalmente requerem um passo adicional de configuracao. +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 a sua configuracao do proto: +Adicione à sua configuração do proto: ```toml # ~/.proto/config.toml @@ -101,18 +101,18 @@ Adicione a sua configuracao do proto: shared-globals-dir = true ``` -Depois adicione o diretorio de globais ao perfil do seu shell (`.bashrc`, `.zshrc` ou equivalente): +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 devera estar disponivel globalmente. +Reinicie seu shell e execute `npm install -g archgate` novamente. O comando `archgate` agora deverá estar disponível globalmente. -## Proximos passos +## Próximos passos -Apos a instalacao, execute `archgate init` no seu projeto para configurar a governanca. Veja o guia de [Inicio Rapido](/getting-started/quick-start/) para um passo a passo. +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 governanca sobre a CLI. [Cadastre-se para acesso beta](https://plugins.archgate.dev). +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 index ca258337..e76f3936 100644 --- a/docs/src/content/docs/pt-br/getting-started/quick-start.mdx +++ b/docs/src/content/docs/pt-br/getting-started/quick-start.mdx @@ -1,28 +1,28 @@ --- -title: Inicio Rapido +title: Início Rápido description: Comece a usar o Archgate em menos de 5 minutos. --- ## 1. Instalar o Archgate -Se voce ainda nao instalou a CLI, instale-a globalmente via npm: +Se você ainda não instalou a CLI, instale-a globalmente via npm: ```bash npm install -g archgate ``` -Veja a pagina de [Instalacao](/getting-started/installation/) para detalhes de plataforma e solucao de problemas. +Veja a página de [Instalação](/getting-started/installation/) para detalhes de plataforma e solução de problemas. ## 2. Inicializar seu projeto -Navegue ate a raiz do seu projeto e execute o comando `init`: +Navegue até a raiz do seu projeto e execute o comando `init`: ```bash cd my-project archgate init ``` -Isso cria o diretorio `.archgate/` com a seguinte estrutura: +Isso cria o diretório `.archgate/` com a seguinte estrutura: ``` .archgate/ @@ -33,11 +33,11 @@ Isso cria o diretorio `.archgate/` com a seguinte estrutura: archgate.config.ts # Archgate configuration ``` -Os arquivos gerados fornecem um exemplo funcional para voce construir a partir dele. +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 comeca com um frontmatter YAML que define sua identidade: +Abra `.archgate/adrs/ARCH-001-example.md`. Todo ADR começa com um frontmatter YAML que define sua identidade: ```yaml --- @@ -49,17 +49,17 @@ files: ["src/**/*.ts"] --- ``` -- **id** — Identificador unico. A convencao e `ARCH-NNN`, mas qualquer string funciona. -- **title** — Nome legivel para a decisao. +- **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 verificacoes automatizadas. -- **files** — Padroes glob opcionais que definem o escopo de quais arquivos as regras se aplicam. +- **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 decisao em markdown. O Archgate nao impoe uma estrutura especifica de secoes, mas as secoes recomendadas sao: Context, Decision, Do's and Don'ts, Consequences, Compliance e References. +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 sao escritas em TypeScript usando a funcao `defineRules`: +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"; @@ -84,29 +84,29 @@ export default defineRules({ }); ``` -Cada regra possui uma chave unica, uma descricao e uma funcao assincrona `check`. Dentro de `check`, voce tem acesso a: +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 padroes glob do campo `files` do ADR. -- **`ctx.grep(file, pattern)`** — Pesquisa um arquivo por correspondencias de regex, retornando caminhos de arquivos e numeros de linha. -- **`ctx.report.violation()`** — Reporta uma violacao com mensagem, caminho do arquivo, numero da linha e sugestao opcional de correcao. +- **`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 verificacoes +## 5. Executar verificações -Execute o verificador de conformidade contra sua base de codigo: +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 codigo de saida indica o resultado: +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: -| Codigo de saida | Significado | +| Código de saída | Significado | | --------------- | ------------------------------------------------------ | -| 0 | Todas as regras passaram. Nenhuma violacao encontrada. | -| 1 | Uma ou mais violacoes detectadas. | +| 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 (util em pre-commit hooks ou CI): +Para verificar apenas arquivos staged (útil em pre-commit hooks ou CI): ```bash archgate check --staged @@ -114,26 +114,26 @@ archgate check --staged ## E agora? -Agora que voce tem uma configuracao funcionando, aprofunde-se: +Agora que você tem uma configuração funcionando, aprofunde-se: **Entenda os conceitos:** -- [ADRs](/concepts/adrs/) — O que sao Architecture Decision Records e como o Archgate os utiliza. -- [Regras](/concepts/rules/) — Como arquivos complementares `.rules.ts` transformam decisoes em verificacoes automatizadas. -- [Dominios](/concepts/domains/) — Como dominios agrupam ADRs relacionados e definem o escopo de correspondencia de arquivos. +- [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 praticas para escrever decisoes eficazes. -- [Escrevendo Regras](/guides/writing-rules/) — Explore a API de regras, padroes avancados e como testar suas regras. -- [Padroes Comuns de Regras](/examples/common-rule-patterns/) — Padroes prontos para copiar e colar para verificacoes de dependencias, convencoes de nomenclatura e mais. +- [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:** -- [Integracao com CI](/guides/ci-integration/) — Conecte `archgate check` ao GitHub Actions, GitLab CI ou qualquer pipeline. -- [Pre-commit Hooks](/guides/pre-commit-hooks/) — Execute verificacoes localmente antes de cada commit. -- [Plugin Claude Code](/guides/claude-code-plugin/) — De aos agentes de IA um fluxo completo de governanca com habilidades baseadas em papeis. -- [Integracao com Cursor](/guides/cursor-integration/) — Use o Archgate com o Cursor IDE para desenvolvimento assistido por IA. +- [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 index 35b07a8a..f2b54d72 100644 --- a/docs/src/content/docs/pt-br/guides/ci-integration.mdx +++ b/docs/src/content/docs/pt-br/guides/ci-integration.mdx @@ -1,13 +1,13 @@ --- -title: Integracao com CI -description: Adicione verificacoes do Archgate ao seu pipeline de CI/CD. +title: Integração com CI +description: Adicione verificações do Archgate ao seu pipeline de CI/CD. --- -As verificacoes do Archgate funcionam em qualquer sistema de CI que respeite codigos de saida. Adicione um unico passo ao seu pipeline e as violacoes bloqueiarao merges automaticamente. +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 configuracao mais simples e um job dedicado que instala o Archgate e executa `archgate check`: +A configuração mais simples é um job dedicado que instala o Archgate e executa `archgate check`: ```yaml name: ADR Compliance @@ -22,27 +22,27 @@ jobs: - run: archgate check ``` -Isso instala o CLI globalmente e executa todas as regras de ADR. Se qualquer regra reportar uma violacao com severidade `error`, o passo termina com codigo 1 e o job falha. +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. -## Anotacoes do GitHub Actions +## Anotações do GitHub Actions -Use `--ci` para exibir violacoes como anotacoes 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. +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 anotacoes `::error` e `::warning` no formato esperado pelo GitHub Actions. Cada anotacao inclui o ID do ADR, o ID da regra, o caminho do arquivo e o numero da linha. +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. -## Saida legivel por maquina +## Saída legível por máquina -Use `--json` para saida estruturada que outras ferramentas podem processar: +Use `--json` para saída estruturada que outras ferramentas podem processar: ```yaml - run: archgate check --json > results.json ``` -A saida JSON inclui: +A saída JSON inclui: ```json { @@ -77,39 +77,39 @@ A saida JSON inclui: } ``` -## Codigos de saida +## Códigos de saída -| Codigo | Significado | Comportamento no CI | +| Código | Significado | Comportamento no CI | | ------ | ------------------------------ | ------------------- | -| 0 | Todas as verificacoes passaram | Job bem-sucedido | -| 1 | Violacoes encontradas | Job falha | +| 0 | Todas as verificações passaram | Job bem-sucedido | +| 1 | Violações encontradas | Job falha | | 2 | Erro interno | Job falha | -Avisos (severidade `warning`) sao registrados, mas nao afetam o codigo de saida. Apenas violacoes com severidade `error` causam o codigo de saida 1. +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 verificacao aos arquivos staged no git. Isso e util em hooks de pre-commit ou quando voce deseja validar apenas o que esta prestes a ser commitado: +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 especifico +### Verificar um ADR específico -Use `--adr <id>` para executar regras de um unico ADR: +Use `--adr <id>` para executar regras de um único ADR: ```yaml - run: archgate check --adr ARCH-006 ``` -Isso e util quando um PR altera apenas arquivos governados por um ADR e voce deseja feedback mais rapido. +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 voce ja tem uma configuracao de CI, adicione o Archgate como um unico passo apos o checkout: +Se você já tem uma configuração de CI, adicione o Archgate como um único passo após o checkout: ```yaml # Existing pipeline @@ -126,11 +126,11 @@ steps: - run: archgate check --ci ``` -Nenhuma dependencia adicional ou arquivo de configuracao e necessario alem do diretorio `.archgate/` que ja esta no seu repositorio. +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 instalacao +## Cache da instalação -Faca cache do diretorio `~/.archgate` para acelerar instalacoes repetidas: +Faça cache do diretório `~/.archgate` para acelerar instalações repetidas: ```yaml jobs: @@ -161,7 +161,7 @@ adr-compliance: ## CI baseado em Bun -Se seu CI ja usa Bun, instale o Archgate com `bun` ao inves de `npm`: +Se seu CI já usa Bun, instale o Archgate com `bun` ao invés de `npm`: ```yaml jobs: @@ -176,33 +176,33 @@ jobs: ## Outros sistemas de CI -O Archgate funciona com qualquer sistema de CI que consiga executar comandos shell. O padrao e sempre o mesmo: +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 codigo de saida (0 = aprovado, 1 = violacoes, 2 = erro) +3. Verificar o código de saída (0 = aprovado, 1 = violações, 2 = erro) -Para sistemas que suportam anotacoes (Azure DevOps, Buildkite, etc.), use `--json` para processar a saida e emitir anotacoes no formato esperado pelo seu CI. +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 -Voce tambem 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): +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 rapido. +A flag `--staged` garante que apenas os arquivos prestes a serem commitados sejam verificados, mantendo o hook rápido. -## Saida detalhada +## Saída detalhada -Use `--verbose` para ver as regras aprovadas e informacoes de tempo junto com as falhas. Isso e util para debugar verificacoes lentas ou confirmar que as regras estao rodando como esperado: +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 governanca de IA ao seu fluxo de trabalho] -O CI detecta violacoes no momento do merge. Plugins de editor detectam no momento da codificacao. Com o plugin [Claude Code](/guides/claude-code-plugin/) ou [Cursor](/guides/cursor-integration/), seu agente de IA le os ADRs antes de escrever codigo e valida a conformidade antes mesmo de voce commitar. [Inscreva-se para acesso beta](https://plugins.archgate.dev). +:::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 index 8f601302..54b2fd5e 100644 --- a/docs/src/content/docs/pt-br/guides/claude-code-plugin.mdx +++ b/docs/src/content/docs/pt-br/guides/claude-code-plugin.mdx @@ -1,31 +1,31 @@ --- title: Plugin para Claude Code -description: De aos agentes de IA um fluxo de governanca completo com o plugin Archgate 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 governanca estruturado. Em vez de depender de instrucoes em prompts que se deterioram com o tempo, os agentes leem seus ADRs diretamente pelo servidor MCP e validam o proprio codigo contra suas regras. +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 papeis ao Claude Code. Cada skill encapsula uma parte especifica do fluxo de governanca, garantindo que os agentes sigam o mesmo processo todas as vezes -- ler as decisoes antes de codificar, validar depois e capturar novos padroes para a equipe. +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 incluidas +### Skills incluídas -| Skill | Proposito | +| Skill | Propósito | | -------------------------- | ------------------------------------------------------------------------------------------ | -| `archgate:developer` | Agente de desenvolvimento geral que le ADRs antes de codificar e valida depois | -| `archgate:architect` | Valida alteracoes de codigo contra todos os ADRs do projeto para conformidade estrutural | -| `archgate:quality-manager` | Revisa a cobertura de regras e propoe novos ADRs quando padroes emergem | -| `archgate:adr-author` | Cria e edita ADRs seguindo as convencoes do projeto | -| `archgate:onboard` | Configuracao unica: explora o codebase, entrevista o desenvolvedor e cria os ADRs iniciais | +| `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 | -## Instalacao +## Instalação -:::note[Acesso beta necessario] -O plugin para Claude Code esta atualmente em beta. [Cadastre-se em plugins.archgate.dev](https://plugins.archgate.dev) para obter acesso antes de seguir os passos abaixo. +:::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. Faca login com o GitHub +### 1. Faça login com o GitHub Autentique-se com sua conta do GitHub para obter um token do plugin: @@ -33,97 +33,97 @@ Autentique-se com sua conta do GitHub para obter um token do plugin: archgate login ``` -Isso inicia um GitHub Device Flow. O CLI exibe um codigo unico e uma URL -- abra a URL no seu navegador, insira o codigo e autorize. Ao concluir, as credenciais sao armazenadas em `~/.archgate/credentials`. +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 voce ja estiver logado, o plugin e instalado automaticamente: +Execute `archgate init` no seu projeto. Se você já estiver logado, o plugin é instalado automaticamente: ```bash archgate init ``` -Para solicitar explicitamente a instalacao do plugin: +Para solicitar explicitamente a instalação do plugin: ```bash archgate init --install-plugin ``` -Se o CLI `claude` estiver no seu PATH, o plugin e instalado automaticamente via: +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` nao for encontrado, o comando exibe os comandos manuais para voce executar. +Se o CLI `claude` não for encontrado, o comando exibe os comandos manuais para você executar. -## Configuracao inicial com onboard +## Configuração inicial com onboard -Apos a instalacao, execute a skill `archgate:onboard` no seu projeto uma vez. Essa skill: +Após a instalação, execute a skill `archgate:onboard` no seu projeto uma vez. Essa skill: -1. Explora a estrutura do seu codebase (diretorios, arquivos-chave, configuracao de pacotes) -2. Entrevista voce sobre as convencoes, restricoes e decisoes arquiteturais da sua equipe +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 diretorio `.archgate/` com suas primeiras regras +4. Configura o diretório `.archgate/` com suas primeiras regras -A skill de onboard foi projetada para ser executada uma vez por projeto. Apos o onboarding, as outras skills cuidam do desenvolvimento no dia a dia. +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 pratica +## Como funciona na prática -O plugin segue um fluxo estruturado para cada tarefa de codificacao: +O plugin segue um fluxo estruturado para cada tarefa de codificação: -### 1. Ler os ADRs aplicaveis +### 1. Ler os ADRs aplicáveis -Quando o desenvolvedor atribui uma tarefa de codificacao, o agente le todos os ADRs que se aplicam aos arquivos sendo alterados. O servidor MCP fornece um resumo condensado com as secoes **Decision** e **Do's and Don'ts** de cada ADR relevante. +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 nao escreve codigo ate ter lido os ADRs aplicaveis. Isso e garantido pela skill `archgate:developer`. +O agente não escreve código até ter lido os ADRs aplicáveis. Isso é garantido pela skill `archgate:developer`. -### 2. Escrever codigo seguindo as restricoes dos ADRs +### 2. Escrever código seguindo as restrições dos ADRs -O agente escreve codigo que cumpre as restricoes dos ADRs. As secoes Do's and Don'ts servem como guardrails concretos -- o agente as consulta enquanto codifica. +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 alteracoes +### 3. Validar as alterações -Apos escrever o codigo, o agente executa `archgate check` para rodar as regras automatizadas contra as alteracoes. Qualquer violacao e corrigida antes de prosseguir. +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. Revisao do arquiteto +### 4. Revisão do arquiteto -O agente invoca `archgate:architect` para validar a conformidade estrutural com os ADRs alem do que as regras automatizadas capturam. A skill de arquiteto revisa o contexto completo das alteracoes contra todos os ADRs aplicaveis. +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 padroes que valem ser capturados. O quality manager pode propor novos ADRs ou atualizacoes em existentes quando convencoes recorrentes surgem. +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 alcancar o mesmo objetivo mantendo a conformidade. +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 dependencia em um projeto governado pelo ARCH-006 (politica de dependencias), o agente ira: +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 dependencias aprovadas +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 e consistente independentemente de como o desenvolvedor formula a solicitacao. ADRs sao tratados como restricoes obrigatorias, nao sugestoes. +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. -## Integracao com o servidor MCP +## 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: -- **Conteudo de ADRs** -- texto completo de qualquer ADR, acessivel por ID -- **Contexto de revisao** -- resumos condensados de todos os ADRs aplicaveis a um conjunto de arquivos alterados -- **Verificacao de regras** -- execucao de regras automatizadas com relatorio de violacoes -- **Listagem de ADRs** -- inventario de todos os ADRs do projeto com metadados +- **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 le diretamente do seu diretorio `.archgate/adrs/`. Nenhum dado sai da sua maquina. +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 -| Cenario | Skill a usar | +| Cenário | Skill a usar | | ------------------------------------------------------- | -------------------------- | | Iniciando um novo projeto com Archgate | `archgate:onboard` | -| Tarefas de codificacao do dia a dia | `archgate:developer` | +| Tarefas de codificação do dia a dia | `archgate:developer` | | Revisando um PR para conformidade com ADRs | `archgate:architect` | -| Percebendo um padrao recorrente que vale ser codificado | `archgate:quality-manager` | +| 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, voce so precisa interagir diretamente com a skill de developer. +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 index aefa22f1..1225a4a9 100644 --- a/docs/src/content/docs/pt-br/guides/cursor-integration.mdx +++ b/docs/src/content/docs/pt-br/guides/cursor-integration.mdx @@ -1,13 +1,13 @@ --- -title: Integracao com Cursor -description: Use o Archgate com o Cursor IDE para desenvolvimento assistido por IA com governanca. +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 governanca estruturado. O agente le seus ADRs antes de escrever codigo, valida depois e captura novos padroes para a equipe -- o mesmo fluxo disponivel no [plugin para Claude Code](/guides/claude-code-plugin/). +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/). -## Configuracao +## Configuração -Execute `archgate init` com a flag `--editor cursor` para configurar a integracao com o Cursor no seu projeto: +Execute `archgate init` com a flag `--editor cursor` para configurar a integração com o Cursor no seu projeto: ```bash archgate init --editor cursor @@ -15,76 +15,76 @@ archgate init --editor cursor ### Com plugin (beta) -:::note[Acesso beta necessario] -O plugin para Cursor esta atualmente em beta. [Cadastre-se em plugins.archgate.dev](https://plugins.archgate.dev) para obter acesso. +:::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 voce fez login via `archgate login`, o comando init tambem baixa e instala o plugin Archgate para o Cursor. O plugin fornece regras de agente pre-configuradas e skills que dao ao agente de IA do Cursor um fluxo de governanca completo. +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 # configuracao unica +archgate login # configuração única archgate init --editor cursor --install-plugin ``` -O pacote do plugin e baixado de `plugins.archgate.dev` e extraido no diretorio `.cursor/`. Ele inclui regras de agente, definicoes de skills e configuracao MCP. +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 conexao com o servidor MCP e uma regra de governanca basica. O agente de IA pode acessar seus ADRs e executar verificacoes, mas nao recebe as skills baseadas em papeis descritas abaixo. +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 | Proposito | +| Arquivo | Propósito | | --------------------------------------- | --------------------------------------------------------------------------- | -| `.cursor/mcp.json` | Conexao com o servidor MCP para que o agente de IA do Cursor acesse os ADRs | +| `.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` ja existir, o Archgate mescla sua configuracao de forma aditiva -- entradas de servidor MCP existentes sao preservadas. +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 papeis ao Cursor. Cada skill e invocada como um slash command com o prefixo `/ag-`. As skills encapsulam partes especificas do fluxo de governanca para que o agente siga o mesmo processo todas as vezes. +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 incluidas +### Skills incluídas -| Slash command | Skill | Proposito | +| Slash command | Skill | Propósito | | --------------------- | --------------- | ------------------------------------------------------------------------------------------ | -| `/ag-developer` | Developer | Agente de desenvolvimento geral que le ADRs antes de codificar e valida depois | -| `/ag-architect` | Architect | Valida alteracoes de codigo contra todos os ADRs do projeto para conformidade estrutural | -| `/ag-quality-manager` | Quality Manager | Revisa a cobertura de regras e propoe novos ADRs quando padroes emergem | -| `/ag-adr-author` | ADR Author | Cria e edita ADRs seguindo as convencoes do projeto | -| `/ag-onboard` | Onboard | Configuracao unica: explora o codebase, entrevista o desenvolvedor e cria os ADRs iniciais | +| `/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 sao as mesmas skills disponiveis no plugin para Claude Code (`archgate:developer`, `archgate:architect`, etc.), adaptadas para a interface de slash commands do Cursor. +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. -## Configuracao inicial com onboard +## Configuração inicial com onboard -Apos instalar o plugin, execute `/ag-onboard` no seu projeto uma vez. Essa skill: +Após instalar o plugin, execute `/ag-onboard` no seu projeto uma vez. Essa skill: -1. Explora a estrutura do seu codebase (diretorios, arquivos-chave, configuracao de pacotes) -2. Entrevista voce sobre as convencoes, restricoes e decisoes arquiteturais da sua equipe +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 diretorio `.archgate/` com suas primeiras regras +4. Configura o diretório `.archgate/` com suas primeiras regras -A skill de onboard foi projetada para ser executada uma vez por projeto. Apos o onboarding, as outras skills cuidam do desenvolvimento no dia a dia. +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 pratica +## Como funciona na prática ### Com o plugin -A skill `/ag-developer` segue um fluxo estruturado para cada tarefa de codificacao: +A skill `/ag-developer` segue um fluxo estruturado para cada tarefa de codificação: -1. **Ler os ADRs aplicaveis** -- O agente chama `review_context` para ver quais ADRs se aplicam aos arquivos sendo alterados. Ele nao escreve codigo ate ter lido os ADRs aplicaveis. +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 codigo seguindo as restricoes dos ADRs** -- O agente implementa as alteracoes seguindo as secoes Do's and Don'ts dos ADRs aplicaveis. +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 verificacoes de conformidade** -- O agente executa `archgate check` para rodar as regras automatizadas. Qualquer violacao e corrigida antes de prosseguir. +3. **Executar verificações de conformidade** -- O agente executa `archgate check` para rodar as regras automatizadas. Qualquer violação é corrigida antes de prosseguir. -4. **Revisao do arquiteto** -- O agente invoca `/ag-architect` para validar a conformidade estrutural com os ADRs alem do que as regras automatizadas capturam. +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 padroes que valem ser capturados como novos ADRs ou atualizacoes em existentes. +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 @@ -92,37 +92,37 @@ 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 decisao especifica, ler o recurso `adr://` (por exemplo, `adr://ARCH-001`). +2. **Ler ADRs individuais** -- Para contexto completo sobre uma decisão específica, ler o recurso `adr://` (por exemplo, `adr://ARCH-001`). -3. **Escrever codigo** -- Implementar as alteracoes seguindo as restricoes dos ADRs aplicaveis. +3. **Escrever código** -- Implementar as alterações seguindo as restrições dos ADRs aplicáveis. -4. **Executar verificacoes de conformidade** -- Chamar `check` (opcionalmente com `staged: true`) para validar que o codigo esta em conformidade com todas as regras dos ADRs. +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 alcancar o mesmo objetivo mantendo a conformidade. +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 dependencia em um projeto governado por um ADR de politica de dependencias, o agente ira: +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 dependencias aprovadas +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 e consistente independentemente de como o desenvolvedor formula a solicitacao. ADRs sao tratados como restricoes obrigatorias, nao sugestoes. +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 -| Cenario | Slash command | +| Cenário | Slash command | | ------------------------------------------------------- | --------------------- | | Iniciando um novo projeto com Archgate | `/ag-onboard` | -| Tarefas de codificacao do dia a dia | `/ag-developer` | +| Tarefas de codificação do dia a dia | `/ag-developer` | | Revisando um PR para conformidade com ADRs | `/ag-architect` | -| Percebendo um padrao recorrente que vale ser codificado | `/ag-quality-manager` | +| 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, voce so precisa usar `/ag-developer` diretamente. +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. -## Configuracao do servidor MCP +## Configuração do servidor MCP O arquivo `.cursor/mcp.json` gerado registra o servidor MCP do Archgate: @@ -137,31 +137,31 @@ O arquivo `.cursor/mcp.json` gerado registra o servidor MCP do Archgate: } ``` -A regra de governanca em `.cursor/rules/archgate-governance.mdc` usa `alwaysApply: true`, o que significa que o agente do Cursor sempre tem o contexto de governanca disponivel sem ativacao manual. +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: -- **Conteudo de ADRs** -- texto completo de qualquer ADR, acessivel por ID via recursos `adr://` -- **Contexto de revisao** -- resumos condensados de todos os ADRs aplicaveis a um conjunto de arquivos alterados -- **Verificacao de regras** -- execucao de regras automatizadas com relatorio de violacoes -- **Listagem de ADRs** -- inventario de todos os ADRs do projeto com metadados +- **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 le diretamente do seu diretorio `.archgate/adrs/`. Nenhum dado sai da sua maquina. +O servidor MCP roda localmente e lê diretamente do seu diretório `.archgate/adrs/`. Nenhum dado sai da sua máquina. -## Acesso a transcricoes de sessao +## Acesso a transcrições de sessão -A ferramenta MCP `cursor_session_context` le transcricoes de sessao do agente Cursor a partir do disco. Isso permite que as skills acessem o historico da conversa atual, o que e util para recuperar contexto que pode ter sido compactado ou truncado. +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 parametros opcionais: +A ferramenta aceita dois parâmetros opcionais: -- `maxEntries` -- Numero maximo de entradas a retornar (padrao: 200, entradas mais recentes). -- `sessionId` -- Um UUID de sessao especifico para ler. Se omitido, a sessao mais recente e usada. +- `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 codificacao.** Ele orquestra todo o fluxo de leitura-validacao-captura automaticamente. -- **Execute `/ag-onboard` uma vez por projeto.** Ele configura seus ADRs iniciais com base no seu codebase e convencoes reais. -- **Use `/ag-architect` para revisoes de PR.** Ele valida a conformidade estrutural alem do que as regras automatizadas capturam. -- **Use `/ag-quality-manager` apos resolver problemas complexos.** Ele captura aprendizados para que os mesmos erros nao se repitam. -- **Faca commit do diretorio `.cursor/`.** Isso garante que cada membro da equipe receba a mesma configuracao de governanca ao clonar o repositorio. -- **Mantenha os arquivos de regras dos ADRs atualizados.** O agente aplica o que as regras verificam -- se uma regra estiver faltando, a violacao nao sera detectada. +- **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 index 1580a242..98e7f1bf 100644 --- a/docs/src/content/docs/pt-br/guides/mcp-server.mdx +++ b/docs/src/content/docs/pt-br/guides/mcp-server.mdx @@ -1,9 +1,9 @@ --- title: Servidor MCP -description: Use o servidor MCP do Archgate para integracao com agentes de IA. +description: Use o servidor MCP do Archgate para integração com agentes de IA. --- -O servidor MCP do Archgate expoe os ADRs e verificacoes de conformidade do seu projeto para agentes de IA por meio do [Model Context Protocol](https://modelcontextprotocol.io/). Qualquer cliente compativel com MCP -- Claude Code, Cursor ou ferramentas customizadas -- pode se conectar a ele. +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 @@ -13,11 +13,11 @@ O servidor usa transporte stdio. Inicie-o com: archgate mcp ``` -Normalmente voce nao executa esse comando manualmente. Em vez disso, configure sua ferramenta de IA para inicia-lo automaticamente (veja abaixo). +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 nao existir): +Adicione o seguinte ao arquivo `.mcp.json` do seu projeto (crie-o se não existir): ```json { @@ -30,94 +30,94 @@ Adicione o seguinte ao arquivo `.mcp.json` do seu projeto (crie-o se nao existir } ``` -O Claude Code le esse arquivo na inicializacao e se conecta ao servidor MCP do Archgate automaticamente. Voce tambem pode executar `archgate init` (que usa `--editor claude` por padrao) para gerar essa configuracao junto com o diretorio `.archgate/` completo. +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 configuracao de servidor. Consulte o guia de [Integracao com Cursor](/guides/cursor-integration/) para mais detalhes. +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 disponiveis +## Ferramentas MCP disponíveis O servidor registra cinco ferramentas que agentes de IA podem chamar. ### `check` -Executa verificacoes de conformidade com ADRs no codebase. +Executa verificações de conformidade com ADRs no codebase. -| Parametro | Tipo | Descricao | +| Parâmetro | Tipo | Descrição | | --------- | ---------- | ----------------------------------------- | -| `adrId` | `string?` | Verificar apenas um ADR especifico por ID | +| `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 aprovacao/reprovacao, contagem de violacoes e resultados detalhados incluindo caminhos de arquivo e numeros de linha. +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. -| Parametro | Tipo | Descricao | +| Parâmetro | Tipo | Descrição | | --------- | --------- | ------------------------------------------------------------------------------ | -| `domain` | `string?` | Filtrar por dominio (`backend`, `frontend`, `data`, `architecture`, `general`) | +| `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` -Obtem arquivos alterados agrupados por dominio com resumos dos ADRs aplicaveis. Este e o ponto de partida recomendado para um agente iniciando uma tarefa -- ele combina deteccao de alteracoes em arquivos, agrupamento por dominio e sumarizacao de ADRs em uma unica chamada. +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. -| Parametro | Tipo | Descricao | +| Parâmetro | Tipo | Descrição | | ----------- | ---------- | -------------------------------------------------------------------------------------- | -| `staged` | `boolean?` | Quando true, inclui apenas arquivos staged no git. Padrao: todos os arquivos alterados | -| `runChecks` | `boolean?` | Quando true, executa verificacoes de conformidade e inclui os resultados | -| `domain` | `string?` | Filtra os resultados para um unico dominio | +| `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 secoes Decision e Do's/Don'ts de cada ADR aplicavel, mantendo a resposta concisa. +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` -Le a transcricao da sessao atual do Claude Code para o projeto. Retorna entradas filtradas (mensagens do usuario e do assistente) do arquivo JSONL da sessao mais recente. +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. -| Parametro | Tipo | Descricao | +| Parâmetro | Tipo | Descrição | | ------------ | --------- | ---------------------------------------------------------------------------- | -| `maxEntries` | `number?` | Numero maximo de entradas relevantes a retornar (padrao: 200, mais recentes) | +| `maxEntries` | `number?` | Número máximo de entradas relevantes a retornar (padrão: 200, mais recentes) | ### `cursor_session_context` -Le transcricoes de sessao do agente Cursor para o projeto. Retorna entradas filtradas dos arquivos JSONL de agent-transcripts do Cursor. +Lê transcrições de sessão do agente Cursor para o projeto. Retorna entradas filtradas dos arquivos JSONL de agent-transcripts do Cursor. -| Parametro | Tipo | Descricao | +| Parâmetro | Tipo | Descrição | | ------------ | --------- | ---------------------------------------------------------------------------- | -| `maxEntries` | `number?` | Numero maximo de entradas relevantes a retornar (padrao: 200, mais recentes) | -| `sessionId` | `string?` | UUID de sessao especifico para ler. Se omitido, le a sessao mais recente | +| `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 disponiveis +## Recursos MCP disponíveis ### `adr://\{id\}` -Le o conteudo completo de um ADR por ID. Substitua o placeholder `id` pelo identificador do ADR (por exemplo, `adr://ARCH-001`). +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, decisao, do's and don'ts, consequencias, conformidade e secoes de referencias. +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 diretorio sem um diretorio `.archgate/`, todas as ferramentas permanecem disponiveis mas retornam orientacoes instruindo o agente a executar `archgate init` para inicializar a governanca. O servidor nao trava nem se recusa a iniciar -- ele fornece feedback acionavel para que o agente possa configurar o 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 sessao tipica de agente de IA usando o servidor MCP segue este padrao: +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 le os resumos** e identifica quais restricoes arquiteturais se aplicam a sua tarefa. +2. **O agente lê os resumos** e identifica quais restrições arquiteturais se aplicam à sua tarefa. -3. **O agente le um ADR completo** via `adr://ARCH-002` (por exemplo) quando precisa da justificativa completa ou exemplos de implementacao alem do resumo condensado. +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 codigo** seguindo as restricoes dos ADRs aplicaveis. +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 violacoes forem encontradas, a resposta inclui caminhos de arquivo e numeros de linha para que o agente possa corrigi-las. +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** ate que `check` reporte zero violacoes. +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 le ADRs, escreve codigo em conformidade, executa verificacoes, 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). +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 index 4a509951..6ec969be 100644 --- a/docs/src/content/docs/pt-br/guides/pre-commit-hooks.mdx +++ b/docs/src/content/docs/pt-br/guides/pre-commit-hooks.mdx @@ -1,17 +1,17 @@ --- title: Hooks de Pre-commit -description: Execute verificacoes do Archgate automaticamente antes de cada commit. +description: Execute verificações do Archgate automaticamente antes de cada commit. --- -## Visao geral +## Visão geral -O comando `archgate check --staged` verifica apenas os arquivos staged no git em relacao as suas regras de ADR. Como ele ignora arquivos nao-staged e nao-rastreados, ele executa rapido o suficiente para ser usado como hook de pre-commit sem desacelerar seu fluxo de trabalho. +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 verificacao falha, o commit e bloqueado. As violacoes sao impressas em stderr com caminhos de arquivo e numeros de linha para que voce possa localiza-las e corrigi-las imediatamente. +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) e um gerenciador de hooks git rapido e multiplataforma. Adicione o seguinte ao seu `lefthook.yml`: +[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 @@ -29,53 +29,53 @@ lefthook install ## Husky -[Husky](https://typicode.github.io/husky/) e uma ferramenta popular de hooks git para projetos Node.js. Adicione a verificacao ao seu hook de pre-commit: +[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 e executavel: +Certifique-se de que o arquivo do hook é executável: ```bash chmod +x .husky/pre-commit ``` -## O que acontece quando as verificacoes falham +## O que acontece quando as verificações falham -Quando `archgate check --staged` encontra violacoes, ele termina com codigo 1. Isso bloqueia o commit. A saida inclui: +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 violacao foi encontrada -- O numero da linha (quando disponivel) -- Uma descricao do que a regra espera +- 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 violacoes, re-stage os arquivos com `git add` e faca o commit novamente. +Corrija as violações, re-stage os arquivos com `git add` e faça o commit novamente. ## Performance -A flag `--staged` restringe as verificacoes apenas aos arquivos na area de staging do git. Isso significa: +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 tres arquivos staged verificara apenas esses tres arquivos. -- Regras que nao correspondem a nenhum arquivo staged sao ignoradas completamente. -- Verificacoes tipicas de pre-commit completam em menos de um segundo. +- 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 padrao glob `files` de cada ADR, o que e util para CI mas mais lento para uso interativo. +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 uteis +## Flags úteis | Flag | Finalidade | | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------- | -| `--staged` | Verifica apenas arquivos staged no git (obrigatorio para pre-commit) | -| `--verbose` | Mostra regras aprovadas e informacoes de tempo -- util para debugar por que uma verificacao esta lenta ou quais regras estao sendo avaliadas | -| `--json` | Exibe resultados como JSON -- util para encaminhar a outras ferramentas ou scripts de relatorio personalizados | -| `--adr <id>` | Verifica apenas regras de um ADR especifico -- util para isolar uma unica regra durante o debug | -| `--ci` | Exibe anotacoes do GitHub Actions -- use em workflows de CI ao inves de hooks de pre-commit | +| `--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 <id>` | 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 multiplos comandos. Por exemplo, com Lefthook: +Hooks de pre-commit podem executar múltiplos comandos. Por exemplo, com Lefthook: ```yaml # lefthook.yml @@ -89,4 +89,4 @@ pre-commit: run: archgate check --staged ``` -Cada comando executa independentemente. Se qualquer comando terminar com codigo diferente de zero, o commit e bloqueado. +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 index 599da6b7..bcf561ed 100644 --- a/docs/src/content/docs/pt-br/guides/writing-adrs.mdx +++ b/docs/src/content/docs/pt-br/guides/writing-adrs.mdx @@ -1,11 +1,11 @@ --- title: Escrevendo ADRs -description: Um guia completo para escrever Registros de Decisao Arquitetural eficazes. +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 padrao. O comando suporta modos interativo e nao-interativo. +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 @@ -15,15 +15,15 @@ Execute o comando sem argumentos para receber prompts guiados: archgate adr create ``` -Voce sera solicitado a fornecer: +Você será solicitado a fornecer: 1. **Domain** -- um entre `backend`, `frontend`, `data`, `architecture` ou `general` -2. **Title** -- um nome curto e descritivo para a decisao -3. **File patterns** -- globs opcionais separados por virgula que delimitam o escopo da verificacao de regras (ex.: `src/commands/**/*.ts`) +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 dominio (`ARCH-001`, `FE-002`, `BE-003`, etc.) e grava o arquivo em `.archgate/adrs/`. +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 nao-interativo +### Modo não-interativo Passe `--title` e `--domain` para pular os prompts: @@ -31,20 +31,20 @@ Passe `--title` e `--domain` para pular os prompts: archgate adr create --title "API Response Format" --domain backend --files "src/api/**/*.ts" ``` -Flags disponiveis: +Flags disponíveis: -| Flag | Descricao | +| Flag | Descrição | | ----------------- | -------------------------------------------------------------- | -| `--title <title>` | Titulo do ADR (obrigatorio no modo nao-interativo) | -| `--domain <name>` | Dominio: backend, frontend, data, architecture, general | -| `--files <globs>` | Padroes de arquivo separados por virgula para escopo de regras | +| `--title <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 voce cria um ADR sem `--body`, o CLI gera um template com todas as secoes padrao: +Quando você cria um ADR sem `--body`, o CLI gera um template com todas as seções padrão: ```markdown --- @@ -98,17 +98,17 @@ Describe how this decision will be enforced. - ``` -## Orientacoes por secao +## Orientações por seção ### Context -Explique por que essa decisao foi necessaria. Qual problema a motivou? Quais alternativas foram consideradas e por que foram descartadas? +Explique por que essa decisão foi necessária. Qual problema a motivou? Quais alternativas foram consideradas e por que foram descartadas? -Boas secoes de contexto incluem: +Boas seções de contexto incluem: -- O problema ou ponto de dor que motivou a decisao -- Alternativas avaliadas, com uma breve analise de trade-offs -- Quaisquer restricoes que limitaram as opcoes (tamanho da equipe, runtime, compatibilidade) +- 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 @@ -129,9 +129,9 @@ graph opaque. ### Decision -Declare o que foi decidido. Seja especifico e concreto -- esta secao nao deve deixar ambiguidade sobre o que os desenvolvedores devem fazer. +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 restricoes numeradas quando a decisao tem multiplas facetas: +Inclua restrições numeradas quando a decisão tem múltiplas facetas: ```markdown ## Decision @@ -149,7 +149,7 @@ function. ### Do's and Don'ts -Esta e a secao que desenvolvedores e agentes de IA consultam com mais frequencia. Escreva exemplos concretos de padroes corretos e incorretos. Use codigo real sempre que possivel. +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 @@ -169,11 +169,11 @@ Esta e a secao que desenvolvedores e agentes de IA consultam com mais frequencia ### Consequences -Divida as consequencias em tres categorias: +Divida as consequências em três categorias: -- **Positive** -- beneficios que a equipe ganha com esta decisao -- **Negative** -- trade-offs que a equipe aceita (toda decisao tem) -- **Risks** -- o que pode dar errado, e como voce planeja mitigar +- **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 @@ -195,10 +195,10 @@ Divida as consequencias em tres categorias: ### Compliance and Enforcement -Descreva como esta decisao e aplicada. Existem dois mecanismos de aplicacao: +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. **Aplicacao manual** -- o que revisores de codigo devem verificar +2. **Aplicação manual** -- o que revisores de código devem verificar ```markdown ## Compliance and Enforcement @@ -218,7 +218,7 @@ Code reviewers MUST verify: ### References -Vincule ADRs relacionados, documentacao externa ou discussoes relevantes: +Vincule ADRs relacionados, documentação externa ou discussões relevantes: ```markdown ## References @@ -230,7 +230,7 @@ Vincule ADRs relacionados, documentacao externa ou discussoes relevantes: ## Delimitando regras com `files` -O campo `files` no frontmatter e um array de padroes glob. Quando definido, `archgate check` passa apenas os arquivos correspondentes para o `ctx.scopedFiles` da regra. Isso mantem as regras focadas no codigo que elas governam. +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 --- @@ -242,21 +242,21 @@ files: ["src/commands/**/*.ts"] --- ``` -Se `files` for omitido, `ctx.scopedFiles` inclui todos os arquivos do projeto. Isso e apropriado para regras que abrangem todo o projeto, como politicas de dependencias. +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. -Padroes comuns: +Padrões comuns: -| Padrao | Corresponde a | +| Padrão | Corresponde a | | ---------------------- | -------------------------------------------- | | `src/commands/**/*.ts` | Todos os arquivos TypeScript em commands | -| `src/**/*.ts` | Todos os arquivos TypeScript do codigo-fonte | +| `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 voce tiver um arquivo `.rules.ts` complementar com verificacoes automatizadas. O arquivo deve ter o mesmo nome do arquivo markdown do ADR, mas com a extensao `.rules.ts`: +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/ @@ -267,7 +267,7 @@ Defina `rules: true` quando voce tiver um arquivo `.rules.ts` complementar com v GEN-001-code-review-process.md # rules: false (no automated checks) ``` -Defina `rules: false` para decisoes que sao aplicadas apenas por revisao de codigo -- decisoes de processo, acordos de equipe ou diretrizes dificeis de verificar programaticamente. +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 @@ -277,34 +277,34 @@ Use `archgate adr update` para modificar um ADR existente: archgate adr update --id ARCH-001 --body "## Context\n\nUpdated context..." --title "New Title" ``` -As flags `--id` e `--body` sao obrigatorias. Todos os outros campos do frontmatter (`--title`, `--domain`, `--files`, `--rules`) sao opcionais e preservam seus valores existentes quando omitidos. +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 | Descricao | +| Flag | Descrição | | ----------------- | ------------------------------------------------------------ | -| `--id <id>` | ID do ADR a ser atualizado (obrigatorio) | -| `--body <md>` | Corpo markdown de substituicao completa (obrigatorio) | -| `--title <title>` | Novo titulo (preserva o existente se omitido) | -| `--domain <name>` | Novo dominio (preserva o existente se omitido) | -| `--files <globs>` | Novos padroes de arquivo (preserva os existentes se omitido) | +| `--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 unica decisao.** Se voce perceber que esta escrevendo sobre dois assuntos nao relacionados, divida-os em ADRs separados. +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 especifico nos Do's and Don'ts.** Diretrizes vagas como "escreva codigo limpo" nao sao acionaveis. Mostre padroes de codigo concretos. +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 codigo reais.** A secao Do's and Don'ts e onde desenvolvedores e agentes de IA olham primeiro. Exemplos de codigo anotados tornam a decisao inequivoca. +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 voce rejeitou.** Futuros colaboradores perguntarao "por que nao usamos X?" A secao Context deve responder a essa pergunta. +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 decisao tem consequencias negativas. Documenta-las gera confianca e ajuda a equipe a entender o que foi sacrificado. +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 decisoes que podem ser verificadas automaticamente.** Se uma regra consegue detectar uma violacao antes da revisao de codigo, defina `rules: true` e escreva um arquivo `.rules.ts` complementar. Veja o guia [Escrevendo Regras](/pt-br/guides/writing-rules/). +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 dominio para organizar.** O campo domain (`backend`, `frontend`, `data`, `architecture`, `general`) determina o prefixo do ID e ajuda a filtrar ADRs por area. +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 voce] -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 convencoes do seu projeto. A skill Quality Manager tambem propoe novos ADRs quando detecta padroes recorrentes. [Inscreva-se para acesso beta](https://plugins.archgate.dev). +:::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 index 8c4deede..1b3bd773 100644 --- a/docs/src/content/docs/pt-br/guides/writing-rules.mdx +++ b/docs/src/content/docs/pt-br/guides/writing-rules.mdx @@ -1,9 +1,9 @@ --- title: Escrevendo Regras -description: Aprenda a escrever regras automatizadas que aplicam suas decisoes de ADR. +description: Aprenda a escrever regras automatizadas que aplicam suas decisões de ADR. --- -Regras sao funcoes TypeScript que verificam seu codebase quanto a conformidade com ADRs. Elas ficam em arquivos `.rules.ts` complementares ao lado dos arquivos markdown dos ADRs e sao executadas quando voce roda `archgate check`. +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/ @@ -11,9 +11,9 @@ Regras sao funcoes TypeScript que verificam seu codebase quanto a conformidade c ARCH-001-command-structure.rules.ts # The automated checks ``` -## Configuracao basica +## Configuração básica -Todo arquivo de regras exporta uma chamada `defineRules()` por padrao. Cada chave se torna um ID de regra, e cada regra tem uma `description` e uma funcao async `check` que recebe um objeto de contexto. +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"; @@ -28,7 +28,7 @@ export default defineRules({ }); ``` -Um unico arquivo de regras pode definir multiplas regras: +Um único arquivo de regras pode definir múltiplas regras: ```typescript import { defineRules } from "archgate/rules"; @@ -51,11 +51,11 @@ export default defineRules({ ## A API de Contexto -O objeto `ctx` passado para toda funcao `check` fornece capacidades de leitura de arquivos, busca e relatorio. Aqui esta uma referencia detalhada com exemplos. +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 nao tiver o campo `files`, isso inclui todos os arquivos do projeto. +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) { @@ -64,11 +64,11 @@ for (const file of ctx.scopedFiles) { } ``` -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` recebera apenas arquivos de comandos. +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). Util para verificacao incremental -- valide apenas os arquivos que foram efetivamente alterados. +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) => @@ -81,7 +81,7 @@ for (const file of filesToCheck) { ### ctx.readFile(path) -Le o conteudo de um arquivo como string. O caminho e relativo a raiz do projeto. +Lê o conteúdo de um arquivo como string. O caminho é relativo à raiz do projeto. ```typescript const content = await ctx.readFile("src/cli.ts"); @@ -89,7 +89,7 @@ const content = await ctx.readFile("src/cli.ts"); ### ctx.readJSON(path) -Le e faz o parse de um arquivo JSON. Retorna `unknown` -- faca cast para o formato esperado. +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 { @@ -99,7 +99,7 @@ const pkg = (await ctx.readJSON("package.json")) as { ### ctx.grep(file, pattern) -Busca em um unico arquivo com uma expressao regular. Retorna um array de objetos `GrepMatch`, cada um com as propriedades `file`, `line`, `column` e `content`. +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\(/); @@ -114,7 +114,7 @@ for (const match of matches) { ### ctx.grepFiles(pattern, fileGlob) -Busca em multiplos arquivos que correspondem a um padrao glob. Retorna um array plano de objetos `GrepMatch` de todos os arquivos correspondentes. +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"); @@ -129,7 +129,7 @@ for (const match of matches) { ### ctx.glob(pattern) -Encontra arquivos por padrao glob. Retorna um array de caminhos de arquivo relativos a raiz do projeto. +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"); @@ -137,20 +137,20 @@ const testFiles = await ctx.glob("tests/**/*.test.ts"); ### ctx.report -A interface de relatorio com tres metodos de severidade: +A interface de relatório com três métodos de severidade: -- `ctx.report.violation(detail)` -- severidade error (codigo de saida 1, bloqueia CI) -- `ctx.report.warning(detail)` -- severidade warning (registrado, mas nao bloqueia) +- `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 metodo aceita um objeto com: +Cada método aceita um objeto com: -| Campo | Tipo | Obrigatorio | Descricao | +| Campo | Tipo | Obrigatório | Descrição | | --------- | -------- | ----------- | -------------------------------------------- | -| `message` | `string` | Sim | Qual e a violacao | -| `file` | `string` | Nao | Caminho do arquivo com a violacao | -| `line` | `number` | Nao | Numero da linha da violacao | -| `fix` | `string` | Nao | Correcao sugerida (exibida ao desenvolvedor) | +| `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({ @@ -163,13 +163,13 @@ ctx.report.violation({ ### ctx.projectRoot -O caminho absoluto para o diretorio raiz do projeto. Util quando voce precisa construir caminhos absolutos. +O caminho absoluto para o diretório raiz do projeto. Útil quando você precisa construir caminhos absolutos. ## Exemplos completos -### Exemplo 1: Lista de dependencias permitidas +### Exemplo 1: Lista de dependências permitidas -Verifica se todas as dependencias de producao estao em uma lista aprovada. Esta e a regra que o Archgate usa para sua propria politica de dependencias ARCH-006. +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"; @@ -207,9 +207,9 @@ export default defineRules({ }); ``` -### Exemplo 2: Padrao de export obrigatorio +### Exemplo 2: Padrão de export obrigatório -Verifica se todo arquivo de comando exporta uma funcao `register*Command`. Esta e a regra que o Archgate usa para sua propria estrutura de comandos ARCH-001. +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"; @@ -234,9 +234,9 @@ export default defineRules({ }); ``` -### Exemplo 3: Padrao de import proibido +### Exemplo 3: Padrão de import proibido -Impede a importacao de uma biblioteca especifica quando alternativas nativas existem. +Impede a importação de uma biblioteca específica quando alternativas nativas existem. ```typescript import { defineRules } from "archgate/rules"; @@ -262,7 +262,7 @@ export default defineRules({ }); ``` -### Exemplo 4: Convencao de nomenclatura de arquivos +### Exemplo 4: Convenção de nomenclatura de arquivos Aplica nomenclatura kebab-case para arquivos fonte. @@ -289,7 +289,7 @@ export default defineRules({ }); ``` -### Exemplo 5: Tamanho maximo de arquivo +### Exemplo 5: Tamanho máximo de arquivo Emite um aviso quando arquivos excedem um limite de linhas. @@ -319,7 +319,7 @@ export default defineRules({ }); ``` -### Exemplo 6: Cobertura de testes obrigatoria +### Exemplo 6: Cobertura de testes obrigatória Verifica se todo arquivo fonte possui um arquivo de teste correspondente. @@ -351,17 +351,17 @@ export default defineRules({ }); ``` -## Niveis de severidade +## Níveis de severidade -Cada regra pode definir uma severidade padrao em sua configuracao. A severidade determina como as violacoes sao tratadas: +Cada regra pode definir uma severidade padrão em sua configuração. A severidade determina como as violações são tratadas: -| Severidade | Codigo de saida | Comportamento | +| Severidade | Código de saída | Comportamento | | ---------- | --------------- | ------------------------------------------- | | `error` | 1 | Bloqueia CI, deve ser corrigido | -| `warning` | 0 | Registrado, mas nao bloqueia | +| `warning` | 0 | Registrado, mas não bloqueia | | `info` | 0 | Informacional, registrado para visibilidade | -Defina a severidade na definicao da regra: +Defina a severidade na definição da regra: ```typescript export default defineRules({ @@ -376,23 +376,23 @@ export default defineRules({ }); ``` -Se `severity` for omitido, o padrao e `error`. +Se `severity` for omitido, o padrão é `error`. -Voce tambem pode reportar com diferentes severidades dentro da mesma regra usando `ctx.report.violation()`, `ctx.report.warning()` e `ctx.report.info()` diretamente. +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 execucao de 30 segundos. Se uma regra exceder esse limite, ela e tratada como erro. Isso impede que verificacoes descontroladas bloqueiem o pipeline. +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 rapidas: +Mantenha as regras rápidas: -- Usando `ctx.grepFiles()` ao inves de ler cada arquivo manualmente +- 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 numero de arquivos processados +- Delimitando regras com o campo `files` do frontmatter para limitar o número de arquivos processados ## O campo `fix` -O campo `fix` e uma string opcional exibida ao desenvolvedor junto com a mensagem de violacao. Ele descreve qual acao tomar para resolver o problema. Correcoes nao sao aplicadas automaticamente -- sao orientacoes. +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({ @@ -402,7 +402,7 @@ ctx.report.violation({ }); ``` -Quando exibido, o fix aparece abaixo da mensagem de violacao: +Quando exibido, o fix aparece abaixo da mensagem de violação: ``` ARCH-006/no-unapproved-deps @@ -413,7 +413,7 @@ ARCH-006/no-unapproved-deps ## Dicas para escrever regras -1. **Use `Promise.all()` para verificacoes de arquivo em paralelo.** Ao verificar multiplos arquivos independentes, processe-os em paralelo ao inves de sequencialmente. +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 @@ -430,24 +430,24 @@ ARCH-006/no-unapproved-deps } ``` -2. **Use `ctx.changedFiles` para verificacao incremental.** Ao executar `archgate check --staged`, `ctx.changedFiles` contem apenas os arquivos staged no git. Filtre `ctx.scopedFiles` com ele para verificar apenas o que mudou. +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 unica preocupacao.** Uma regra que verifica tanto convencoes de nomenclatura quanto padroes de import deve ser dividida em duas regras com IDs separados. +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 inves de iteracao manual.** Ao buscar um padrao em muitos arquivos, `ctx.grepFiles()` e mais eficiente do que ler cada arquivo e executar uma regex. +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. **Forneca mensagens de `fix` acionaveis.** Um fix como "Nao faca isso" nao e util. Diga ao desenvolvedor exatamente o que fazer. +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 nao-aplicaveis cedo.** Se sua regra se aplica apenas a certos arquivos dentro do escopo, filtre `ctx.scopedFiles` antes de processar: +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 elegancia.** Se sua regra le um arquivo especifico como `package.json`, envolva a leitura em um try/catch e retorne antecipadamente se o arquivo nao existir. +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. -## Proximos passos +## Próximos passos -- [Common Rule Patterns](/examples/common-rule-patterns/) — Padroes prontos para copiar e colar para verificacoes de dependencias, convencoes de nomenclatura, restricoes de import e mais. -- [Rule API Reference](/reference/rule-api/) — Referencia completa de todos os tipos e funcoes da API de regras. -- [Integracao com CI](/pt-br/guides/ci-integration/) — Integre `archgate check` ao seu pipeline para aplicar regras em cada PR. +- [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 index e31eeb72..349d8a06 100644 --- a/docs/src/content/docs/pt-br/index.mdx +++ b/docs/src/content/docs/pt-br/index.mdx @@ -1,6 +1,6 @@ --- title: Archgate -description: Aplique Architecture Decision Records como regras executaveis — para humanos e agentes de IA. +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. @@ -21,9 +21,9 @@ import { Card, CardGrid, LinkCard } from "@astrojs/starlight/components"; O Archgate possui duas camadas que trabalham juntas: -1. **ADRs como documentos** — Arquivos Markdown com frontmatter YAML que descrevem decisoes arquiteturais em linguagem natural. Humanos os leem. Agentes de IA os leem. Todos ficam alinhados. +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 verificacoes automatizadas escritas em TypeScript. Eles sao executados contra sua base de codigo e reportam violacoes com caminhos de arquivos e numeros de linha. +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/ @@ -36,62 +36,62 @@ O Archgate possui duas camadas que trabalham juntas: archgate.config.ts # Archgate configuration ``` -Quando voce executa `archgate check`, a CLI carrega cada ADR que possui `rules: true` em seu frontmatter, executa o arquivo de regras complementar e reporta quaisquer violacoes. Codigo de saida 0 significa que seu codigo esta em conformidade. Codigo de saida 1 significa que nao esta. +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 Executaveis" icon="seti:typescript"> + <Card title="Regras Executáveis" icon="seti:typescript"> Escreva regras em TypeScript. O Archgate as executa contra sua base de - codigo e reporta violacoes com caminhos de arquivos e numeros de linha. As - regras ficam ao lado das decisoes que elas aplicam. + 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="Integracao com CI" icon="seti:pipeline"> - Conecte `archgate check` ao seu pipeline. Codigo de saida 1 bloqueia merges - quando regras sao violadas. Funciona com GitHub Actions, GitLab CI ou - qualquer sistema de CI que respeite codigos de saida. + <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="Governanca com IA" icon="star"> - O servidor MCP da aos agentes de IA acesso em tempo real aos seus ADRs. Eles - leem as decisoes antes de escrever codigo e validam depois. Sem copiar e + <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-Governanca" icon="approve-check-circle"> - O Archgate governa seu proprio desenvolvimento. A mesma ferramenta que - verifica seu codigo verifica o nosso. Seis ADRs aplicam estrutura de - comandos, tratamento de erros, formatacao de saida, testes e mais. + <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 governanca com IA. Os plugins dao aos agentes de IA habilidades baseadas em papeis para que leiam seus ADRs antes de programar, validem depois e capturem novos padroes para sua equipe -- automaticamente. +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-validacao-captura em cada tarefa. + estruturado de leitura-validação-captura em cada tarefa. </Card> <Card title="Cursor" icon="pencil"> - O plugin para Cursor fornece regras e habilidades pre-configuradas para - agentes, dando ao agente de IA do Cursor o mesmo fluxo de governanca do + 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 estao 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`. +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 configuracao e uso do plugin Claude Code." + description="Guia completo de configuração e uso do plugin Claude Code." /> <LinkCard - title="Guia de integracao com Cursor" + title="Guia de integração com Cursor" href="/guides/cursor-integration/" description="Configure o Archgate com o Cursor IDE." /> @@ -101,23 +101,23 @@ Os plugins para editores estao atualmente em beta. Cadastre-se em [plugins.archg <CardGrid> <LinkCard - title="O que sao ADRs?" + 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 decisoes automaticamente." + description="Escreva regras em TypeScript que aplicam suas decisões automaticamente." /> <LinkCard - title="Integracao com CI" + 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="Referencia completa de todos os comandos e opcoes da CLI do Archgate." + 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 index 393b91bb..19b48c60 100644 --- a/docs/src/content/docs/pt-br/reference/adr-schema.mdx +++ b/docs/src/content/docs/pt-br/reference/adr-schema.mdx @@ -3,7 +3,7 @@ title: Esquema de ADR description: Esquema de frontmatter YAML e estrutura markdown para ADRs do Archgate. --- -Todo ADR do Archgate e um arquivo Markdown armazenado em `.archgate/adrs/` com frontmatter YAML que define a identidade e o escopo da decisao. Esta pagina documenta o esquema do frontmatter, a estrutura das secoes markdown e o comportamento de validacao. +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 @@ -21,41 +21,41 @@ files: ["src/commands/**/*.ts"] ### Campos -| Campo | Tipo | Obrigatorio | Descricao | +| Campo | Tipo | Obrigatório | Descrição | | -------- | ---------- | ----------- | -------------------------------------------------------------------------------------- | -| `id` | `string` | Sim | Identificador unico. Nao pode ser vazio. Convencao: `PREFIX-NNN` (ex.: `ARCH-001`). | -| `title` | `string` | Sim | Titulo legivel da decisao. Nao pode ser vazio. | -| `domain` | `enum` | Sim | Categoria de dominio. Um de: `backend`, `frontend`, `data`, `architecture`, `general`. | -| `rules` | `boolean` | Sim | Se este ADR possui um arquivo `.rules.ts` complementar com verificacoes automatizadas. | -| `files` | `string[]` | Nao | Padroes glob que definem o escopo de quais arquivos as regras se aplicam. | +| `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 convencao, usa o prefixo do dominio seguido de um numero de sequencia com preenchimento de zeros (ex.: `ARCH-001`, `BE-003`). O comando `archgate adr create` gera IDs automaticamente. +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 nao vazia e valida, mas seguir a convencao de prefixo mantem os ADRs organizados e ordenaveis. +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 decisao arquitetural. Exibido na saida de `archgate adr list` e usado como cabecalho quando agentes de IA referenciam o ADR. +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 dominio tambem determina o prefixo do ID usado por `archgate adr create`. +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` e executado, ele pula ADRs onde `rules` e `false`. +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 padroes glob que definem o escopo de cobertura de arquivos da regra. Quando presente, `ctx.scopedFiles` no arquivo de regras contem apenas arquivos que correspondem a esses padroes. Quando ausente, todos os arquivos do projeto estao no escopo. +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"] ``` -Multiplos padroes podem ser especificados: +Múltiplos padrões podem ser especificados: ```yaml files: ["src/api/**/*.ts", "src/middleware/**/*.ts"] @@ -63,11 +63,11 @@ files: ["src/api/**/*.ts", "src/middleware/**/*.ts"] --- -## Prefixos de Dominio +## Prefixos de Domínio -Cada dominio mapeia para um prefixo usado na convencao de ID do ADR. +Cada domínio mapeia para um prefixo usado na convenção de ID do ADR. -| Dominio | Prefixo | ID de Exemplo | +| Domínio | Prefixo | ID de Exemplo | | -------------- | ------- | ------------- | | `backend` | `BE` | `BE-001` | | `frontend` | `FE` | `FE-001` | @@ -79,9 +79,9 @@ O comando `archgate adr create` usa esse mapeamento para gerar IDs automaticamen --- -## Convencao de Nomenclatura de Arquivos +## Convenção de Nomenclatura de Arquivos -Os arquivos de ADR seguem uma convencao de nomenclatura que codifica o ID e um slug legivel: +Os arquivos de ADR seguem uma convenção de nomenclatura que codifica o ID e um slug legível: ``` {ID}-{slug}.md # The document @@ -95,17 +95,17 @@ ARCH-001-command-structure.md ARCH-001-command-structure.rules.ts ``` -O slug e uma versao kebab-case do titulo, gerada automaticamente por `archgate adr create`. +O slug é uma versão kebab-case do título, gerada automaticamente por `archgate adr create`. --- -## Secoes Markdown +## Seções Markdown -Apos o frontmatter, o corpo do ADR segue uma estrutura de secoes padrao. Embora o Archgate nao imponha secoes especificas, a estrutura a seguir e recomendada para consistencia. +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 situacao que motivou a decisao. Inclua alternativas que foram consideradas e por que foram rejeitadas. +Descreve o problema ou situação que motivou a decisão. Inclua alternativas que foram consideradas e por que foram rejeitadas. ```markdown ## Context @@ -124,7 +124,7 @@ custom formatting. ### Decision -Declara a decisao em si e suas principais restricoes. Esta e a secao principal que os agentes de IA leem antes de escrever codigo. +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 @@ -135,7 +135,7 @@ output. Commands MUST NOT call `console.error()` directly. ### Do's and Don'ts -Orientacao concreta e acionavel dividida em duas subsecoes. Funciona como um checklist de referencia rapida para desenvolvedores e agentes de IA. +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 @@ -155,7 +155,7 @@ Orientacao concreta e acionavel dividida em duas subsecoes. Funciona como um che ### Consequences -Dividida em tres subsecoes que documentam os tradeoffs. +Dividida em três subseções que documentam os tradeoffs. ```markdown ## Consequences @@ -178,7 +178,7 @@ Dividida em tres subsecoes que documentam os tradeoffs. ### Compliance and Enforcement -Descreve como a decisao e aplicada por meio de regras automatizadas e revisao manual. +Descreve como a decisão é aplicada por meio de regras automatizadas e revisão manual. ```markdown ## Compliance and Enforcement @@ -198,7 +198,7 @@ Code reviewers MUST verify: ### References -Links para ADRs relacionados, documentacao externa ou documentos de design. +Links para ADRs relacionados, documentação externa ou documentos de design. ```markdown ## References @@ -211,14 +211,14 @@ Links para ADRs relacionados, documentacao externa ou documentos de design. ## Arquivo de Regras Complementar -Quando `rules: true`, o Archgate procura um arquivo complementar com o mesmo nome mas extensao `.rules.ts`. +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` padrao criado via `defineRules()`: +O arquivo de regras deve exportar um `RuleSet` padrão criado via `defineRules()`: ```typescript import { defineRules } from "archgate/rules"; @@ -243,26 +243,26 @@ export default defineRules({ }); ``` -Consulte a [API de Regras](/pt-br/reference/rule-api/) para a referencia completa da API TypeScript. +Consulte a [API de Regras](/pt-br/reference/rule-api/) para a referência completa da API TypeScript. --- -## Validacao +## Validação -O frontmatter YAML e validado no momento do parse usando um esquema Zod. Frontmatter invalido causa um erro de parse com uma mensagem descritiva. +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 obrigatorios +### Campos obrigatórios -Se um campo obrigatorio estiver ausente, o ADR falha no parse: +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 invalidos +### Valores de enum inválidos -Se `domain` nao for um dos valores validos: +Se `domain` não for um dos valores válidos: ``` Invalid ADR frontmatter in ARCH-001-example.md: @@ -278,4 +278,4 @@ Invalid ADR frontmatter in ARCH-001-example.md: - rules: Expected boolean, received string ``` -ADRs que falham na validacao sao ignorados por `archgate check` e reportados como erros. +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 index d08d9232..0db6b86a 100644 --- a/docs/src/content/docs/pt-br/reference/cli-commands.mdx +++ b/docs/src/content/docs/pt-br/reference/cli-commands.mdx @@ -1,15 +1,15 @@ --- title: Comandos da CLI -description: Referencia completa de todos os comandos da CLI do Archgate. +description: Referência completa de todos os comandos da CLI do Archgate. --- -## Opcoes globais +## Opções globais -Estas opcoes estao disponiveis em todos os comandos: +Estas opções estão disponíveis em todos os comandos: -| Opcao | Descricao | +| Opção | Descrição | | ----------------- | ---------------------------------- | -| `--version`, `-V` | Exibe a versao do Archgate | +| `--version`, `-V` | Exibe a versão do Archgate | | `--help`, `-h` | Mostra ajuda para qualquer comando | ```bash @@ -27,20 +27,20 @@ Autentique-se com o GitHub para acessar os plugins de editor do Archgate. archgate login ``` -Inicia um GitHub Device Flow (OAuth). A CLI exibe um codigo de uso unico e uma URL. Abra a URL no seu navegador, insira o codigo e autorize o Archgate GitHub OAuth App. Apos a autorizacao, a CLI troca sua identidade do GitHub por um token de plugin do Archgate e armazena ambos em `~/.archgate/credentials`. +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 sao necessarias para instalar plugins de editor via `archgate init --install-plugin`. A CLI em si (check, init, mcp, etc.) funciona sem login. +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 estao atualmente em beta. Cadastre-se em [plugins.archgate.dev](https://plugins.archgate.dev) para obter acesso. +Os plugins de editor estão atualmente em beta. Cadastre-se em [plugins.archgate.dev](https://plugins.archgate.dev) para obter acesso. ::: ### Subcomandos -| Subcomando | Descricao | +| Subcomando | Descrição | | ------------------------ | -------------------------------------- | -| `archgate login` | Autenticar (pula se ja estiver logado) | -| `archgate login status` | Mostrar o status atual de autenticacao | +| `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 | @@ -92,30 +92,30 @@ archgate login refresh ## archgate init -Inicializa a governanca do Archgate no projeto atual. +Inicializa a governança do Archgate no projeto atual. ```bash archgate init [options] ``` -Cria o diretorio `.archgate/` com um ADR de exemplo, arquivo de regras complementar e configuracao do linter. Opcionalmente configura a integracao com o editor para fluxos de trabalho com agentes de IA e instala o plugin de editor do Archgate. +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. -### Opcoes +### Opções -| Opcao | Padrao | Descricao | +| Opção | Padrão | Descrição | | ------------------- | -------- | ------------------------------------------------------------------------ | -| `--editor <editor>` | `claude` | Integracao de editor a configurar (`claude`, `cursor`) | -| `--install-plugin` | auto | Instalar o plugin de editor do Archgate (requer `archgate login` previo) | +| `--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` e passado, a CLI instala o plugin do Archgate para o editor selecionado. Se a flag for omitida, a CLI faz deteccao automatica: instala o plugin quando existem credenciais validas (de um `archgate login` anterior) e pula caso contrario. +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 instalacao do plugin +### Comportamento de instalação do plugin -**Claude Code:** Se a CLI `claude` estiver no seu PATH, o plugin e instalado automaticamente via `claude plugin marketplace add` e `claude plugin install`. Se a CLI `claude` nao for encontrada, o comando exibe os comandos de instalacao manual. +**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 e baixado de `plugins.archgate.dev` e extraido no diretorio `.cursor/`. +**Cursor:** O pacote do plugin é baixado de `plugins.archgate.dev` e extraído no diretório `.cursor/`. -### Saida +### Saída ``` Initialized Archgate governance in /path/to/project @@ -126,7 +126,7 @@ Initialized Archgate governance in /path/to/project Archgate plugin installed for Claude Code. ``` -Quando `--editor cursor` e usado, a saida mostra `.cursor/` em vez de `.claude/`. +Quando `--editor cursor` é usado, a saída mostra `.cursor/` em vez de `.claude/`. ### Estrutura gerada @@ -143,30 +143,30 @@ Quando `--editor cursor` e usado, a saida mostra `.cursor/` em vez de `.claude/` ## archgate check -Executa todas as verificacoes automatizadas de conformidade com ADRs no codebase. +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 violacoes com caminhos de arquivo e numeros de linha. +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. -### Opcoes +### Opções -| Opcao | Descricao | +| Opção | Descrição | | ------------ | ---------------------------------------------------------------------- | -| `--staged` | Verificar apenas arquivos no git stage (util para hooks de pre-commit) | -| `--json` | Saida JSON legivel por maquina | -| `--ci` | Formato de anotacao do GitHub Actions | -| `--adr <id>` | Verificar apenas regras de um ADR especifico | -| `--verbose` | Mostrar regras aprovadas e informacoes de tempo | +| `--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 | -### Codigos de saida +### Códigos de saída -| Codigo | Significado | +| Código | Significado | | ------ | ------------------------------------------------------ | -| 0 | Todas as regras passaram. Nenhuma violacao encontrada. | -| 1 | Uma ou mais violacoes detectadas. | +| 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 @@ -183,27 +183,27 @@ Verificar apenas arquivos no stage antes de commitar: archgate check --staged ``` -Verificar um unico ADR: +Verificar um único ADR: ```bash archgate check --adr ARCH-001 ``` -Obter saida JSON para integracao com CI: +Obter saída JSON para integração com CI: ```bash archgate check --json ``` -Obter anotacoes do GitHub Actions: +Obter anotações do GitHub Actions: ```bash archgate check --ci ``` -### Formato da saida JSON +### Formato da saída JSON -Quando `--json` e usado, a saida e um unico objeto JSON: +Quando `--json` é usado, a saída é um único objeto JSON: ```json { @@ -248,20 +248,20 @@ Cria um novo ADR interativamente ou via flags. archgate adr create [options] ``` -Quando executado sem `--title` e `--domain`, o comando solicita interativamente o dominio, titulo e padroes de arquivo opcionais. Quando ambos `--title` e `--domain` sao fornecidos, ele executa de forma nao interativa. +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 e gerado automaticamente com o prefixo do dominio e o proximo numero de sequencia disponivel (ex.: `ARCH-002`, `BE-001`). +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`). -### Opcoes +### Opções -| Opcao | Descricao | +| Opção | Descrição | | -------------------- | ------------------------------------------------------------------------- | -| `--title <title>` | Titulo do ADR (pula o prompt interativo) | -| `--domain <domain>` | Dominio do ADR (`backend`, `frontend`, `data`, `architecture`, `general`) | -| `--files <patterns>` | Padroes de arquivo, separados por virgula | +| `--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` | Saida como JSON | +| `--json` | Saída como JSON | ### Exemplos @@ -271,7 +271,7 @@ Modo interativo: archgate adr create ``` -Modo nao interativo: +Modo não interativo: ```bash archgate adr create \ @@ -291,12 +291,12 @@ Lista todos os ADRs do projeto. archgate adr list [options] ``` -### Opcoes +### Opções -| Opcao | Descricao | +| Opção | Descrição | | ------------------- | ------------------- | -| `--json` | Saida como JSON | -| `--domain <domain>` | Filtrar por dominio | +| `--json` | Saída como JSON | +| `--domain <domain>` | Filtrar por domínio | ### Exemplos @@ -320,7 +320,7 @@ Listar ADRs como JSON: archgate adr list --json ``` -Filtrar por dominio: +Filtrar por domínio: ```bash archgate adr list --domain backend @@ -330,17 +330,17 @@ archgate adr list --domain backend ## archgate adr show -Exibe um ADR especifico pelo ID. +Exibe um ADR específico pelo ID. ```bash archgate adr show <id> ``` -Imprime o conteudo completo do ADR (frontmatter e corpo) na saida padrao. +Imprime o conteúdo completo do ADR (frontmatter e corpo) na saída padrão. ### Argumentos -| Argumento | Descricao | +| Argumento | Descrição | | --------- | ------------------------------------- | | `<id>` | ID do ADR (ex.: `ARCH-001`, `BE-003`) | @@ -360,19 +360,19 @@ Atualiza um ADR existente pelo ID. archgate adr update --id <id> --body <markdown> [options] ``` -Substitui o corpo do ADR pelo markdown fornecido. Campos do frontmatter (`--title`, `--domain`, `--files`, `--rules`) sao atualizados apenas quando passados explicitamente; caso contrario, os valores existentes sao preservados. +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. -### Opcoes +### Opções -| Opcao | Obrigatorio | Descricao | +| 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>` | Nao | Novo titulo do ADR (preserva o existente se omitido) | -| `--domain <domain>` | Nao | Novo dominio (`backend`, `frontend`, `data`, `architecture`, `general`) | -| `--files <patterns>` | Nao | Novos padroes de arquivo, separados por virgula (preserva existente se omitido) | -| `--rules` | Nao | Define `rules: true` no frontmatter | -| `--json` | Nao | Saida como JSON | +| `--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 @@ -387,19 +387,19 @@ archgate adr update \ ## archgate mcp -Inicia o servidor MCP para integracao com agentes de IA. +Inicia o servidor MCP para integração com agentes de IA. ```bash archgate mcp ``` -Executa um servidor MCP usando transporte stdio. O servidor expoe ferramentas para verificar conformidade com ADRs, listar ADRs e obter contexto de revisao. Consulte a referencia de [Ferramentas MCP](/pt-br/reference/mcp-tools/) para a lista completa de ferramentas e recursos disponiveis. +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 diretorio `.archgate/` e encontrado. Nesse caso, as ferramentas retornam orientacoes direcionando o agente a inicializar a governanca primeiro. +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. -### Configuracao +### Configuração -Adicione a configuracao MCP do seu projeto (`.mcp.json` na raiz do projeto): +Adicione a configuração MCP do seu projeto (`.mcp.json` na raiz do projeto): ```json { @@ -412,19 +412,19 @@ Adicione a configuracao MCP do seu projeto (`.mcp.json` na raiz do projeto): } ``` -Executar `archgate init` cria essa configuracao automaticamente para o seu editor. +Executar `archgate init` cria essa configuração automaticamente para o seu editor. --- ## archgate upgrade -Atualiza o Archgate para a versao mais recente via npm. +Atualiza o Archgate para a versão mais recente via npm. ```bash archgate upgrade ``` -Verifica o registro npm para a versao mais recente publicada. Se uma versao mais nova estiver disponivel, executa `npm install -g archgate@latest` para atualizar. Se ja estiver atualizado, exibe uma mensagem e encerra. +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 @@ -442,13 +442,13 @@ Archgate upgraded to 0.4.0 successfully. ## archgate clean -Remove o diretorio de cache da CLI. +Remove o diretório de cache da CLI. ```bash archgate clean ``` -Remove `~/.archgate/`, que armazena dados em cache como timestamps de verificacao de atualizacao. Seguro para executar a qualquer momento -- o diretorio e recriado automaticamente quando necessario. +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 diff --git a/docs/src/content/docs/pt-br/reference/mcp-tools.mdx b/docs/src/content/docs/pt-br/reference/mcp-tools.mdx index d6f8704b..15a4c24d 100644 --- a/docs/src/content/docs/pt-br/reference/mcp-tools.mdx +++ b/docs/src/content/docs/pt-br/reference/mcp-tools.mdx @@ -1,24 +1,24 @@ --- title: Ferramentas MCP -description: Referencia de todas as ferramentas e recursos MCP expostos pelo servidor Archgate. +description: Referência de todas as ferramentas e recursos MCP expostos pelo servidor Archgate. --- -O servidor MCP do Archgate expoe ferramentas e recursos que agentes de IA utilizam para ler ADRs, validar codigo contra regras e acessar o contexto de revisao. Inicie o servidor com `archgate mcp`. +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 verificacoes de conformidade com ADRs no codebase. +Executa verificações de conformidade com ADRs no codebase. -**Parametros:** +**Parâmetros:** -| Nome | Tipo | Obrigatorio | Descricao | +| Nome | Tipo | Obrigatório | Descrição | | -------- | ------- | ----------- | ----------------------------------------- | -| `adrId` | string | Nao | Verificar apenas um ADR especifico por ID | -| `staged` | boolean | Nao | Verificar apenas arquivos no git stage | +| `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 verificacao: +**Retorna** um objeto JSON com os resultados da verificação: ```json { @@ -53,9 +53,9 @@ Executa verificacoes de conformidade com ADRs no codebase. } ``` -Quando nenhuma regra e encontrada, retorna `{ "pass": true, "total": 0, "results": [], "message": "No rules to check" }`. +Quando nenhuma regra é encontrada, retorna `{ "pass": true, "total": 0, "results": [], "message": "No rules to check" }`. -As violacoes sao limitadas a 20 por regra para manter as respostas concisas. Quando uma regra tem mais violacoes do que o limite, `totalViolations` reflete a contagem real enquanto `shownViolations` e o array `violations` incluem apenas as 20 primeiras. O campo `truncated` no nivel superior e definido como `true` quando alguma regra foi limitada. +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. --- @@ -63,11 +63,11 @@ As violacoes sao limitadas a 20 por regra para manter as respostas concisas. Qua Lista todos os ADRs do projeto com seus metadados. -**Parametros:** +**Parâmetros:** -| Nome | Tipo | Obrigatorio | Descricao | +| Nome | Tipo | Obrigatório | Descrição | | -------- | ------ | ----------- | ------------------------------------------------------------------------------ | -| `domain` | string | Nao | Filtrar por dominio (`backend`, `frontend`, `data`, `architecture`, `general`) | +| `domain` | string | Não | Filtrar por domínio (`backend`, `frontend`, `data`, `architecture`, `general`) | **Retorna** um array JSON de objetos ADR: @@ -92,17 +92,17 @@ Lista todos os ADRs do projeto com seus metadados. ### review_context -Obtem arquivos alterados agrupados por dominio com resumos dos ADRs aplicaveis. Esta e a ferramenta principal que os agentes usam antes de escrever codigo -- ela fornece uma visao condensada de todas as decisoes e restricoes de ADR relevantes sem precisar ler cada arquivo de ADR individualmente. +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. -**Parametros:** +**Parâmetros:** -| Nome | Tipo | Obrigatorio | Descricao | +| Nome | Tipo | Obrigatório | Descrição | | ----------- | ------- | ----------- | -------------------------------------------------------------------------------------------- | -| `staged` | boolean | Nao | Quando `true`, inclui apenas arquivos no git stage. Padrao: `false` (todos os alterados). | -| `runChecks` | boolean | Nao | Quando `true`, executa verificacoes de conformidade e inclui os resultados. Padrao: `false`. | -| `domain` | string | Nao | Filtrar por um unico dominio (`backend`, `frontend`, `data`, `architecture`, `general`). | +| `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 dominio: +**Retorna** um objeto JSON com resumos agrupados por domínio: ```json { @@ -129,23 +129,23 @@ Obtem arquivos alterados agrupados por dominio com resumos dos ADRs aplicaveis. } ``` -Cada grupo de dominio inclui os arquivos alterados que correspondem aos seus ADRs, e resumos condensados dos ADRs com apenas as secoes **Decision** e **Do's and Don'ts**. +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` e `true`, `checkSummary` contem os resultados completos da verificacao (mesmo formato da resposta da ferramenta `check`). Quando `false` ou omitido, `checkSummary` e `null`. +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 -Le a transcricao da sessao atual do Claude Code para o projeto. Util para recuperar contexto da sessao que pode ter sido compactado da conversa. +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. -**Parametros:** +**Parâmetros:** -| Nome | Tipo | Obrigatorio | Padrao | Descricao | +| Nome | Tipo | Obrigatório | Padrão | Descrição | | ------------ | ------ | ----------- | ------ | ----------------------------------------------------------------------------------- | -| `maxEntries` | number | Nao | 200 | Numero maximo de entradas relevantes a retornar. Retorna as entradas mais recentes. | +| `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 sessao e transcricao filtrada: +**Retorna** um objeto JSON com metadados da sessão e transcrição filtrada: ```json { @@ -167,22 +167,22 @@ Le a transcricao da sessao atual do Claude Code para o projeto. Util para recupe } ``` -Apenas tipos de mensagem `user` e `assistant` sao incluidos. As previas de conteudo sao truncadas para 500 caracteres para mensagens de usuario e 300 caracteres por bloco de conteudo para mensagens do assistente. +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 -Le as transcricoes de sessao do agente Cursor para o projeto. Funciona da mesma forma que `claude_code_session_context`, mas le do diretorio `agent-transcripts` do Cursor. +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. -**Parametros:** +**Parâmetros:** -| Nome | Tipo | Obrigatorio | Padrao | Descricao | +| Nome | Tipo | Obrigatório | Padrão | Descrição | | ------------ | ------ | ----------- | ------ | ------------------------------------------------------------------------- | -| `maxEntries` | number | Nao | 200 | Numero maximo de entradas relevantes a retornar. | -| `sessionId` | string | Nao | -- | UUID de sessao especifico para ler. Se omitido, le a sessao mais recente. | +| `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 sessao e transcricao filtrada: +**Retorna** um objeto JSON com metadados da sessão e transcrição filtrada: ```json { @@ -203,7 +203,7 @@ Le as transcricoes de sessao do agente Cursor para o projeto. Funciona da mesma } ``` -Se o `sessionId` especificado nao for encontrado, a resposta inclui uma lista de IDs de sessao disponiveis. +Se o `sessionId` especificado não for encontrado, a resposta inclui uma lista de IDs de sessão disponíveis. --- @@ -211,16 +211,16 @@ Se o `sessionId` especificado nao for encontrado, a resposta inclui uma lista de ### adr://\{id\} -Le o conteudo completo de um ADR pelo seu ID. Retorna o markdown completo incluindo frontmatter YAML e corpo. +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\}` e o identificador do ADR (ex.: `ARCH-001`, `BE-003`). +**Formato da URI:** `adr://\{id\}` onde `\{id\}` é o identificador do ADR (ex.: `ARCH-001`, `BE-003`). **Exemplo:** -Solicitar `adr://ARCH-001` retorna o conteudo markdown completo do arquivo ADR ARCH-001 com tipo MIME `text/markdown`. +Solicitar `adr://ARCH-001` retorna o conteúdo markdown completo do arquivo ADR ARCH-001 com tipo MIME `text/markdown`. -Se o ADR solicitado nao for encontrado, o recurso retorna uma mensagem em texto simples: `ADR ARCH-001 not found`. +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 governanca. Seu agente le ADRs, valida conformidade e captura aprendizados sem voce invocar nenhuma ferramenta manualmente. [Cadastre-se para acesso beta](https://plugins.archgate.dev). +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 index 45e1a0ec..18511af9 100644 --- a/docs/src/content/docs/pt-br/reference/rule-api.mdx +++ b/docs/src/content/docs/pt-br/reference/rule-api.mdx @@ -1,9 +1,9 @@ --- title: API de Regras -description: Referencia da API TypeScript para escrever regras do Archgate. +description: Referência da API TypeScript para escrever regras do Archgate. --- -As regras do Archgate sao arquivos TypeScript que exportam verificacoes automatizadas via `defineRules()`. Cada regra recebe um `RuleContext` com utilitarios para buscar arquivos, ler conteudo e reportar violacoes. +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 @@ -21,7 +21,7 @@ export default defineRules({ }); ``` -A funcao `defineRules` recebe um registro de configuracoes de regras indexadas por ID de regra. As chaves se tornam os IDs das regras que aparecem na saida de verificacao e nos relatorios de violacao. A funcao retorna um objeto `RuleSet`. +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; @@ -41,17 +41,17 @@ interface RuleConfig { } ``` -| Campo | Tipo | Obrigatorio | Descricao | +| Campo | Tipo | Obrigatório | Descrição | | ------------- | ------------------------------------- | ----------- | --------------------------------------------------- | -| `description` | `string` | Sim | Descricao legivel exibida na saida de verificacao | -| `severity` | `Severity` | Nao | Severidade padrao para violacoes. Padrao: `"error"` | -| `check` | `(ctx: RuleContext) => Promise<void>` | Sim | Funcao assincrona contendo a logica da regra | +| `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 funcao `check` recebe um objeto `RuleContext` com o estado do projeto e metodos utilitarios. +A função `check` recebe um objeto `RuleContext` com o estado do projeto e métodos utilitários. ```typescript interface RuleContext { @@ -75,7 +75,7 @@ interface RuleContext { projectRoot: string; ``` -Caminho absoluto para o diretorio raiz do projeto (onde `.archgate/` esta localizado). +Caminho absoluto para o diretório raiz do projeto (onde `.archgate/` está localizado). #### scopedFiles @@ -83,7 +83,7 @@ Caminho absoluto para o diretorio raiz do projeto (onde `.archgate/` esta locali scopedFiles: string[]; ``` -Arquivos que correspondem aos padroes glob de `files` do frontmatter do ADR. Se o ADR nao tiver o campo `files`, contem todos os arquivos do projeto. Use esta lista como a lista principal de arquivos para suas verificacoes de regra. +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 @@ -91,7 +91,7 @@ Arquivos que correspondem aos padroes glob de `files` do frontmatter do ADR. Se changedFiles: string[]; ``` -Arquivos que foram modificados de acordo com o git. Quando `--staged` e usado, contem apenas arquivos no stage. Quando executado sem `--staged`, contem todos os arquivos alterados (staged e unstaged). Vazio quando nenhuma alteracao git e detectada. +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 @@ -99,9 +99,9 @@ Arquivos que foram modificados de acordo com o git. Quando `--staged` e usado, c report: RuleReport; ``` -A interface de relatorio para registrar violacoes, avisos e mensagens informativas. Veja [RuleReport](#rulereport) abaixo. +A interface de relatório para registrar violações, avisos e mensagens informativas. Veja [RuleReport](#rulereport) abaixo. -### Metodos +### Métodos #### glob @@ -109,7 +109,7 @@ A interface de relatorio para registrar violacoes, avisos e mensagens informativ glob(pattern: string): Promise<string[]>; ``` -Encontra arquivos correspondentes a um padrao glob relativo a raiz do projeto. Retorna um array de caminhos absolutos de arquivo. +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"); @@ -121,7 +121,7 @@ const testFiles = await ctx.glob("tests/**/*.test.ts"); grep(file: string, pattern: RegExp): Promise<GrepMatch[]>; ``` -Busca em um unico arquivo por linhas correspondentes a uma expressao regular. Retorna um array de objetos `GrepMatch` com caminho do arquivo, numero da linha, coluna e conteudo correspondente. +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\(/); @@ -133,7 +133,7 @@ const matches = await ctx.grep(file, /console\.error\(/); grepFiles(pattern: RegExp, fileGlob: string): Promise<GrepMatch[]>; ``` -Busca em multiplos arquivos correspondentes a um padrao glob por linhas que correspondam a uma expressao regular. Combina `glob` e `grep` em uma unica chamada. +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"); @@ -145,7 +145,7 @@ const matches = await ctx.grepFiles(/TODO:/i, "src/**/*.ts"); readFile(path: string): Promise<string>; ``` -Le o conteudo de um arquivo como string. O caminho e relativo a raiz do projeto. +Lê o conteúdo de um arquivo como string. O caminho é relativo à raiz do projeto. ```typescript const content = await ctx.readFile("src/config.ts"); @@ -157,7 +157,7 @@ const content = await ctx.readFile("src/config.ts"); readJSON(path: string): Promise<unknown>; ``` -Le e faz o parse de um arquivo JSON. O caminho e relativo a raiz do projeto. Retorna o valor parseado como `unknown` -- faca o cast para o tipo esperado na sua regra. +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 { @@ -169,7 +169,7 @@ const pkg = (await ctx.readJSON("package.json")) as { ## RuleReport -A interface de relatorio para registrar resultados de verificacao. Cada metodo aceita um objeto de detalhe descrevendo o problema. +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 { @@ -185,7 +185,7 @@ interface RuleReport { report.violation(detail: ReportDetail): void; ``` -Reporta uma violacao de regra. Violacoes fazem a verificacao falhar com codigo de saida 1. Use para restricoes rigidas que nao devem ser mergeadas. +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 @@ -193,7 +193,7 @@ Reporta uma violacao de regra. Violacoes fazem a verificacao falhar com codigo d report.warning(detail: ReportDetail): void; ``` -Reporta um aviso. Avisos aparecem na saida de verificacao mas nao fazem a verificacao falhar. Use para orientacoes nao bloqueantes. +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 @@ -201,7 +201,7 @@ Reporta um aviso. Avisos aparecem na saida de verificacao mas nao fazem a verifi report.info(detail: ReportDetail): void; ``` -Reporta uma mensagem informativa. Nao afeta o codigo de saida da verificacao. Use para sugestoes ou notas. +Reporta uma mensagem informativa. Não afeta o código de saída da verificação. Use para sugestões ou notas. ### ReportDetail @@ -216,12 +216,12 @@ interface ReportDetail { } ``` -| Campo | Tipo | Obrigatorio | Descricao | +| Campo | Tipo | Obrigatório | Descrição | | --------- | -------- | ----------- | ------------------------------------------------- | -| `message` | `string` | Sim | Descricao legivel do problema | -| `file` | `string` | Nao | Caminho do arquivo onde o problema foi encontrado | -| `line` | `number` | Nao | Numero da linha no arquivo | -| `fix` | `string` | Nao | Sugestao de correcao ou acao de remediacao | +| `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 | --- @@ -238,12 +238,12 @@ interface GrepMatch { } ``` -| Campo | Tipo | Descricao | +| Campo | Tipo | Descrição | | --------- | -------- | -------------------------------------------- | | `file` | `string` | Caminho absoluto do arquivo correspondente | -| `line` | `number` | Numero da linha da correspondencia (base 1) | -| `column` | `number` | Numero da coluna da correspondencia (base 1) | -| `content` | `string` | Conteudo completo da linha 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 | --- @@ -253,17 +253,17 @@ interface GrepMatch { type Severity = "error" | "warning" | "info"; ``` -| Valor | Impacto no codigo de saida | Descricao | +| Valor | Impacto no código de saída | Descrição | | ----------- | -------------------------- | --------------------------------- | -| `"error"` | Causa saida 1 | Restricao rigida, bloqueia merges | -| `"warning"` | Sem impacto | Orientacao nao bloqueante | -| `"info"` | Sem impacto | Informativo, apenas sugestoes | +| `"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 representacao interna de um problema reportado, usada na saida de verificacao e nos resultados JSON. +A representação interna de um problema reportado, usada na saída de verificação e nos resultados JSON. ```typescript interface ViolationDetail { @@ -277,21 +277,21 @@ interface ViolationDetail { } ``` -| Campo | Tipo | Descricao | +| Campo | Tipo | Descrição | | ---------- | ---------- | ------------------------------------------------- | | `ruleId` | `string` | ID da regra da chave de `defineRules` | | `adrId` | `string` | ID do ADR do frontmatter | -| `message` | `string` | Descricao legivel | +| `message` | `string` | Descrição legível | | `file` | `string?` | Caminho do arquivo onde o problema foi encontrado | -| `line` | `number?` | Numero da linha no arquivo | -| `fix` | `string?` | Sugestao de correcao | -| `severity` | `Severity` | Severidade efetiva desta violacao | +| `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`. Voce nao constroi isso diretamente. +O tipo de retorno de `defineRules`. Você não constrói isso diretamente. ```typescript type RuleSet = {