From 47d7cebc36990f94e8d05ee1612480f53704ad19 Mon Sep 17 00:00:00 2001 From: Rhuan Barreto Date: Sun, 24 May 2026 01:40:49 +0200 Subject: [PATCH 1/2] docs: document upgrade --plugins and check diagnostics Add missing documentation for two recent features: - `archgate upgrade --plugins`: Options table, plugin update section explaining the interactive prompt and non-interactive flag - `archgate check` diagnostics: Broad file scope warning (>1000 files or >2s scan), unscoped gitignore opt-out, and all-files-excluded warnings - Writing ADRs guide: Tip about keeping file scope narrow to avoid performance warnings All changes include EN and pt-BR translations. Regenerated llms-full.txt. Signed-off-by: Rhuan Barreto --- docs/public/llms-full.txt | 50 ++++++++++++++++++- docs/src/content/docs/guides/writing-adrs.mdx | 4 ++ .../docs/pt-br/guides/writing-adrs.mdx | 4 ++ .../docs/pt-br/reference/cli/check.mdx | 12 +++++ .../docs/pt-br/reference/cli/upgrade.mdx | 37 +++++++++++++- docs/src/content/docs/reference/cli/check.mdx | 12 +++++ .../content/docs/reference/cli/upgrade.mdx | 37 +++++++++++++- 7 files changed, 153 insertions(+), 3 deletions(-) diff --git a/docs/public/llms-full.txt b/docs/public/llms-full.txt index 742ade51..53328277 100644 --- a/docs/public/llms-full.txt +++ b/docs/public/llms-full.txt @@ -2556,6 +2556,8 @@ files: ["dist/**/*.js"] --- ``` +The CLI warns when an ADR's `files` patterns resolve to more than 1,000 files or the glob scan takes over 2 seconds. Broad patterns like `**/*.ts` may cause slow checks in large projects. Prefer targeting specific directories (e.g., `src/commands/**/*.ts`) over project-wide globs. + Common patterns: | Pattern | Matches | @@ -3635,6 +3637,18 @@ Get GitHub Actions annotations: archgate check --ci ``` +## Diagnostics + +During execution, `archgate check` emits warnings for common misconfigurations that may cause slow or unexpected results: + +| Warning | Condition | Recommendation | +| ------- | --------- | -------------- | +| **Broad file scope** | An ADR's `files` patterns resolve to more than 1,000 files or the glob scan takes over 2 seconds | Narrow the `files` patterns in the ADR frontmatter to target only the relevant source directories | +| **Unscoped gitignore opt-out** | `respectGitignore: false` is set without a `files` scope | Add `files` patterns to avoid scanning all files including `node_modules/`, `.git/`, etc. | +| **All files excluded by gitignore** | Explicit `files` patterns match files, but every match is excluded by `.gitignore` | Set `respectGitignore: false` in the ADR frontmatter to include gitignored files | + +These warnings appear in the standard output and do not affect the exit code. They also appear in JSON output when `--json` is used (as violations with `"severity": "warning"`). + ## JSON output format When `--json` is used, the output is a single JSON object: @@ -4297,6 +4311,12 @@ archgate upgrade Checks GitHub Releases for the latest published version. If a newer version is available, the command auto-detects how Archgate was installed and runs the appropriate upgrade strategy. If already up-to-date, prints a message and exits. +## Options + +| Option | Description | +| ----------- | ------------------------------------------------ | +| `--plugins` | Also update editor plugins after upgrading | + ## Install method detection The upgrade command inspects the running binary path to determine the install method, then delegates to the matching strategy: @@ -4310,7 +4330,29 @@ The upgrade command inspects the running binary path to determine the install me If no specific method is detected, the command falls back to `npm install -g archgate@latest`. -## Example +## Plugin updates + +After a successful upgrade, the CLI offers to update your editor plugins. In an interactive terminal, you get a confirmation prompt: + +``` +Archgate upgraded to 0.35.0 successfully. +? Would you like to update your editor plugins too? (Y/n) +``` + +The CLI auto-detects installed editors (Claude Code, Cursor, VS Code, Copilot CLI, opencode) and runs the plugin install for each selected editor. Plugin update failures are reported but do not affect the exit code -- the CLI upgrade itself is already complete. + +Use `--plugins` to skip the prompt and update all detected editors automatically: + +```bash +archgate upgrade --plugins +``` + +:::note +Plugin updates require authentication. If you are not logged in, the CLI prints a reminder to run `archgate login` first. + +## Examples + +Upgrade the CLI: ```bash archgate upgrade @@ -4322,6 +4364,12 @@ Upgrading 0.34.0 -> 0.35.0... Archgate upgraded to 0.35.0 successfully. ``` +Upgrade and update all editor plugins in one step: + +```bash +archgate upgrade --plugins +``` + --- ## Reference: Configuration diff --git a/docs/src/content/docs/guides/writing-adrs.mdx b/docs/src/content/docs/guides/writing-adrs.mdx index aacd8dc1..0ccfaf5b 100644 --- a/docs/src/content/docs/guides/writing-adrs.mdx +++ b/docs/src/content/docs/guides/writing-adrs.mdx @@ -257,6 +257,10 @@ files: ["dist/**/*.js"] --- ``` +:::tip[Keep file scope narrow] +The CLI warns when an ADR's `files` patterns resolve to more than 1,000 files or the glob scan takes over 2 seconds. Broad patterns like `**/*.ts` may cause slow checks in large projects. Prefer targeting specific directories (e.g., `src/commands/**/*.ts`) over project-wide globs. +::: + Common patterns: | Pattern | Matches | 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 8eb81172..9798d0b8 100644 --- a/docs/src/content/docs/pt-br/guides/writing-adrs.mdx +++ b/docs/src/content/docs/pt-br/guides/writing-adrs.mdx @@ -257,6 +257,10 @@ files: ["dist/**/*.js"] --- ``` +:::tip[Mantenha o escopo de arquivos restrito] +O CLI avisa quando os padrões `files` de um ADR resolvem mais de 1.000 arquivos ou quando a varredura de glob leva mais de 2 segundos. Padrões amplos como `**/*.ts` podem causar verificações lentas em projetos grandes. Prefira direcionar diretórios específicos (ex.: `src/commands/**/*.ts`) em vez de globs que abrangem todo o projeto. +::: + Padrões comuns: | Padrão | Corresponde a | diff --git a/docs/src/content/docs/pt-br/reference/cli/check.mdx b/docs/src/content/docs/pt-br/reference/cli/check.mdx index c31bbc46..e50e1acf 100644 --- a/docs/src/content/docs/pt-br/reference/cli/check.mdx +++ b/docs/src/content/docs/pt-br/reference/cli/check.mdx @@ -79,6 +79,18 @@ Obter anotações do GitHub Actions: archgate check --ci ``` +## Diagnósticos + +Durante a execução, `archgate check` emite avisos para configurações incorretas comuns que podem causar resultados lentos ou inesperados: + +| Aviso | Condição | Recomendação | +| ---------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- | +| **Escopo de arquivos amplo** | Os padrões `files` de um ADR resolvem mais de 1.000 arquivos ou a varredura de glob leva mais de 2 segundos | Estreite os padrões `files` no frontmatter do ADR para atingir apenas os diretórios de código relevantes | +| **Opt-out de gitignore sem escopo** | `respectGitignore: false` está definido sem um escopo `files` | Adicione padrões `files` para evitar a varredura de todos os arquivos incluindo `node_modules/`, `.git/`, etc. | +| **Todos os arquivos excluídos pelo gitignore** | Padrões `files` explícitos correspondem a arquivos, mas todas as correspondências são excluídas pelo `.gitignore` | Defina `respectGitignore: false` no frontmatter do ADR para incluir arquivos ignorados pelo git | + +Esses avisos aparecem na saída padrão e não afetam o código de saída. Eles também aparecem na saída JSON quando `--json` é usado (como violações com `"severity": "warning"`). + ## Formato da saída JSON Quando `--json` é usado, a saída é um único objeto JSON: diff --git a/docs/src/content/docs/pt-br/reference/cli/upgrade.mdx b/docs/src/content/docs/pt-br/reference/cli/upgrade.mdx index 10654edc..2fbf14eb 100644 --- a/docs/src/content/docs/pt-br/reference/cli/upgrade.mdx +++ b/docs/src/content/docs/pt-br/reference/cli/upgrade.mdx @@ -11,6 +11,12 @@ archgate upgrade Verifica o GitHub Releases para a versão mais recente publicada. Se uma versão mais nova estiver disponível, o comando detecta automaticamente como o Archgate foi instalado e executa a estratégia de atualização apropriada. Se já estiver atualizado, exibe uma mensagem e encerra. +## Opções + +| Opção | Descrição | +| ----------- | -------------------------------------------------------------- | +| `--plugins` | Também atualiza os plugins de editor após a atualização do CLI | + ## Detecção do método de instalação O comando de atualização inspeciona o caminho do binário em execução para determinar o método de instalação e delega para a estratégia correspondente: @@ -24,7 +30,30 @@ O comando de atualização inspeciona o caminho do binário em execução para d Se nenhum método específico for detectado, o comando usa `npm install -g archgate@latest` como fallback. -## Exemplo +## Atualização de plugins + +Após uma atualização bem-sucedida, o CLI oferece atualizar os plugins do seu editor. Em um terminal interativo, você recebe um prompt de confirmação: + +``` +Archgate upgraded to 0.35.0 successfully. +? Would you like to update your editor plugins too? (Y/n) +``` + +O CLI detecta automaticamente os editores instalados (Claude Code, Cursor, VS Code, Copilot CLI, opencode) e executa a instalação do plugin para cada editor selecionado. Falhas na atualização de plugins são reportadas, mas não afetam o código de saída -- a atualização do CLI em si já está completa. + +Use `--plugins` para pular o prompt e atualizar todos os editores detectados automaticamente: + +```bash +archgate upgrade --plugins +``` + +:::note +Atualizações de plugins requerem autenticação. Se você não estiver logado, o CLI exibe um lembrete para executar `archgate login` primeiro. +::: + +## Exemplos + +Atualizar o CLI: ```bash archgate upgrade @@ -35,3 +64,9 @@ Checking for latest Archgate release... Upgrading 0.34.0 -> 0.35.0... Archgate upgraded to 0.35.0 successfully. ``` + +Atualizar e instalar todos os plugins de editor em um único passo: + +```bash +archgate upgrade --plugins +``` diff --git a/docs/src/content/docs/reference/cli/check.mdx b/docs/src/content/docs/reference/cli/check.mdx index b3c43b56..47d9b0e9 100644 --- a/docs/src/content/docs/reference/cli/check.mdx +++ b/docs/src/content/docs/reference/cli/check.mdx @@ -79,6 +79,18 @@ Get GitHub Actions annotations: archgate check --ci ``` +## Diagnostics + +During execution, `archgate check` emits warnings for common misconfigurations that may cause slow or unexpected results: + +| Warning | Condition | Recommendation | +| ----------------------------------- | ------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------- | +| **Broad file scope** | An ADR's `files` patterns resolve to more than 1,000 files or the glob scan takes over 2 seconds | Narrow the `files` patterns in the ADR frontmatter to target only the relevant source directories | +| **Unscoped gitignore opt-out** | `respectGitignore: false` is set without a `files` scope | Add `files` patterns to avoid scanning all files including `node_modules/`, `.git/`, etc. | +| **All files excluded by gitignore** | Explicit `files` patterns match files, but every match is excluded by `.gitignore` | Set `respectGitignore: false` in the ADR frontmatter to include gitignored files | + +These warnings appear in the standard output and do not affect the exit code. They also appear in JSON output when `--json` is used (as violations with `"severity": "warning"`). + ## JSON output format When `--json` is used, the output is a single JSON object: diff --git a/docs/src/content/docs/reference/cli/upgrade.mdx b/docs/src/content/docs/reference/cli/upgrade.mdx index 0f77bb88..244a3d46 100644 --- a/docs/src/content/docs/reference/cli/upgrade.mdx +++ b/docs/src/content/docs/reference/cli/upgrade.mdx @@ -11,6 +11,12 @@ archgate upgrade Checks GitHub Releases for the latest published version. If a newer version is available, the command auto-detects how Archgate was installed and runs the appropriate upgrade strategy. If already up-to-date, prints a message and exits. +## Options + +| Option | Description | +| ----------- | ------------------------------------------ | +| `--plugins` | Also update editor plugins after upgrading | + ## Install method detection The upgrade command inspects the running binary path to determine the install method, then delegates to the matching strategy: @@ -24,7 +30,30 @@ The upgrade command inspects the running binary path to determine the install me If no specific method is detected, the command falls back to `npm install -g archgate@latest`. -## Example +## Plugin updates + +After a successful upgrade, the CLI offers to update your editor plugins. In an interactive terminal, you get a confirmation prompt: + +``` +Archgate upgraded to 0.35.0 successfully. +? Would you like to update your editor plugins too? (Y/n) +``` + +The CLI auto-detects installed editors (Claude Code, Cursor, VS Code, Copilot CLI, opencode) and runs the plugin install for each selected editor. Plugin update failures are reported but do not affect the exit code -- the CLI upgrade itself is already complete. + +Use `--plugins` to skip the prompt and update all detected editors automatically: + +```bash +archgate upgrade --plugins +``` + +:::note +Plugin updates require authentication. If you are not logged in, the CLI prints a reminder to run `archgate login` first. +::: + +## Examples + +Upgrade the CLI: ```bash archgate upgrade @@ -35,3 +64,9 @@ Checking for latest Archgate release... Upgrading 0.34.0 -> 0.35.0... Archgate upgraded to 0.35.0 successfully. ``` + +Upgrade and update all editor plugins in one step: + +```bash +archgate upgrade --plugins +``` From b693db3f7b703498a7d266cec66e932b5d3d2942 Mon Sep 17 00:00:00 2001 From: rhuanbarreto <283004+rhuanbarreto@users.noreply.github.com> Date: Sat, 23 May 2026 23:41:32 +0000 Subject: [PATCH 2/2] docs: regenerate llms-full.txt Signed-off-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> --- docs/public/llms-full.txt | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/public/llms-full.txt b/docs/public/llms-full.txt index 53328277..64b3b8cb 100644 --- a/docs/public/llms-full.txt +++ b/docs/public/llms-full.txt @@ -3641,11 +3641,11 @@ archgate check --ci During execution, `archgate check` emits warnings for common misconfigurations that may cause slow or unexpected results: -| Warning | Condition | Recommendation | -| ------- | --------- | -------------- | -| **Broad file scope** | An ADR's `files` patterns resolve to more than 1,000 files or the glob scan takes over 2 seconds | Narrow the `files` patterns in the ADR frontmatter to target only the relevant source directories | -| **Unscoped gitignore opt-out** | `respectGitignore: false` is set without a `files` scope | Add `files` patterns to avoid scanning all files including `node_modules/`, `.git/`, etc. | -| **All files excluded by gitignore** | Explicit `files` patterns match files, but every match is excluded by `.gitignore` | Set `respectGitignore: false` in the ADR frontmatter to include gitignored files | +| Warning | Condition | Recommendation | +| ----------------------------------- | ------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------- | +| **Broad file scope** | An ADR's `files` patterns resolve to more than 1,000 files or the glob scan takes over 2 seconds | Narrow the `files` patterns in the ADR frontmatter to target only the relevant source directories | +| **Unscoped gitignore opt-out** | `respectGitignore: false` is set without a `files` scope | Add `files` patterns to avoid scanning all files including `node_modules/`, `.git/`, etc. | +| **All files excluded by gitignore** | Explicit `files` patterns match files, but every match is excluded by `.gitignore` | Set `respectGitignore: false` in the ADR frontmatter to include gitignored files | These warnings appear in the standard output and do not affect the exit code. They also appear in JSON output when `--json` is used (as violations with `"severity": "warning"`). @@ -4313,9 +4313,9 @@ Checks GitHub Releases for the latest published version. If a newer version is a ## Options -| Option | Description | -| ----------- | ------------------------------------------------ | -| `--plugins` | Also update editor plugins after upgrading | +| Option | Description | +| ----------- | ------------------------------------------ | +| `--plugins` | Also update editor plugins after upgrading | ## Install method detection