diff --git a/.archgate/adrs/ARCH-006-dependency-policy.rules.ts b/.archgate/adrs/ARCH-006-dependency-policy.rules.ts index d310a8fe..5ab22582 100644 --- a/.archgate/adrs/ARCH-006-dependency-policy.rules.ts +++ b/.archgate/adrs/ARCH-006-dependency-policy.rules.ts @@ -16,7 +16,7 @@ export default { try { pkg = await ctx.readJSON("package.json"); } catch { - return; // No package.json — nothing to check + return; // No package.json, nothing to check } const deps = Object.keys(pkg.dependencies ?? {}); diff --git a/.archgate/adrs/ARCH-009-platform-detection-helper.rules.ts b/.archgate/adrs/ARCH-009-platform-detection-helper.rules.ts index 3c070a3b..a72dd27e 100644 --- a/.archgate/adrs/ARCH-009-platform-detection-helper.rules.ts +++ b/.archgate/adrs/ARCH-009-platform-detection-helper.rules.ts @@ -20,7 +20,7 @@ export default { for (const m of fileMatches) { ctx.report.violation({ message: - "Do not access process.platform directly — use isWindows(), isMacOS(), isLinux(), or getPlatformInfo() from src/helpers/platform.ts instead.", + "Do not access process.platform directly. Use isWindows(), isMacOS(), isLinux(), or getPlatformInfo() from src/helpers/platform.ts instead.", file: m.file, line: m.line, fix: 'Import { isWindows } from "../helpers/platform" (or the appropriate helper) and use it instead of process.platform', diff --git a/ASSURANCE-CASE.md b/ASSURANCE-CASE.md index 71060e31..548b58ac 100644 --- a/ASSURANCE-CASE.md +++ b/ASSURANCE-CASE.md @@ -19,8 +19,8 @@ Archgate is a CLI tool that enforces Architecture Decision Records (ADRs) as exe Archgate does **not**: - Modify source code or project files during checks -- Store credentials on disk — authentication tokens are managed by the OS credential manager (macOS Keychain, Windows Credential Manager, Linux secret service) -- Send telemetry or source code to external servers (telemetry is opt-in, anonymized, and contains only usage counts — see [Telemetry docs](https://cli.archgate.dev/reference/telemetry/)) +- Store credentials on disk. Authentication tokens are managed by the OS credential manager (macOS Keychain, Windows Credential Manager, Linux secret service) +- Send telemetry or source code to external servers (telemetry is opt-in, anonymized, and contains only usage counts; see [Telemetry docs](https://cli.archgate.dev/reference/telemetry/)) - Require network access for core functionality (`archgate check` is fully offline) ### 1.2 Threat Categories @@ -83,32 +83,32 @@ Archgate does **not**: └─────────────┘ ``` -**Boundary 1 — Rule Sandbox:** `.rules.ts` files are untrusted code. They execute within a restricted context that blocks dangerous APIs and scopes file access to the project root. +**Boundary 1, Rule Sandbox:** `.rules.ts` files are untrusted code. They execute within a restricted context that blocks dangerous APIs and scopes file access to the project root. -**Boundary 2 — CLI Process:** The CLI itself runs with the user's permissions. It reads project files and manages its own cache directory (`~/.archgate/`). Authentication tokens are delegated to the OS credential manager. It does not require elevated privileges. +**Boundary 2, CLI Process:** The CLI itself runs with the user's permissions. It reads project files and manages its own cache directory (`~/.archgate/`). Authentication tokens are delegated to the OS credential manager. It does not require elevated privileges. -**Boundary 3 — Network:** Network access is only used for binary downloads (install/upgrade), plugin installation (authenticated), and optional anonymized telemetry. No analytics services are contacted. Core functionality (`archgate check`) is fully offline. +**Boundary 3, Network:** Network access is only used for binary downloads (install/upgrade), plugin installation (authenticated), and optional anonymized telemetry. No analytics services are contacted. Core functionality (`archgate check`) is fully offline. ## 3. Secure Design Principles Applied ### 3.1 Least Privilege -- **Rule sandbox is read-only.** The `RuleContext` API exposes `readFile`, `readJSON`, `grep`, `grepFiles`, and `glob` — all read-only operations. Rules cannot write files, spawn processes, or access the network. -- **CI jobs use minimal permissions.** The documented CI configuration requests only `contents: read` — no secrets, deployment keys, or write permissions ([Security guide](https://cli.archgate.dev/guides/security/)). -- **Credentials are delegated to the OS.** Authentication tokens are stored in the operating system's credential manager (macOS Keychain, Windows Credential Manager, Linux secret service) — never written to disk as plain-text files. +- **Rule sandbox is read-only.** The `RuleContext` API exposes `readFile`, `readJSON`, `grep`, `grepFiles`, and `glob`, all read-only operations. Rules cannot write files, spawn processes, or access the network. +- **CI jobs use minimal permissions.** The documented CI configuration requests only `contents: read`, with no secrets, deployment keys, or write permissions ([Security guide](https://cli.archgate.dev/guides/security/)). +- **Credentials are delegated to the OS.** Authentication tokens are stored in the operating system's credential manager (macOS Keychain, Windows Credential Manager, Linux secret service). They are never written to disk as plain-text files. ### 3.2 Defense in Depth Two independent layers protect against malicious rules: -1. **Static analysis security scanner** — Before any `.rules.ts` file is executed, the CLI parses its AST and rejects files containing dangerous patterns: +1. **Static analysis security scanner.** Before any `.rules.ts` file is executed, the CLI parses its AST and rejects files containing dangerous patterns: - Imports of `node:fs`, `child_process`, `net`, `http`, `vm`, and other system modules - Bun-specific APIs: `Bun.spawn()`, `Bun.write()`, `Bun.file()`, `Bun.$` - Network access: `fetch()` - Code generation: `eval()`, `new Function()` - Obfuscation patterns: computed property access (`Bun[variable]`), `globalThis` assignment, dynamic `import()` -2. **Runtime sandbox** — Even if a pattern bypasses the static scanner, the `RuleContext` API enforces path scoping (blocks `../`, absolute paths, and symlinks) and a 30-second timeout per rule. +2. **Runtime sandbox.** Even if a pattern bypasses the static scanner, the `RuleContext` API enforces path scoping (blocks `../`, absolute paths, and symlinks) and a 30-second timeout per rule. ### 3.3 Input Validation @@ -124,7 +124,7 @@ Two independent layers protect against malicious rules: ### 3.5 Minimal Attack Surface -- **Minimal dependencies.** The project follows [ARCH-006 (Dependency Policy)](/.archgate/adrs/ARCH-006-dependency-policy.md): prefer Bun built-ins over third-party packages. All runtime dependencies are bundled into the compiled binary — the npm package has zero runtime `dependencies`. +- **Minimal dependencies.** The project follows [ARCH-006 (Dependency Policy)](/.archgate/adrs/ARCH-006-dependency-policy.md): prefer Bun built-ins over third-party packages. All runtime dependencies are bundled into the compiled binary. The npm package has zero runtime `dependencies`. - **No daemon or server mode.** The CLI runs as a short-lived process. The MCP server uses stdio transport (no network listener). - **No shell execution.** The CLI never spawns shell commands. Git operations use `git ls-files` via Bun's process API with explicit arguments (no shell interpolation). @@ -150,11 +150,11 @@ Two independent layers protect against malicious rules: ### 4.3 Information Disclosure -| Risk | Countermeasure | -| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Credential leakage | Authentication tokens are stored in the OS credential manager (macOS Keychain, Windows Credential Manager, Linux secret service) — never written to disk as plain text. Tokens are never logged. Plugin install passes credentials via authenticated git URLs (not command-line arguments visible in `ps`). | -| Source code exposure | Rules are read-only. `archgate check` output contains only violation messages (file paths and line numbers), not file contents. | -| Error messages | Error output uses `logError()` (ARCH-002) which writes structured messages to stderr. Stack traces are only shown with `--verbose`. | +| Risk | Countermeasure | +| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Credential leakage | Authentication tokens are stored in the OS credential manager (macOS Keychain, Windows Credential Manager, Linux secret service), never written to disk as plain text. Tokens are never logged. Plugin install passes credentials via authenticated git URLs (not command-line arguments visible in `ps`). | +| Source code exposure | Rules are read-only. `archgate check` output contains only violation messages (file paths and line numbers), not file contents. | +| Error messages | Error output uses `logError()` (ARCH-002) which writes structured messages to stderr. Stack traces are only shown with `--verbose`. | ### 4.4 Availability @@ -171,7 +171,7 @@ Two independent layers protect against malicious rules: - **CI pipeline** runs on every pull request: lint (Oxlint), typecheck (tsc --build), format check (Oxfmt), test suite (Bun test), ADR compliance check (`archgate check`), and build verification. - **OpenSSF Scorecard** runs weekly via GitHub Actions, publishing results to the GitHub Security tab. - **GitHub Security Advisories** are enabled for responsible vulnerability disclosure. -- **Pinned dependencies** — all GitHub Actions use commit SHA pins, not mutable tags. +- **Pinned dependencies.** All GitHub Actions use commit SHA pins, not mutable tags. ### 5.2 Manual Verification @@ -181,8 +181,8 @@ Two independent layers protect against malicious rules: ## 6. References -- [SECURITY.md](SECURITY.md) — Vulnerability reporting policy -- [Security Guide](https://cli.archgate.dev/guides/security/) — Full trust model and CI best practices -- [OpenSSF Scorecard](https://securityscorecards.dev/viewer/?uri=github.com/archgate/cli) — Automated security analysis -- [ARCH-006: Dependency Policy](/.archgate/adrs/ARCH-006-dependency-policy.md) — Minimal dependency governance -- [CII Best Practices Badge](https://www.bestpractices.dev/projects/9981) — OpenSSF Best Practices compliance +- [SECURITY.md](SECURITY.md): Vulnerability reporting policy +- [Security Guide](https://cli.archgate.dev/guides/security/): Full trust model and CI best practices +- [OpenSSF Scorecard](https://securityscorecards.dev/viewer/?uri=github.com/archgate/cli): Automated security analysis +- [ARCH-006: Dependency Policy](/.archgate/adrs/ARCH-006-dependency-policy.md): Minimal dependency rules +- [CII Best Practices Badge](https://www.bestpractices.dev/projects/9981): OpenSSF Best Practices compliance diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index c0d9b562..aa84b28f 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -6,7 +6,7 @@ Thank you for your interest in contributing to Archgate CLI! We welcome all kind ## Architecture Decision Records (ADRs) -Archgate dogfoods itself — the CLI is governed by its own ADRs in `.archgate/adrs/`. **Before writing any code, read the ADRs that apply to the area you're changing.** +Archgate dogfoods itself. The CLI is governed by its own ADRs in `.archgate/adrs/`. **Before writing any code, read the ADRs that apply to the area you're changing.** ### Quick reference @@ -29,7 +29,7 @@ bun run src/cli.ts adr list bun run src/cli.ts adr show ARCH-001 ``` -ADR compliance is enforced automatically — `bun run validate` includes an ADR check step that verifies your changes against every rule. **Pull requests that violate an ADR will not pass CI.** +ADR compliance is enforced automatically. `bun run validate` includes an ADR check step that verifies your changes against every rule. **Pull requests that violate an ADR will not pass CI.** ## Quick Start @@ -199,8 +199,8 @@ git rebase --signoff HEAD~N # where N is the number of commits to sign ## Guidelines -- **Read the ADRs first** — all code changes must comply with the project's Architecture Decision Records -- **Sign your commits** — all commits must include a `Signed-off-by` line (see DCO section above) +- **Read the ADRs first**: all code changes must comply with the project's Architecture Decision Records +- **Sign your commits**: all commits must include a `Signed-off-by` line (see DCO section above) - Follow the existing code style and conventions - Write clear, descriptive commit messages using [Conventional Commits](https://www.conventionalcommits.org/) - Add tests for new functionality when applicable diff --git a/README.md b/README.md index d019d1cc..3be2327a 100644 --- a/README.md +++ b/README.md @@ -13,7 +13,7 @@ --- -AI agents write code fast, but they don't know your rules. Archgate turns your team's decisions into executable checks — a lint step for architecture, conventions, and AI output. Your agents read the rules before writing code, and `archgate check` blocks what slips through. In CI, in pre-commit hooks, and inside every major AI coding tool. +AI agents write code fast, but they don't know your rules. Archgate turns your team's decisions into executable checks: a lint step for architecture, conventions, and AI output. Your agents read the rules before writing code, and `archgate check` blocks what slips through. In CI, in pre-commit hooks, and inside every major AI coding tool. **Write an ADR once. Enforce it everywhere.** @@ -21,8 +21,8 @@ AI agents write code fast, but they don't know your rules. Archgate turns your t Archgate has two layers: -1. **ADRs as documents** — markdown files with YAML frontmatter stored in `.archgate/adrs/`. Each ADR records a decision: what was decided, why, and what to do and not do. -2. **ADRs as rules** — each ADR can have a companion `.rules.ts` file that exports automated checks. Archgate runs these checks against your codebase and reports violations. +1. **ADRs as documents**: markdown files with YAML frontmatter stored in `.archgate/adrs/`. Each ADR records a decision: what was decided, why, and what to do and not do. +2. **ADRs as rules**: each ADR can have a companion `.rules.ts` file that exports automated checks. Archgate runs these checks against your codebase and reports violations. ``` .archgate/ @@ -33,7 +33,7 @@ Archgate has two layers: └── ARCH-002-error-handling.rules.ts ``` -When a rule is violated, `archgate check` reports the file, line, and which ADR was broken. Exit code 1 means violations — wire it into CI and it blocks merges automatically. +When a rule is violated, `archgate check` reports the file, line, and which ADR was broken. Exit code 1 means violations. Wire it into CI and it blocks merges automatically. **The CLI is free and open source.** Writing ADRs, enforcing rules, running checks in CI, and wiring up pre-commit hooks all work without an account or subscription. @@ -64,7 +64,7 @@ Each ADR can have a companion `.rules.ts` file that exports automated checks. Se ## Supercharge with AI plugins -> **Make your AI agent architecture-aware.** With the optional editor plugins, your AI coding agent reads ADRs before writing code, validates changes against your rules, and captures new architectural patterns back into ADRs — automatically. +> **Make your AI agent architecture-aware.** With the optional editor plugins, your AI coding agent reads ADRs before writing code, validates changes against your rules, and captures new architectural patterns back into ADRs, automatically. > > Plugins are available for [**Claude Code**](https://cli.archgate.dev/guides/claude-code-plugin/) and [**Cursor**](https://cli.archgate.dev/guides/cursor-integration/). > @@ -73,11 +73,11 @@ Each ADR can have a companion `.rules.ts` file that exports automated checks. Se > archgate init # installs the plugin automatically > ``` > -> **[Get started with plugins](https://cli.archgate.dev/guides/claude-code-plugin/)** — the CLI works fully without them, but plugins close the loop between decisions and code. +> **[Get started with plugins](https://cli.archgate.dev/guides/claude-code-plugin/)**. The CLI works fully without them, but plugins close the loop between decisions and code. ## Documentation -Full documentation is available at **[cli.archgate.dev](https://cli.archgate.dev)** — including guides for writing ADRs, writing rules, CI integration, editor plugin setup, and the complete CLI reference. +Full documentation is available at **[cli.archgate.dev](https://cli.archgate.dev)**, including guides for writing ADRs, writing rules, CI integration, editor plugin setup, and the complete CLI reference. ## Contributing diff --git a/ROADMAP.md b/ROADMAP.md index c3b1c0d7..75fce4f0 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -6,20 +6,20 @@ This document describes what Archgate intends to build, improve, and explicitly ## Vision -Archgate becomes the standard linting and guardrails for AI-assisted development. ADRs are the universal format for expressing architectural decisions, and Archgate enforces them automatically — across AI tools, CI systems, and teams. +Archgate becomes the standard for linting and guardrails in AI-assisted development. ADRs are the universal format for expressing architectural decisions, and Archgate enforces them automatically across AI tools, CI systems, and teams. ## What's Done (Phases 0–2.5) These phases are complete and stable: -- **ADR format & lifecycle** — create, list, show, update ADRs with YAML frontmatter and companion `.rules.ts` files -- **Check engine** — fast, deterministic ADR compliance validation (`archgate check`) with CI annotations, `--staged` support, and JSON output -- **AI integration** — MCP server exposing tools and resources for AI agents to consume ADR context -- **Editor plugins** — Claude Code, VS Code, Cursor, Copilot CLI, and opencode integrations -- **Documentation site** — [cli.archgate.dev](https://cli.archgate.dev) with i18n (English + Brazilian Portuguese) -- **Binary distribution** — macOS ARM, Linux x64, Windows x64 via GitHub Releases with npm thin shim, install script, and proto plugin -- **GitHub Actions** — `archgate/check-action@v1` and `archgate/setup-action@v1` published -- **Self-governance** — the CLI dogfoods 17+ ADRs with executable rules +- **ADR format & lifecycle**: create, list, show, update ADRs with YAML frontmatter and companion `.rules.ts` files +- **Check engine**: fast, deterministic ADR compliance validation (`archgate check`) with CI annotations, `--staged` support, and JSON output +- **AI integration**: MCP server exposing tools and resources for AI agents to consume ADR context +- **Editor plugins**: Claude Code, VS Code, Cursor, Copilot CLI, and opencode integrations +- **Documentation site**: [cli.archgate.dev](https://cli.archgate.dev) with i18n (English + Brazilian Portuguese) +- **Binary distribution**: macOS ARM, Linux x64, Windows x64 via GitHub Releases with npm thin shim, install script, and proto plugin +- **GitHub Actions**: `archgate/check-action@v1` and `archgate/setup-action@v1` published +- **Self-governance**: the CLI dogfoods 17+ ADRs with executable rules ## In Progress: Ecosystem Growth (Phase 3) @@ -40,9 +40,9 @@ These phases are complete and stable: ### Starter ADR Sets -- **TypeScript** — strict tsconfig rules, no `any`, naming conventions -- **Testing** — test file co-location, coverage thresholds, fixture patterns -- **API Design** — REST naming, error response format, OpenAPI requirements +- **TypeScript**: strict tsconfig rules, no `any`, naming conventions +- **Testing**: test file co-location, coverage thresholds, fixture patterns +- **API Design**: REST naming, error response format, OpenAPI requirements ### Documentation & Community @@ -57,7 +57,7 @@ These are explicit non-goals for the foreseeable future: - **Become a linter.** Archgate orchestrates enforcement (including linting) but will not compete with ESLint, Biome, or Oxlint on code style rules. - **Lock into a single AI tool.** The MCP server and ADR format are tool-agnostic. We will not build features that only work with one AI vendor. - **Dictate technology stacks.** Archgate governs how you build, not what you build with. ADRs are stack-agnostic by design. -- **Build a code generation tool.** Archgate governs AI-generated code — it does not generate code itself. +- **Build a code generation tool.** Archgate governs AI-generated code. It does not generate code itself. - **Support pre-1.0 API stability guarantees.** The ADR format and Rule API may have breaking changes before 1.0. We version clearly and document migrations. ## Release Cadence diff --git a/docs/astro.config.mjs b/docs/astro.config.mjs index 08414416..07056e7c 100644 --- a/docs/astro.config.mjs +++ b/docs/astro.config.mjs @@ -25,7 +25,7 @@ export default defineConfig({ // hand-picked colors from archgate.dev take full effect. useStarlightUiThemeColors: false, styleOverrides: { - // ── Frame chrome — matches archgate.dev marketing site ─── + // ── Frame chrome, matches archgate.dev marketing site ─── borderRadius: "0.75rem", borderColor: "#333", borderWidth: "1px", @@ -69,7 +69,7 @@ export default defineConfig({ inlineButtonForeground: "#999", inlineButtonBorder: "#555", - // No shadow — flat design like the website + // No shadow, flat design like the website frameBoxShadowCssValue: "none", // Tooltip @@ -132,7 +132,7 @@ export default defineConfig({ attrs: { property: "og:image:alt", content: - "Archgate — Enterprise-grade linting and guardrails for AI work", + "Archgate: Enterprise-grade linting and guardrails for AI work", }, }, // ── Twitter / X card ────────────────────────────────────── @@ -168,7 +168,7 @@ export default defineConfig({ name: "Archgate CLI Documentation", url: "https://cli.archgate.dev", description: - "Documentation for Archgate — enterprise-grade linting and guardrails for AI work.", + "Documentation for Archgate, enterprise-grade linting and guardrails for AI work.", inLanguage: ["en", "pt-BR", "nb"], }), }, diff --git a/docs/public/llms-full.txt b/docs/public/llms-full.txt index 7585dba4..38f93ebb 100644 --- a/docs/public/llms-full.txt +++ b/docs/public/llms-full.txt @@ -1,6 +1,6 @@ # Archgate CLI -> Archgate is a CLI tool for AI governance via Architecture Decision Records (ADRs). It combines human-readable documentation with machine-checkable TypeScript rules to enforce architectural decisions across codebases — for both humans and AI agents. +> Archgate is a CLI for enterprise-grade linting and guardrails for AI work, built on Architecture Decision Records (ADRs). It combines human-readable documentation with machine-checkable TypeScript rules to enforce architectural decisions across codebases, for both humans and AI agents. Archgate lets teams write an ADR once and enforce it everywhere. ADRs are Markdown files with YAML frontmatter that describe architectural decisions. Companion `.rules.ts` files contain automated TypeScript checks that run against the codebase and report violations with file paths and line numbers. @@ -8,8 +8,8 @@ Archgate lets teams write an ADR once and enforce it everywhere. ADRs are Markdo - **Executable rules**: Write compliance rules in TypeScript. Archgate runs them against your codebase and reports violations with file paths and line numbers. - **CI integration**: Wire `archgate check` into any CI/CD pipeline. Exit code 1 blocks merges when rules are violated. -- **AI-aware governance**: Editor plugins give AI agents (Claude, Cursor, Copilot) live access to ADRs. Agents read decisions before writing code and validate after. -- **Editor plugins**: Claude Code, VS Code, Cursor, and Copilot CLI plugins give AI agents role-based governance skills. +- **AI-aware guardrails**: Editor plugins give AI agents (Claude, Cursor, Copilot) live access to ADRs. Agents read decisions before writing code and validate after. +- **Editor plugins**: Claude Code, VS Code, Cursor, and Copilot CLI plugins give AI agents role-based enforcement skills. - **Self-governance**: Archgate governs its own development using the same tool. ## Installation @@ -18,23 +18,23 @@ Install standalone (no Node.js required): `curl -fsSL https://raw.githubusercont ## Documentation -- [Getting Started — Installation](https://cli.archgate.dev/getting-started/installation/): Install on macOS, Linux, or Windows via npm, Homebrew, or standalone binary. -- [Getting Started — Quick Start](https://cli.archgate.dev/getting-started/quick-start/): Set up Archgate in under 5 minutes with your first ADR and rule. -- [Core Concepts — ADRs](https://cli.archgate.dev/concepts/adrs/): How Architecture Decision Records work as both documentation and executable rules. -- [Core Concepts — Rules](https://cli.archgate.dev/concepts/rules/): The TypeScript rule system that turns ADR decisions into automated compliance checks. -- [Core Concepts — Domains](https://cli.archgate.dev/concepts/domains/): Organize ADRs by domain for targeted governance. -- [Guide — Writing ADRs](https://cli.archgate.dev/guides/writing-adrs/): Complete guide to writing effective ADRs with YAML frontmatter and markdown structure. -- [Guide — Writing Rules](https://cli.archgate.dev/guides/writing-rules/): Write TypeScript rules using the satisfies RuleSet pattern with file matching and violation reporting. -- [Guide — CI Integration](https://cli.archgate.dev/guides/ci-integration/): Add Archgate checks to GitHub Actions, GitLab CI, or any pipeline. -- [Guide — Claude Code Plugin](https://cli.archgate.dev/guides/claude-code-plugin/): Give AI agents a governance workflow that reads ADRs, validates code, and captures patterns. -- [Guide — VS Code Plugin](https://cli.archgate.dev/guides/vscode-plugin/): Real-time ADR compliance in VS Code. -- [Guide — Copilot CLI Plugin](https://cli.archgate.dev/guides/copilot-cli-plugin/): Add architecture governance to GitHub Copilot CLI. -- [Guide — Cursor Integration](https://cli.archgate.dev/guides/cursor-integration/): Configure Cursor IDE with Archgate agent rules and skills. -- [Guide — Pre-commit Hooks](https://cli.archgate.dev/guides/pre-commit-hooks/): Automatically check ADR compliance before every commit. -- [Reference — CLI Commands](https://cli.archgate.dev/reference/cli-commands/): Complete reference for init, check, adr create/list/show, login, and more. -- [Reference — Rule API](https://cli.archgate.dev/reference/rule-api/): TypeScript API reference for RuleSet with satisfies, RuleContext, and violation reporting. -- [Reference — ADR Schema](https://cli.archgate.dev/reference/adr-schema/): YAML frontmatter schema and markdown structure reference for ADRs. -- [Examples — Common Rule Patterns](https://cli.archgate.dev/examples/common-rule-patterns/): Ready-to-use rule patterns for naming conventions, import restrictions, and more. +- [Getting Started: Installation](https://cli.archgate.dev/getting-started/installation/): Install on macOS, Linux, or Windows via npm, Homebrew, or standalone binary. +- [Getting Started: Quick Start](https://cli.archgate.dev/getting-started/quick-start/): Set up Archgate in under 5 minutes with your first ADR and rule. +- [Core Concepts: ADRs](https://cli.archgate.dev/concepts/adrs/): How Architecture Decision Records work as both documentation and executable rules. +- [Core Concepts: Rules](https://cli.archgate.dev/concepts/rules/): The TypeScript rule system that turns ADR decisions into automated compliance checks. +- [Core Concepts: Domains](https://cli.archgate.dev/concepts/domains/): Organize ADRs by domain to scope and enforce rules. +- [Guide: Writing ADRs](https://cli.archgate.dev/guides/writing-adrs/): Complete guide to writing effective ADRs with YAML frontmatter and markdown structure. +- [Guide: Writing Rules](https://cli.archgate.dev/guides/writing-rules/): Write TypeScript rules using the satisfies RuleSet pattern with file matching and violation reporting. +- [Guide: CI Integration](https://cli.archgate.dev/guides/ci-integration/): Add Archgate checks to GitHub Actions, GitLab CI, or any pipeline. +- [Guide: Claude Code Plugin](https://cli.archgate.dev/guides/claude-code-plugin/): Give AI agents a guardrails workflow that reads ADRs, validates code, and captures patterns. +- [Guide: VS Code Plugin](https://cli.archgate.dev/guides/vscode-plugin/): Real-time ADR compliance in VS Code. +- [Guide: Copilot CLI Plugin](https://cli.archgate.dev/guides/copilot-cli-plugin/): Add architecture guardrails to GitHub Copilot CLI. +- [Guide: Cursor Integration](https://cli.archgate.dev/guides/cursor-integration/): Configure Cursor IDE with Archgate agent rules and skills. +- [Guide: Pre-commit Hooks](https://cli.archgate.dev/guides/pre-commit-hooks/): Automatically check ADR compliance before every commit. +- [Reference: CLI Commands](https://cli.archgate.dev/reference/cli-commands/): Complete reference for init, check, adr create/list/show, login, and more. +- [Reference: Rule API](https://cli.archgate.dev/reference/rule-api/): TypeScript API reference for RuleSet with satisfies, RuleContext, and violation reporting. +- [Reference: ADR Schema](https://cli.archgate.dev/reference/adr-schema/): YAML frontmatter schema and markdown structure reference for ADRs. +- [Examples: Common Rule Patterns](https://cli.archgate.dev/examples/common-rule-patterns/): Ready-to-use rule patterns for naming conventions, import restrictions, and more. ## Full documentation @@ -60,9 +60,9 @@ Source: https://cli.archgate.dev/ Archgate has two layers that work together: -1. **ADRs as documents** — Markdown files with YAML frontmatter that describe architectural decisions in plain language. Humans read them. AI agents read them. Everyone stays aligned. +1. **ADRs as documents**: Markdown files with YAML frontmatter that describe architectural decisions in plain language. Humans read them. AI agents read them. Everyone stays aligned. -2. **ADRs as rules** — Companion `.rules.ts` files with automated checks written in TypeScript. They run against your codebase and report violations with file paths and line numbers. +2. **ADRs as rules**: Companion `.rules.ts` files with automated checks written in TypeScript. They run against your codebase and report violations with file paths and line numbers. When you run `archgate check`, the CLI loads every ADR that has `rules: true` in its frontmatter, executes the companion rules file, and reports any violations. Exit code 0 means your code complies. Exit code 1 means it does not. @@ -86,7 +86,7 @@ When you run `archgate check`, the CLI loads every ADR that has `rules: true` in Archgate governs its own development. The same tool that checks your code checks ours. Our own ADRs enforce command structure, error handling, output - formatting, testing, and more — [see them on + formatting, testing, and more. [See them on GitHub](https://github.com/archgate/cli/tree/main/.archgate/adrs). @@ -116,7 +116,7 @@ Source: https://cli.archgate.dev/getting-started/installation/ ## Install standalone (recommended) -The fastest way to install Archgate — no Node.js or package manager required: +The fastest way to install Archgate. No Node.js or package manager required: ```bash # macOS / Linux @@ -160,7 +160,7 @@ yarn global add archgate pnpm add -g archgate ``` -This installs a lightweight wrapper that delegates to a platform-specific binary. The CLI itself is a standalone binary compiled with Bun — Node.js is only needed for the npm/yarn/pnpm wrapper. +This installs a lightweight wrapper that delegates to a platform-specific binary. The CLI itself is a standalone binary compiled with Bun. Node.js is only needed for the npm/yarn/pnpm wrapper. ## Install as a dev dependency @@ -286,7 +286,7 @@ You should see the installed version printed to stdout. ## Install via proto -If you use [proto](https://moonrepo.dev/proto) (moonrepo's toolchain manager), you can install Archgate directly as a proto plugin — no Node.js or npm required. +If you use [proto](https://moonrepo.dev/proto) (moonrepo's toolchain manager), you can install Archgate directly as a proto plugin. No Node.js or npm required. Add the plugin to your `.prototools`: @@ -383,11 +383,11 @@ files: ["src/**/*.ts"] --- ``` -- **id** — Unique identifier. Convention is `ARCH-NNN` but any string works. -- **title** — Human-readable name for the decision. -- **domain** — Groups related ADRs together (`architecture`, `backend`, `frontend`, `data`, or `general`). -- **rules** — Set to `true` if this ADR has a companion `.rules.ts` file with automated checks. -- **files** — Optional glob patterns that scope which files the rules apply to. +- **id**: Unique identifier. Convention is `ARCH-NNN` but any string works. +- **title**: Human-readable name for the decision. +- **domain**: Groups related ADRs together (`architecture`, `backend`, `frontend`, `data`, or `general`). +- **rules**: Set to `true` if this ADR has a companion `.rules.ts` file with automated checks. +- **files**: Optional glob patterns that scope which files the rules apply to. Below the frontmatter, write the decision in markdown. Archgate does not enforce a specific section structure, but the recommended sections are: Context, Decision, Do's and Don'ts, Consequences, Compliance, and References. @@ -422,9 +422,9 @@ export default { Each rule has a unique key, a description, and an async `check` function. Inside `check`, you have access to: -- **`ctx.scopedFiles`** — Files matching the ADR's `files` glob patterns. -- **`ctx.grep(file, pattern)`** — Search a file for regex matches, returning file paths and line numbers. -- **`ctx.report.violation()`** — Report a violation with a message, file path, line number, and optional fix suggestion. +- **`ctx.scopedFiles`**: Files matching the ADR's `files` glob patterns. +- **`ctx.grep(file, pattern)`**: Search a file for regex matches, returning file paths and line numbers. +- **`ctx.report.violation()`**: Report a violation with a message, file path, line number, and optional fix suggestion. ## 5. Run checks @@ -454,22 +454,22 @@ Now that you have a working setup, dive deeper: **Understand the concepts:** -- [ADRs](/concepts/adrs/) — What Architecture Decision Records are and how Archgate uses them. -- [Rules](/concepts/rules/) — How companion `.rules.ts` files turn decisions into automated checks. -- [Domains](/concepts/domains/) — How domains group related ADRs and scope file matching. +- [ADRs](/concepts/adrs/): What Architecture Decision Records are and how Archgate uses them. +- [Rules](/concepts/rules/): How companion `.rules.ts` files turn decisions into automated checks. +- [Domains](/concepts/domains/): How domains group related ADRs and scope file matching. **Write your own:** -- [Writing ADRs](/guides/writing-adrs/) — Learn the full ADR format and best practices for writing effective decisions. -- [Writing Rules](/guides/writing-rules/) — Explore the rule API, advanced patterns, and how to test your rules. -- [Common Rule Patterns](/examples/common-rule-patterns/) — Copy-pasteable patterns for dependency checks, naming conventions, and more. +- [Writing ADRs](/guides/writing-adrs/): Learn the full ADR format and best practices for writing effective decisions. +- [Writing Rules](/guides/writing-rules/): Explore the rule API, advanced patterns, and how to test your rules. +- [Common Rule Patterns](/examples/common-rule-patterns/): Copy-pasteable patterns for dependency checks, naming conventions, and more. **Integrate into your workflow:** -- [CI Integration](/guides/ci-integration/) — Wire `archgate check` into GitHub Actions, GitLab CI, or any pipeline. -- [Pre-commit Hooks](/guides/pre-commit-hooks/) — Run checks locally before every commit. -- [Claude Code Plugin](/guides/claude-code-plugin/) — Give AI agents architecture-aware guardrails with role-based skills. -- [Cursor Integration](/guides/cursor-integration/) — Use Archgate with Cursor IDE for AI-assisted development. +- [CI Integration](/guides/ci-integration/): Wire `archgate check` into GitHub Actions, GitLab CI, or any pipeline. +- [Pre-commit Hooks](/guides/pre-commit-hooks/): Run checks locally before every commit. +- [Claude Code Plugin](/guides/claude-code-plugin/): Give AI agents architecture-aware guardrails with role-based skills. +- [Cursor Integration](/guides/cursor-integration/): Use Archgate with Cursor IDE for AI-assisted development. Want AI agents that automatically read your ADRs before coding? Run `archgate login` to sign up and authenticate, then run `archgate init --install-plugin` to set up the plugin. @@ -756,7 +756,7 @@ When in doubt between `architecture` and a specific domain, prefer the more spec ## Custom Domains -When the built-in five are a genuine mismatch for a category of decisions — for example, `security`, `ml-ops`, or `compliance` — you can register a custom domain via the CLI: +When the built-in five are a genuine mismatch for a category of decisions (for example, `security`, `ml-ops`, or `compliance`), you can register a custom domain via the CLI: ```bash # See what's currently recognised in this project @@ -773,8 +773,8 @@ Custom domain-to-prefix mappings persist in [`.archgate/config.json`](/reference ### Naming rules -- **Name** — lowercase kebab-case, 2–32 characters (e.g., `security`, `ml-ops`, `compliance`). -- **Prefix** — uppercase letters, digits, or underscores, 2–10 characters (e.g., `SEC`, `MLOPS`, `COMP`). +- **Name**: lowercase kebab-case, 2–32 characters (e.g., `security`, `ml-ops`, `compliance`). +- **Prefix**: uppercase letters, digits, or underscores, 2–10 characters (e.g., `SEC`, `MLOPS`, `COMP`). - Custom names and prefixes cannot collide with built-ins or any other custom entry. ### When to prefer a built-in @@ -785,7 +785,7 @@ The built-in five are deliberately opinionated. Before registering a custom doma - A decision about schema versioning usually fits under `data`, even if the motivation is compliance. - A decision that spans multiple technical areas usually fits under `architecture`. -Reach for a custom domain only when none of the built-ins is a genuine fit — for example, when you have a dedicated team or compliance regime that needs its own governance surface. +Reach for a custom domain only when none of the built-ins is a genuine fit: for example, when you have a dedicated team or compliance regime that needs its own governance surface. ### AI agent guidance @@ -946,7 +946,7 @@ When this rule runs against a file containing `import { readFileSync } from "nod ``` 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. + 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" ``` @@ -988,7 +988,7 @@ jobs: - uses: archgate/check-action@v1 ``` -That's it — no Node.js setup, no install step. If any rule reports a violation with `error` severity, the job fails with exit code 1. +That's it. No Node.js setup, no install step. If any rule reports a violation with `error` severity, the job fails with exit code 1. ### Pin a version @@ -1048,7 +1048,7 @@ Use `--ci` to output violations as GitHub Actions workflow annotations. These ap The `--ci` flag produces `::error` and `::warning` annotations in the format GitHub Actions expects. Each annotation includes the ADR ID, rule ID, file path, and line number. :::note -The `archgate/check-action` passes `--ci` automatically — you only need this flag when running `archgate check` manually. +The `archgate/check-action` passes `--ci` automatically. You only need this flag when running `archgate check` manually. ## Machine-readable output @@ -1199,7 +1199,7 @@ jobs: - run: ~/.archgate/bin/archgate check --ci ``` -This works in any environment with `curl` and `tar` — no runtime dependencies needed. You can pin a version with the `ARCHGATE_VERSION` environment variable: +This works in any environment with `curl` and `tar`, no runtime dependencies needed. You can pin a version with the `ARCHGATE_VERSION` environment variable: ```yaml - run: curl -fsSL https://raw.githubusercontent.com/archgate/cli/main/install.sh | ARCHGATE_VERSION=v0.11.2 sh @@ -1788,7 +1788,7 @@ This reads `.archgate/imports.json` and displays each source, version, and the A ## How ID remapping works -When you import ADRs, the original IDs are **remapped** to match your project's domain prefixes. Each ADR's `domain` field determines which prefix it gets — for example, an ADR with `domain: frontend` becomes `FE-XXX`, while one with `domain: backend` becomes `BE-XXX`. Each domain has its own counter, so importing a pack with mixed domains produces correctly prefixed IDs without collisions. +When you import ADRs, the original IDs are **remapped** to match your project's domain prefixes. Each ADR's `domain` field determines which prefix it gets. For example, an ADR with `domain: frontend` becomes `FE-XXX`, while one with `domain: backend` becomes `BE-XXX`. Each domain has its own counter, so importing a pack with mixed domains produces correctly prefixed IDs without collisions. For example, importing a pack with three frontend ADRs and two backend ADRs into a project that already has `FE-001` and `BE-001` produces: @@ -1818,7 +1818,7 @@ Every import is recorded in `.archgate/imports.json`: } ``` -This manifest lets you track provenance — where each imported ADR came from and when. Commit it to version control alongside your ADRs. +This manifest lets you track provenance: where each imported ADR came from and when. Commit it to version control alongside your ADRs. ## Command options reference @@ -1847,7 +1847,7 @@ archgate init --editor opencode The opencode agent bundle is currently in beta. Run `archgate login` to sign up and authenticate. -Unlike the Claude Code or Cursor integrations, the opencode agents are **not written to your project tree**. They are installed at the user scope instead — so they live on your machine, not in your repository, and are available across every project you open with opencode. +Unlike the Claude Code or Cursor integrations, the opencode agents are **not written to your project tree**. They are installed at the user scope instead, so they live on your machine, not in your repository, and are available across every project you open with opencode. opencode uses the XDG Base Directory convention on every platform (via the `xdg-basedir` package), so the install location resolves to `$XDG_CONFIG_HOME/opencode/agents/` when that variable is set, and falls back to `$HOME/.config/opencode/agents/` otherwise. That means Windows installs land under `C:\Users\\.config\opencode\agents\`, not under `%APPDATA%`: @@ -1858,7 +1858,7 @@ opencode uses the XDG Base Directory convention on every platform (via the `xdg- ### Authenticated install -The install step only runs when the `opencode` CLI is on your PATH. Archgate needs to confirm opencode is present before writing files into its user-scope config directory — otherwise the agents would sit in a location nothing reads. Install opencode from [opencode.ai](https://opencode.ai/docs/) first, then re-run `archgate init --editor opencode` or `archgate plugin install --editor opencode`. +The install step only runs when the `opencode` CLI is on your PATH. Archgate needs to confirm opencode is present before writing files into its user-scope config directory. Otherwise the agents would sit in a location nothing reads. Install opencode from [opencode.ai](https://opencode.ai/docs/) first, then re-run `archgate init --editor opencode` or `archgate plugin install --editor opencode`. If you have logged in via `archgate login` **and** `opencode` is on your PATH, the init command downloads and installs the Archgate agent bundle for opencode. The bundle provides a pre-built primary agent and four subagents that give opencode's AI a full guardrails workflow. @@ -1887,7 +1887,7 @@ The install step downloads an authenticated tarball from the Archgate plugins se | `/archgate-adr-author.md` | Subagent that creates and edits ADRs following project conventions | | `/archgate-cli-reference.md` | Internal reference subagent with the Archgate CLI command guide (hidden) | -`.archgate/adrs/` and `.archgate/lint/` are still created in your project as usual — only the opencode-specific agent files live outside the project tree. +`.archgate/adrs/` and `.archgate/lint/` are still created in your project as usual. Only the opencode-specific agent files live outside the project tree. ## What the bundle provides @@ -3005,20 +3005,20 @@ There are two ways to handle exceptions in Archgate: **engine-level suppression* Archgate supports inline `archgate-ignore` comments that suppress violations without modifying the rule itself. The engine parses these comments and filters matching violations before reporting. -**Next-line suppression** — suppresses the violation on the immediately following line: +**Next-line suppression** suppresses the violation on the immediately following line: ```typescript // archgate-ignore ARCH-006/no-unapproved-deps legacy dep, migration planned for Q3 ``` -**File-level suppression** — suppresses all matching violations anywhere in the file: +**File-level suppression** suppresses all matching violations anywhere in the file: ```typescript // archgate-ignore-file ARCH-005/test-mirrors-src generated file, no manual test ``` -**Multiple rules** — stack comments to suppress more than one rule on the same line: +**Multiple rules**: stack comments to suppress more than one rule on the same line: ```typescript // archgate-ignore ARCH-006/no-unapproved-deps legacy dep @@ -3028,7 +3028,7 @@ Archgate supports inline `archgate-ignore` comments that suppress violations wit Consecutive suppression comments all target the first non-suppression line that follows. -The format is `ADR-ID/rule-id` followed by a reason. The reason is **required** — a suppression without a reason is ignored and produces a warning: +The format is `ADR-ID/rule-id` followed by a reason. The reason is **required**. A suppression without a reason is ignored and produces a warning: ``` [suppression] Suppression for ARCH-006/no-unapproved-deps is missing a reason src/foo.ts:1 @@ -3078,13 +3078,13 @@ The developer opts out by adding the directive to their file: | `archgate-ignore` | Ad-hoc exceptions for any rule | Developer using the rule | | Custom directive | Domain-specific opt-outs with structured reasons | Rule author | -Use `archgate-ignore` when a developer needs to suppress a one-off violation. Use custom directives when the opt-out is a first-class concept in your rule's domain — for example, marking a component as intentionally unpaired, or a file as auto-generated. +Use `archgate-ignore` when a developer needs to suppress a one-off violation. Use custom directives when the opt-out is a first-class concept in your rule's domain, for example, marking a component as intentionally unpaired, or a file as auto-generated. ## Next steps -- [Common Rule Patterns](/examples/common-rule-patterns/) — Copy-pasteable patterns organized by category: dependency management, import restrictions, file structure, code quality, database schema, and architecture boundaries. -- [Rule API Reference](/reference/rule-api/) — Full reference for all rule API types and functions. -- [CI Integration](/guides/ci-integration/) — Wire `archgate check` into your pipeline to enforce rules on every PR. +- [Common Rule Patterns](/examples/common-rule-patterns/): Copy-pasteable patterns organized by category: dependency management, import restrictions, file structure, code quality, database schema, and architecture boundaries. +- [Rule API Reference](/reference/rule-api/): Full reference for all rule API types and functions. +- [CI Integration](/guides/ci-integration/): Wire `archgate check` into your pipeline to enforce rules on every PR. --- @@ -3384,7 +3384,7 @@ Invalid ADR frontmatter in ARCH-001-example.md: - domain: domain must be lowercase kebab-case (e.g. 'backend', 'ml-ops') ``` -Note: the parser accepts any name that matches the kebab-case pattern. Whether a specific name is "known" to the project — and therefore has a prefix that `archgate adr create` can use — depends on the built-in set plus any custom domains registered via [`archgate adr domain add`](/reference/cli/adr/#archgate-adr-domain). Creating an ADR with an unregistered domain name fails with a "Unknown ADR domain" error that suggests running `archgate adr domain add`. +Note: the parser accepts any name that matches the kebab-case pattern. Whether a specific name is "known" to the project (and therefore has a prefix that `archgate adr create` can use) depends on the built-in set plus any custom domains registered via [`archgate adr domain add`](/reference/cli/adr/#archgate-adr-domain). Creating an ADR with an unregistered domain name fails with a "Unknown ADR domain" error that suggests running `archgate adr domain add`. ### Type mismatches @@ -3552,7 +3552,7 @@ archgate adr update \ Manage custom ADR domains. Custom domains are name → ID-prefix mappings persisted in `.archgate/config.json` and merged with the five built-ins (`backend`, `frontend`, `data`, `architecture`, `general`) at read time. -Use this command when a decision doesn't cleanly fit any built-in domain. Before registering a new one, check whether the decision can be folded under an existing domain — built-ins are the default and a custom domain should only be introduced when no built-in is a genuine fit. +Use this command when a decision doesn't cleanly fit any built-in domain. Before registering a new one, check whether the decision can be folded under an existing domain. Built-ins are the default and a custom domain should only be introduced when no built-in is a genuine fit. ```bash archgate adr domain [options] @@ -3568,8 +3568,8 @@ archgate adr domain [options] ### Naming rules -- `` — lowercase kebab-case, 2–32 chars (e.g., `security`, `ml-ops`) -- `` — uppercase letters, digits, or underscores, 2–10 chars (e.g., `SEC`, `MLOPS`) +- ``: lowercase kebab-case, 2–32 chars (e.g., `security`, `ml-ops`) +- ``: uppercase letters, digits, or underscores, 2–10 chars (e.g., `SEC`, `MLOPS`) - Custom names and prefixes cannot collide with built-ins or with any other custom entry. ### Options @@ -3682,9 +3682,9 @@ The command compares local imported ADRs against their upstream source and shows ### Arguments -| Argument | Description | -| ------------- | ------------------------------------------------------ | -| `[source...]` | Optional source filter(s) — sync only matching imports | +| Argument | Description | +| ------------- | ------------------------------------------------------- | +| `[source...]` | Optional source filter(s) to sync only matching imports | ### Options @@ -3708,7 +3708,7 @@ Check only imports from a specific source: archgate adr sync archgate/packs/typescript ``` -CI mode — fail the build if any imported ADR is outdated: +CI mode, failing the build if any imported ADR is outdated: ```bash archgate adr sync --check @@ -4059,7 +4059,7 @@ When `--install-plugin` is passed, the CLI installs the Archgate plugin for the **Cursor:** Downloads an authenticated tarball of skills, agents, and hooks into `~/.cursor/`. Also writes `.cursor/hooks.json` to the project for cloud agent compatibility. No CLI detection needed. -**opencode:** Requires the `opencode` CLI to be on your PATH — if it's not, the install is skipped and a message prompts you to install opencode first. When present, the CLI downloads an authenticated tarball of agent files from the Archgate plugins service and extracts it into the user-scope opencode agents directory (`$XDG_CONFIG_HOME/opencode/agents/`, falling back to `$HOME/.config/opencode/agents/` on every platform including Windows — opencode uses XDG paths via `xdg-basedir` and does not read `%APPDATA%`). No files are written to the project tree. See the [opencode integration guide](/guides/opencode-integration/) for details. +**opencode:** Requires the `opencode` CLI to be on your PATH. If it's not, the install is skipped and a message prompts you to install opencode first. When present, the CLI downloads an authenticated tarball of agent files from the Archgate plugins service and extracts it into the user-scope opencode agents directory (`$XDG_CONFIG_HOME/opencode/agents/`, falling back to `$HOME/.config/opencode/agents/` on every platform including Windows; opencode uses XDG paths via `xdg-basedir` and does not read `%APPDATA%`). No files are written to the project tree. See the [opencode integration guide](/guides/opencode-integration/) for details. ## Output @@ -4274,9 +4274,9 @@ Installation behavior varies by editor: - **Claude Code:** Auto-installs via `claude` CLI if available; prints manual commands otherwise. - **Copilot CLI:** Auto-installs via `copilot` CLI if available; prints manual commands otherwise. -- **Cursor:** Downloads an authenticated tarball and extracts skills, agents, and hooks into `~/.cursor/`. No CLI detection needed — files are written directly to the Cursor user directory. +- **Cursor:** Downloads an authenticated tarball and extracts skills, agents, and hooks into `~/.cursor/`. No CLI detection needed. Files are written directly to the Cursor user directory. - **VS Code:** Installs the VS Code extension (`.vsix`) via `code` CLI if available; prints manual instructions otherwise. -- **opencode:** Requires the `opencode` CLI to be on PATH — skips the install with a clear message otherwise. When present, downloads an authenticated tarball of agent files and extracts it into the user-scope opencode agents directory. `archgate plugin url --editor opencode` prints "N/A" — opencode has no marketplace URL. See the [opencode integration guide](/guides/opencode-integration/) for details. +- **opencode:** Requires the `opencode` CLI to be on PATH, and skips the install with a clear message otherwise. When present, downloads an authenticated tarball of agent files and extracts it into the user-scope opencode agents directory. `archgate plugin url --editor opencode` prints "N/A" because opencode has no marketplace URL. See the [opencode integration guide](/guides/opencode-integration/) for details. ## Examples @@ -4724,7 +4724,7 @@ Archgate collects **anonymous usage analytics** (via PostHog) and **crash report | Sentry Cloud | Crash reports | EU (Frankfurt) | 90 days | | Turso | Plugins Service account data | EU | Until deletion requested | -Data is transmitted via reverse proxies at `n.archgate.dev` (analytics) and `s.archgate.dev` (errors) — transparent forwarders operated by Dasolve AS on Cloudflare, with no logging or storage. +Data is transmitted via reverse proxies at `n.archgate.dev` (analytics) and `s.archgate.dev` (errors). These are transparent forwarders operated by Dasolve AS on Cloudflare, with no logging or storage. ### Archgate Plugins Service @@ -4746,8 +4746,8 @@ Note: telemetry opt-out disables CLI analytics and crash reporting. It does not ### Your rights -- **Access:** Request a copy of your data — email [privacy@archgate.dev](mailto:privacy@archgate.dev) with your install ID (from `~/.archgate/config.json` or `archgate telemetry status`). -- **Erasure:** Request deletion of historical data — email with your install ID. Completed within 30 days. +- **Access:** Request a copy of your data. Email [privacy@archgate.dev](mailto:privacy@archgate.dev) with your install ID (from `~/.archgate/config.json` or `archgate telemetry status`). +- **Erasure:** Request deletion of historical data. Email with your install ID. Completed within 30 days. - **Object:** Disable telemetry at any time via `archgate telemetry disable`. - **Portability:** Request data export in JSON or CSV format. - **Complaint:** Contact the Norwegian Data Protection Authority ([Datatilsynet](https://www.datatilsynet.no)). @@ -4981,14 +4981,14 @@ interface ReportDetail { } ``` -| Field | Type | Required | Description | -| ----------- | -------- | -------- | ------------------------------------------------------------------- | -| `message` | `string` | Yes | Human-readable description of the issue | -| `file` | `string` | No | File path where the issue was found | -| `line` | `number` | No | Start line number (1-based) | -| `endLine` | `number` | No | End line number (1-based) — for precise editor range highlighting | -| `endColumn` | `number` | No | End column number (0-based) — for precise editor range highlighting | -| `fix` | `string` | No | Suggested fix or remediation action | +| Field | Type | Required | Description | +| ----------- | -------- | -------- | ------------------------------------------------------------------ | +| `message` | `string` | Yes | Human-readable description of the issue | +| `file` | `string` | No | File path where the issue was found | +| `line` | `number` | No | Start line number (1-based) | +| `endLine` | `number` | No | End line number (1-based), for precise editor range highlighting | +| `endColumn` | `number` | No | End column number (0-based), for precise editor range highlighting | +| `fix` | `string` | No | Suggested fix or remediation action | When `endLine` and `endColumn` are provided, editors (VS Code, Cursor) can highlight the exact expression that violates the rule, rather than the entire line. If omitted, the full line at `line` is highlighted. @@ -5048,23 +5048,23 @@ interface ViolationDetail { } ``` -| Field | Type | Description | -| ----------- | ---------- | ------------------------------------------------------ | -| `ruleId` | `string` | Rule ID from the `rules` object key | -| `adrId` | `string` | ADR ID from the frontmatter | -| `message` | `string` | Human-readable description | -| `file` | `string?` | File path where the issue was found | -| `line` | `number?` | Start line number (1-based) | -| `endLine` | `number?` | End line (1-based) — for precise editor highlighting | -| `endColumn` | `number?` | End column (0-based) — for precise editor highlighting | -| `fix` | `string?` | Suggested fix | -| `severity` | `Severity` | Effective severity of this violation | +| Field | Type | Description | +| ----------- | ---------- | ----------------------------------------------------- | +| `ruleId` | `string` | Rule ID from the `rules` object key | +| `adrId` | `string` | ADR ID from the frontmatter | +| `message` | `string` | Human-readable description | +| `file` | `string?` | File path where the issue was found | +| `line` | `number?` | Start line number (1-based) | +| `endLine` | `number?` | End line (1-based), for precise editor highlighting | +| `endColumn` | `number?` | End column (0-based), for precise editor highlighting | +| `fix` | `string?` | Suggested fix | +| `severity` | `Severity` | Effective severity of this violation | --- ## Inline suppression -Violations can be suppressed in source code using `archgate-ignore` comments. The engine handles this automatically — rules do not need any special logic. +Violations can be suppressed in source code using `archgate-ignore` comments. The engine handles this automatically. Rules do not need any special logic. ```typescript // archgate-ignore ARCH-006/no-unapproved-deps legacy dep, migration planned @@ -5087,19 +5087,19 @@ Archgate collects **anonymous usage data** to help us understand how the CLI is When you run an Archgate command, we record: -- **Command name** and **which flags were used** (e.g., `check --json` — only flag presence, never flag values) +- **Command name** and **which flags were used** (e.g., `check --json`; only flag presence, never flag values) - **Exit code** (0, 1, 2, or 130) and **execution duration** (milliseconds), plus a short **outcome** tag (`success`, `user_error`, `internal_error`, `cancelled`) - **Environment**: OS, architecture, Bun version, Archgate version, CI detection (including provider: GitHub Actions / GitLab CI / CircleCI / etc.), TTY detection, WSL detection, shell (bash, zsh, pwsh...), and locale - **Install context**: how the CLI was installed (binary, proto, local dev dependency, or global package manager) - **Project context**: whether an Archgate project exists in the current directory, how many ADRs it has, how many have automated rules, and how many distinct ADR domains are used -- **Repo context** (non-identifying): whether the current directory is a git repository, the host bucket (`github` / `gitlab` / `bitbucket` / `azure-devops` / `other`), a **hashed `repo_id`** (SHA-256 of the normalized remote URL, truncated to 16 hex characters — not reversible), and the default branch name -- **Coarse location**: country and region (resolved server-side from your IP, then the IP is discarded — see [IP anonymization](#ip-anonymization)) -- **Anonymous install ID**: a random UUID generated on first run — not derived from any personal data +- **Repo context** (non-identifying): whether the current directory is a git repository, the host bucket (`github` / `gitlab` / `bitbucket` / `azure-devops` / `other`), a **hashed `repo_id`** (SHA-256 of the normalized remote URL, truncated to 16 hex characters, not reversible), and the default branch name +- **Coarse location**: country and region (resolved server-side from your IP, then the IP is discarded; see [IP anonymization](#ip-anonymization)) +- **Anonymous install ID**: a random UUID generated on first run, not derived from any personal data In addition to the general command lifecycle events (`command_executed` / `command_completed`), specific commands send enriched outcome events: -- **`check`**: aggregate rule counts (total, passed, failed, warnings, errors), output format used, whether filters were applied, files scanned, load duration, check duration — no file paths or violation content -- **`init`**: editor choice, whether the plugin was installed, whether the project already existed. A separate one-time `project_initialized` event is emitted with the repo host bucket, `repo_is_git`, and a `repo_public` flag. For repos confirmed public on GitHub / GitLab / Bitbucket, this event also carries the remote URL, owner, and repo name — see [Repo identity](#repo-identity). Private and self-hosted repos never have identity shared. +- **`check`**: aggregate rule counts (total, passed, failed, warnings, errors), output format used, whether filters were applied, files scanned, load duration, check duration. No file paths or violation content +- **`init`**: editor choice, whether the plugin was installed, whether the project already existed. A separate one-time `project_initialized` event is emitted with the repo host bucket, `repo_is_git`, and a `repo_public` flag. For repos confirmed public on GitHub / GitLab / Bitbucket / Azure DevOps, this event also carries the remote URL, owner, and repo name. See [Repo identity](#repo-identity). Private and self-hosted repos never have identity shared. - **`upgrade`**: version transition (from → to), install method, success/failure, and an optional failure reason - **`login`**: subcommand used (login, logout, refresh, status), success/failure, and a failure bucket (`network`, `tls`, `denied`, `other`) when it fails - **`telemetry_preference_changed`**: fires once when you enable or disable telemetry, so we can understand opt-out rates @@ -5108,7 +5108,7 @@ In addition to the general command lifecycle events (`command_executed` / `comma Archgate sends a **hashed** `repo_id` with every event so we can count distinct repositories using the CLI without learning their names. The raw remote URL, owner, and repository name are **not** included in the common event stream. -On `archgate init`, a one-time `project_initialized` event is emitted. If — and only if — the repository is confirmed **public** on GitHub, GitLab, Bitbucket, or Azure DevOps (via an unauthenticated API probe against the host), that event additionally includes `remote_url`, `repo_owner`, and `repo_name`. This lets us see which public repositories are adopting Archgate without ever exposing private ones. +On `archgate init`, a one-time `project_initialized` event is emitted. If, and only if, the repository is confirmed **public** on GitHub, GitLab, Bitbucket, or Azure DevOps (via an unauthenticated API probe against the host), that event additionally includes `remote_url`, `repo_owner`, and `repo_name`. This lets us see which public repositories are adopting Archgate without ever exposing private ones. **What's never shared:** @@ -5116,7 +5116,7 @@ On `archgate init`, a one-time `project_initialized` event is emitted. If — an - Self-hosted Git hosts (the probe skips these entirely) - Repositories where the probe times out, is rate-limited, or otherwise fails to return a definitive public answer -**Don't want the event at all?** Disable telemetry entirely — the whole `project_initialized` event is then suppressed along with everything else: +**Don't want the event at all?** Disable telemetry entirely. The whole `project_initialized` event is then suppressed along with everything else: ```bash # Per-shell / per-invocation @@ -5138,8 +5138,8 @@ When the CLI crashes (exit code 2), we send: ## What we do NOT collect -- **No personal information**: no usernames, emails, or IP addresses. GitHub / GitLab / Bitbucket owner/repository names are only sent on the one-time `project_initialized` event for repositories that are confirmed public by their host — see [Repo identity](#repo-identity). Private and self-hosted repos never have identity shared. -- **No file content**: no ADR content, source code, or file paths +- **No personal information**: no emails, passwords, secrets, or IP addresses. The one-time `project_initialized` event can include `repo_owner` and `repo_name` for repositories confirmed public by their host. See [Repo identity](#repo-identity). Private and self-hosted repos never have identity shared. +- **No file content**: no ADR content or source code. Crash reports (Sentry) may include relative file paths in stack traces, but never absolute paths or file contents. - **No prompt or AI context**: nothing from agent interactions, prompts, or AI-generated content - **No flag values**: we record that `--json` was used, not what the JSON output contained - **No network activity**: no URLs, API keys, or tokens @@ -5150,7 +5150,7 @@ Archgate uses PostHog's built-in IP anonymization: 1. Your CLI sends an event to PostHog with `$ip: null` 2. PostHog resolves your IP to a **country and region** (e.g., "US", "California") server-side -3. The IP address is then **discarded** — it is never stored in PostHog +3. The IP address is then **discarded**. It is never stored in PostHog For Sentry error tracking, the project has **"Prevent Storing of IP Addresses"** enabled, so IPs are stripped before storage. @@ -5190,7 +5190,7 @@ The environment variable takes precedence over the CLI setting. If `ARCHGATE_TEL ## Legal basis -Archgate CLI telemetry operates on an **opt-out basis** under GDPR Article 6(1)(f) and LGPD Article 7, IX c/c Article 10 — legitimate interests of the controller. We have published a formal [Legitimate Interest Assessment](https://archgate.dev/legitimate-interest-assessment) documenting why this is proportionate and lawful. +Archgate CLI telemetry operates on an **opt-out basis** under GDPR Article 6(1)(f) and LGPD Article 7, IX c/c Article 10: legitimate interests of the controller. We have published a formal [Legitimate Interest Assessment](https://archgate.dev/legitimate-interest-assessment) documenting why this is proportionate and lawful. In summary: the data is anonymous (random UUID, no PII), the impact on users is minimal, robust safeguards are in place (IP anonymization, EU storage, limited retention, transparency), and users retain full control via an easy, permanent opt-out. @@ -5202,7 +5202,7 @@ In summary: the data is anonymous (random UUID, no PII), the impact on users is | Sentry Cloud | Crash reports | EU (Frankfurt) | 90 days | | Local config | Telemetry preference + install ID | Your machine | Until you delete it | -Analytics events are routed through `n.archgate.dev` and error reports through `s.archgate.dev`. These are transparent reverse proxies operated by Dasolve AS on Cloudflare infrastructure — they forward requests without logging, storing, or inspecting payloads. +Analytics events are routed through `n.archgate.dev` and error reports through `s.archgate.dev`. These are transparent reverse proxies operated by Dasolve AS on Cloudflare infrastructure. They forward requests without logging, storing, or inspecting payloads. ## Your rights @@ -5219,9 +5219,9 @@ Analytics events are routed through `n.archgate.dev` and error reports through ` The telemetry implementation is fully open source. You can inspect exactly what data is collected by reading: -- [`src/helpers/telemetry.ts`](https://github.com/archgate/cli/blob/main/src/helpers/telemetry.ts) — PostHog event tracking -- [`src/helpers/sentry.ts`](https://github.com/archgate/cli/blob/main/src/helpers/sentry.ts) — Sentry error capture -- [`src/helpers/telemetry-config.ts`](https://github.com/archgate/cli/blob/main/src/helpers/telemetry-config.ts) — Config and opt-out logic +- [`src/helpers/telemetry.ts`](https://github.com/archgate/cli/blob/main/src/helpers/telemetry.ts): PostHog event tracking +- [`src/helpers/sentry.ts`](https://github.com/archgate/cli/blob/main/src/helpers/sentry.ts): Sentry error capture +- [`src/helpers/telemetry-config.ts`](https://github.com/archgate/cli/blob/main/src/helpers/telemetry-config.ts): Config and opt-out logic --- @@ -5229,13 +5229,13 @@ The telemetry implementation is fully open source. You can inspect exactly what Source: https://cli.archgate.dev/examples/clean-architecture-layers/ -Enforce dependency direction in clean architecture — inner layers must not reference outer layers. +Enforce dependency direction in clean architecture: inner layers must not reference outer layers. ## Rule details Clean architecture mandates that dependencies point inward: API → Application → Domain. The Domain layer must have zero external dependencies, the Application layer must not reference Infrastructure directly, and no lower layer should reference the API project. This rule checks `using` directives (C#) or `import` statements to enforce these boundaries. -The same pattern applies to any layered architecture in any language — adjust the import patterns and layer paths accordingly. +The same pattern applies to any layered architecture in any language. Adjust the import patterns and layer paths accordingly. ## Examples of **incorrect** code @@ -5253,7 +5253,7 @@ using StavangerChallenge.API; // ✗ Application → API ```csharp title="Domain/Entities/User.cs" namespace StavangerChallenge.Domain.Entities; -// No external dependencies — pure domain logic +// No external dependencies, pure domain logic ``` ```csharp title="Application/Services/UserService.cs" @@ -5752,7 +5752,7 @@ function isAllowed(license: string | undefined): boolean { if (!license) return false; if (ALLOWED_LICENSES.has(license)) return true; - // Handle SPDX OR expressions — at least one option must be allowed + // Handle SPDX OR expressions: at least one option must be allowed const normalized = license.trim().replace(/^\(/u, "").replace(/\)$/u, ""); if (ALLOWED_LICENSES.has(normalized)) return true; @@ -5784,7 +5784,7 @@ export default { description: "All dependencies (including transitive) must use permissive licenses", async check(ctx) { - // Scan ALL packages in node_modules — direct AND transitive. + // Scan ALL packages in node_modules, direct AND transitive. // Brace expansion covers both regular and scoped packages. const pkgFiles = await ctx.glob("node_modules/{*,@*/*}/package.json"); @@ -5953,7 +5953,7 @@ export default { rules: { "no-package-scripts": { description: - "package.json must not have scripts — use the task runner instead", + "package.json must not have scripts. Use the task runner instead", async check(ctx) { const packageJsonFiles = [ ...(await ctx.glob("packages/*/package.json")), @@ -5966,7 +5966,7 @@ export default { }; if (pkg.scripts && Object.keys(pkg.scripts).length > 0) { ctx.report.violation({ - message: `${file}: has "scripts" field — use task runner config instead`, + message: `${file}: has "scripts" field. Use task runner config instead`, file, fix: 'Move scripts to the task runner config and remove "scripts" from package.json', }); @@ -6026,7 +6026,7 @@ Ban specific runtime APIs that cause cross-platform or reliability issues. ## Rule details -Some APIs work correctly on one platform but fail on another. For example, Bun's shell API (`Bun.$`) hangs on Windows due to pipe deadlocks. This rule detects multiple variants of a banned API — the direct call, the import, and destructured usage — ensuring no form slips through. +Some APIs work correctly on one platform but fail on another. For example, Bun's shell API (`Bun.$`) hangs on Windows due to pipe deadlocks. This rule detects multiple variants of a banned API (the direct call, the import, and destructured usage), ensuring no form slips through. This pattern generalizes to any API you want to ban while allowing a safe alternative. @@ -6072,7 +6072,7 @@ export default { for (const m of fileMatches) { ctx.report.violation({ message: - "Do not use Bun.$ template literals — they hang on Windows. Use Bun.spawn instead.", + "Do not use Bun.$ template literals. They hang on Windows. Use Bun.spawn instead.", file: m.file, line: m.line, fix: "Replace Bun.$`cmd args` with Bun.spawn(['cmd', 'args'], { stdout: 'pipe', stderr: 'pipe' })", @@ -6090,7 +6090,7 @@ export default { for (const m of fileMatches) { ctx.report.violation({ message: - 'Do not import $ from "bun" — the shell API hangs on Windows. Use Bun.spawn instead.', + 'Do not import $ from "bun". The shell API hangs on Windows. Use Bun.spawn instead.', file: m.file, line: m.line, fix: "Remove the $ import and replace shell calls with Bun.spawn", @@ -6106,7 +6106,7 @@ export default { for (const m of fileMatches) { ctx.report.violation({ message: - "Do not use $` template literals — they hang on Windows. Use Bun.spawn instead.", + "Do not use $` template literals. They hang on Windows. Use Bun.spawn instead.", file: m.file, line: m.line, fix: "Replace $`cmd args` with Bun.spawn(['cmd', 'args'], { stdout: 'pipe', stderr: 'pipe' })", @@ -6137,7 +6137,7 @@ Prevent usage of banned libraries and enforce recommended alternatives. ## Rule details -Teams often ban heavy or deprecated libraries in favor of lighter or native alternatives. This rule uses a data-driven configuration — an array of objects specifying the regex pattern, the library name, and the recommended alternative. Adding a new ban is a one-line change. +Teams often ban heavy or deprecated libraries in favor of lighter or native alternatives. This rule uses a data-driven configuration: an array of objects specifying the regex pattern, the library name, and the recommended alternative. Adding a new ban is a one-line change. ## Examples of **incorrect** code @@ -6218,7 +6218,7 @@ When your project has no preference between libraries, or when the banned librar Source: https://cli.archgate.dev/examples/no-barrel-files/ -Detect and ban barrel files — `index.ts` files that contain only re-exports and no logic. +Detect and ban barrel files: `index.ts` files that contain only re-exports and no logic. ## Rule details @@ -6246,7 +6246,7 @@ export function getHelperVersion(): string { } ``` -Or better — delete `index.ts` entirely and import directly: +Or better, delete `index.ts` entirely and import directly: ```typescript @@ -6463,7 +6463,7 @@ export default { ); for (const match of matches) { ctx.report.warning({ - message: `${match.content.trim()} — resolve before merging`, + message: `${match.content.trim()} (resolve before merging)`, file: match.file, line: match.line, }); @@ -6534,7 +6534,7 @@ export default { try { pkg = (await ctx.readJSON("package.json")) as typeof pkg; } catch { - return; // No package.json — nothing to check + return; // No package.json, nothing to check } const deps = Object.keys(pkg.dependencies ?? {}); @@ -6675,14 +6675,14 @@ When not all routes require OpenAPI documentation (e.g., internal health checks, Source: https://cli.archgate.dev/examples/page-component-constraints/ -Enforce that page components are thin layout wrappers — small in size and free of data-fetching logic. +Enforce that page components are thin layout wrappers: small in size and free of data-fetching logic. ## Rule details In frontend architectures that separate routing from logic, page components should only compose layout and delegate data-fetching to Connected components. This rule enforces two constraints in a single rules file: -1. **Size limit** — Page components must stay under a configurable line count (default: 75 lines). -2. **No data hooks** — Page components must not use `useState`, `useQuery`, `useMutation`, or other data-fetching hooks directly. +1. **Size limit**: Page components must stay under a configurable line count (default: 75 lines). +2. **No data hooks**: Page components must not use `useState`, `useQuery`, `useMutation`, or other data-fetching hooks directly. ## Examples of **incorrect** code @@ -6877,7 +6877,7 @@ Ensure every source file declares its license with a machine-readable SPDX ident ## Rule details -Open-source projects benefit from per-file license declarations — they survive file extraction, bundling, and copy-paste scenarios where the root LICENSE file is not present. This rule verifies that every TypeScript source file starts with the standard SPDX header comment. +Open-source projects benefit from per-file license declarations. They survive file extraction, bundling, and copy-paste scenarios where the root LICENSE file is not present. This rule verifies that every TypeScript source file starts with the standard SPDX header comment. ## Examples of **incorrect** code @@ -7248,7 +7248,7 @@ export default { for (const m of fileMatches) { ctx.report.violation({ message: - "Do not access process.platform directly — use isWindows(), isMacOS(), or isLinux() from src/helpers/platform.ts instead.", + "Do not access process.platform directly. Use isWindows(), isMacOS(), isLinux(), or getPlatformInfo() from src/helpers/platform.ts instead.", file: m.file, line: m.line, fix: 'Import { isWindows } from "../helpers/platform" and use it instead of process.platform', diff --git a/docs/public/llms.txt b/docs/public/llms.txt index 87655d99..61012076 100644 --- a/docs/public/llms.txt +++ b/docs/public/llms.txt @@ -1,6 +1,6 @@ # Archgate CLI -> Archgate is a CLI tool for AI governance via Architecture Decision Records (ADRs). It combines human-readable documentation with machine-checkable TypeScript rules to enforce architectural decisions across codebases — for both humans and AI agents. +> Archgate is a CLI for enterprise-grade linting and guardrails for AI work, built on Architecture Decision Records (ADRs). It combines human-readable documentation with machine-checkable TypeScript rules to enforce architectural decisions across codebases, for both humans and AI agents. Archgate lets teams write an ADR once and enforce it everywhere. ADRs are Markdown files with YAML frontmatter that describe architectural decisions. Companion `.rules.ts` files contain automated TypeScript checks that run against the codebase and report violations with file paths and line numbers. @@ -8,8 +8,8 @@ Archgate lets teams write an ADR once and enforce it everywhere. ADRs are Markdo - **Executable rules**: Write compliance rules in TypeScript. Archgate runs them against your codebase and reports violations with file paths and line numbers. - **CI integration**: Wire `archgate check` into any CI/CD pipeline. Exit code 1 blocks merges when rules are violated. -- **AI-aware governance**: Editor plugins give AI agents (Claude, Cursor, Copilot) live access to ADRs. Agents read decisions before writing code and validate after. -- **Editor plugins**: Claude Code, VS Code, Cursor, and Copilot CLI plugins give AI agents role-based governance skills. +- **AI-aware guardrails**: Editor plugins give AI agents (Claude, Cursor, Copilot) live access to ADRs. Agents read decisions before writing code and validate after. +- **Editor plugins**: Claude Code, VS Code, Cursor, and Copilot CLI plugins give AI agents role-based enforcement skills. - **Self-governance**: Archgate governs its own development using the same tool. ## Installation @@ -18,23 +18,23 @@ Install standalone (no Node.js required): `curl -fsSL https://raw.githubusercont ## Documentation -- [Getting Started — Installation](https://cli.archgate.dev/getting-started/installation/): Install on macOS, Linux, or Windows via npm, Homebrew, or standalone binary. -- [Getting Started — Quick Start](https://cli.archgate.dev/getting-started/quick-start/): Set up Archgate in under 5 minutes with your first ADR and rule. -- [Core Concepts — ADRs](https://cli.archgate.dev/concepts/adrs/): How Architecture Decision Records work as both documentation and executable rules. -- [Core Concepts — Rules](https://cli.archgate.dev/concepts/rules/): The TypeScript rule system that turns ADR decisions into automated compliance checks. -- [Core Concepts — Domains](https://cli.archgate.dev/concepts/domains/): Organize ADRs by domain for targeted governance. -- [Guide — Writing ADRs](https://cli.archgate.dev/guides/writing-adrs/): Complete guide to writing effective ADRs with YAML frontmatter and markdown structure. -- [Guide — Writing Rules](https://cli.archgate.dev/guides/writing-rules/): Write TypeScript rules using the satisfies RuleSet pattern with file matching and violation reporting. -- [Guide — CI Integration](https://cli.archgate.dev/guides/ci-integration/): Add Archgate checks to GitHub Actions, GitLab CI, or any pipeline. -- [Guide — Claude Code Plugin](https://cli.archgate.dev/guides/claude-code-plugin/): Give AI agents a governance workflow that reads ADRs, validates code, and captures patterns. -- [Guide — VS Code Plugin](https://cli.archgate.dev/guides/vscode-plugin/): Real-time ADR compliance in VS Code. -- [Guide — Copilot CLI Plugin](https://cli.archgate.dev/guides/copilot-cli-plugin/): Add architecture governance to GitHub Copilot CLI. -- [Guide — Cursor Integration](https://cli.archgate.dev/guides/cursor-integration/): Configure Cursor IDE with Archgate agent rules and skills. -- [Guide — Pre-commit Hooks](https://cli.archgate.dev/guides/pre-commit-hooks/): Automatically check ADR compliance before every commit. -- [Reference — CLI Commands](https://cli.archgate.dev/reference/cli-commands/): Complete reference for init, check, adr create/list/show, login, and more. -- [Reference — Rule API](https://cli.archgate.dev/reference/rule-api/): TypeScript API reference for RuleSet with satisfies, RuleContext, and violation reporting. -- [Reference — ADR Schema](https://cli.archgate.dev/reference/adr-schema/): YAML frontmatter schema and markdown structure reference for ADRs. -- [Examples — Common Rule Patterns](https://cli.archgate.dev/examples/common-rule-patterns/): Ready-to-use rule patterns for naming conventions, import restrictions, and more. +- [Getting Started: Installation](https://cli.archgate.dev/getting-started/installation/): Install on macOS, Linux, or Windows via npm, Homebrew, or standalone binary. +- [Getting Started: Quick Start](https://cli.archgate.dev/getting-started/quick-start/): Set up Archgate in under 5 minutes with your first ADR and rule. +- [Core Concepts: ADRs](https://cli.archgate.dev/concepts/adrs/): How Architecture Decision Records work as both documentation and executable rules. +- [Core Concepts: Rules](https://cli.archgate.dev/concepts/rules/): The TypeScript rule system that turns ADR decisions into automated compliance checks. +- [Core Concepts: Domains](https://cli.archgate.dev/concepts/domains/): Organize ADRs by domain to scope and enforce rules. +- [Guide: Writing ADRs](https://cli.archgate.dev/guides/writing-adrs/): Complete guide to writing effective ADRs with YAML frontmatter and markdown structure. +- [Guide: Writing Rules](https://cli.archgate.dev/guides/writing-rules/): Write TypeScript rules using the satisfies RuleSet pattern with file matching and violation reporting. +- [Guide: CI Integration](https://cli.archgate.dev/guides/ci-integration/): Add Archgate checks to GitHub Actions, GitLab CI, or any pipeline. +- [Guide: Claude Code Plugin](https://cli.archgate.dev/guides/claude-code-plugin/): Give AI agents a guardrails workflow that reads ADRs, validates code, and captures patterns. +- [Guide: VS Code Plugin](https://cli.archgate.dev/guides/vscode-plugin/): Real-time ADR compliance in VS Code. +- [Guide: Copilot CLI Plugin](https://cli.archgate.dev/guides/copilot-cli-plugin/): Add architecture guardrails to GitHub Copilot CLI. +- [Guide: Cursor Integration](https://cli.archgate.dev/guides/cursor-integration/): Configure Cursor IDE with Archgate agent rules and skills. +- [Guide: Pre-commit Hooks](https://cli.archgate.dev/guides/pre-commit-hooks/): Automatically check ADR compliance before every commit. +- [Reference: CLI Commands](https://cli.archgate.dev/reference/cli-commands/): Complete reference for init, check, adr create/list/show, login, and more. +- [Reference: Rule API](https://cli.archgate.dev/reference/rule-api/): TypeScript API reference for RuleSet with satisfies, RuleContext, and violation reporting. +- [Reference: ADR Schema](https://cli.archgate.dev/reference/adr-schema/): YAML frontmatter schema and markdown structure reference for ADRs. +- [Examples: Common Rule Patterns](https://cli.archgate.dev/examples/common-rule-patterns/): Ready-to-use rule patterns for naming conventions, import restrictions, and more. ## Full documentation diff --git a/docs/src/content/docs/concepts/domains.mdx b/docs/src/content/docs/concepts/domains.mdx index 9afbec28..03b96fce 100644 --- a/docs/src/content/docs/concepts/domains.mdx +++ b/docs/src/content/docs/concepts/domains.mdx @@ -97,7 +97,7 @@ When in doubt between `architecture` and a specific domain, prefer the more spec ## Custom Domains -When the built-in five are a genuine mismatch for a category of decisions — for example, `security`, `ml-ops`, or `compliance` — you can register a custom domain via the CLI: +When the built-in five are a genuine mismatch for a category of decisions (for example, `security`, `ml-ops`, or `compliance`), you can register a custom domain via the CLI: ```bash # See what's currently recognised in this project @@ -114,8 +114,8 @@ Custom domain-to-prefix mappings persist in [`.archgate/config.json`](/reference ### Naming rules -- **Name** — lowercase kebab-case, 2–32 characters (e.g., `security`, `ml-ops`, `compliance`). -- **Prefix** — uppercase letters, digits, or underscores, 2–10 characters (e.g., `SEC`, `MLOPS`, `COMP`). +- **Name**: lowercase kebab-case, 2–32 characters (e.g., `security`, `ml-ops`, `compliance`). +- **Prefix**: uppercase letters, digits, or underscores, 2–10 characters (e.g., `SEC`, `MLOPS`, `COMP`). - Custom names and prefixes cannot collide with built-ins or any other custom entry. ### When to prefer a built-in @@ -126,7 +126,7 @@ The built-in five are deliberately opinionated. Before registering a custom doma - A decision about schema versioning usually fits under `data`, even if the motivation is compliance. - A decision that spans multiple technical areas usually fits under `architecture`. -Reach for a custom domain only when none of the built-ins is a genuine fit — for example, when you have a dedicated team or compliance regime that needs its own governance surface. +Reach for a custom domain only when none of the built-ins is a genuine fit: for example, when you have a dedicated team or compliance regime that needs its own governance surface. ### AI agent guidance diff --git a/docs/src/content/docs/concepts/rules.mdx b/docs/src/content/docs/concepts/rules.mdx index 0a40b3fc..2f4703d6 100644 --- a/docs/src/content/docs/concepts/rules.mdx +++ b/docs/src/content/docs/concepts/rules.mdx @@ -152,7 +152,7 @@ When this rule runs against a file containing `import { readFileSync } from "nod ``` 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. + 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" ``` diff --git a/docs/src/content/docs/examples/clean-architecture-layers.mdx b/docs/src/content/docs/examples/clean-architecture-layers.mdx index 8eee3049..0c845044 100644 --- a/docs/src/content/docs/examples/clean-architecture-layers.mdx +++ b/docs/src/content/docs/examples/clean-architecture-layers.mdx @@ -3,13 +3,13 @@ title: clean-architecture-layers description: Enforce dependency direction in clean architecture by preventing inner layers from referencing outer layers. --- -Enforce dependency direction in clean architecture — inner layers must not reference outer layers. +Enforce dependency direction in clean architecture: inner layers must not reference outer layers. ## Rule details Clean architecture mandates that dependencies point inward: API → Application → Domain. The Domain layer must have zero external dependencies, the Application layer must not reference Infrastructure directly, and no lower layer should reference the API project. This rule checks `using` directives (C#) or `import` statements to enforce these boundaries. -The same pattern applies to any layered architecture in any language — adjust the import patterns and layer paths accordingly. +The same pattern applies to any layered architecture in any language. Adjust the import patterns and layer paths accordingly. ## Examples of **incorrect** code @@ -27,7 +27,7 @@ using StavangerChallenge.API; // ✗ Application → API ```csharp title="Domain/Entities/User.cs" namespace StavangerChallenge.Domain.Entities; -// No external dependencies — pure domain logic +// No external dependencies, pure domain logic ``` ```csharp title="Application/Services/UserService.cs" diff --git a/docs/src/content/docs/examples/license-compatibility.mdx b/docs/src/content/docs/examples/license-compatibility.mdx index 1dfe3ca5..40698b42 100644 --- a/docs/src/content/docs/examples/license-compatibility.mdx +++ b/docs/src/content/docs/examples/license-compatibility.mdx @@ -52,7 +52,7 @@ function isAllowed(license: string | undefined): boolean { if (!license) return false; if (ALLOWED_LICENSES.has(license)) return true; - // Handle SPDX OR expressions — at least one option must be allowed + // Handle SPDX OR expressions: at least one option must be allowed const normalized = license.trim().replace(/^\(/u, "").replace(/\)$/u, ""); if (ALLOWED_LICENSES.has(normalized)) return true; @@ -84,7 +84,7 @@ export default { description: "All dependencies (including transitive) must use permissive licenses", async check(ctx) { - // Scan ALL packages in node_modules — direct AND transitive. + // Scan ALL packages in node_modules, direct AND transitive. // Brace expansion covers both regular and scoped packages. const pkgFiles = await ctx.glob("node_modules/{*,@*/*}/package.json"); diff --git a/docs/src/content/docs/examples/monorepo-task-runner.mdx b/docs/src/content/docs/examples/monorepo-task-runner.mdx index eb38767c..6eb8beed 100644 --- a/docs/src/content/docs/examples/monorepo-task-runner.mdx +++ b/docs/src/content/docs/examples/monorepo-task-runner.mdx @@ -47,7 +47,7 @@ export default { rules: { "no-package-scripts": { description: - "package.json must not have scripts — use the task runner instead", + "package.json must not have scripts. Use the task runner instead", async check(ctx) { const packageJsonFiles = [ ...(await ctx.glob("packages/*/package.json")), @@ -60,7 +60,7 @@ export default { }; if (pkg.scripts && Object.keys(pkg.scripts).length > 0) { ctx.report.violation({ - message: `${file}: has "scripts" field — use task runner config instead`, + message: `${file}: has "scripts" field. Use task runner config instead`, file, fix: 'Move scripts to the task runner config and remove "scripts" from package.json', }); diff --git a/docs/src/content/docs/examples/no-banned-api.mdx b/docs/src/content/docs/examples/no-banned-api.mdx index cc7dd0e5..0344e617 100644 --- a/docs/src/content/docs/examples/no-banned-api.mdx +++ b/docs/src/content/docs/examples/no-banned-api.mdx @@ -7,7 +7,7 @@ Ban specific runtime APIs that cause cross-platform or reliability issues. ## Rule details -Some APIs work correctly on one platform but fail on another. For example, Bun's shell API (`Bun.$`) hangs on Windows due to pipe deadlocks. This rule detects multiple variants of a banned API — the direct call, the import, and destructured usage — ensuring no form slips through. +Some APIs work correctly on one platform but fail on another. For example, Bun's shell API (`Bun.$`) hangs on Windows due to pipe deadlocks. This rule detects multiple variants of a banned API (the direct call, the import, and destructured usage), ensuring no form slips through. This pattern generalizes to any API you want to ban while allowing a safe alternative. @@ -54,7 +54,7 @@ export default { for (const m of fileMatches) { ctx.report.violation({ message: - "Do not use Bun.$ template literals — they hang on Windows. Use Bun.spawn instead.", + "Do not use Bun.$ template literals. They hang on Windows. Use Bun.spawn instead.", file: m.file, line: m.line, fix: "Replace Bun.$`cmd args` with Bun.spawn(['cmd', 'args'], { stdout: 'pipe', stderr: 'pipe' })", @@ -72,7 +72,7 @@ export default { for (const m of fileMatches) { ctx.report.violation({ message: - 'Do not import $ from "bun" — the shell API hangs on Windows. Use Bun.spawn instead.', + 'Do not import $ from "bun". The shell API hangs on Windows. Use Bun.spawn instead.', file: m.file, line: m.line, fix: "Remove the $ import and replace shell calls with Bun.spawn", @@ -88,7 +88,7 @@ export default { for (const m of fileMatches) { ctx.report.violation({ message: - "Do not use $` template literals — they hang on Windows. Use Bun.spawn instead.", + "Do not use $` template literals. They hang on Windows. Use Bun.spawn instead.", file: m.file, line: m.line, fix: "Replace $`cmd args` with Bun.spawn(['cmd', 'args'], { stdout: 'pipe', stderr: 'pipe' })", diff --git a/docs/src/content/docs/examples/no-banned-imports.mdx b/docs/src/content/docs/examples/no-banned-imports.mdx index 2f85fdd5..2b8fcdae 100644 --- a/docs/src/content/docs/examples/no-banned-imports.mdx +++ b/docs/src/content/docs/examples/no-banned-imports.mdx @@ -7,7 +7,7 @@ Prevent usage of banned libraries and enforce recommended alternatives. ## Rule details -Teams often ban heavy or deprecated libraries in favor of lighter or native alternatives. This rule uses a data-driven configuration — an array of objects specifying the regex pattern, the library name, and the recommended alternative. Adding a new ban is a one-line change. +Teams often ban heavy or deprecated libraries in favor of lighter or native alternatives. This rule uses a data-driven configuration: an array of objects specifying the regex pattern, the library name, and the recommended alternative. Adding a new ban is a one-line change. ## Examples of **incorrect** code diff --git a/docs/src/content/docs/examples/no-barrel-files.mdx b/docs/src/content/docs/examples/no-barrel-files.mdx index 6d5e5505..980304d6 100644 --- a/docs/src/content/docs/examples/no-barrel-files.mdx +++ b/docs/src/content/docs/examples/no-barrel-files.mdx @@ -3,7 +3,7 @@ title: no-barrel-files description: Detect and ban barrel files (index.ts with only re-exports) to enforce direct imports and improve tree-shaking. --- -Detect and ban barrel files — `index.ts` files that contain only re-exports and no logic. +Detect and ban barrel files: `index.ts` files that contain only re-exports and no logic. ## Rule details @@ -31,7 +31,7 @@ export function getHelperVersion(): string { } ``` -Or better — delete `index.ts` entirely and import directly: +Or better, delete `index.ts` entirely and import directly: ```typescript import { logInfo } from "./helpers/log"; diff --git a/docs/src/content/docs/examples/no-todo-comments.mdx b/docs/src/content/docs/examples/no-todo-comments.mdx index e9d1b96d..6295d510 100644 --- a/docs/src/content/docs/examples/no-todo-comments.mdx +++ b/docs/src/content/docs/examples/no-todo-comments.mdx @@ -41,7 +41,7 @@ export default { ); for (const match of matches) { ctx.report.warning({ - message: `${match.content.trim()} — resolve before merging`, + message: `${match.content.trim()} (resolve before merging)`, file: match.file, line: match.line, }); diff --git a/docs/src/content/docs/examples/no-unapproved-deps.mdx b/docs/src/content/docs/examples/no-unapproved-deps.mdx index d333484e..88b27ebe 100644 --- a/docs/src/content/docs/examples/no-unapproved-deps.mdx +++ b/docs/src/content/docs/examples/no-unapproved-deps.mdx @@ -49,7 +49,7 @@ export default { try { pkg = (await ctx.readJSON("package.json")) as typeof pkg; } catch { - return; // No package.json — nothing to check + return; // No package.json, nothing to check } const deps = Object.keys(pkg.dependencies ?? {}); diff --git a/docs/src/content/docs/examples/page-component-constraints.mdx b/docs/src/content/docs/examples/page-component-constraints.mdx index 625db25d..d26b68ae 100644 --- a/docs/src/content/docs/examples/page-component-constraints.mdx +++ b/docs/src/content/docs/examples/page-component-constraints.mdx @@ -3,14 +3,14 @@ title: page-component-constraints description: Enforce that page components are thin layout wrappers by limiting their size and banning data-fetching hooks. --- -Enforce that page components are thin layout wrappers — small in size and free of data-fetching logic. +Enforce that page components are thin layout wrappers: small in size and free of data-fetching logic. ## Rule details In frontend architectures that separate routing from logic, page components should only compose layout and delegate data-fetching to Connected components. This rule enforces two constraints in a single rules file: -1. **Size limit** — Page components must stay under a configurable line count (default: 75 lines). -2. **No data hooks** — Page components must not use `useState`, `useQuery`, `useMutation`, or other data-fetching hooks directly. +1. **Size limit**: Page components must stay under a configurable line count (default: 75 lines). +2. **No data hooks**: Page components must not use `useState`, `useQuery`, `useMutation`, or other data-fetching hooks directly. ## Examples of **incorrect** code diff --git a/docs/src/content/docs/examples/spdx-license-headers.mdx b/docs/src/content/docs/examples/spdx-license-headers.mdx index 3dd1c007..250ce1e3 100644 --- a/docs/src/content/docs/examples/spdx-license-headers.mdx +++ b/docs/src/content/docs/examples/spdx-license-headers.mdx @@ -7,7 +7,7 @@ Ensure every source file declares its license with a machine-readable SPDX ident ## Rule details -Open-source projects benefit from per-file license declarations — they survive file extraction, bundling, and copy-paste scenarios where the root LICENSE file is not present. This rule verifies that every TypeScript source file starts with the standard SPDX header comment. +Open-source projects benefit from per-file license declarations. They survive file extraction, bundling, and copy-paste scenarios where the root LICENSE file is not present. This rule verifies that every TypeScript source file starts with the standard SPDX header comment. ## Examples of **incorrect** code diff --git a/docs/src/content/docs/examples/wrapper-enforcement.mdx b/docs/src/content/docs/examples/wrapper-enforcement.mdx index a93f9068..326dee87 100644 --- a/docs/src/content/docs/examples/wrapper-enforcement.mdx +++ b/docs/src/content/docs/examples/wrapper-enforcement.mdx @@ -52,7 +52,7 @@ export default { for (const m of fileMatches) { ctx.report.violation({ message: - "Do not access process.platform directly — use isWindows(), isMacOS(), or isLinux() from src/helpers/platform.ts instead.", + "Do not access process.platform directly. Use isWindows(), isMacOS(), isLinux(), or getPlatformInfo() from src/helpers/platform.ts instead.", file: m.file, line: m.line, fix: 'Import { isWindows } from "../helpers/platform" and use it instead of process.platform', diff --git a/docs/src/content/docs/getting-started/installation.mdx b/docs/src/content/docs/getting-started/installation.mdx index 1debc73b..b543725b 100644 --- a/docs/src/content/docs/getting-started/installation.mdx +++ b/docs/src/content/docs/getting-started/installation.mdx @@ -5,7 +5,7 @@ description: Install the Archgate CLI on macOS, Linux, or Windows via a one-line ## Install standalone (recommended) -The fastest way to install Archgate — no Node.js or package manager required: +The fastest way to install Archgate. No Node.js or package manager required: ```bash # macOS / Linux @@ -49,7 +49,7 @@ yarn global add archgate pnpm add -g archgate ``` -This installs a lightweight wrapper that delegates to a platform-specific binary. The CLI itself is a standalone binary compiled with Bun — Node.js is only needed for the npm/yarn/pnpm wrapper. +This installs a lightweight wrapper that delegates to a platform-specific binary. The CLI itself is a standalone binary compiled with Bun. Node.js is only needed for the npm/yarn/pnpm wrapper. ## Install as a dev dependency @@ -175,7 +175,7 @@ You should see the installed version printed to stdout. ## Install via proto -If you use [proto](https://moonrepo.dev/proto) (moonrepo's toolchain manager), you can install Archgate directly as a proto plugin — no Node.js or npm required. +If you use [proto](https://moonrepo.dev/proto) (moonrepo's toolchain manager), you can install Archgate directly as a proto plugin. No Node.js or npm required. Add the plugin to your `.prototools`: diff --git a/docs/src/content/docs/getting-started/quick-start.mdx b/docs/src/content/docs/getting-started/quick-start.mdx index d9a7b216..7844f5c0 100644 --- a/docs/src/content/docs/getting-started/quick-start.mdx +++ b/docs/src/content/docs/getting-started/quick-start.mdx @@ -53,11 +53,11 @@ files: ["src/**/*.ts"] --- ``` -- **id** — Unique identifier. Convention is `ARCH-NNN` but any string works. -- **title** — Human-readable name for the decision. -- **domain** — Groups related ADRs together (`architecture`, `backend`, `frontend`, `data`, or `general`). -- **rules** — Set to `true` if this ADR has a companion `.rules.ts` file with automated checks. -- **files** — Optional glob patterns that scope which files the rules apply to. +- **id**: Unique identifier. Convention is `ARCH-NNN` but any string works. +- **title**: Human-readable name for the decision. +- **domain**: Groups related ADRs together (`architecture`, `backend`, `frontend`, `data`, or `general`). +- **rules**: Set to `true` if this ADR has a companion `.rules.ts` file with automated checks. +- **files**: Optional glob patterns that scope which files the rules apply to. Below the frontmatter, write the decision in markdown. Archgate does not enforce a specific section structure, but the recommended sections are: Context, Decision, Do's and Don'ts, Consequences, Compliance, and References. @@ -92,9 +92,9 @@ export default { Each rule has a unique key, a description, and an async `check` function. Inside `check`, you have access to: -- **`ctx.scopedFiles`** — Files matching the ADR's `files` glob patterns. -- **`ctx.grep(file, pattern)`** — Search a file for regex matches, returning file paths and line numbers. -- **`ctx.report.violation()`** — Report a violation with a message, file path, line number, and optional fix suggestion. +- **`ctx.scopedFiles`**: Files matching the ADR's `files` glob patterns. +- **`ctx.grep(file, pattern)`**: Search a file for regex matches, returning file paths and line numbers. +- **`ctx.report.violation()`**: Report a violation with a message, file path, line number, and optional fix suggestion. ## 5. Run checks @@ -124,22 +124,22 @@ Now that you have a working setup, dive deeper: **Understand the concepts:** -- [ADRs](/concepts/adrs/) — What Architecture Decision Records are and how Archgate uses them. -- [Rules](/concepts/rules/) — How companion `.rules.ts` files turn decisions into automated checks. -- [Domains](/concepts/domains/) — How domains group related ADRs and scope file matching. +- [ADRs](/concepts/adrs/): What Architecture Decision Records are and how Archgate uses them. +- [Rules](/concepts/rules/): How companion `.rules.ts` files turn decisions into automated checks. +- [Domains](/concepts/domains/): How domains group related ADRs and scope file matching. **Write your own:** -- [Writing ADRs](/guides/writing-adrs/) — Learn the full ADR format and best practices for writing effective decisions. -- [Writing Rules](/guides/writing-rules/) — Explore the rule API, advanced patterns, and how to test your rules. -- [Common Rule Patterns](/examples/common-rule-patterns/) — Copy-pasteable patterns for dependency checks, naming conventions, and more. +- [Writing ADRs](/guides/writing-adrs/): Learn the full ADR format and best practices for writing effective decisions. +- [Writing Rules](/guides/writing-rules/): Explore the rule API, advanced patterns, and how to test your rules. +- [Common Rule Patterns](/examples/common-rule-patterns/): Copy-pasteable patterns for dependency checks, naming conventions, and more. **Integrate into your workflow:** -- [CI Integration](/guides/ci-integration/) — Wire `archgate check` into GitHub Actions, GitLab CI, or any pipeline. -- [Pre-commit Hooks](/guides/pre-commit-hooks/) — Run checks locally before every commit. -- [Claude Code Plugin](/guides/claude-code-plugin/) — Give AI agents architecture-aware guardrails with role-based skills. -- [Cursor Integration](/guides/cursor-integration/) — Use Archgate with Cursor IDE for AI-assisted development. +- [CI Integration](/guides/ci-integration/): Wire `archgate check` into GitHub Actions, GitLab CI, or any pipeline. +- [Pre-commit Hooks](/guides/pre-commit-hooks/): Run checks locally before every commit. +- [Claude Code Plugin](/guides/claude-code-plugin/): Give AI agents architecture-aware guardrails with role-based skills. +- [Cursor Integration](/guides/cursor-integration/): Use Archgate with Cursor IDE for AI-assisted development. :::tip[Editor plugins (beta)] Want AI agents that automatically read your ADRs before coding? Run `archgate login` to sign up and authenticate, then run `archgate init --install-plugin` to set up the plugin. diff --git a/docs/src/content/docs/guides/ci-integration.mdx b/docs/src/content/docs/guides/ci-integration.mdx index 4cf681d8..bb3eadfe 100644 --- a/docs/src/content/docs/guides/ci-integration.mdx +++ b/docs/src/content/docs/guides/ci-integration.mdx @@ -24,7 +24,7 @@ jobs: - uses: archgate/check-action@v1 ``` -That's it — no Node.js setup, no install step. If any rule reports a violation with `error` severity, the job fails with exit code 1. +That's it. No Node.js setup, no install step. If any rule reports a violation with `error` severity, the job fails with exit code 1. ### Pin a version @@ -84,7 +84,7 @@ Use `--ci` to output violations as GitHub Actions workflow annotations. These ap The `--ci` flag produces `::error` and `::warning` annotations in the format GitHub Actions expects. Each annotation includes the ADR ID, rule ID, file path, and line number. :::note -The `archgate/check-action` passes `--ci` automatically — you only need this flag when running `archgate check` manually. +The `archgate/check-action` passes `--ci` automatically. You only need this flag when running `archgate check` manually. ::: ## Machine-readable output @@ -236,7 +236,7 @@ jobs: - run: ~/.archgate/bin/archgate check --ci ``` -This works in any environment with `curl` and `tar` — no runtime dependencies needed. You can pin a version with the `ARCHGATE_VERSION` environment variable: +This works in any environment with `curl` and `tar`, no runtime dependencies needed. You can pin a version with the `ARCHGATE_VERSION` environment variable: ```yaml - run: curl -fsSL https://raw.githubusercontent.com/archgate/cli/main/install.sh | ARCHGATE_VERSION=v0.11.2 sh diff --git a/docs/src/content/docs/guides/importing-adrs.mdx b/docs/src/content/docs/guides/importing-adrs.mdx index 7909dac7..fb3bc272 100644 --- a/docs/src/content/docs/guides/importing-adrs.mdx +++ b/docs/src/content/docs/guides/importing-adrs.mdx @@ -89,7 +89,7 @@ This reads `.archgate/imports.json` and displays each source, version, and the A ## How ID remapping works -When you import ADRs, the original IDs are **remapped** to match your project's domain prefixes. Each ADR's `domain` field determines which prefix it gets — for example, an ADR with `domain: frontend` becomes `FE-XXX`, while one with `domain: backend` becomes `BE-XXX`. Each domain has its own counter, so importing a pack with mixed domains produces correctly prefixed IDs without collisions. +When you import ADRs, the original IDs are **remapped** to match your project's domain prefixes. Each ADR's `domain` field determines which prefix it gets. For example, an ADR with `domain: frontend` becomes `FE-XXX`, while one with `domain: backend` becomes `BE-XXX`. Each domain has its own counter, so importing a pack with mixed domains produces correctly prefixed IDs without collisions. For example, importing a pack with three frontend ADRs and two backend ADRs into a project that already has `FE-001` and `BE-001` produces: @@ -119,7 +119,7 @@ Every import is recorded in `.archgate/imports.json`: } ``` -This manifest lets you track provenance — where each imported ADR came from and when. Commit it to version control alongside your ADRs. +This manifest lets you track provenance: where each imported ADR came from and when. Commit it to version control alongside your ADRs. ## Command options reference diff --git a/docs/src/content/docs/guides/opencode-integration.mdx b/docs/src/content/docs/guides/opencode-integration.mdx index 4ecd938a..b94673ed 100644 --- a/docs/src/content/docs/guides/opencode-integration.mdx +++ b/docs/src/content/docs/guides/opencode-integration.mdx @@ -17,7 +17,7 @@ archgate init --editor opencode The opencode agent bundle is currently in beta. Run `archgate login` to sign up and authenticate. ::: -Unlike the Claude Code or Cursor integrations, the opencode agents are **not written to your project tree**. They are installed at the user scope instead — so they live on your machine, not in your repository, and are available across every project you open with opencode. +Unlike the Claude Code or Cursor integrations, the opencode agents are **not written to your project tree**. They are installed at the user scope instead, so they live on your machine, not in your repository, and are available across every project you open with opencode. opencode uses the XDG Base Directory convention on every platform (via the `xdg-basedir` package), so the install location resolves to `$XDG_CONFIG_HOME/opencode/agents/` when that variable is set, and falls back to `$HOME/.config/opencode/agents/` otherwise. That means Windows installs land under `C:\Users\\.config\opencode\agents\`, not under `%APPDATA%`: @@ -29,7 +29,7 @@ opencode uses the XDG Base Directory convention on every platform (via the `xdg- ### Authenticated install :::caution[opencode must be installed first] -The install step only runs when the `opencode` CLI is on your PATH. Archgate needs to confirm opencode is present before writing files into its user-scope config directory — otherwise the agents would sit in a location nothing reads. Install opencode from [opencode.ai](https://opencode.ai/docs/) first, then re-run `archgate init --editor opencode` or `archgate plugin install --editor opencode`. +The install step only runs when the `opencode` CLI is on your PATH. Archgate needs to confirm opencode is present before writing files into its user-scope config directory. Otherwise the agents would sit in a location nothing reads. Install opencode from [opencode.ai](https://opencode.ai/docs/) first, then re-run `archgate init --editor opencode` or `archgate plugin install --editor opencode`. ::: If you have logged in via `archgate login` **and** `opencode` is on your PATH, the init command downloads and installs the Archgate agent bundle for opencode. The bundle provides a pre-built primary agent and four subagents that give opencode's AI a full guardrails workflow. @@ -59,7 +59,7 @@ The install step downloads an authenticated tarball from the Archgate plugins se | `/archgate-adr-author.md` | Subagent that creates and edits ADRs following project conventions | | `/archgate-cli-reference.md` | Internal reference subagent with the Archgate CLI command guide (hidden) | -`.archgate/adrs/` and `.archgate/lint/` are still created in your project as usual — only the opencode-specific agent files live outside the project tree. +`.archgate/adrs/` and `.archgate/lint/` are still created in your project as usual. Only the opencode-specific agent files live outside the project tree. ## What the bundle provides diff --git a/docs/src/content/docs/guides/writing-rules.mdx b/docs/src/content/docs/guides/writing-rules.mdx index f3ef0532..3ce4696b 100644 --- a/docs/src/content/docs/guides/writing-rules.mdx +++ b/docs/src/content/docs/guides/writing-rules.mdx @@ -309,20 +309,20 @@ There are two ways to handle exceptions in Archgate: **engine-level suppression* Archgate supports inline `archgate-ignore` comments that suppress violations without modifying the rule itself. The engine parses these comments and filters matching violations before reporting. -**Next-line suppression** — suppresses the violation on the immediately following line: +**Next-line suppression** suppresses the violation on the immediately following line: ```typescript // archgate-ignore ARCH-006/no-unapproved-deps legacy dep, migration planned for Q3 import chalk from "chalk"; ``` -**File-level suppression** — suppresses all matching violations anywhere in the file: +**File-level suppression** suppresses all matching violations anywhere in the file: ```typescript // archgate-ignore-file ARCH-005/test-mirrors-src generated file, no manual test ``` -**Multiple rules** — stack comments to suppress more than one rule on the same line: +**Multiple rules**: stack comments to suppress more than one rule on the same line: ```typescript // archgate-ignore ARCH-006/no-unapproved-deps legacy dep @@ -332,7 +332,7 @@ import chalk from "chalk"; Consecutive suppression comments all target the first non-suppression line that follows. -The format is `ADR-ID/rule-id` followed by a reason. The reason is **required** — a suppression without a reason is ignored and produces a warning: +The format is `ADR-ID/rule-id` followed by a reason. The reason is **required**. A suppression without a reason is ignored and produces a warning: ``` [suppression] Suppression for ARCH-006/no-unapproved-deps is missing a reason src/foo.ts:1 @@ -383,10 +383,10 @@ import { useNavigate } from "react-router"; | `archgate-ignore` | Ad-hoc exceptions for any rule | Developer using the rule | | Custom directive | Domain-specific opt-outs with structured reasons | Rule author | -Use `archgate-ignore` when a developer needs to suppress a one-off violation. Use custom directives when the opt-out is a first-class concept in your rule's domain — for example, marking a component as intentionally unpaired, or a file as auto-generated. +Use `archgate-ignore` when a developer needs to suppress a one-off violation. Use custom directives when the opt-out is a first-class concept in your rule's domain, for example, marking a component as intentionally unpaired, or a file as auto-generated. ## Next steps -- [Common Rule Patterns](/examples/common-rule-patterns/) — Copy-pasteable patterns organized by category: dependency management, import restrictions, file structure, code quality, database schema, and architecture boundaries. -- [Rule API Reference](/reference/rule-api/) — Full reference for all rule API types and functions. -- [CI Integration](/guides/ci-integration/) — Wire `archgate check` into your pipeline to enforce rules on every PR. +- [Common Rule Patterns](/examples/common-rule-patterns/): Copy-pasteable patterns organized by category: dependency management, import restrictions, file structure, code quality, database schema, and architecture boundaries. +- [Rule API Reference](/reference/rule-api/): Full reference for all rule API types and functions. +- [CI Integration](/guides/ci-integration/): Wire `archgate check` into your pipeline to enforce rules on every PR. diff --git a/docs/src/content/docs/index.mdx b/docs/src/content/docs/index.mdx index 80826749..449458b3 100644 --- a/docs/src/content/docs/index.mdx +++ b/docs/src/content/docs/index.mdx @@ -22,9 +22,9 @@ import CodeShowcase from "../../components/CodeShowcase.astro"; Archgate has two layers that work together: -1. **ADRs as documents** — Markdown files with YAML frontmatter that describe architectural decisions in plain language. Humans read them. AI agents read them. Everyone stays aligned. +1. **ADRs as documents**: Markdown files with YAML frontmatter that describe architectural decisions in plain language. Humans read them. AI agents read them. Everyone stays aligned. -2. **ADRs as rules** — Companion `.rules.ts` files with automated checks written in TypeScript. They run against your codebase and report violations with file paths and line numbers. +2. **ADRs as rules**: Companion `.rules.ts` files with automated checks written in TypeScript. They run against your codebase and report violations with file paths and line numbers. Archgate governs its own development. The same tool that checks your code checks ours. Our own ADRs enforce command structure, error handling, output - formatting, testing, and more — [see them on + formatting, testing, and more. [See them on GitHub](https://github.com/archgate/cli/tree/main/.archgate/adrs). diff --git a/docs/src/content/docs/nb/concepts/domains.mdx b/docs/src/content/docs/nb/concepts/domains.mdx index 82cad8f0..3b6c03c7 100644 --- a/docs/src/content/docs/nb/concepts/domains.mdx +++ b/docs/src/content/docs/nb/concepts/domains.mdx @@ -97,7 +97,7 @@ Når du er i tvil mellom `architecture` og et spesifikt domene, foretrekk det me ## Egendefinerte domener -Når de fem innebygde domenene virkelig ikke passer for en kategori av beslutninger -- for eksempel `security`, `ml-ops` eller `compliance` -- kan du registrere et egendefinert domene via CLI-en: +Når de fem innebygde domenene virkelig ikke passer for en kategori av beslutninger (for eksempel `security`, `ml-ops` eller `compliance`), kan du registrere et egendefinert domene via CLI-en: ```bash # Se hva som for øyeblikket er gjenkjent i dette prosjektet diff --git a/docs/src/content/docs/nb/concepts/rules.mdx b/docs/src/content/docs/nb/concepts/rules.mdx index 554a7559..4cc74762 100644 --- a/docs/src/content/docs/nb/concepts/rules.mdx +++ b/docs/src/content/docs/nb/concepts/rules.mdx @@ -152,7 +152,7 @@ Når denne regelen kjøres mot en fil som inneholder `import { readFileSync } fr ``` 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. + 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" ``` diff --git a/docs/src/content/docs/nb/examples/clean-architecture-layers.mdx b/docs/src/content/docs/nb/examples/clean-architecture-layers.mdx index 3694bba8..e376e85d 100644 --- a/docs/src/content/docs/nb/examples/clean-architecture-layers.mdx +++ b/docs/src/content/docs/nb/examples/clean-architecture-layers.mdx @@ -27,7 +27,7 @@ using StavangerChallenge.API; // ✗ Application → API ```csharp title="Domain/Entities/User.cs" namespace StavangerChallenge.Domain.Entities; -// No external dependencies — pure domain logic +// No external dependencies, pure domain logic ``` ```csharp title="Application/Services/UserService.cs" diff --git a/docs/src/content/docs/nb/examples/license-compatibility.mdx b/docs/src/content/docs/nb/examples/license-compatibility.mdx index 31c68abf..2283d9dd 100644 --- a/docs/src/content/docs/nb/examples/license-compatibility.mdx +++ b/docs/src/content/docs/nb/examples/license-compatibility.mdx @@ -52,7 +52,7 @@ function isAllowed(license: string | undefined): boolean { if (!license) return false; if (ALLOWED_LICENSES.has(license)) return true; - // Handle SPDX OR expressions — at least one option must be allowed + // Handle SPDX OR expressions: at least one option must be allowed const normalized = license.trim().replace(/^\(/u, "").replace(/\)$/u, ""); if (ALLOWED_LICENSES.has(normalized)) return true; @@ -84,7 +84,7 @@ export default { description: "All dependencies (including transitive) must use permissive licenses", async check(ctx) { - // Scan ALL packages in node_modules — direct AND transitive. + // Scan ALL packages in node_modules, direct AND transitive. // Brace expansion covers both regular and scoped packages. const pkgFiles = await ctx.glob("node_modules/{*,@*/*}/package.json"); diff --git a/docs/src/content/docs/nb/examples/monorepo-task-runner.mdx b/docs/src/content/docs/nb/examples/monorepo-task-runner.mdx index ff8b14b6..51ddd2db 100644 --- a/docs/src/content/docs/nb/examples/monorepo-task-runner.mdx +++ b/docs/src/content/docs/nb/examples/monorepo-task-runner.mdx @@ -47,7 +47,7 @@ export default { rules: { "no-package-scripts": { description: - "package.json must not have scripts — use the task runner instead", + "package.json must not have scripts. Use the task runner instead", async check(ctx) { const packageJsonFiles = [ ...(await ctx.glob("packages/*/package.json")), @@ -60,7 +60,7 @@ export default { }; if (pkg.scripts && Object.keys(pkg.scripts).length > 0) { ctx.report.violation({ - message: `${file}: has "scripts" field — use task runner config instead`, + message: `${file}: has "scripts" field. Use task runner config instead`, file, fix: 'Move scripts to the task runner config and remove "scripts" from package.json', }); diff --git a/docs/src/content/docs/nb/examples/no-banned-api.mdx b/docs/src/content/docs/nb/examples/no-banned-api.mdx index 437fab52..88958cef 100644 --- a/docs/src/content/docs/nb/examples/no-banned-api.mdx +++ b/docs/src/content/docs/nb/examples/no-banned-api.mdx @@ -54,7 +54,7 @@ export default { for (const m of fileMatches) { ctx.report.violation({ message: - "Do not use Bun.$ template literals — they hang on Windows. Use Bun.spawn instead.", + "Do not use Bun.$ template literals. They hang on Windows. Use Bun.spawn instead.", file: m.file, line: m.line, fix: "Replace Bun.$`cmd args` with Bun.spawn(['cmd', 'args'], { stdout: 'pipe', stderr: 'pipe' })", @@ -72,7 +72,7 @@ export default { for (const m of fileMatches) { ctx.report.violation({ message: - 'Do not import $ from "bun" — the shell API hangs on Windows. Use Bun.spawn instead.', + 'Do not import $ from "bun". The shell API hangs on Windows. Use Bun.spawn instead.', file: m.file, line: m.line, fix: "Remove the $ import and replace shell calls with Bun.spawn", @@ -88,7 +88,7 @@ export default { for (const m of fileMatches) { ctx.report.violation({ message: - "Do not use $` template literals — they hang on Windows. Use Bun.spawn instead.", + "Do not use $` template literals. They hang on Windows. Use Bun.spawn instead.", file: m.file, line: m.line, fix: "Replace $`cmd args` with Bun.spawn(['cmd', 'args'], { stdout: 'pipe', stderr: 'pipe' })", diff --git a/docs/src/content/docs/nb/examples/no-banned-imports.mdx b/docs/src/content/docs/nb/examples/no-banned-imports.mdx index 5b9391e6..9d8d0b16 100644 --- a/docs/src/content/docs/nb/examples/no-banned-imports.mdx +++ b/docs/src/content/docs/nb/examples/no-banned-imports.mdx @@ -7,7 +7,7 @@ Forhindre bruk av forbudte biblioteker og krev anbefalte alternativer. ## Regeldetaljer -Team forbyr ofte tunge eller utdaterte biblioteker til fordel for lettere eller native alternativer. Denne regelen bruker en datadrevet konfigurasjon -- en array med objekter som spesifiserer regex-mønsteret, biblioteknavnet og det anbefalte alternativet. Å legge til et nytt forbud er en endring på en linje. +Team forbyr ofte tunge eller utdaterte biblioteker til fordel for lettere eller native alternativer. Denne regelen bruker en datadrevet konfigurasjon: en array med objekter som spesifiserer regex-mønsteret, biblioteknavnet og det anbefalte alternativet. Å legge til et nytt forbud er en endring på en linje. ## Eksempler på **feil** kode diff --git a/docs/src/content/docs/nb/examples/no-barrel-files.mdx b/docs/src/content/docs/nb/examples/no-barrel-files.mdx index 6b25c327..c012a71c 100644 --- a/docs/src/content/docs/nb/examples/no-barrel-files.mdx +++ b/docs/src/content/docs/nb/examples/no-barrel-files.mdx @@ -3,7 +3,7 @@ title: no-barrel-files description: Oppdag og forby barrel-filer (index.ts med kun re-eksporter) for å kreve direkte importer og forbedre tree-shaking. --- -Oppdag og forby barrel-filer -- `index.ts`-filer som kun inneholder re-eksporter og ingen logikk. +Oppdag og forby barrel-filer: `index.ts`-filer som kun inneholder re-eksporter og ingen logikk. ## Regeldetaljer diff --git a/docs/src/content/docs/nb/examples/no-todo-comments.mdx b/docs/src/content/docs/nb/examples/no-todo-comments.mdx index 475322e6..94d7c56d 100644 --- a/docs/src/content/docs/nb/examples/no-todo-comments.mdx +++ b/docs/src/content/docs/nb/examples/no-todo-comments.mdx @@ -41,7 +41,7 @@ export default { ); for (const match of matches) { ctx.report.warning({ - message: `${match.content.trim()} — resolve before merging`, + message: `${match.content.trim()} (resolve before merging)`, file: match.file, line: match.line, }); diff --git a/docs/src/content/docs/nb/examples/no-unapproved-deps.mdx b/docs/src/content/docs/nb/examples/no-unapproved-deps.mdx index 3af3eb22..b0253393 100644 --- a/docs/src/content/docs/nb/examples/no-unapproved-deps.mdx +++ b/docs/src/content/docs/nb/examples/no-unapproved-deps.mdx @@ -49,7 +49,7 @@ export default { try { pkg = (await ctx.readJSON("package.json")) as typeof pkg; } catch { - return; // No package.json — nothing to check + return; // No package.json, nothing to check } const deps = Object.keys(pkg.dependencies ?? {}); diff --git a/docs/src/content/docs/nb/examples/page-component-constraints.mdx b/docs/src/content/docs/nb/examples/page-component-constraints.mdx index dfba40ab..85d8fd1d 100644 --- a/docs/src/content/docs/nb/examples/page-component-constraints.mdx +++ b/docs/src/content/docs/nb/examples/page-component-constraints.mdx @@ -3,7 +3,7 @@ title: page-component-constraints description: Håndhev at sidekomponenter er tynne layout-innpakninger ved å begrense størrelsen og forby datahentings-hooks. --- -Håndhev at sidekomponenter er tynne layout-innpakninger -- små i størrelse og fri for datahentingslogikk. +Håndhev at sidekomponenter er tynne layout-innpakninger: små i størrelse og fri for datahentingslogikk. ## Regeldetaljer diff --git a/docs/src/content/docs/nb/examples/spdx-license-headers.mdx b/docs/src/content/docs/nb/examples/spdx-license-headers.mdx index 1f95496a..557ca1ca 100644 --- a/docs/src/content/docs/nb/examples/spdx-license-headers.mdx +++ b/docs/src/content/docs/nb/examples/spdx-license-headers.mdx @@ -7,7 +7,7 @@ Sørg for at hver kildefil deklarerer lisensen sin med en maskinlesbar SPDX-iden ## Regeldetaljer -Åpen kildekode-prosjekter drar nytte av lisensdeklarasjoner per fil -- de overlever filutpakking, bunting og kopier-og-lim-scenarier der rot-LICENSE-filen ikke er til stede. Denne regelen verifiserer at hver TypeScript-kildefil starter med standard SPDX-hodekommentar. +Åpen kildekode-prosjekter drar nytte av lisensdeklarasjoner per fil. De overlever filutpakking, bunting og kopier-og-lim-scenarier der rot-LICENSE-filen ikke er til stede. Denne regelen verifiserer at hver TypeScript-kildefil starter med standard SPDX-hodekommentar. ## Eksempler på **feil** kode diff --git a/docs/src/content/docs/nb/examples/wrapper-enforcement.mdx b/docs/src/content/docs/nb/examples/wrapper-enforcement.mdx index de6ed302..875590f3 100644 --- a/docs/src/content/docs/nb/examples/wrapper-enforcement.mdx +++ b/docs/src/content/docs/nb/examples/wrapper-enforcement.mdx @@ -52,7 +52,7 @@ export default { for (const m of fileMatches) { ctx.report.violation({ message: - "Do not access process.platform directly — use isWindows(), isMacOS(), or isLinux() from src/helpers/platform.ts instead.", + "Do not access process.platform directly. Use isWindows(), isMacOS(), isLinux(), or getPlatformInfo() from src/helpers/platform.ts instead.", file: m.file, line: m.line, fix: 'Import { isWindows } from "../helpers/platform" and use it instead of process.platform', diff --git a/docs/src/content/docs/nb/getting-started/installation.mdx b/docs/src/content/docs/nb/getting-started/installation.mdx index ddb4a086..d25e75c5 100644 --- a/docs/src/content/docs/nb/getting-started/installation.mdx +++ b/docs/src/content/docs/nb/getting-started/installation.mdx @@ -5,7 +5,7 @@ description: Installer Archgate CLI på macOS, Linux eller Windows via en enlinj ## Frittstående installasjon (anbefalt) -Den raskeste måten å installere Archgate på -- ingen Node.js eller pakkebehandler nødvendig: +Den raskeste måten å installere Archgate på. Ingen Node.js eller pakkebehandler nødvendig: ```bash # macOS / Linux diff --git a/docs/src/content/docs/nb/getting-started/quick-start.mdx b/docs/src/content/docs/nb/getting-started/quick-start.mdx index 43ea1df0..043dbc8f 100644 --- a/docs/src/content/docs/nb/getting-started/quick-start.mdx +++ b/docs/src/content/docs/nb/getting-started/quick-start.mdx @@ -53,11 +53,11 @@ files: ["src/**/*.ts"] --- ``` -- **id** -- Unik identifikator. Konvensjonen er `ARCH-NNN`, men enhver streng fungerer. -- **title** -- Lesbart navn for beslutningen. -- **domain** -- Grupperer relaterte ADR-er (`architecture`, `backend`, `frontend`, `data` eller `general`). -- **rules** -- Sett til `true` hvis denne ADR-en har en tilhørende `.rules.ts`-fil med automatiserte sjekker. -- **files** -- Valgfrie glob-mønstre som begrenser hvilke filer reglene gjelder for. +- **id**: Unik identifikator. Konvensjonen er `ARCH-NNN`, men enhver streng fungerer. +- **title**: Lesbart navn for beslutningen. +- **domain**: Grupperer relaterte ADR-er (`architecture`, `backend`, `frontend`, `data` eller `general`). +- **rules**: Sett til `true` hvis denne ADR-en har en tilhørende `.rules.ts`-fil med automatiserte sjekker. +- **files**: Valgfrie glob-mønstre som begrenser hvilke filer reglene gjelder for. Under frontmatter skriver du beslutningen i markdown. Archgate pålegger ikke en bestemt seksjonsstruktur, men de anbefalte seksjonene er: Context, Decision, Do's and Don'ts, Consequences, Compliance og References. diff --git a/docs/src/content/docs/nb/guides/ci-integration.mdx b/docs/src/content/docs/nb/guides/ci-integration.mdx index 62abea1b..7bf61ed7 100644 --- a/docs/src/content/docs/nb/guides/ci-integration.mdx +++ b/docs/src/content/docs/nb/guides/ci-integration.mdx @@ -24,7 +24,7 @@ jobs: - uses: archgate/check-action@v1 ``` -Det er alt -- ingen Node.js-oppsett, ingen installasjonssteg. Hvis en regel rapporterer et brudd med `error`-alvorlighetsgrad, feiler jobben med exit-kode 1. +Det er alt. Ingen Node.js-oppsett, ingen installasjonssteg. Hvis en regel rapporterer et brudd med `error`-alvorlighetsgrad, feiler jobben med exit-kode 1. ### Fest en versjon diff --git a/docs/src/content/docs/nb/guides/importing-adrs.mdx b/docs/src/content/docs/nb/guides/importing-adrs.mdx index d11025f5..72d27b4e 100644 --- a/docs/src/content/docs/nb/guides/importing-adrs.mdx +++ b/docs/src/content/docs/nb/guides/importing-adrs.mdx @@ -89,7 +89,7 @@ Dette leser `.archgate/imports.json` og viser hver kilde, versjon og ADR-ID-ene ## Hvordan ID-nytilordning fungerer -Når du importerer ADR-er, blir de opprinnelige ID-ene **nytilordnet** for å matche prosjektets domeneprefikser. Hver ADRs `domain`-felt bestemmer hvilket prefiks den får -- for eksempel blir en ADR med `domain: frontend` til `FE-XXX`, mens en med `domain: backend` blir `BE-XXX`. Hvert domene har sin egen teller, så import av en pakke med blandede domener produserer korrekt prefiksede ID-er uten kollisjoner. +Når du importerer ADR-er, blir de opprinnelige ID-ene **nytilordnet** for å matche prosjektets domeneprefikser. Hver ADRs `domain`-felt bestemmer hvilket prefiks den får. For eksempel blir en ADR med `domain: frontend` til `FE-XXX`, mens en med `domain: backend` blir `BE-XXX`. Hvert domene har sin egen teller, så import av en pakke med blandede domener produserer korrekt prefiksede ID-er uten kollisjoner. For eksempel, når du importerer en pakke med tre frontend-ADR-er og to backend-ADR-er inn i et prosjekt som allerede har `FE-001` og `BE-001`, produseres: diff --git a/docs/src/content/docs/nb/guides/opencode-integration.mdx b/docs/src/content/docs/nb/guides/opencode-integration.mdx index 99c1d28a..931d9622 100644 --- a/docs/src/content/docs/nb/guides/opencode-integration.mdx +++ b/docs/src/content/docs/nb/guides/opencode-integration.mdx @@ -17,7 +17,7 @@ archgate init --editor opencode opencode-agentpakken er for øyeblikket i beta. Kjør `archgate login` for å registrere deg og autentisere. ::: -I motsetning til Claude Code- eller Cursor-integrasjonene skrives opencode-agentene **ikke til prosjekttreet ditt**. De installeres i stedet på brukernivå -- så de bor på maskinen din, ikke i repositoriet ditt, og er tilgjengelige på tvers av alle prosjekter du åpner med opencode. +I motsetning til Claude Code- eller Cursor-integrasjonene skrives opencode-agentene **ikke til prosjekttreet ditt**. De installeres i stedet på brukernivå, så de bor på maskinen din, ikke i repositoriet ditt, og er tilgjengelige på tvers av alle prosjekter du åpner med opencode. opencode bruker XDG Base Directory-konvensjonen på alle plattformer (via `xdg-basedir`-pakken), så installasjonsplasseringen resolves til `$XDG_CONFIG_HOME/opencode/agents/` når den variabelen er satt, og faller tilbake til `$HOME/.config/opencode/agents/` ellers. Det betyr at Windows-installasjoner havner under `C:\Users\\.config\opencode\agents\`, ikke under `%APPDATA%`: diff --git a/docs/src/content/docs/nb/guides/writing-rules.mdx b/docs/src/content/docs/nb/guides/writing-rules.mdx index 28405801..2eaa9a4c 100644 --- a/docs/src/content/docs/nb/guides/writing-rules.mdx +++ b/docs/src/content/docs/nb/guides/writing-rules.mdx @@ -309,20 +309,20 @@ Det finnes to måter å håndtere unntak i Archgate: **undertrykkelse på motorn Archgate støtter inline `archgate-ignore`-kommentarer som undertrykker brudd uten å endre selve regelen. Motoren analyserer disse kommentarene og filtrerer matchende brudd før rapportering. -**Neste-linje-undertrykkelse** — undertrykker bruddet på den umiddelbart følgende linjen: +**Neste-linje-undertrykkelse**: undertrykker bruddet på den umiddelbart følgende linjen: ```typescript // archgate-ignore ARCH-006/no-unapproved-deps legacy-avhengighet, migrering planlagt for Q3 import chalk from "chalk"; ``` -**Filnivå-undertrykkelse** — undertrykker alle matchende brudd hvor som helst i filen: +**Filnivå-undertrykkelse**: undertrykker alle matchende brudd hvor som helst i filen: ```typescript // archgate-ignore-file ARCH-005/test-mirrors-src generert fil, ingen manuell test ``` -**Flere regler** — stable kommentarer for å undertrykke mer enn én regel på samme linje: +**Flere regler**: stable kommentarer for å undertrykke mer enn én regel på samme linje: ```typescript // archgate-ignore ARCH-006/no-unapproved-deps legacy-avhengighet @@ -332,7 +332,7 @@ import chalk from "chalk"; Sammenhengende undertrykkelseskommentarer sikter alle mot den første ikke-undertrykkelseslinjen etter blokken. -Formatet er `ADR-ID/rule-id` etterfulgt av en begrunnelse. Begrunnelsen er **påkrevd** — en undertrykkelse uten begrunnelse ignoreres og gir en advarsel: +Formatet er `ADR-ID/rule-id` etterfulgt av en begrunnelse. Begrunnelsen er **påkrevd**. En undertrykkelse uten begrunnelse ignoreres og gir en advarsel: ``` [suppression] Suppression for ARCH-006/no-unapproved-deps is missing a reason src/foo.ts:1 @@ -383,7 +383,7 @@ import { useNavigate } from "react-router"; | `archgate-ignore` | Ad-hoc-unntak for alle regler | Utvikleren som bruker regelen | | Egendefinert direktiv | Domenespesifikke opt-outs med strukturerte begrunnelser | Regelforfatteren | -Bruk `archgate-ignore` når en utvikler trenger å undertrykke et engangsbrudd. Bruk egendefinerte direktiver når opt-outen er et førsteklasses konsept i regelens domene — for eksempel å markere en komponent som med vilje uparet, eller en fil som automatisk generert. +Bruk `archgate-ignore` når en utvikler trenger å undertrykke et engangsbrudd. Bruk egendefinerte direktiver når opt-outen er et førsteklasses konsept i regelens domene, for eksempel å markere en komponent som med vilje uparet, eller en fil som automatisk generert. ## Neste steg diff --git a/docs/src/content/docs/nb/index.mdx b/docs/src/content/docs/nb/index.mdx index da4dc9c3..c84a2366 100644 --- a/docs/src/content/docs/nb/index.mdx +++ b/docs/src/content/docs/nb/index.mdx @@ -22,9 +22,9 @@ import CodeShowcase from "../../../components/CodeShowcase.astro"; Archgate har to lag som fungerer sammen: -1. **ADR-er som dokumenter** — Markdown-filer med YAML-frontmatter som beskriver arkitekturbeslutninger i klartekst. Mennesker leser dem. AI-agenter leser dem. Alle holder seg samkjørte. +1. **ADR-er som dokumenter**: Markdown-filer med YAML-frontmatter som beskriver arkitekturbeslutninger i klartekst. Mennesker leser dem. AI-agenter leser dem. Alle holder seg samkjørte. -2. **ADR-er som regler** — Tilhørende `.rules.ts`-filer med automatiserte kontroller skrevet i TypeScript. De kjøres mot kodebasen din og rapporterer brudd med filstier og linjenumre. +2. **ADR-er som regler**: Tilhørende `.rules.ts`-filer med automatiserte kontroller skrevet i TypeScript. De kjøres mot kodebasen din og rapporterer brudd med filstier og linjenumre. Archgate styrer sin egen utvikling. Det samme verktøyet som sjekker koden din, sjekker vår. Våre egne ADR-er håndhever kommandostruktur, - feilhåndtering, utdataformatering, testing og mer — [se dem på + feilhåndtering, utdataformatering, testing og mer. [Se dem på GitHub](https://github.com/archgate/cli/tree/main/.archgate/adrs). ## Editorplugins -Archgate CLI fungerer frittstående, men **editorplugins** låser opp en fullstendig AI-guardrails-arbeidsflyt. Plugins gir AI-agenter rollebaserte ferdigheter slik at de leser ADR-ene dine før de koder, validerer etterpå og fanger opp nye mønstre for teamet ditt — automatisk. +Archgate CLI fungerer frittstående, men **editorplugins** låser opp en fullstendig AI-guardrails-arbeidsflyt. Plugins gir AI-agenter rollebaserte ferdigheter slik at de leser ADR-ene dine før de koder, validerer etterpå og fanger opp nye mønstre for teamet ditt, helt automatisk. diff --git a/docs/src/content/docs/nb/reference/adr-schema.mdx b/docs/src/content/docs/nb/reference/adr-schema.mdx index de631f29..4d21c800 100644 --- a/docs/src/content/docs/nb/reference/adr-schema.mdx +++ b/docs/src/content/docs/nb/reference/adr-schema.mdx @@ -295,7 +295,7 @@ Invalid ADR frontmatter in ARCH-001-example.md: - domain: domain must be lowercase kebab-case (e.g. 'backend', 'ml-ops') ``` -Merk: parseren aksepterer ethvert navn som matcher kebab-case-mønsteret. Om et spesifikt navn er "kjent" for prosjektet -- og dermed har et prefiks som `archgate adr create` kan bruke -- avhenger av det innebygde settet pluss eventuelle egendefinerte domener registrert via [`archgate adr domain add`](/reference/cli/adr/#archgate-adr-domain). Å opprette en ADR med et uregistrert domenenavn feiler med en "Unknown ADR domain"-feil som foreslår å kjøre `archgate adr domain add`. +Merk: parseren aksepterer ethvert navn som matcher kebab-case-mønsteret. Om et spesifikt navn er "kjent" for prosjektet (og dermed har et prefiks som `archgate adr create` kan bruke) avhenger av det innebygde settet pluss eventuelle egendefinerte domener registrert via [`archgate adr domain add`](/reference/cli/adr/#archgate-adr-domain). Å opprette en ADR med et uregistrert domenenavn feiler med en "Unknown ADR domain"-feil som foreslår å kjøre `archgate adr domain add`. ### Typefeil diff --git a/docs/src/content/docs/nb/reference/cli/adr.mdx b/docs/src/content/docs/nb/reference/cli/adr.mdx index 4ef3aa04..7ad6b945 100644 --- a/docs/src/content/docs/nb/reference/cli/adr.mdx +++ b/docs/src/content/docs/nb/reference/cli/adr.mdx @@ -152,7 +152,7 @@ archgate adr update \ Administrer egendefinerte ADR-domener. Egendefinerte domener er navn-til-ID-prefiks-tilordninger som lagres i `.archgate/config.json` og slås sammen med de fem innebygde (`backend`, `frontend`, `data`, `architecture`, `general`) ved lesing. -Bruk denne kommandoen når en beslutning ikke passer inn under noe innebygd domene. Før du registrerer et nytt, sjekk om beslutningen kan legges under et eksisterende domene -- innebygde er standarden, og et egendefinert domene bør bare introduseres når ingen innebygde passer. +Bruk denne kommandoen når en beslutning ikke passer inn under noe innebygd domene. Før du registrerer et nytt, sjekk om beslutningen kan legges under et eksisterende domene. Innebygde er standarden, og et egendefinert domene bør bare introduseres når ingen innebygde passer. ```bash archgate adr domain [options] diff --git a/docs/src/content/docs/nb/reference/cli/init.mdx b/docs/src/content/docs/nb/reference/cli/init.mdx index cb764302..1c72d39a 100644 --- a/docs/src/content/docs/nb/reference/cli/init.mdx +++ b/docs/src/content/docs/nb/reference/cli/init.mdx @@ -26,7 +26,7 @@ Når `--install-plugin` sendes med, installerer CLI-en Archgate-pluginen for den **Cursor:** Laster ned en autentisert tarball med skills, agenter og hooks i `~/.cursor/`. Skriver også `.cursor/hooks.json` til prosjektet for kompatibilitet med skyagenter. Ingen CLI-deteksjon nødvendig. -**opencode:** Krever at `opencode`-CLI-en er på din PATH -- hvis den ikke er det, hoppes installasjonen over og en melding ber deg installere opencode først. Når den er til stede, laster CLI-en ned en autentisert tarball med agentfiler fra Archgate plugins-tjenesten og pakker den ut i opencode-agentkatalogen for brukerskoopet (`$XDG_CONFIG_HOME/opencode/agents/`, faller tilbake til `$HOME/.config/opencode/agents/` på alle plattformer inkludert Windows -- opencode bruker XDG-stier via `xdg-basedir` og leser ikke `%APPDATA%`). Ingen filer skrives til prosjekttreet. Se [opencode-integrasjonsguiden](/guides/opencode-integration/) for detaljer. +**opencode:** Krever at `opencode`-CLI-en er på din PATH. Hvis den ikke er det, hoppes installasjonen over og en melding ber deg installere opencode først. Når den er til stede, laster CLI-en ned en autentisert tarball med agentfiler fra Archgate plugins-tjenesten og pakker den ut i opencode-agentkatalogen for brukerskoopet (`$XDG_CONFIG_HOME/opencode/agents/`, faller tilbake til `$HOME/.config/opencode/agents/` på alle plattformer inkludert Windows; opencode bruker XDG-stier via `xdg-basedir` og leser ikke `%APPDATA%`). Ingen filer skrives til prosjekttreet. Se [opencode-integrasjonsguiden](/guides/opencode-integration/) for detaljer. ## Utdata diff --git a/docs/src/content/docs/nb/reference/cli/plugin.mdx b/docs/src/content/docs/nb/reference/cli/plugin.mdx index 104994bf..d19139c4 100644 --- a/docs/src/content/docs/nb/reference/cli/plugin.mdx +++ b/docs/src/content/docs/nb/reference/cli/plugin.mdx @@ -54,7 +54,7 @@ Installasjonsoppførselen varierer etter editor: - **Claude Code:** Autoinstallerer via `claude`-CLI-en hvis tilgjengelig; skriver ut manuelle kommandoer ellers. - **Copilot CLI:** Autoinstallerer via `copilot`-CLI-en hvis tilgjengelig; skriver ut manuelle kommandoer ellers. -- **Cursor:** Laster ned en autentisert tarball og pakker ut skills, agenter og hooks i `~/.cursor/`. Ingen CLI-deteksjon nødvendig -- filene skrives direkte til Cursor-brukerkatalogen. +- **Cursor:** Laster ned en autentisert tarball og pakker ut skills, agenter og hooks i `~/.cursor/`. Ingen CLI-deteksjon nødvendig. Filene skrives direkte til Cursor-brukerkatalogen. - **VS Code:** Installerer VS Code-utvidelsen (`.vsix`) via `code`-CLI-en hvis tilgjengelig; skriver ut manuelle instruksjoner ellers. - **opencode:** Krever at `opencode`-CLI-en er på PATH -- hopper over installasjonen med en tydelig melding ellers. Når den er til stede, laster den ned en autentisert tarball med agentfiler og pakker den ut i opencode-agentkatalogen for brukerskoopet. `archgate plugin url --editor opencode` skriver ut "N/A" -- opencode har ingen markedsplassURL. Se [opencode-integrasjonsguiden](/guides/opencode-integration/) for detaljer. diff --git a/docs/src/content/docs/nb/reference/privacy-policy.mdx b/docs/src/content/docs/nb/reference/privacy-policy.mdx index 20d0e724..cbc5bfad 100644 --- a/docs/src/content/docs/nb/reference/privacy-policy.mdx +++ b/docs/src/content/docs/nb/reference/privacy-policy.mdx @@ -27,7 +27,7 @@ Archgate samler inn **anonym bruksanalyse** (via PostHog) og **krasjrapporter** | Sentry Cloud | Krasjrapporter | EU (Frankfurt) | 90 dager | | Turso | Plugins Service-kontodata | EU | Til sletting etterspørres | -Data overføres via reverseproksier på `n.archgate.dev` (analyse) og `s.archgate.dev` (feil) -- transparente videresendere driftet av Dasolve AS på Cloudflare, uten logging eller lagring. +Data overføres via reverseproksier på `n.archgate.dev` (analyse) og `s.archgate.dev` (feil). Disse er transparente videresendere driftet av Dasolve AS på Cloudflare, uten logging eller lagring. ### Archgate Plugins Service diff --git a/docs/src/content/docs/nb/reference/rule-api.mdx b/docs/src/content/docs/nb/reference/rule-api.mdx index a375a532..31d682a0 100644 --- a/docs/src/content/docs/nb/reference/rule-api.mdx +++ b/docs/src/content/docs/nb/reference/rule-api.mdx @@ -303,7 +303,7 @@ interface ViolationDetail { ## Inline undertrykkelse -Brudd kan undertrykkes i kildekoden ved hjelp av `archgate-ignore`-kommentarer. Motoren håndterer dette automatisk — regler trenger ingen spesiell logikk. +Brudd kan undertrykkes i kildekoden ved hjelp av `archgate-ignore`-kommentarer. Motoren håndterer dette automatisk. Regler trenger ingen spesiell logikk. ```typescript // archgate-ignore ARCH-006/no-unapproved-deps legacy-avhengighet, migrering planlagt diff --git a/docs/src/content/docs/nb/reference/telemetry.mdx b/docs/src/content/docs/nb/reference/telemetry.mdx index 81aef712..bc7624ad 100644 --- a/docs/src/content/docs/nb/reference/telemetry.mdx +++ b/docs/src/content/docs/nb/reference/telemetry.mdx @@ -11,7 +11,7 @@ Archgate samler inn **anonyme bruksdata** for å hjelpe oss med å forstå hvord Når du kjører en Archgate-kommando, registrerer vi: -- **Kommandonavn** og **hvilke flagg som ble brukt** (f.eks. `check --json` -- kun flaggtilstedeværelse, aldri flaggverdier) +- **Kommandonavn** og **hvilke flagg som ble brukt** (f.eks. `check --json`; kun flaggtilstedeværelse, aldri flaggverdier) - **Avslutningskode** (0, 1, 2 eller 130) og **kjøretid** (millisekunder), pluss en kort **utfallstagg** (`success`, `user_error`, `internal_error`, `cancelled`) - **Miljø**: OS, arkitektur, Bun-versjon, Archgate-versjon, CI-deteksjon (inkludert leverandør: GitHub Actions / GitLab CI / CircleCI / osv.), TTY-deteksjon, WSL-deteksjon, shell (bash, zsh, pwsh...) og locale - **Installasjonskontekst**: hvordan CLI-en ble installert (binærfil, proto, lokal dev-avhengighet eller global pakkebehandler) @@ -62,8 +62,8 @@ Når CLI-en krasjer (avslutningskode 2), sender vi: ## Hva vi IKKE samler inn -- **Ingen personopplysninger**: ingen brukernavn, e-postadresser eller IP-adresser. GitHub / GitLab / Bitbucket eier-/reponavn sendes kun på engangshendelsen `project_initialized` for repositorier som er bekreftet offentlige av verten sin -- se [Repoidentitet](#repoidentitet). Private og selvhostede repoer får aldri identitet delt. -- **Intet filinnhold**: ingen ADR-innhold, kildekode eller filstier +- **Ingen personopplysninger**: ingen e-postadresser, passord, hemmeligheter eller IP-adresser. Engangshendelsen `project_initialized` kan inkludere `repo_owner` og `repo_name` for repositorier som er bekreftet offentlige av verten sin; se [Repoidentitet](#repoidentitet). Private og selvhostede repoer får aldri identitet delt. +- **Intet filinnhold**: ingen ADR-innhold eller kildekode. Feilrapporter (Sentry) kan inkludere relative filstier i stakkspor, men aldri absolutte stier eller filinnhold. - **Ingen prompt- eller AI-kontekst**: ingenting fra agentinteraksjoner, prompter eller AI-generert innhold - **Ingen flaggverdier**: vi registrerer at `--json` ble brukt, ikke hva JSON-utdataene inneholdt - **Ingen nettverksaktivitet**: ingen URL-er, API-nøkler eller tokener diff --git a/docs/src/content/docs/pt-br/concepts/domains.mdx b/docs/src/content/docs/pt-br/concepts/domains.mdx index 4ba5b107..e456f764 100644 --- a/docs/src/content/docs/pt-br/concepts/domains.mdx +++ b/docs/src/content/docs/pt-br/concepts/domains.mdx @@ -97,7 +97,7 @@ Em caso de dúvida entre `architecture` e um domínio específico, prefira o dom ## Domínios Personalizados -Quando os cinco domínios integrados realmente não encaixam uma categoria de decisões — por exemplo, `security`, `ml-ops` ou `compliance` — você pode registrar um domínio personalizado via CLI: +Quando os cinco domínios integrados realmente não encaixam uma categoria de decisões (por exemplo, `security`, `ml-ops` ou `compliance`), você pode registrar um domínio personalizado via CLI: ```bash # Ver o conjunto reconhecido atualmente neste projeto @@ -114,8 +114,8 @@ Os mapeamentos de domínio personalizado para prefixo persistem em [`.archgate/c ### Regras de nomenclatura -- **Nome** — kebab-case em minúsculas, 2–32 caracteres (ex.: `security`, `ml-ops`, `compliance`). -- **Prefixo** — letras maiúsculas, dígitos ou underscores, 2–10 caracteres (ex.: `SEC`, `MLOPS`, `COMP`). +- **Nome:** kebab-case em minúsculas, 2–32 caracteres (ex.: `security`, `ml-ops`, `compliance`). +- **Prefixo:** letras maiúsculas, dígitos ou underscores, 2–10 caracteres (ex.: `SEC`, `MLOPS`, `COMP`). - Nomes e prefixos personalizados não podem colidir com integrados ou com qualquer outro personalizado. ### Quando preferir um integrado @@ -126,7 +126,7 @@ Os cinco integrados são deliberadamente opinativos. Antes de registrar um domí - Uma decisão sobre versionamento de schema geralmente cabe em `data`, mesmo que a motivação seja de compliance. - Uma decisão que abrange múltiplas áreas técnicas geralmente cabe em `architecture`. -Recorra a um domínio personalizado apenas quando nenhum dos integrados for uma opção genuína — por exemplo, quando você tem uma equipe dedicada ou um regime de compliance que precisa de sua própria superfície de governança. +Recorra a um domínio personalizado apenas quando nenhum dos integrados for uma opção genuína, por exemplo, quando você tem uma equipe dedicada ou um regime de compliance que precisa de sua própria superfície de governança. ### Orientação para agentes de IA diff --git a/docs/src/content/docs/pt-br/concepts/rules.mdx b/docs/src/content/docs/pt-br/concepts/rules.mdx index 0c698080..15e17a7e 100644 --- a/docs/src/content/docs/pt-br/concepts/rules.mdx +++ b/docs/src/content/docs/pt-br/concepts/rules.mdx @@ -152,7 +152,7 @@ Quando essa regra é executada contra um arquivo contendo `import { readFileSync ``` 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. + 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" ``` diff --git a/docs/src/content/docs/pt-br/examples/clean-architecture-layers.mdx b/docs/src/content/docs/pt-br/examples/clean-architecture-layers.mdx index a88983c8..2de33bb1 100644 --- a/docs/src/content/docs/pt-br/examples/clean-architecture-layers.mdx +++ b/docs/src/content/docs/pt-br/examples/clean-architecture-layers.mdx @@ -3,13 +3,13 @@ title: clean-architecture-layers description: Garanta a direção das dependências em clean architecture impedindo que camadas internas referenciem camadas externas. --- -Garanta a direção das dependências em clean architecture — camadas internas não devem referenciar camadas externas. +Garanta a direção das dependências em clean architecture. Camadas internas não devem referenciar camadas externas. ## Detalhes da regra Clean architecture determina que as dependências apontem para dentro: API → Application → Domain. A camada Domain não deve ter dependências externas, a camada Application não deve referenciar Infrastructure diretamente, e nenhuma camada inferior deve referenciar o projeto API. Esta regra verifica diretivas `using` (C#) ou declarações `import` para garantir essas fronteiras. -O mesmo padrão se aplica a qualquer arquitetura em camadas em qualquer linguagem — ajuste os padrões de import e os caminhos das camadas conforme necessário. +O mesmo padrão se aplica a qualquer arquitetura em camadas em qualquer linguagem. Ajuste os padrões de import e os caminhos das camadas conforme necessário. ## Exemplos de código **incorreto** @@ -27,7 +27,7 @@ using StavangerChallenge.API; // ✗ Application → API ```csharp title="Domain/Entities/User.cs" namespace StavangerChallenge.Domain.Entities; -// No external dependencies — pure domain logic +// No external dependencies, pure domain logic ``` ```csharp title="Application/Services/UserService.cs" diff --git a/docs/src/content/docs/pt-br/examples/license-compatibility.mdx b/docs/src/content/docs/pt-br/examples/license-compatibility.mdx index 531110d4..ff74a9dc 100644 --- a/docs/src/content/docs/pt-br/examples/license-compatibility.mdx +++ b/docs/src/content/docs/pt-br/examples/license-compatibility.mdx @@ -52,7 +52,7 @@ function isAllowed(license: string | undefined): boolean { if (!license) return false; if (ALLOWED_LICENSES.has(license)) return true; - // Handle SPDX OR expressions — at least one option must be allowed + // Handle SPDX OR expressions: at least one option must be allowed const normalized = license.trim().replace(/^\(/u, "").replace(/\)$/u, ""); if (ALLOWED_LICENSES.has(normalized)) return true; @@ -84,7 +84,7 @@ export default { description: "All dependencies (including transitive) must use permissive licenses", async check(ctx) { - // Escaneia TODOS os pacotes em node_modules — diretos E transitivos. + // Escaneia TODOS os pacotes em node_modules, diretos E transitivos. // Brace expansion cobre pacotes regulares e escopados. const pkgFiles = await ctx.glob("node_modules/{*,@*/*}/package.json"); diff --git a/docs/src/content/docs/pt-br/examples/monorepo-task-runner.mdx b/docs/src/content/docs/pt-br/examples/monorepo-task-runner.mdx index 732d6af9..e266ff03 100644 --- a/docs/src/content/docs/pt-br/examples/monorepo-task-runner.mdx +++ b/docs/src/content/docs/pt-br/examples/monorepo-task-runner.mdx @@ -47,7 +47,7 @@ export default { rules: { "no-package-scripts": { description: - "package.json must not have scripts — use the task runner instead", + "package.json must not have scripts. Use the task runner instead.", async check(ctx) { const packageJsonFiles = [ ...(await ctx.glob("packages/*/package.json")), @@ -60,7 +60,7 @@ export default { }; if (pkg.scripts && Object.keys(pkg.scripts).length > 0) { ctx.report.violation({ - message: `${file}: has "scripts" field — use task runner config instead`, + message: `${file}: has "scripts" field. Use task runner config instead.`, file, fix: 'Move scripts to the task runner config and remove "scripts" from package.json', }); diff --git a/docs/src/content/docs/pt-br/examples/no-banned-api.mdx b/docs/src/content/docs/pt-br/examples/no-banned-api.mdx index 7f78de8d..ddc00928 100644 --- a/docs/src/content/docs/pt-br/examples/no-banned-api.mdx +++ b/docs/src/content/docs/pt-br/examples/no-banned-api.mdx @@ -7,7 +7,7 @@ Bane APIs de runtime especificas que causam problemas de compatibilidade entre p ## Detalhes da regra -Algumas APIs funcionam corretamente em uma plataforma mas falham em outra. Por exemplo, a API shell do Bun (`Bun.$`) trava no Windows devido a deadlocks de pipe. Esta regra detecta multiplas variantes de uma API banida — a chamada direta, o import e o uso desestruturado — garantindo que nenhuma forma passe despercebida. +Algumas APIs funcionam corretamente em uma plataforma, mas falham em outra. Por exemplo, a API shell do Bun (`Bun.$`) trava no Windows devido a deadlocks de pipe. Esta regra detecta multiplas variantes de uma API banida (a chamada direta, o import e o uso desestruturado), garantindo que nenhuma forma passe despercebida. Este padrao se generaliza para qualquer API que voce queira banir enquanto permite uma alternativa segura. @@ -54,7 +54,7 @@ export default { for (const m of fileMatches) { ctx.report.violation({ message: - "Do not use Bun.$ template literals — they hang on Windows. Use Bun.spawn instead.", + "Do not use Bun.$ template literals. They hang on Windows. Use Bun.spawn instead.", file: m.file, line: m.line, fix: "Replace Bun.$`cmd args` with Bun.spawn(['cmd', 'args'], { stdout: 'pipe', stderr: 'pipe' })", @@ -72,7 +72,7 @@ export default { for (const m of fileMatches) { ctx.report.violation({ message: - 'Do not import $ from "bun" — the shell API hangs on Windows. Use Bun.spawn instead.', + 'Do not import $ from "bun". The shell API hangs on Windows. Use Bun.spawn instead.', file: m.file, line: m.line, fix: "Remove the $ import and replace shell calls with Bun.spawn", @@ -88,7 +88,7 @@ export default { for (const m of fileMatches) { ctx.report.violation({ message: - "Do not use $` template literals — they hang on Windows. Use Bun.spawn instead.", + "Do not use $` template literals. They hang on Windows. Use Bun.spawn instead.", file: m.file, line: m.line, fix: "Replace $`cmd args` with Bun.spawn(['cmd', 'args'], { stdout: 'pipe', stderr: 'pipe' })", diff --git a/docs/src/content/docs/pt-br/examples/no-banned-imports.mdx b/docs/src/content/docs/pt-br/examples/no-banned-imports.mdx index 102f27e6..d7bd7e01 100644 --- a/docs/src/content/docs/pt-br/examples/no-banned-imports.mdx +++ b/docs/src/content/docs/pt-br/examples/no-banned-imports.mdx @@ -7,7 +7,7 @@ Previne o uso de bibliotecas banidas e impoe alternativas recomendadas. ## Detalhes da regra -Equipes frequentemente banem bibliotecas pesadas ou depreciadas em favor de alternativas mais leves ou nativas. Esta regra usa uma configuracao orientada a dados — um array de objetos especificando o padrao regex, o nome da biblioteca e a alternativa recomendada. Adicionar um novo banimento e uma alteracao de uma linha. +Equipes frequentemente banem bibliotecas pesadas ou depreciadas em favor de alternativas mais leves, ou nativas. Esta regra usa uma configuracao orientada a dados: um array de objetos especificando o padrao regex, o nome da biblioteca e a alternativa recomendada. Adicionar um novo banimento e uma alteracao de uma linha. ## Exemplos de codigo **incorreto** diff --git a/docs/src/content/docs/pt-br/examples/no-barrel-files.mdx b/docs/src/content/docs/pt-br/examples/no-barrel-files.mdx index f2b3953e..7fae3d3d 100644 --- a/docs/src/content/docs/pt-br/examples/no-barrel-files.mdx +++ b/docs/src/content/docs/pt-br/examples/no-barrel-files.mdx @@ -3,7 +3,7 @@ title: no-barrel-files description: Detecta e proibe barrel files (index.ts com apenas re-exports) para forcar importacoes diretas e melhorar o tree-shaking. --- -Detecta e proibe barrel files — arquivos `index.ts` que contêm apenas re-exports e nenhuma lógica. +Detecta e proibe barrel files, ou seja, arquivos `index.ts` que contêm apenas re-exports e nenhuma lógica. ## Detalhes da regra @@ -31,7 +31,7 @@ export function getHelperVersion(): string { } ``` -Ou melhor ainda — delete o `index.ts` e importe diretamente: +Ou melhor ainda, delete o `index.ts` e importe diretamente: ```typescript import { logInfo } from "./helpers/log"; diff --git a/docs/src/content/docs/pt-br/examples/no-todo-comments.mdx b/docs/src/content/docs/pt-br/examples/no-todo-comments.mdx index 69159a30..e041e133 100644 --- a/docs/src/content/docs/pt-br/examples/no-todo-comments.mdx +++ b/docs/src/content/docs/pt-br/examples/no-todo-comments.mdx @@ -41,7 +41,7 @@ export default { ); for (const match of matches) { ctx.report.warning({ - message: `${match.content.trim()} — resolve before merging`, + message: `${match.content.trim()} (resolve before merging)`, file: match.file, line: match.line, }); diff --git a/docs/src/content/docs/pt-br/examples/no-unapproved-deps.mdx b/docs/src/content/docs/pt-br/examples/no-unapproved-deps.mdx index e74dc0c8..41e06b31 100644 --- a/docs/src/content/docs/pt-br/examples/no-unapproved-deps.mdx +++ b/docs/src/content/docs/pt-br/examples/no-unapproved-deps.mdx @@ -49,7 +49,7 @@ export default { try { pkg = (await ctx.readJSON("package.json")) as typeof pkg; } catch { - return; // No package.json — nothing to check + return; // No package.json, nothing to check } const deps = Object.keys(pkg.dependencies ?? {}); diff --git a/docs/src/content/docs/pt-br/examples/page-component-constraints.mdx b/docs/src/content/docs/pt-br/examples/page-component-constraints.mdx index d9cf473d..9c686a61 100644 --- a/docs/src/content/docs/pt-br/examples/page-component-constraints.mdx +++ b/docs/src/content/docs/pt-br/examples/page-component-constraints.mdx @@ -3,14 +3,14 @@ title: page-component-constraints description: Garanta que componentes de página sejam wrappers finos de layout limitando seu tamanho e proibindo hooks de busca de dados. --- -Garanta que componentes de página sejam wrappers finos de layout — pequenos em tamanho e livres de lógica de busca de dados. +Garanta que componentes de página sejam wrappers finos de layout, pequenos e livres de lógica de busca de dados. ## Detalhes da regra Em arquiteturas frontend que separam roteamento de lógica, componentes de página devem apenas compor o layout e delegar a busca de dados para componentes Connected. Esta regra aplica duas restrições em um único arquivo de regras: -1. **Limite de tamanho** — Componentes de página devem ter menos de um número configurável de linhas (padrão: 75 linhas). -2. **Sem hooks de dados** — Componentes de página não devem usar `useState`, `useQuery`, `useMutation` ou outros hooks de busca de dados diretamente. +1. **Limite de tamanho:** Componentes de página devem ter menos de um número configurável de linhas (padrão: 75 linhas). +2. **Sem hooks de dados:** Componentes de página não devem usar `useState`, `useQuery`, `useMutation` ou outros hooks de busca de dados diretamente. ## Exemplos de código **incorreto** diff --git a/docs/src/content/docs/pt-br/examples/spdx-license-headers.mdx b/docs/src/content/docs/pt-br/examples/spdx-license-headers.mdx index a267ae7e..37ca9282 100644 --- a/docs/src/content/docs/pt-br/examples/spdx-license-headers.mdx +++ b/docs/src/content/docs/pt-br/examples/spdx-license-headers.mdx @@ -7,7 +7,7 @@ Garanta que cada arquivo fonte declare sua licença com um identificador SPDX le ## Detalhes da regra -Projetos open-source se beneficiam de declarações de licença por arquivo — elas sobrevivem à extração de arquivos, bundling e cenários de cópia onde o arquivo LICENSE raiz não está presente. Esta regra verifica que cada arquivo TypeScript fonte começa com o comentário de cabeçalho SPDX padrão. +Projetos open-source se beneficiam de declarações de licença por arquivo. Elas sobrevivem à extração de arquivos, bundling e cenários de cópia onde o arquivo LICENSE raiz não está presente. Esta regra verifica que cada arquivo TypeScript fonte começa com o comentário de cabeçalho SPDX padrão. ## Exemplos de código **incorreto** diff --git a/docs/src/content/docs/pt-br/examples/wrapper-enforcement.mdx b/docs/src/content/docs/pt-br/examples/wrapper-enforcement.mdx index e0ebc3d7..65fe78b3 100644 --- a/docs/src/content/docs/pt-br/examples/wrapper-enforcement.mdx +++ b/docs/src/content/docs/pt-br/examples/wrapper-enforcement.mdx @@ -52,7 +52,7 @@ export default { for (const m of fileMatches) { ctx.report.violation({ message: - "Do not access process.platform directly — use isWindows(), isMacOS(), or isLinux() from src/helpers/platform.ts instead.", + "Não acesse process.platform diretamente. Use isWindows(), isMacOS(), isLinux() ou getPlatformInfo() de src/helpers/platform.ts.", file: m.file, line: m.line, fix: 'Import { isWindows } from "../helpers/platform" and use it instead of process.platform', 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 09f3e9bc..2375a26e 100644 --- a/docs/src/content/docs/pt-br/getting-started/installation.mdx +++ b/docs/src/content/docs/pt-br/getting-started/installation.mdx @@ -5,7 +5,7 @@ description: Instale o Archgate CLI no macOS, Linux ou Windows via instalador, n ## Instalação standalone (recomendado) -A forma mais rápida de instalar o Archgate — sem necessidade de Node.js ou gerenciador de pacotes: +A forma mais rápida de instalar o Archgate, sem necessidade de Node.js ou gerenciador de pacotes: ```bash # macOS / Linux @@ -49,7 +49,7 @@ yarn global add archgate pnpm add -g archgate ``` -Isso instala um wrapper leve que delega para um binário específico da plataforma. A CLI em si é um binário standalone compilado com Bun — o Node.js é necessário apenas para o wrapper do npm/yarn/pnpm. +Isso instala um wrapper leve que delega para um binário específico da plataforma. A CLI em si é um binário standalone compilado com Bun. O Node.js é necessário apenas para o wrapper do npm/yarn/pnpm. ## Instalar como dependência de desenvolvimento @@ -175,7 +175,7 @@ Você deverá ver a versão instalada impressa no stdout. ## Instalar via proto -Se você usa o [proto](https://moonrepo.dev/proto) (gerenciador de toolchain do moonrepo), pode instalar o Archgate diretamente como um plugin proto — sem necessidade de Node.js ou npm. +Se você usa o [proto](https://moonrepo.dev/proto) (gerenciador de toolchain do moonrepo), pode instalar o Archgate diretamente como um plugin proto, sem necessidade de Node.js ou npm. Adicione o plugin ao seu `.prototools`: 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 62a6481f..0a8b8863 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 @@ -53,11 +53,11 @@ files: ["src/**/*.ts"] --- ``` -- **id** — Identificador único. A convenção é `ARCH-NNN`, mas qualquer string funciona. -- **title** — Nome legível para a decisão. -- **domain** — Agrupa ADRs relacionados (`architecture`, `backend`, `frontend`, `data` ou `general`). -- **rules** — Defina como `true` se este ADR possui um arquivo complementar `.rules.ts` com verificações automatizadas. -- **files** — Padrões glob opcionais que definem o escopo de quais arquivos as regras se aplicam. +- **id**: identificador único. A convenção é `ARCH-NNN`, mas qualquer string funciona. +- **title**: nome legível para a decisão. +- **domain**: agrupa ADRs relacionados (`architecture`, `backend`, `frontend`, `data` ou `general`). +- **rules**: defina como `true` se este ADR possui um arquivo complementar `.rules.ts` com verificações automatizadas. +- **files**: padrões glob opcionais que definem o escopo de quais arquivos as regras se aplicam. Abaixo do frontmatter, escreva a decisão em markdown. O Archgate não impõe uma estrutura específica de seções, mas as seções recomendadas são: Context, Decision, Do's and Don'ts, Consequences, Compliance e References. @@ -92,9 +92,9 @@ export default { Cada regra possui uma chave única, uma descrição e uma função assíncrona `check`. Dentro de `check`, você tem acesso a: -- **`ctx.scopedFiles`** — Arquivos que correspondem aos padrões glob do campo `files` do ADR. -- **`ctx.grep(file, pattern)`** — Pesquisa um arquivo por correspondências de regex, retornando caminhos de arquivos e números de linha. -- **`ctx.report.violation()`** — Reporta uma violação com mensagem, caminho do arquivo, número da linha e sugestão opcional de correção. +- **`ctx.scopedFiles`**: arquivos que correspondem aos padrões glob do campo `files` do ADR. +- **`ctx.grep(file, pattern)`**: pesquisa um arquivo por correspondências de regex, retornando caminhos de arquivos e números de linha. +- **`ctx.report.violation()`**: reporta uma violação com mensagem, caminho do arquivo, número da linha e sugestão opcional de correção. ## 5. Executar verificações @@ -124,22 +124,22 @@ Agora que você tem uma configuração funcionando, aprofunde-se: **Entenda os conceitos:** -- [ADRs](/concepts/adrs/) — O que são Architecture Decision Records e como o Archgate os utiliza. -- [Regras](/concepts/rules/) — Como arquivos complementares `.rules.ts` transformam decisões em verificações automatizadas. -- [Domínios](/concepts/domains/) — Como domínios agrupam ADRs relacionados e definem o escopo de correspondência de arquivos. +- [ADRs](/concepts/adrs/): o que são Architecture Decision Records e como o Archgate os utiliza. +- [Regras](/concepts/rules/): como arquivos complementares `.rules.ts` transformam decisões em verificações automatizadas. +- [Domínios](/concepts/domains/): como domínios agrupam ADRs relacionados e definem o escopo de correspondência de arquivos. **Escreva os seus:** -- [Escrevendo ADRs](/guides/writing-adrs/) — Aprenda o formato completo de ADR e as melhores práticas para escrever decisões eficazes. -- [Escrevendo Regras](/guides/writing-rules/) — Explore a API de regras, padrões avançados e como testar suas regras. -- [Padrões Comuns de Regras](/examples/common-rule-patterns/) — Padrões prontos para copiar e colar para verificações de dependências, convenções de nomenclatura e mais. +- [Escrevendo ADRs](/guides/writing-adrs/): aprenda o formato completo de ADR e as melhores práticas para escrever decisões eficazes. +- [Escrevendo Regras](/guides/writing-rules/): explore a API de regras, padrões avançados e como testar suas regras. +- [Padrões Comuns de Regras](/examples/common-rule-patterns/): padrões prontos para copiar e colar para verificações de dependências, convenções de nomenclatura e mais. **Integre ao seu fluxo de trabalho:** -- [Integração com CI](/guides/ci-integration/) — Conecte `archgate check` ao GitHub Actions, GitLab CI ou qualquer pipeline. -- [Pre-commit Hooks](/guides/pre-commit-hooks/) — Execute verificações localmente antes de cada commit. -- [Plugin Claude Code](/guides/claude-code-plugin/) — Dê aos agentes de IA guardrails arquiteturais 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. +- [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 guardrails arquiteturais 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? Execute `archgate login` para se cadastrar e autenticar, depois execute `archgate init --install-plugin` para configurar o 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 84da4e1c..6d5f01c0 100644 --- a/docs/src/content/docs/pt-br/guides/ci-integration.mdx +++ b/docs/src/content/docs/pt-br/guides/ci-integration.mdx @@ -24,7 +24,7 @@ jobs: - uses: archgate/check-action@v1 ``` -Isso é tudo — sem configuração de Node.js, sem passo de instalação. Se qualquer regra reportar uma violação com severidade `error`, o job falha com código de saída 1. +Isso é tudo. Sem configuração de Node.js, sem passo de instalação. Se qualquer regra reportar uma violação com severidade `error`, o job falha com código de saída 1. ### Fixar uma versão @@ -84,7 +84,7 @@ Use `--ci` para exibir violações como anotações de workflow do GitHub Action 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. :::note -A `archgate/check-action` passa `--ci` automaticamente — você só precisa dessa flag ao executar `archgate check` manualmente. +A `archgate/check-action` passa `--ci` automaticamente. Você só precisa dessa flag ao executar `archgate check` manualmente. ::: ## Saída legível por máquina @@ -236,7 +236,7 @@ jobs: - run: ~/.archgate/bin/archgate check --ci ``` -Isso funciona em qualquer ambiente com `curl` e `tar` — sem dependências de runtime. Você pode fixar uma versão com a variável de ambiente `ARCHGATE_VERSION`: +Isso funciona em qualquer ambiente com `curl` e `tar`, sem dependências de runtime. Você pode fixar uma versão com a variável de ambiente `ARCHGATE_VERSION`: ```yaml - run: curl -fsSL https://raw.githubusercontent.com/archgate/cli/main/install.sh | ARCHGATE_VERSION=v0.11.2 sh diff --git a/docs/src/content/docs/pt-br/guides/importing-adrs.mdx b/docs/src/content/docs/pt-br/guides/importing-adrs.mdx index ec83f5b7..e87b03aa 100644 --- a/docs/src/content/docs/pt-br/guides/importing-adrs.mdx +++ b/docs/src/content/docs/pt-br/guides/importing-adrs.mdx @@ -89,7 +89,7 @@ Isso lê `.archgate/imports.json` e exibe cada fonte, versão e os IDs de ADR pr ## Como funciona o remapeamento de IDs -Quando você importa ADRs, os IDs originais são **remapeados** para corresponder aos prefixos de domínio do seu projeto. O campo `domain` de cada ADR determina qual prefixo ele recebe — por exemplo, um ADR com `domain: frontend` vira `FE-XXX`, enquanto um com `domain: backend` vira `BE-XXX`. Cada domínio tem seu próprio contador, então importar um pack com domínios mistos produz IDs corretamente prefixados sem colisões. +Quando você importa ADRs, os IDs originais são **remapeados** para corresponder aos prefixos de domínio do seu projeto. O campo `domain` de cada ADR determina qual prefixo ele recebe. Por exemplo, um ADR com `domain: frontend` vira `FE-XXX`, enquanto um com `domain: backend` vira `BE-XXX`. Cada domínio tem seu próprio contador, então importar um pack com domínios mistos produz IDs corretamente prefixados sem colisões. Por exemplo, importar um pack com três ADRs de frontend e dois de backend em um projeto que já tem `FE-001` e `BE-001` produz: @@ -119,7 +119,7 @@ Cada importação é registrada em `.archgate/imports.json`: } ``` -Este manifesto permite rastrear a proveniência — de onde cada ADR importado veio e quando. Faça commit dele no controle de versão junto com seus ADRs. +Este manifesto permite rastrear a proveniência: de onde cada ADR importado veio e quando. Faça commit dele no controle de versão junto com seus ADRs. ## Referência de opções do comando diff --git a/docs/src/content/docs/pt-br/guides/opencode-integration.mdx b/docs/src/content/docs/pt-br/guides/opencode-integration.mdx index c42e1849..70076ed2 100644 --- a/docs/src/content/docs/pt-br/guides/opencode-integration.mdx +++ b/docs/src/content/docs/pt-br/guides/opencode-integration.mdx @@ -17,7 +17,7 @@ archgate init --editor opencode O bundle de agentes do opencode está atualmente em beta. Execute `archgate login` para se cadastrar e autenticar. ::: -Diferente das integrações com Claude Code ou Cursor, os agentes do opencode **não são gravados na árvore do seu projeto**. Em vez disso, são instalados no escopo do usuário -- portanto vivem na sua máquina, não no repositório, e ficam disponíveis em todos os projetos que você abrir com o opencode. +Diferente das integrações com Claude Code ou Cursor, os agentes do opencode **não são gravados na árvore do seu projeto**. Em vez disso, são instalados no escopo do usuário, portanto vivem na sua máquina, não no repositório, e ficam disponíveis em todos os projetos que você abrir com o opencode. O opencode usa a convenção XDG Base Directory em todas as plataformas (via o pacote `xdg-basedir`), então o local de instalação é `$XDG_CONFIG_HOME/opencode/agents/` quando essa variável está definida e `$HOME/.config/opencode/agents/` caso contrário. Isso significa que instalações no Windows ficam em `C:\Users\\.config\opencode\agents\`, não em `%APPDATA%`: 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 972978d3..6a8e035d 100644 --- a/docs/src/content/docs/pt-br/guides/writing-rules.mdx +++ b/docs/src/content/docs/pt-br/guides/writing-rules.mdx @@ -309,20 +309,20 @@ Existem duas formas de lidar com exceções no Archgate: **supressão no nível O Archgate suporta comentários inline `archgate-ignore` que suprimem violações sem modificar a regra em si. O engine analisa esses comentários e filtra as violações correspondentes antes de reportar. -**Supressão da próxima linha** — suprime a violação na linha imediatamente seguinte: +**Supressão da próxima linha**: suprime a violação na linha imediatamente seguinte: ```typescript // archgate-ignore ARCH-006/no-unapproved-deps dep legada, migração planejada para Q3 import chalk from "chalk"; ``` -**Supressão no nível do arquivo** — suprime todas as violações correspondentes em qualquer lugar do arquivo: +**Supressão no nível do arquivo**: suprime todas as violações correspondentes em qualquer lugar do arquivo: ```typescript // archgate-ignore-file ARCH-005/test-mirrors-src arquivo gerado, sem teste manual ``` -**Múltiplas regras** — empilhe comentários para suprimir mais de uma regra na mesma linha: +**Múltiplas regras**: empilhe comentários para suprimir mais de uma regra na mesma linha: ```typescript // archgate-ignore ARCH-006/no-unapproved-deps dep legada @@ -332,7 +332,7 @@ import chalk from "chalk"; Comentários de supressão consecutivos todos visam a primeira linha que não é uma supressão após o bloco. -O formato é `ADR-ID/rule-id` seguido de um motivo. O motivo é **obrigatório** — uma supressão sem motivo é ignorada e produz um aviso: +O formato é `ADR-ID/rule-id` seguido de um motivo. O motivo é **obrigatório**: uma supressão sem motivo é ignorada e produz um aviso: ``` [suppression] Suppression for ARCH-006/no-unapproved-deps is missing a reason src/foo.ts:1 @@ -383,10 +383,10 @@ import { useNavigate } from "react-router"; | `archgate-ignore` | Exceções ad-hoc para qualquer regra | Desenvolvedor usando a regra | | Diretiva customizada | Opt-outs específicos do domínio com motivos estruturados | Autor da regra | -Use `archgate-ignore` quando um desenvolvedor precisa suprimir uma violação pontual. Use diretivas customizadas quando o opt-out é um conceito de primeira classe no domínio da sua regra — por exemplo, marcar um componente como intencionalmente sem par, ou um arquivo como auto-gerado. +Use `archgate-ignore` quando um desenvolvedor precisa suprimir uma violação pontual. Use diretivas customizadas quando o opt-out é um conceito de primeira classe no domínio da sua regra. Por exemplo, marcar um componente como intencionalmente sem par, ou um arquivo como auto-gerado. ## Próximos passos -- [Padrões Comuns de Regras](/examples/common-rule-patterns/) — Padrões prontos para copiar e colar, organizados por categoria: gerenciamento de dependências, restrições de import, estrutura de arquivos, qualidade de código, esquema de banco de dados e limites de arquitetura. -- [Referência da API de Regras](/reference/rule-api/) — Referência completa de todos os tipos e funções da API de regras. -- [Integração com CI](/guides/ci-integration/) — Integre `archgate check` ao seu pipeline para aplicar regras em cada PR. +- [Padrões Comuns de Regras](/examples/common-rule-patterns/): padrões prontos para copiar e colar, organizados por categoria: gerenciamento de dependências, restrições de import, estrutura de arquivos, qualidade de código, esquema de banco de dados e limites de arquitetura. +- [Referência da API de Regras](/reference/rule-api/): referência completa de todos os tipos e funções da API de regras. +- [Integração com CI](/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 9d23c1a4..516a96aa 100644 --- a/docs/src/content/docs/pt-br/index.mdx +++ b/docs/src/content/docs/pt-br/index.mdx @@ -22,9 +22,9 @@ import CodeShowcase from "../../../components/CodeShowcase.astro"; O Archgate possui duas camadas que trabalham juntas: -1. **ADRs como documentos** — Arquivos Markdown com frontmatter YAML que descrevem decisões arquiteturais em linguagem natural. Humanos os leem. Agentes de IA os leem. Todos ficam alinhados. +1. **ADRs como documentos**: arquivos Markdown com frontmatter YAML que descrevem decisões arquiteturais em linguagem natural. Humanos os leem. Agentes de IA os leem. Todos ficam alinhados. -2. **ADRs como regras** — Arquivos complementares `.rules.ts` com verificações automatizadas escritas em TypeScript. Eles são executados contra sua base de código e reportam violações com caminhos de arquivos e números de linha. +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. O Archgate governa seu próprio desenvolvimento. A mesma ferramenta que verifica seu código verifica o nosso. Nossos próprios ADRs aplicam estrutura - de comandos, tratamento de erros, formatação de saída, testes e mais — [veja + de comandos, tratamento de erros, formatação de saída, testes e mais. [Veja no GitHub](https://github.com/archgate/cli/tree/main/.archgate/adrs). 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 6e52e9b3..9d2373fc 100644 --- a/docs/src/content/docs/pt-br/reference/adr-schema.mdx +++ b/docs/src/content/docs/pt-br/reference/adr-schema.mdx @@ -295,7 +295,7 @@ Invalid ADR frontmatter in ARCH-001-example.md: - domain: domain must be lowercase kebab-case (e.g. 'backend', 'ml-ops') ``` -Observação: o parser aceita qualquer nome que corresponda ao padrão kebab-case. Se um nome específico é "conhecido" pelo projeto — e portanto tem um prefixo que `archgate adr create` pode usar — depende do conjunto integrado mais quaisquer domínios personalizados registrados via [`archgate adr domain add`](/reference/cli/adr/#archgate-adr-domain). Criar um ADR com um nome de domínio não registrado falha com um erro "Unknown ADR domain" que sugere executar `archgate adr domain add`. +Observação: o parser aceita qualquer nome que corresponda ao padrão kebab-case. Se um nome específico é "conhecido" pelo projeto (e portanto tem um prefixo que `archgate adr create` pode usar) depende do conjunto integrado mais quaisquer domínios personalizados registrados via [`archgate adr domain add`](/reference/cli/adr/#archgate-adr-domain). Criar um ADR com um nome de domínio não registrado falha com um erro "Unknown ADR domain" que sugere executar `archgate adr domain add`. ### Incompatibilidade de tipos diff --git a/docs/src/content/docs/pt-br/reference/cli/adr.mdx b/docs/src/content/docs/pt-br/reference/cli/adr.mdx index 49d2e5c4..c65dfdcb 100644 --- a/docs/src/content/docs/pt-br/reference/cli/adr.mdx +++ b/docs/src/content/docs/pt-br/reference/cli/adr.mdx @@ -152,7 +152,7 @@ archgate adr update \ Gerencia domínios ADR personalizados. Domínios personalizados são mapeamentos nome → prefixo de ID persistidos em `.archgate/config.json` e mesclados com os cinco integrados (`backend`, `frontend`, `data`, `architecture`, `general`) no momento da leitura. -Use este comando quando uma decisão não se encaixar claramente em nenhum domínio integrado. Antes de registrar um novo, verifique se a decisão pode ser agrupada sob um domínio existente — integrados são o padrão e um domínio personalizado deve ser introduzido apenas quando nenhum integrado for uma opção genuína. +Use este comando quando uma decisão não se encaixar claramente em nenhum domínio integrado. Antes de registrar um novo, verifique se a decisão pode ser agrupada sob um domínio existente. Integrados são o padrão, e um domínio personalizado deve ser introduzido apenas quando nenhum integrado for uma opção genuína. ```bash archgate adr domain [options] @@ -168,8 +168,8 @@ archgate adr domain [options] ### Regras de nomenclatura -- `` — kebab-case em minúsculas, 2–32 caracteres (ex.: `security`, `ml-ops`) -- `` — letras maiúsculas, dígitos ou underscores, 2–10 caracteres (ex.: `SEC`, `MLOPS`) +- ``: kebab-case em minúsculas, 2–32 caracteres (ex.: `security`, `ml-ops`) +- ``: letras maiúsculas, dígitos ou underscores, 2–10 caracteres (ex.: `SEC`, `MLOPS`) - Nomes e prefixos personalizados não podem colidir com integrados ou com qualquer outra entrada personalizada. ### Opções @@ -284,7 +284,7 @@ O comando compara os ADRs importados locais com a fonte upstream e mostra quais | Argumento | Descrição | | ------------- | ---------------------------------------------------------------------------- | -| `[source...]` | Filtro(s) de fonte opcionais — sincroniza apenas importações correspondentes | +| `[source...]` | Filtro(s) de fonte opcionais. Sincroniza apenas importações correspondentes. | ### Opções @@ -308,7 +308,7 @@ Verificar apenas importações de uma fonte específica: archgate adr sync archgate/packs/typescript ``` -Modo CI — falha o build se algum ADR importado estiver desatualizado: +Modo CI (falha o build se algum ADR importado estiver desatualizado): ```bash archgate adr sync --check diff --git a/docs/src/content/docs/pt-br/reference/cli/init.mdx b/docs/src/content/docs/pt-br/reference/cli/init.mdx index 22e67310..325a8e3b 100644 --- a/docs/src/content/docs/pt-br/reference/cli/init.mdx +++ b/docs/src/content/docs/pt-br/reference/cli/init.mdx @@ -26,7 +26,7 @@ Quando `--install-plugin` é passado, a CLI instala o plugin do Archgate para o **Cursor:** Faz o download de um tarball autenticado de skills, agentes e hooks em `~/.cursor/`. Também grava `.cursor/hooks.json` no projeto para compatibilidade com agentes na nuvem. Nenhuma detecção de CLI é necessária. -**opencode:** Requer que a CLI `opencode` esteja no seu PATH -- se não estiver, a instalação é pulada e uma mensagem pede que você instale o opencode primeiro. Quando presente, a CLI baixa um tarball autenticado de arquivos de agente do serviço de plugins do Archgate e o extrai no diretório de agentes opencode do escopo do usuário (`$XDG_CONFIG_HOME/opencode/agents/`, com fallback para `$HOME/.config/opencode/agents/` em qualquer plataforma, inclusive Windows -- o opencode usa paths XDG via `xdg-basedir` e não lê `%APPDATA%`). Nenhum arquivo é gravado na árvore do projeto. Veja o [guia de integração com opencode](/guides/opencode-integration/) para detalhes. +**opencode:** Requer que a CLI `opencode` esteja no seu PATH. Se não estiver, a instalação é pulada e uma mensagem pede que você instale o opencode primeiro. Quando presente, a CLI baixa um tarball autenticado de arquivos de agente do serviço de plugins do Archgate e o extrai no diretório de agentes opencode do escopo do usuário (`$XDG_CONFIG_HOME/opencode/agents/`, com fallback para `$HOME/.config/opencode/agents/` em qualquer plataforma, inclusive Windows; o opencode usa paths XDG via `xdg-basedir` e não lê `%APPDATA%`). Nenhum arquivo é gravado na árvore do projeto. Veja o [guia de integração com opencode](/guides/opencode-integration/) para detalhes. ## Saída diff --git a/docs/src/content/docs/pt-br/reference/cli/plugin.mdx b/docs/src/content/docs/pt-br/reference/cli/plugin.mdx index 05ee8903..6dc3bc0b 100644 --- a/docs/src/content/docs/pt-br/reference/cli/plugin.mdx +++ b/docs/src/content/docs/pt-br/reference/cli/plugin.mdx @@ -54,7 +54,7 @@ O comportamento de instalação varia por editor: - **Claude Code:** Instala automaticamente via CLI `claude` se disponível; exibe comandos manuais caso contrário. - **Copilot CLI:** Instala automaticamente via CLI `copilot` se disponível; exibe comandos manuais caso contrário. -- **Cursor:** Faz o download de um tarball autenticado e extrai skills, agentes e hooks em `~/.cursor/`. Nenhuma detecção de CLI é necessária -- os arquivos são gravados diretamente no diretório de usuário do Cursor. +- **Cursor:** Faz o download de um tarball autenticado e extrai skills, agentes e hooks em `~/.cursor/`. Nenhuma detecção de CLI é necessária. Os arquivos são gravados diretamente no diretório de usuário do Cursor. - **VS Code:** Instala a extensão VS Code (`.vsix`) via CLI `code` se disponível; exibe instruções manuais caso contrário. - **opencode:** Requer que a CLI `opencode` esteja no PATH -- pula a instalação com uma mensagem clara caso contrário. Quando presente, baixa um tarball autenticado de arquivos de agente e o extrai no diretório de agentes opencode do escopo do usuário. `archgate plugin url --editor opencode` exibe "N/A" -- opencode não tem URL de marketplace. Veja o [guia de integração com opencode](/guides/opencode-integration/) para detalhes. diff --git a/docs/src/content/docs/pt-br/reference/privacy-policy.mdx b/docs/src/content/docs/pt-br/reference/privacy-policy.mdx index 5dfaae00..fdbbe1c0 100644 --- a/docs/src/content/docs/pt-br/reference/privacy-policy.mdx +++ b/docs/src/content/docs/pt-br/reference/privacy-policy.mdx @@ -1,6 +1,6 @@ --- title: Política de Privacidade -description: Como o Archgate trata seus dados, o que coletamos e seus direitos. +description: Como o Archgate trata os seus dados, o que coletamos e os seus direitos. --- Para a Política de Privacidade completa do Archgate, acesse: 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 65dddce2..214d6850 100644 --- a/docs/src/content/docs/pt-br/reference/rule-api.mdx +++ b/docs/src/content/docs/pt-br/reference/rule-api.mdx @@ -220,14 +220,14 @@ interface ReportDetail { } ``` -| Campo | Tipo | Obrigatório | Descrição | -| ----------- | -------- | ----------- | ----------------------------------------------------------------- | -| `message` | `string` | Sim | Descrição legível do problema | -| `file` | `string` | Não | Caminho do arquivo onde o problema foi encontrado | -| `line` | `number` | Não | Número da linha inicial (base 1) | -| `endLine` | `number` | Não | Número da linha final (base 1) — para destaque preciso no editor | -| `endColumn` | `number` | Não | Número da coluna final (base 0) — para destaque preciso no editor | -| `fix` | `string` | Não | Sugestão de correção ou ação de remediação | +| Campo | Tipo | Obrigatório | Descrição | +| ----------- | -------- | ----------- | ---------------------------------------------------------------- | +| `message` | `string` | Sim | Descrição legível do problema | +| `file` | `string` | Não | Caminho do arquivo onde o problema foi encontrado | +| `line` | `number` | Não | Número da linha inicial (base 1) | +| `endLine` | `number` | Não | Número da linha final (base 1), para destaque preciso no editor | +| `endColumn` | `number` | Não | Número da coluna final (base 0), para destaque preciso no editor | +| `fix` | `string` | Não | Sugestão de correção ou ação de remediação | Quando `endLine` e `endColumn` são fornecidos, editores (VS Code, Cursor) podem destacar a expressão exata que viola a regra, em vez da linha inteira. Se omitidos, a linha completa em `line` é destacada. @@ -287,23 +287,23 @@ interface ViolationDetail { } ``` -| Campo | Tipo | Descrição | -| ----------- | ---------- | ------------------------------------------------------- | -| `ruleId` | `string` | ID da regra da chave do objeto `rules` | -| `adrId` | `string` | ID do ADR do frontmatter | -| `message` | `string` | Descrição legível | -| `file` | `string?` | Caminho do arquivo onde o problema foi encontrado | -| `line` | `number?` | Número da linha inicial (base 1) | -| `endLine` | `number?` | Linha final (base 1) — para destaque preciso no editor | -| `endColumn` | `number?` | Coluna final (base 0) — para destaque preciso no editor | -| `fix` | `string?` | Sugestão de correção | -| `severity` | `Severity` | Severidade efetiva desta violação | +| Campo | Tipo | Descrição | +| ----------- | ---------- | ------------------------------------------------------ | +| `ruleId` | `string` | ID da regra da chave do objeto `rules` | +| `adrId` | `string` | ID do ADR do frontmatter | +| `message` | `string` | Descrição legível | +| `file` | `string?` | Caminho do arquivo onde o problema foi encontrado | +| `line` | `number?` | Número da linha inicial (base 1) | +| `endLine` | `number?` | Linha final (base 1), para destaque preciso no editor | +| `endColumn` | `number?` | Coluna final (base 0), para destaque preciso no editor | +| `fix` | `string?` | Sugestão de correção | +| `severity` | `Severity` | Severidade efetiva desta violação | --- ## Supressão inline -Violações podem ser suprimidas no código-fonte usando comentários `archgate-ignore`. O engine lida com isso automaticamente — as regras não precisam de nenhuma lógica especial. +Violações podem ser suprimidas no código-fonte usando comentários `archgate-ignore`. O engine lida com isso automaticamente. As regras não precisam de nenhuma lógica especial. ```typescript // archgate-ignore ARCH-006/no-unapproved-deps dep legada, migração planejada diff --git a/docs/src/content/docs/pt-br/reference/telemetry.mdx b/docs/src/content/docs/pt-br/reference/telemetry.mdx index 8809e99f..1568765e 100644 --- a/docs/src/content/docs/pt-br/reference/telemetry.mdx +++ b/docs/src/content/docs/pt-br/reference/telemetry.mdx @@ -11,19 +11,19 @@ O Archgate coleta **dados de uso anônimos** para nos ajudar a entender como a C Quando você executa um comando do Archgate, registramos: -- **Nome do comando** e **quais flags foram usadas** (ex: `check --json` — apenas a presença da flag, nunca valores) +- **Nome do comando** e **quais flags foram usadas** (ex: `check --json`, apenas a presença da flag, nunca valores) - **Código de saída** (0, 1, 2 ou 130) e **duração da execução** (milissegundos), além de um **tag de desfecho** resumida (`success`, `user_error`, `internal_error`, `cancelled`) -- **Ambiente**: SO, arquitetura, versão do Bun, versão do Archgate, detecção de CI (incluindo provedor: GitHub Actions / GitLab CI / CircleCI / etc.), detecção de TTY, detecção de WSL, shell (bash, zsh, pwsh...) e locale +- **Ambiente**: SO, arquitetura, versão do Bun, versão do Archgate, detecção de CI (incluindo provedor: GitHub Actions / GitLab CI / CircleCI, etc.), detecção de TTY, detecção de WSL, shell (bash, zsh, pwsh...) e locale - **Contexto de instalação**: como a CLI foi instalada (binário, proto, dependência local ou gerenciador de pacotes global) - **Contexto do projeto**: se existe um projeto Archgate no diretório atual, quantas ADRs possui, quantas têm regras automatizadas e quantos domínios distintos de ADR estão em uso -- **Contexto do repositório** (não identificável): se o diretório atual é um repositório git, o bucket do host (`github` / `gitlab` / `bitbucket` / `azure-devops` / `other`), um **`repo_id` com hash** (SHA-256 da URL remota normalizada, truncado em 16 caracteres hex — não reversível) e o nome do branch padrão -- **Localização aproximada**: país e região (resolvidos no servidor a partir do seu IP, que é descartado em seguida — veja [Anonimização de IP](#anonimização-de-ip)) -- **ID de instalação anônimo**: um UUID aleatório gerado na primeira execução — não derivado de nenhum dado pessoal +- **Contexto do repositório** (não identificável): se o diretório atual é um repositório git, o bucket do host (`github` / `gitlab` / `bitbucket` / `azure-devops` / `other`), um **`repo_id` com hash** (SHA-256 da URL remota normalizada, truncado em 16 caracteres hex, não reversível) e o nome do branch padrão +- **Localização aproximada**: país e região, resolvidos no servidor a partir do seu IP (descartado em seguida; veja [Anonimização de IP](#anonimização-de-ip)) +- **ID de instalação anônimo**: um UUID aleatório gerado na primeira execução, não derivado de nenhum dado pessoal Além dos eventos gerais do ciclo de vida do comando (`command_executed` / `command_completed`), comandos específicos enviam eventos enriquecidos: -- **`check`**: contagens agregadas de regras (total, aprovadas, reprovadas, avisos, erros), formato de saída usado, se filtros foram aplicados, arquivos analisados, duração de carregamento, duração da verificação — sem caminhos de arquivo ou conteúdo de violação -- **`init`**: escolha do editor, se o plugin foi instalado, se o projeto já existia. Um evento separado `project_initialized` é enviado uma única vez, contendo o bucket do host do repositório, `repo_is_git` e um flag `repo_public`. Para repositórios confirmados como públicos no GitHub / GitLab / Bitbucket, esse evento também leva URL remota, owner e nome do repositório — veja [Identidade do repositório](#identidade-do-repositório). Repositórios privados e auto-hospedados nunca têm identidade compartilhada. +- **`check`**: contagens agregadas de regras (total, aprovadas, reprovadas, avisos, erros), formato de saída usado, se filtros foram aplicados, arquivos analisados, duração de carregamento, duração da verificação. Sem caminhos de arquivo ou conteúdo de violação +- **`init`**: escolha do editor, se o plugin foi instalado, se o projeto já existia. Um evento separado `project_initialized` é enviado uma única vez, contendo o bucket do host do repositório, `repo_is_git` e uma flag `repo_public`. Para repositórios confirmados como públicos no GitHub / GitLab / Bitbucket / Azure DevOps, esse evento também leva URL remota, owner e nome do repositório; veja [Identidade do repositório](#identidade-do-repositório). Repositórios privados e auto-hospedados nunca têm identidade compartilhada. - **`upgrade`**: transição de versão (de → para), método de instalação, sucesso/falha e uma razão de falha opcional - **`login`**: subcomando usado (login, logout, refresh, status), sucesso/falha e um bucket de falha (`network`, `tls`, `denied`, `other`) quando falha - **`telemetry_preference_changed`**: disparado uma vez quando você ativa ou desativa a telemetria, para que possamos entender as taxas de opt-out @@ -32,7 +32,7 @@ Além dos eventos gerais do ciclo de vida do comando (`command_executed` / `comm O Archgate envia um `repo_id` **com hash** em todo evento para que possamos contar repositórios distintos usando a CLI sem aprender seus nomes. A URL remota bruta, o owner e o nome do repositório **não** são incluídos no fluxo comum de eventos. -Em `archgate init`, um evento `project_initialized` único é enviado. Se — e somente se — o repositório for confirmado como **público** no GitHub, GitLab, Bitbucket ou Azure DevOps (via consulta não autenticada à API do host), esse evento também inclui `remote_url`, `repo_owner` e `repo_name`. Isso nos permite ver quais repositórios públicos estão adotando o Archgate sem jamais expor os privados. +Em `archgate init`, um evento `project_initialized` único é enviado. Se, e somente se, o repositório for confirmado como **público** no GitHub, GitLab, Bitbucket ou Azure DevOps (via consulta não autenticada à API do host), esse evento também inclui `remote_url`, `repo_owner` e `repo_name`. Isso nos permite ver quais repositórios públicos estão adotando o Archgate sem jamais expor os privados. **O que nunca é compartilhado:** @@ -40,7 +40,7 @@ Em `archgate init`, um evento `project_initialized` único é enviado. Se — e - Hosts Git auto-hospedados (a verificação pula esses completamente) - Repositórios em que a consulta expira, é limitada por rate-limit ou não retorna uma resposta pública definitiva -**Não quer o evento de forma alguma?** Desative a telemetria por completo — o evento `project_initialized` é suprimido junto com todos os outros: +**Não quer o evento de forma alguma?** Desative a telemetria por completo. O evento `project_initialized` é suprimido quando você desativa a telemetria: ```bash # Por shell / por invocação @@ -62,8 +62,8 @@ Quando a CLI falha (código de saída 2), enviamos: ## O que NÃO coletamos -- **Nenhuma informação pessoal**: nenhum nome de usuário, email ou endereço IP. Owners e nomes de repositórios no GitHub / GitLab / Bitbucket só são enviados no evento único `project_initialized` para repositórios confirmados como públicos pelo host — veja [Identidade do repositório](#identidade-do-repositório). Repositórios privados e auto-hospedados nunca têm identidade compartilhada. -- **Nenhum conteúdo de arquivo**: nenhum conteúdo de ADR, código-fonte ou caminho de arquivo +- **Nenhuma informação pessoal**: nenhum email, senha, segredo ou endereço IP. O evento único `project_initialized` pode incluir `repo_owner` e `repo_name` para repositórios confirmados como públicos pelo host; veja [Identidade do repositório](#identidade-do-repositório). Repositórios privados e auto-hospedados nunca têm identidade compartilhada. +- **Nenhum conteúdo de arquivo**: nenhum conteúdo de ADR ou código-fonte. Relatórios de erro (Sentry) podem incluir caminhos relativos em stack traces, mas nunca caminhos absolutos ou conteúdos de arquivo. - **Nenhum contexto de IA**: nada de interações com agentes, prompts ou conteúdo gerado por IA - **Nenhum valor de flag**: registramos que `--json` foi usado, não o conteúdo da saída JSON - **Nenhuma atividade de rede**: nenhuma URL, chave de API ou token @@ -74,7 +74,7 @@ O Archgate usa a anonimização de IP nativa do PostHog: 1. Sua CLI envia um evento ao PostHog com `$ip: null` 2. O PostHog resolve seu IP para um **país e região** (ex: "BR", "São Paulo") no servidor -3. O endereço IP é então **descartado** — nunca é armazenado no PostHog +3. O endereço IP é então **descartado**. Ele nunca é armazenado no PostHog Para o rastreamento de erros do Sentry, o projeto tem **"Prevent Storing of IP Addresses"** habilitado, então os IPs são removidos antes do armazenamento. @@ -122,6 +122,6 @@ A variável de ambiente tem prioridade sobre a configuração da CLI. Se `ARCHGA A implementação da telemetria é totalmente open source. Você pode inspecionar exatamente quais dados são coletados lendo: -- [`src/helpers/telemetry.ts`](https://github.com/archgate/cli/blob/main/src/helpers/telemetry.ts) — Rastreamento de eventos PostHog -- [`src/helpers/sentry.ts`](https://github.com/archgate/cli/blob/main/src/helpers/sentry.ts) — Captura de erros Sentry -- [`src/helpers/telemetry-config.ts`](https://github.com/archgate/cli/blob/main/src/helpers/telemetry-config.ts) — Configuração e lógica de desativação +- [`src/helpers/telemetry.ts`](https://github.com/archgate/cli/blob/main/src/helpers/telemetry.ts): rastreamento de eventos PostHog +- [`src/helpers/sentry.ts`](https://github.com/archgate/cli/blob/main/src/helpers/sentry.ts): captura de erros Sentry +- [`src/helpers/telemetry-config.ts`](https://github.com/archgate/cli/blob/main/src/helpers/telemetry-config.ts): configuração e lógica de desativação diff --git a/docs/src/content/docs/pt-br/studies/sentry-pr-review-friction-and-adr-pack.mdx b/docs/src/content/docs/pt-br/studies/sentry-pr-review-friction-and-adr-pack.mdx index 040f3722..197b75ac 100644 --- a/docs/src/content/docs/pt-br/studies/sentry-pr-review-friction-and-adr-pack.mdx +++ b/docs/src/content/docs/pt-br/studies/sentry-pr-review-friction-and-adr-pack.mdx @@ -15,7 +15,7 @@ O objetivo não é eliminar revisão humana, e sim levar debates repetitivos e p Leia a publicação canônica (metodologia, métricas, índice de ADRs) em: -- [**Visão geral — atrito em PRs do Sentry**](https://studies.archgate.dev/studies/sentry-pr-review-friction/) — mesmo conteúdo que as páginas narrativas em [`archgate/studies`](https://github.com/archgate/studies) +- [**Visão geral: atrito em PRs do Sentry**](https://studies.archgate.dev/studies/sentry-pr-review-friction/), mesmo conteúdo que as páginas narrativas em [`archgate/studies`](https://github.com/archgate/studies) ## Escopo e método @@ -63,7 +63,7 @@ Só PRs mesclados podem omitir **ambiguidade de decisão**: PRs com muita discus - **Tempo mediano até merge:** ~`4.98h`; **P90** ~`70.54h` (~14× a mediana) - **Tamanho do PR é o principal preditor de atrito:** PRs grandes (≥10 arquivos ou ≥400 de churn) entram no quartil de alto atrito em **~57%** dos casos vs **~10%** para PRs minúsculos -Uma taxa baixa de `CHANGES_REQUESTED` formal não significa pouco retrabalho—muitos ciclos ficam nos comentários. +Uma taxa baixa de `CHANGES_REQUESTED` formal não significa pouco retrabalho: muitos ciclos ficam nos comentários. ### Tamanho importa (PRs mesclados) @@ -74,7 +74,7 @@ PRs grandes são minoria, mas dominam o custo de review. ### Domínios, escopo e temas -O estudo detalha atrito por domínio, escopo do título do commit (`feat` vs `fix`, etc.) e temas de discussão a partir de **604 comentários não-bot** em **60** PRs de alto atrito—veja [temas](https://studies.archgate.dev/studies/sentry-pr-review-friction/themes/) e [mapa de atrito](https://studies.archgate.dev/studies/sentry-pr-review-friction/friction-map/). +O estudo detalha atrito por domínio, escopo do título do commit (`feat` vs `fix`, etc.) e temas de discussão a partir de **604 comentários não-bot** em **60** PRs de alto atrito. Veja [temas](https://studies.archgate.dev/studies/sentry-pr-review-friction/themes/) e [mapa de atrito](https://studies.archgate.dev/studies/sentry-pr-review-friction/friction-map/). ## PRs abandonados e estagnados @@ -85,7 +85,7 @@ Na visão geral publicada: - **12** PRs fechados sem merge (**2.4%**) tinham **≥10** itens de discussão; esses casos **abandonados** mostram **~2×** TTM mediano e **~2.5×** eventos de review vs PRs mesclados de alto atrito - **92** PRs abertos estagnados há **14+** dias; **33** há **30+** dias (exemplo estagnado mais discutido: **55** eventos de review) -Se você mede só PRs mesclados, a governança pode parecer mais saudável do que é. Trate coortes fechadas sem merge e abertas estagnadas como métricas de primeira classe—detalhes em [**PRs abandonados**](https://studies.archgate.dev/studies/sentry-pr-review-friction/abandoned/). +Se você mede só PRs mesclados, a governança pode parecer mais saudável do que é. Trate coortes fechadas sem merge e abertas estagnadas como métricas de primeira classe. Detalhes em [**PRs abandonados**](https://studies.archgate.dev/studies/sentry-pr-review-friction/abandoned/). ## Exemplos de PRs de alto atrito @@ -118,7 +118,7 @@ São exatamente decisões de equipe que ADRs podem codificar e regras podem faze ## Pacote de ADRs proposto para o Sentry -O conjunto fundamentado em evidências—com ADRs em Markdown, arquivos `.rules.ts` e artefatos de lint—está indexado no site do estudo em [**Propostas de ADR**](https://studies.archgate.dev/studies/sentry-pr-review-friction/adr-proposals/) e em [`archgate/studies` em `proposed-adrs/`](https://github.com/archgate/studies/tree/main/studies/sentry-pr-review-friction/proposed-adrs). +O conjunto fundamentado em evidências (com ADRs em Markdown, arquivos `.rules.ts` e artefatos de lint) está indexado no site do estudo em [**Propostas de ADR**](https://studies.archgate.dev/studies/sentry-pr-review-friction/adr-proposals/) e em [`archgate/studies` em `proposed-adrs/`](https://github.com/archgate/studies/tree/main/studies/sentry-pr-review-friction/proposed-adrs). A narrativa abaixo está priorizada pela redução esperada de atrito em review. diff --git a/docs/src/content/docs/reference/adr-schema.mdx b/docs/src/content/docs/reference/adr-schema.mdx index 130e0f5b..45e57048 100644 --- a/docs/src/content/docs/reference/adr-schema.mdx +++ b/docs/src/content/docs/reference/adr-schema.mdx @@ -295,7 +295,7 @@ Invalid ADR frontmatter in ARCH-001-example.md: - domain: domain must be lowercase kebab-case (e.g. 'backend', 'ml-ops') ``` -Note: the parser accepts any name that matches the kebab-case pattern. Whether a specific name is "known" to the project — and therefore has a prefix that `archgate adr create` can use — depends on the built-in set plus any custom domains registered via [`archgate adr domain add`](/reference/cli/adr/#archgate-adr-domain). Creating an ADR with an unregistered domain name fails with a "Unknown ADR domain" error that suggests running `archgate adr domain add`. +Note: the parser accepts any name that matches the kebab-case pattern. Whether a specific name is "known" to the project (and therefore has a prefix that `archgate adr create` can use) depends on the built-in set plus any custom domains registered via [`archgate adr domain add`](/reference/cli/adr/#archgate-adr-domain). Creating an ADR with an unregistered domain name fails with a "Unknown ADR domain" error that suggests running `archgate adr domain add`. ### Type mismatches diff --git a/docs/src/content/docs/reference/cli/adr.mdx b/docs/src/content/docs/reference/cli/adr.mdx index 1979bba7..80935881 100644 --- a/docs/src/content/docs/reference/cli/adr.mdx +++ b/docs/src/content/docs/reference/cli/adr.mdx @@ -152,7 +152,7 @@ archgate adr update \ Manage custom ADR domains. Custom domains are name → ID-prefix mappings persisted in `.archgate/config.json` and merged with the five built-ins (`backend`, `frontend`, `data`, `architecture`, `general`) at read time. -Use this command when a decision doesn't cleanly fit any built-in domain. Before registering a new one, check whether the decision can be folded under an existing domain — built-ins are the default and a custom domain should only be introduced when no built-in is a genuine fit. +Use this command when a decision doesn't cleanly fit any built-in domain. Before registering a new one, check whether the decision can be folded under an existing domain. Built-ins are the default and a custom domain should only be introduced when no built-in is a genuine fit. ```bash archgate adr domain [options] @@ -168,8 +168,8 @@ archgate adr domain [options] ### Naming rules -- `` — lowercase kebab-case, 2–32 chars (e.g., `security`, `ml-ops`) -- `` — uppercase letters, digits, or underscores, 2–10 chars (e.g., `SEC`, `MLOPS`) +- ``: lowercase kebab-case, 2–32 chars (e.g., `security`, `ml-ops`) +- ``: uppercase letters, digits, or underscores, 2–10 chars (e.g., `SEC`, `MLOPS`) - Custom names and prefixes cannot collide with built-ins or with any other custom entry. ### Options @@ -282,9 +282,9 @@ The command compares local imported ADRs against their upstream source and shows ### Arguments -| Argument | Description | -| ------------- | ------------------------------------------------------ | -| `[source...]` | Optional source filter(s) — sync only matching imports | +| Argument | Description | +| ------------- | ------------------------------------------------------- | +| `[source...]` | Optional source filter(s) to sync only matching imports | ### Options @@ -308,7 +308,7 @@ Check only imports from a specific source: archgate adr sync archgate/packs/typescript ``` -CI mode — fail the build if any imported ADR is outdated: +CI mode, failing the build if any imported ADR is outdated: ```bash archgate adr sync --check diff --git a/docs/src/content/docs/reference/cli/init.mdx b/docs/src/content/docs/reference/cli/init.mdx index 1f7a5979..0eca21b3 100644 --- a/docs/src/content/docs/reference/cli/init.mdx +++ b/docs/src/content/docs/reference/cli/init.mdx @@ -26,7 +26,7 @@ When `--install-plugin` is passed, the CLI installs the Archgate plugin for the **Cursor:** Downloads an authenticated tarball of skills, agents, and hooks into `~/.cursor/`. Also writes `.cursor/hooks.json` to the project for cloud agent compatibility. No CLI detection needed. -**opencode:** Requires the `opencode` CLI to be on your PATH — if it's not, the install is skipped and a message prompts you to install opencode first. When present, the CLI downloads an authenticated tarball of agent files from the Archgate plugins service and extracts it into the user-scope opencode agents directory (`$XDG_CONFIG_HOME/opencode/agents/`, falling back to `$HOME/.config/opencode/agents/` on every platform including Windows — opencode uses XDG paths via `xdg-basedir` and does not read `%APPDATA%`). No files are written to the project tree. See the [opencode integration guide](/guides/opencode-integration/) for details. +**opencode:** Requires the `opencode` CLI to be on your PATH. If it's not, the install is skipped and a message prompts you to install opencode first. When present, the CLI downloads an authenticated tarball of agent files from the Archgate plugins service and extracts it into the user-scope opencode agents directory (`$XDG_CONFIG_HOME/opencode/agents/`, falling back to `$HOME/.config/opencode/agents/` on every platform including Windows; opencode uses XDG paths via `xdg-basedir` and does not read `%APPDATA%`). No files are written to the project tree. See the [opencode integration guide](/guides/opencode-integration/) for details. ## Output diff --git a/docs/src/content/docs/reference/cli/plugin.mdx b/docs/src/content/docs/reference/cli/plugin.mdx index 1d490615..999c8c17 100644 --- a/docs/src/content/docs/reference/cli/plugin.mdx +++ b/docs/src/content/docs/reference/cli/plugin.mdx @@ -54,9 +54,9 @@ Installation behavior varies by editor: - **Claude Code:** Auto-installs via `claude` CLI if available; prints manual commands otherwise. - **Copilot CLI:** Auto-installs via `copilot` CLI if available; prints manual commands otherwise. -- **Cursor:** Downloads an authenticated tarball and extracts skills, agents, and hooks into `~/.cursor/`. No CLI detection needed — files are written directly to the Cursor user directory. +- **Cursor:** Downloads an authenticated tarball and extracts skills, agents, and hooks into `~/.cursor/`. No CLI detection needed. Files are written directly to the Cursor user directory. - **VS Code:** Installs the VS Code extension (`.vsix`) via `code` CLI if available; prints manual instructions otherwise. -- **opencode:** Requires the `opencode` CLI to be on PATH — skips the install with a clear message otherwise. When present, downloads an authenticated tarball of agent files and extracts it into the user-scope opencode agents directory. `archgate plugin url --editor opencode` prints "N/A" — opencode has no marketplace URL. See the [opencode integration guide](/guides/opencode-integration/) for details. +- **opencode:** Requires the `opencode` CLI to be on PATH, and skips the install with a clear message otherwise. When present, downloads an authenticated tarball of agent files and extracts it into the user-scope opencode agents directory. `archgate plugin url --editor opencode` prints "N/A" because opencode has no marketplace URL. See the [opencode integration guide](/guides/opencode-integration/) for details. ## Examples diff --git a/docs/src/content/docs/reference/privacy-policy.mdx b/docs/src/content/docs/reference/privacy-policy.mdx index fa5c5f7c..2c8a1658 100644 --- a/docs/src/content/docs/reference/privacy-policy.mdx +++ b/docs/src/content/docs/reference/privacy-policy.mdx @@ -27,7 +27,7 @@ Archgate collects **anonymous usage analytics** (via PostHog) and **crash report | Sentry Cloud | Crash reports | EU (Frankfurt) | 90 days | | Turso | Plugins Service account data | EU | Until deletion requested | -Data is transmitted via reverse proxies at `n.archgate.dev` (analytics) and `s.archgate.dev` (errors) — transparent forwarders operated by Dasolve AS on Cloudflare, with no logging or storage. +Data is transmitted via reverse proxies at `n.archgate.dev` (analytics) and `s.archgate.dev` (errors). These are transparent forwarders operated by Dasolve AS on Cloudflare, with no logging or storage. ### Archgate Plugins Service @@ -49,8 +49,8 @@ Note: telemetry opt-out disables CLI analytics and crash reporting. It does not ### Your rights -- **Access:** Request a copy of your data — email [privacy@archgate.dev](mailto:privacy@archgate.dev) with your install ID (from `~/.archgate/config.json` or `archgate telemetry status`). -- **Erasure:** Request deletion of historical data — email with your install ID. Completed within 30 days. +- **Access:** Request a copy of your data. Email [privacy@archgate.dev](mailto:privacy@archgate.dev) with your install ID (from `~/.archgate/config.json` or `archgate telemetry status`). +- **Erasure:** Request deletion of historical data. Email with your install ID. Completed within 30 days. - **Object:** Disable telemetry at any time via `archgate telemetry disable`. - **Portability:** Request data export in JSON or CSV format. - **Complaint:** Contact the Norwegian Data Protection Authority ([Datatilsynet](https://www.datatilsynet.no)). diff --git a/docs/src/content/docs/reference/rule-api.mdx b/docs/src/content/docs/reference/rule-api.mdx index 18ba6cb0..cff22121 100644 --- a/docs/src/content/docs/reference/rule-api.mdx +++ b/docs/src/content/docs/reference/rule-api.mdx @@ -220,14 +220,14 @@ interface ReportDetail { } ``` -| Field | Type | Required | Description | -| ----------- | -------- | -------- | ------------------------------------------------------------------- | -| `message` | `string` | Yes | Human-readable description of the issue | -| `file` | `string` | No | File path where the issue was found | -| `line` | `number` | No | Start line number (1-based) | -| `endLine` | `number` | No | End line number (1-based) — for precise editor range highlighting | -| `endColumn` | `number` | No | End column number (0-based) — for precise editor range highlighting | -| `fix` | `string` | No | Suggested fix or remediation action | +| Field | Type | Required | Description | +| ----------- | -------- | -------- | ------------------------------------------------------------------ | +| `message` | `string` | Yes | Human-readable description of the issue | +| `file` | `string` | No | File path where the issue was found | +| `line` | `number` | No | Start line number (1-based) | +| `endLine` | `number` | No | End line number (1-based), for precise editor range highlighting | +| `endColumn` | `number` | No | End column number (0-based), for precise editor range highlighting | +| `fix` | `string` | No | Suggested fix or remediation action | When `endLine` and `endColumn` are provided, editors (VS Code, Cursor) can highlight the exact expression that violates the rule, rather than the entire line. If omitted, the full line at `line` is highlighted. @@ -287,23 +287,23 @@ interface ViolationDetail { } ``` -| Field | Type | Description | -| ----------- | ---------- | ------------------------------------------------------ | -| `ruleId` | `string` | Rule ID from the `rules` object key | -| `adrId` | `string` | ADR ID from the frontmatter | -| `message` | `string` | Human-readable description | -| `file` | `string?` | File path where the issue was found | -| `line` | `number?` | Start line number (1-based) | -| `endLine` | `number?` | End line (1-based) — for precise editor highlighting | -| `endColumn` | `number?` | End column (0-based) — for precise editor highlighting | -| `fix` | `string?` | Suggested fix | -| `severity` | `Severity` | Effective severity of this violation | +| Field | Type | Description | +| ----------- | ---------- | ----------------------------------------------------- | +| `ruleId` | `string` | Rule ID from the `rules` object key | +| `adrId` | `string` | ADR ID from the frontmatter | +| `message` | `string` | Human-readable description | +| `file` | `string?` | File path where the issue was found | +| `line` | `number?` | Start line number (1-based) | +| `endLine` | `number?` | End line (1-based), for precise editor highlighting | +| `endColumn` | `number?` | End column (0-based), for precise editor highlighting | +| `fix` | `string?` | Suggested fix | +| `severity` | `Severity` | Effective severity of this violation | --- ## Inline suppression -Violations can be suppressed in source code using `archgate-ignore` comments. The engine handles this automatically — rules do not need any special logic. +Violations can be suppressed in source code using `archgate-ignore` comments. The engine handles this automatically. Rules do not need any special logic. ```typescript // archgate-ignore ARCH-006/no-unapproved-deps legacy dep, migration planned diff --git a/docs/src/content/docs/reference/telemetry.mdx b/docs/src/content/docs/reference/telemetry.mdx index dab0338f..7b958365 100644 --- a/docs/src/content/docs/reference/telemetry.mdx +++ b/docs/src/content/docs/reference/telemetry.mdx @@ -11,19 +11,19 @@ Archgate collects **anonymous usage data** to help us understand how the CLI is When you run an Archgate command, we record: -- **Command name** and **which flags were used** (e.g., `check --json` — only flag presence, never flag values) +- **Command name** and **which flags were used** (e.g., `check --json`; only flag presence, never flag values) - **Exit code** (0, 1, 2, or 130) and **execution duration** (milliseconds), plus a short **outcome** tag (`success`, `user_error`, `internal_error`, `cancelled`) - **Environment**: OS, architecture, Bun version, Archgate version, CI detection (including provider: GitHub Actions / GitLab CI / CircleCI / etc.), TTY detection, WSL detection, shell (bash, zsh, pwsh...), and locale - **Install context**: how the CLI was installed (binary, proto, local dev dependency, or global package manager) - **Project context**: whether an Archgate project exists in the current directory, how many ADRs it has, how many have automated rules, and how many distinct ADR domains are used -- **Repo context** (non-identifying): whether the current directory is a git repository, the host bucket (`github` / `gitlab` / `bitbucket` / `azure-devops` / `other`), a **hashed `repo_id`** (SHA-256 of the normalized remote URL, truncated to 16 hex characters — not reversible), and the default branch name -- **Coarse location**: country and region (resolved server-side from your IP, then the IP is discarded — see [IP anonymization](#ip-anonymization)) -- **Anonymous install ID**: a random UUID generated on first run — not derived from any personal data +- **Repo context** (non-identifying): whether the current directory is a git repository, the host bucket (`github` / `gitlab` / `bitbucket` / `azure-devops` / `other`), a **hashed `repo_id`** (SHA-256 of the normalized remote URL, truncated to 16 hex characters, not reversible), and the default branch name +- **Coarse location**: country and region (resolved server-side from your IP, then the IP is discarded; see [IP anonymization](#ip-anonymization)) +- **Anonymous install ID**: a random UUID generated on first run, not derived from any personal data In addition to the general command lifecycle events (`command_executed` / `command_completed`), specific commands send enriched outcome events: -- **`check`**: aggregate rule counts (total, passed, failed, warnings, errors), output format used, whether filters were applied, files scanned, load duration, check duration — no file paths or violation content -- **`init`**: editor choice, whether the plugin was installed, whether the project already existed. A separate one-time `project_initialized` event is emitted with the repo host bucket, `repo_is_git`, and a `repo_public` flag. For repos confirmed public on GitHub / GitLab / Bitbucket, this event also carries the remote URL, owner, and repo name — see [Repo identity](#repo-identity). Private and self-hosted repos never have identity shared. +- **`check`**: aggregate rule counts (total, passed, failed, warnings, errors), output format used, whether filters were applied, files scanned, load duration, check duration. No file paths or violation content +- **`init`**: editor choice, whether the plugin was installed, whether the project already existed. A separate one-time `project_initialized` event is emitted with the repo host bucket, `repo_is_git`, and a `repo_public` flag. For repos confirmed public on GitHub / GitLab / Bitbucket / Azure DevOps, this event also carries the remote URL, owner, and repo name. See [Repo identity](#repo-identity). Private and self-hosted repos never have identity shared. - **`upgrade`**: version transition (from → to), install method, success/failure, and an optional failure reason - **`login`**: subcommand used (login, logout, refresh, status), success/failure, and a failure bucket (`network`, `tls`, `denied`, `other`) when it fails - **`telemetry_preference_changed`**: fires once when you enable or disable telemetry, so we can understand opt-out rates @@ -32,7 +32,7 @@ In addition to the general command lifecycle events (`command_executed` / `comma Archgate sends a **hashed** `repo_id` with every event so we can count distinct repositories using the CLI without learning their names. The raw remote URL, owner, and repository name are **not** included in the common event stream. -On `archgate init`, a one-time `project_initialized` event is emitted. If — and only if — the repository is confirmed **public** on GitHub, GitLab, Bitbucket, or Azure DevOps (via an unauthenticated API probe against the host), that event additionally includes `remote_url`, `repo_owner`, and `repo_name`. This lets us see which public repositories are adopting Archgate without ever exposing private ones. +On `archgate init`, a one-time `project_initialized` event is emitted. If, and only if, the repository is confirmed **public** on GitHub, GitLab, Bitbucket, or Azure DevOps (via an unauthenticated API probe against the host), that event additionally includes `remote_url`, `repo_owner`, and `repo_name`. This lets us see which public repositories are adopting Archgate without ever exposing private ones. **What's never shared:** @@ -40,7 +40,7 @@ On `archgate init`, a one-time `project_initialized` event is emitted. If — an - Self-hosted Git hosts (the probe skips these entirely) - Repositories where the probe times out, is rate-limited, or otherwise fails to return a definitive public answer -**Don't want the event at all?** Disable telemetry entirely — the whole `project_initialized` event is then suppressed along with everything else: +**Don't want the event at all?** Disable telemetry entirely. The whole `project_initialized` event is then suppressed along with everything else: ```bash # Per-shell / per-invocation @@ -62,8 +62,8 @@ When the CLI crashes (exit code 2), we send: ## What we do NOT collect -- **No personal information**: no usernames, emails, or IP addresses. GitHub / GitLab / Bitbucket owner/repository names are only sent on the one-time `project_initialized` event for repositories that are confirmed public by their host — see [Repo identity](#repo-identity). Private and self-hosted repos never have identity shared. -- **No file content**: no ADR content, source code, or file paths +- **No personal information**: no emails, passwords, secrets, or IP addresses. The one-time `project_initialized` event can include `repo_owner` and `repo_name` for repositories confirmed public by their host. See [Repo identity](#repo-identity). Private and self-hosted repos never have identity shared. +- **No file content**: no ADR content or source code. Crash reports (Sentry) may include relative file paths in stack traces, but never absolute paths or file contents. - **No prompt or AI context**: nothing from agent interactions, prompts, or AI-generated content - **No flag values**: we record that `--json` was used, not what the JSON output contained - **No network activity**: no URLs, API keys, or tokens @@ -74,7 +74,7 @@ Archgate uses PostHog's built-in IP anonymization: 1. Your CLI sends an event to PostHog with `$ip: null` 2. PostHog resolves your IP to a **country and region** (e.g., "US", "California") server-side -3. The IP address is then **discarded** — it is never stored in PostHog +3. The IP address is then **discarded**. It is never stored in PostHog For Sentry error tracking, the project has **"Prevent Storing of IP Addresses"** enabled, so IPs are stripped before storage. @@ -114,7 +114,7 @@ The environment variable takes precedence over the CLI setting. If `ARCHGATE_TEL ## Legal basis -Archgate CLI telemetry operates on an **opt-out basis** under GDPR Article 6(1)(f) and LGPD Article 7, IX c/c Article 10 — legitimate interests of the controller. We have published a formal [Legitimate Interest Assessment](https://archgate.dev/legitimate-interest-assessment) documenting why this is proportionate and lawful. +Archgate CLI telemetry operates on an **opt-out basis** under GDPR Article 6(1)(f) and LGPD Article 7, IX c/c Article 10: legitimate interests of the controller. We have published a formal [Legitimate Interest Assessment](https://archgate.dev/legitimate-interest-assessment) documenting why this is proportionate and lawful. In summary: the data is anonymous (random UUID, no PII), the impact on users is minimal, robust safeguards are in place (IP anonymization, EU storage, limited retention, transparency), and users retain full control via an easy, permanent opt-out. @@ -126,7 +126,7 @@ In summary: the data is anonymous (random UUID, no PII), the impact on users is | Sentry Cloud | Crash reports | EU (Frankfurt) | 90 days | | Local config | Telemetry preference + install ID | Your machine | Until you delete it | -Analytics events are routed through `n.archgate.dev` and error reports through `s.archgate.dev`. These are transparent reverse proxies operated by Dasolve AS on Cloudflare infrastructure — they forward requests without logging, storing, or inspecting payloads. +Analytics events are routed through `n.archgate.dev` and error reports through `s.archgate.dev`. These are transparent reverse proxies operated by Dasolve AS on Cloudflare infrastructure. They forward requests without logging, storing, or inspecting payloads. ## Your rights @@ -143,6 +143,6 @@ Analytics events are routed through `n.archgate.dev` and error reports through ` The telemetry implementation is fully open source. You can inspect exactly what data is collected by reading: -- [`src/helpers/telemetry.ts`](https://github.com/archgate/cli/blob/main/src/helpers/telemetry.ts) — PostHog event tracking -- [`src/helpers/sentry.ts`](https://github.com/archgate/cli/blob/main/src/helpers/sentry.ts) — Sentry error capture -- [`src/helpers/telemetry-config.ts`](https://github.com/archgate/cli/blob/main/src/helpers/telemetry-config.ts) — Config and opt-out logic +- [`src/helpers/telemetry.ts`](https://github.com/archgate/cli/blob/main/src/helpers/telemetry.ts): PostHog event tracking +- [`src/helpers/sentry.ts`](https://github.com/archgate/cli/blob/main/src/helpers/sentry.ts): Sentry error capture +- [`src/helpers/telemetry-config.ts`](https://github.com/archgate/cli/blob/main/src/helpers/telemetry-config.ts): Config and opt-out logic diff --git a/shims/go/README.md b/shims/go/README.md index d019d1cc..3be2327a 100644 --- a/shims/go/README.md +++ b/shims/go/README.md @@ -13,7 +13,7 @@ --- -AI agents write code fast, but they don't know your rules. Archgate turns your team's decisions into executable checks — a lint step for architecture, conventions, and AI output. Your agents read the rules before writing code, and `archgate check` blocks what slips through. In CI, in pre-commit hooks, and inside every major AI coding tool. +AI agents write code fast, but they don't know your rules. Archgate turns your team's decisions into executable checks: a lint step for architecture, conventions, and AI output. Your agents read the rules before writing code, and `archgate check` blocks what slips through. In CI, in pre-commit hooks, and inside every major AI coding tool. **Write an ADR once. Enforce it everywhere.** @@ -21,8 +21,8 @@ AI agents write code fast, but they don't know your rules. Archgate turns your t Archgate has two layers: -1. **ADRs as documents** — markdown files with YAML frontmatter stored in `.archgate/adrs/`. Each ADR records a decision: what was decided, why, and what to do and not do. -2. **ADRs as rules** — each ADR can have a companion `.rules.ts` file that exports automated checks. Archgate runs these checks against your codebase and reports violations. +1. **ADRs as documents**: markdown files with YAML frontmatter stored in `.archgate/adrs/`. Each ADR records a decision: what was decided, why, and what to do and not do. +2. **ADRs as rules**: each ADR can have a companion `.rules.ts` file that exports automated checks. Archgate runs these checks against your codebase and reports violations. ``` .archgate/ @@ -33,7 +33,7 @@ Archgate has two layers: └── ARCH-002-error-handling.rules.ts ``` -When a rule is violated, `archgate check` reports the file, line, and which ADR was broken. Exit code 1 means violations — wire it into CI and it blocks merges automatically. +When a rule is violated, `archgate check` reports the file, line, and which ADR was broken. Exit code 1 means violations. Wire it into CI and it blocks merges automatically. **The CLI is free and open source.** Writing ADRs, enforcing rules, running checks in CI, and wiring up pre-commit hooks all work without an account or subscription. @@ -64,7 +64,7 @@ Each ADR can have a companion `.rules.ts` file that exports automated checks. Se ## Supercharge with AI plugins -> **Make your AI agent architecture-aware.** With the optional editor plugins, your AI coding agent reads ADRs before writing code, validates changes against your rules, and captures new architectural patterns back into ADRs — automatically. +> **Make your AI agent architecture-aware.** With the optional editor plugins, your AI coding agent reads ADRs before writing code, validates changes against your rules, and captures new architectural patterns back into ADRs, automatically. > > Plugins are available for [**Claude Code**](https://cli.archgate.dev/guides/claude-code-plugin/) and [**Cursor**](https://cli.archgate.dev/guides/cursor-integration/). > @@ -73,11 +73,11 @@ Each ADR can have a companion `.rules.ts` file that exports automated checks. Se > archgate init # installs the plugin automatically > ``` > -> **[Get started with plugins](https://cli.archgate.dev/guides/claude-code-plugin/)** — the CLI works fully without them, but plugins close the loop between decisions and code. +> **[Get started with plugins](https://cli.archgate.dev/guides/claude-code-plugin/)**. The CLI works fully without them, but plugins close the loop between decisions and code. ## Documentation -Full documentation is available at **[cli.archgate.dev](https://cli.archgate.dev)** — including guides for writing ADRs, writing rules, CI integration, editor plugin setup, and the complete CLI reference. +Full documentation is available at **[cli.archgate.dev](https://cli.archgate.dev)**, including guides for writing ADRs, writing rules, CI integration, editor plugin setup, and the complete CLI reference. ## Contributing diff --git a/shims/maven/README.md b/shims/maven/README.md index d019d1cc..3be2327a 100644 --- a/shims/maven/README.md +++ b/shims/maven/README.md @@ -13,7 +13,7 @@ --- -AI agents write code fast, but they don't know your rules. Archgate turns your team's decisions into executable checks — a lint step for architecture, conventions, and AI output. Your agents read the rules before writing code, and `archgate check` blocks what slips through. In CI, in pre-commit hooks, and inside every major AI coding tool. +AI agents write code fast, but they don't know your rules. Archgate turns your team's decisions into executable checks: a lint step for architecture, conventions, and AI output. Your agents read the rules before writing code, and `archgate check` blocks what slips through. In CI, in pre-commit hooks, and inside every major AI coding tool. **Write an ADR once. Enforce it everywhere.** @@ -21,8 +21,8 @@ AI agents write code fast, but they don't know your rules. Archgate turns your t Archgate has two layers: -1. **ADRs as documents** — markdown files with YAML frontmatter stored in `.archgate/adrs/`. Each ADR records a decision: what was decided, why, and what to do and not do. -2. **ADRs as rules** — each ADR can have a companion `.rules.ts` file that exports automated checks. Archgate runs these checks against your codebase and reports violations. +1. **ADRs as documents**: markdown files with YAML frontmatter stored in `.archgate/adrs/`. Each ADR records a decision: what was decided, why, and what to do and not do. +2. **ADRs as rules**: each ADR can have a companion `.rules.ts` file that exports automated checks. Archgate runs these checks against your codebase and reports violations. ``` .archgate/ @@ -33,7 +33,7 @@ Archgate has two layers: └── ARCH-002-error-handling.rules.ts ``` -When a rule is violated, `archgate check` reports the file, line, and which ADR was broken. Exit code 1 means violations — wire it into CI and it blocks merges automatically. +When a rule is violated, `archgate check` reports the file, line, and which ADR was broken. Exit code 1 means violations. Wire it into CI and it blocks merges automatically. **The CLI is free and open source.** Writing ADRs, enforcing rules, running checks in CI, and wiring up pre-commit hooks all work without an account or subscription. @@ -64,7 +64,7 @@ Each ADR can have a companion `.rules.ts` file that exports automated checks. Se ## Supercharge with AI plugins -> **Make your AI agent architecture-aware.** With the optional editor plugins, your AI coding agent reads ADRs before writing code, validates changes against your rules, and captures new architectural patterns back into ADRs — automatically. +> **Make your AI agent architecture-aware.** With the optional editor plugins, your AI coding agent reads ADRs before writing code, validates changes against your rules, and captures new architectural patterns back into ADRs, automatically. > > Plugins are available for [**Claude Code**](https://cli.archgate.dev/guides/claude-code-plugin/) and [**Cursor**](https://cli.archgate.dev/guides/cursor-integration/). > @@ -73,11 +73,11 @@ Each ADR can have a companion `.rules.ts` file that exports automated checks. Se > archgate init # installs the plugin automatically > ``` > -> **[Get started with plugins](https://cli.archgate.dev/guides/claude-code-plugin/)** — the CLI works fully without them, but plugins close the loop between decisions and code. +> **[Get started with plugins](https://cli.archgate.dev/guides/claude-code-plugin/)**. The CLI works fully without them, but plugins close the loop between decisions and code. ## Documentation -Full documentation is available at **[cli.archgate.dev](https://cli.archgate.dev)** — including guides for writing ADRs, writing rules, CI integration, editor plugin setup, and the complete CLI reference. +Full documentation is available at **[cli.archgate.dev](https://cli.archgate.dev)**, including guides for writing ADRs, writing rules, CI integration, editor plugin setup, and the complete CLI reference. ## Contributing diff --git a/shims/nuget/Archgate.Tool/README.md b/shims/nuget/Archgate.Tool/README.md index d019d1cc..3be2327a 100644 --- a/shims/nuget/Archgate.Tool/README.md +++ b/shims/nuget/Archgate.Tool/README.md @@ -13,7 +13,7 @@ --- -AI agents write code fast, but they don't know your rules. Archgate turns your team's decisions into executable checks — a lint step for architecture, conventions, and AI output. Your agents read the rules before writing code, and `archgate check` blocks what slips through. In CI, in pre-commit hooks, and inside every major AI coding tool. +AI agents write code fast, but they don't know your rules. Archgate turns your team's decisions into executable checks: a lint step for architecture, conventions, and AI output. Your agents read the rules before writing code, and `archgate check` blocks what slips through. In CI, in pre-commit hooks, and inside every major AI coding tool. **Write an ADR once. Enforce it everywhere.** @@ -21,8 +21,8 @@ AI agents write code fast, but they don't know your rules. Archgate turns your t Archgate has two layers: -1. **ADRs as documents** — markdown files with YAML frontmatter stored in `.archgate/adrs/`. Each ADR records a decision: what was decided, why, and what to do and not do. -2. **ADRs as rules** — each ADR can have a companion `.rules.ts` file that exports automated checks. Archgate runs these checks against your codebase and reports violations. +1. **ADRs as documents**: markdown files with YAML frontmatter stored in `.archgate/adrs/`. Each ADR records a decision: what was decided, why, and what to do and not do. +2. **ADRs as rules**: each ADR can have a companion `.rules.ts` file that exports automated checks. Archgate runs these checks against your codebase and reports violations. ``` .archgate/ @@ -33,7 +33,7 @@ Archgate has two layers: └── ARCH-002-error-handling.rules.ts ``` -When a rule is violated, `archgate check` reports the file, line, and which ADR was broken. Exit code 1 means violations — wire it into CI and it blocks merges automatically. +When a rule is violated, `archgate check` reports the file, line, and which ADR was broken. Exit code 1 means violations. Wire it into CI and it blocks merges automatically. **The CLI is free and open source.** Writing ADRs, enforcing rules, running checks in CI, and wiring up pre-commit hooks all work without an account or subscription. @@ -64,7 +64,7 @@ Each ADR can have a companion `.rules.ts` file that exports automated checks. Se ## Supercharge with AI plugins -> **Make your AI agent architecture-aware.** With the optional editor plugins, your AI coding agent reads ADRs before writing code, validates changes against your rules, and captures new architectural patterns back into ADRs — automatically. +> **Make your AI agent architecture-aware.** With the optional editor plugins, your AI coding agent reads ADRs before writing code, validates changes against your rules, and captures new architectural patterns back into ADRs, automatically. > > Plugins are available for [**Claude Code**](https://cli.archgate.dev/guides/claude-code-plugin/) and [**Cursor**](https://cli.archgate.dev/guides/cursor-integration/). > @@ -73,11 +73,11 @@ Each ADR can have a companion `.rules.ts` file that exports automated checks. Se > archgate init # installs the plugin automatically > ``` > -> **[Get started with plugins](https://cli.archgate.dev/guides/claude-code-plugin/)** — the CLI works fully without them, but plugins close the loop between decisions and code. +> **[Get started with plugins](https://cli.archgate.dev/guides/claude-code-plugin/)**. The CLI works fully without them, but plugins close the loop between decisions and code. ## Documentation -Full documentation is available at **[cli.archgate.dev](https://cli.archgate.dev)** — including guides for writing ADRs, writing rules, CI integration, editor plugin setup, and the complete CLI reference. +Full documentation is available at **[cli.archgate.dev](https://cli.archgate.dev)**, including guides for writing ADRs, writing rules, CI integration, editor plugin setup, and the complete CLI reference. ## Contributing diff --git a/shims/pypi/README.md b/shims/pypi/README.md index d019d1cc..3be2327a 100644 --- a/shims/pypi/README.md +++ b/shims/pypi/README.md @@ -13,7 +13,7 @@ --- -AI agents write code fast, but they don't know your rules. Archgate turns your team's decisions into executable checks — a lint step for architecture, conventions, and AI output. Your agents read the rules before writing code, and `archgate check` blocks what slips through. In CI, in pre-commit hooks, and inside every major AI coding tool. +AI agents write code fast, but they don't know your rules. Archgate turns your team's decisions into executable checks: a lint step for architecture, conventions, and AI output. Your agents read the rules before writing code, and `archgate check` blocks what slips through. In CI, in pre-commit hooks, and inside every major AI coding tool. **Write an ADR once. Enforce it everywhere.** @@ -21,8 +21,8 @@ AI agents write code fast, but they don't know your rules. Archgate turns your t Archgate has two layers: -1. **ADRs as documents** — markdown files with YAML frontmatter stored in `.archgate/adrs/`. Each ADR records a decision: what was decided, why, and what to do and not do. -2. **ADRs as rules** — each ADR can have a companion `.rules.ts` file that exports automated checks. Archgate runs these checks against your codebase and reports violations. +1. **ADRs as documents**: markdown files with YAML frontmatter stored in `.archgate/adrs/`. Each ADR records a decision: what was decided, why, and what to do and not do. +2. **ADRs as rules**: each ADR can have a companion `.rules.ts` file that exports automated checks. Archgate runs these checks against your codebase and reports violations. ``` .archgate/ @@ -33,7 +33,7 @@ Archgate has two layers: └── ARCH-002-error-handling.rules.ts ``` -When a rule is violated, `archgate check` reports the file, line, and which ADR was broken. Exit code 1 means violations — wire it into CI and it blocks merges automatically. +When a rule is violated, `archgate check` reports the file, line, and which ADR was broken. Exit code 1 means violations. Wire it into CI and it blocks merges automatically. **The CLI is free and open source.** Writing ADRs, enforcing rules, running checks in CI, and wiring up pre-commit hooks all work without an account or subscription. @@ -64,7 +64,7 @@ Each ADR can have a companion `.rules.ts` file that exports automated checks. Se ## Supercharge with AI plugins -> **Make your AI agent architecture-aware.** With the optional editor plugins, your AI coding agent reads ADRs before writing code, validates changes against your rules, and captures new architectural patterns back into ADRs — automatically. +> **Make your AI agent architecture-aware.** With the optional editor plugins, your AI coding agent reads ADRs before writing code, validates changes against your rules, and captures new architectural patterns back into ADRs, automatically. > > Plugins are available for [**Claude Code**](https://cli.archgate.dev/guides/claude-code-plugin/) and [**Cursor**](https://cli.archgate.dev/guides/cursor-integration/). > @@ -73,11 +73,11 @@ Each ADR can have a companion `.rules.ts` file that exports automated checks. Se > archgate init # installs the plugin automatically > ``` > -> **[Get started with plugins](https://cli.archgate.dev/guides/claude-code-plugin/)** — the CLI works fully without them, but plugins close the loop between decisions and code. +> **[Get started with plugins](https://cli.archgate.dev/guides/claude-code-plugin/)**. The CLI works fully without them, but plugins close the loop between decisions and code. ## Documentation -Full documentation is available at **[cli.archgate.dev](https://cli.archgate.dev)** — including guides for writing ADRs, writing rules, CI integration, editor plugin setup, and the complete CLI reference. +Full documentation is available at **[cli.archgate.dev](https://cli.archgate.dev)**, including guides for writing ADRs, writing rules, CI integration, editor plugin setup, and the complete CLI reference. ## Contributing diff --git a/shims/rubygem/README.md b/shims/rubygem/README.md index d019d1cc..3be2327a 100644 --- a/shims/rubygem/README.md +++ b/shims/rubygem/README.md @@ -13,7 +13,7 @@ --- -AI agents write code fast, but they don't know your rules. Archgate turns your team's decisions into executable checks — a lint step for architecture, conventions, and AI output. Your agents read the rules before writing code, and `archgate check` blocks what slips through. In CI, in pre-commit hooks, and inside every major AI coding tool. +AI agents write code fast, but they don't know your rules. Archgate turns your team's decisions into executable checks: a lint step for architecture, conventions, and AI output. Your agents read the rules before writing code, and `archgate check` blocks what slips through. In CI, in pre-commit hooks, and inside every major AI coding tool. **Write an ADR once. Enforce it everywhere.** @@ -21,8 +21,8 @@ AI agents write code fast, but they don't know your rules. Archgate turns your t Archgate has two layers: -1. **ADRs as documents** — markdown files with YAML frontmatter stored in `.archgate/adrs/`. Each ADR records a decision: what was decided, why, and what to do and not do. -2. **ADRs as rules** — each ADR can have a companion `.rules.ts` file that exports automated checks. Archgate runs these checks against your codebase and reports violations. +1. **ADRs as documents**: markdown files with YAML frontmatter stored in `.archgate/adrs/`. Each ADR records a decision: what was decided, why, and what to do and not do. +2. **ADRs as rules**: each ADR can have a companion `.rules.ts` file that exports automated checks. Archgate runs these checks against your codebase and reports violations. ``` .archgate/ @@ -33,7 +33,7 @@ Archgate has two layers: └── ARCH-002-error-handling.rules.ts ``` -When a rule is violated, `archgate check` reports the file, line, and which ADR was broken. Exit code 1 means violations — wire it into CI and it blocks merges automatically. +When a rule is violated, `archgate check` reports the file, line, and which ADR was broken. Exit code 1 means violations. Wire it into CI and it blocks merges automatically. **The CLI is free and open source.** Writing ADRs, enforcing rules, running checks in CI, and wiring up pre-commit hooks all work without an account or subscription. @@ -64,7 +64,7 @@ Each ADR can have a companion `.rules.ts` file that exports automated checks. Se ## Supercharge with AI plugins -> **Make your AI agent architecture-aware.** With the optional editor plugins, your AI coding agent reads ADRs before writing code, validates changes against your rules, and captures new architectural patterns back into ADRs — automatically. +> **Make your AI agent architecture-aware.** With the optional editor plugins, your AI coding agent reads ADRs before writing code, validates changes against your rules, and captures new architectural patterns back into ADRs, automatically. > > Plugins are available for [**Claude Code**](https://cli.archgate.dev/guides/claude-code-plugin/) and [**Cursor**](https://cli.archgate.dev/guides/cursor-integration/). > @@ -73,11 +73,11 @@ Each ADR can have a companion `.rules.ts` file that exports automated checks. Se > archgate init # installs the plugin automatically > ``` > -> **[Get started with plugins](https://cli.archgate.dev/guides/claude-code-plugin/)** — the CLI works fully without them, but plugins close the loop between decisions and code. +> **[Get started with plugins](https://cli.archgate.dev/guides/claude-code-plugin/)**. The CLI works fully without them, but plugins close the loop between decisions and code. ## Documentation -Full documentation is available at **[cli.archgate.dev](https://cli.archgate.dev)** — including guides for writing ADRs, writing rules, CI integration, editor plugin setup, and the complete CLI reference. +Full documentation is available at **[cli.archgate.dev](https://cli.archgate.dev)**, including guides for writing ADRs, writing rules, CI integration, editor plugin setup, and the complete CLI reference. ## Contributing