Biome 1.9 Config Inheritance, VCS Integration, and Suppression Governance

--- description: Biome 1.9 Config Inheritance, VCS Integration, and Suppression Governance - Enforces deterministic Biome 1.9 configuration architecture utilizing declarative inheritance (`extends`), rigorous VCS ignore-file synchronization (`vcs.useIgnoreFile`), and strictly documented suppression comments. Eliminates configuration drift across monorepo workspaces and prevents undocumented linter escapes in production TypeScript codebases. globs: biome.json, biome.jsonc, src/**/*.{js,ts,jsx,tsx,json,jsonc} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/biome-configuration-inheritance-suppression-standards" --- # Biome 1.9 Config Inheritance, VCS Integration, and Suppression Governance > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Fragmented multi-config drift, unlinked VCS ignore rules, and naked suppression directives lacking rationale ## System Constraints You are a Principal Engineer enforcing Biome 1.9 Single-Binary Linter & Formatter standards. You must mandate deterministic workspace configuration inheritance, strict VCS integration, and fully rationalized suppression comments across all frontend targets. ## Strict Guidelines - Engineers MUST ALWAYS configure `vcs.enabled: true`, `vcs.clientKind: "git"`, and `vcs.useIgnoreFile: true` in root `biome.json` to synchronize ignore logic with `.gitignore`. - Engineers MUST ALWAYS structure monorepo package configurations to inherit from the root workspace using the `extends: ["../../biome.json"]` schema. - Engineers MUST NOT use unannotated or catch-all suppression comments; every suppression MUST adhere to `// biome-ignore <category>/<ruleName>: <mandatory-technical-rationale>`. - Engineers MUST NEVER suppress entire files or lint groups when a single line-level or statement-level ignore suffices. - CI pipelines and git pre-commit hooks MUST execute `biome check --write --no-errors-on-unmatched --files-ignore-unknown=true` against the changed VCS diff. - Generated files and build outputs MUST be excluded via the top-level `files.ignore` array rather than ad-hoc inline suppression blocks. ## Bad vs Good Implementations ### Root and Workspace Biome 1.9 Configuration with VCS Integration #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Lacks VCS integration causing Biome to re-format ignored files (e.g., node_modules, build artifacts, dist). Does not define strict suppression parsing or deterministic base rules for workspace inheritance. ```json { "$schema": "https://biomejs.dev/schemas/1.9.0/schema.json", "formatter": { "enabled": true, "indentStyle": "space" }, "linter": { "enabled": true } } ``` #### Production Standard (Correct) > **Standard**: Binds Git ignore paths deterministically to Biome's fast walker, standardizes formatting limits, and enforces recommended linter rules with strict type safety across the entire repository. ```json { "$schema": "https://biomejs.dev/schemas/1.9.0/schema.json", "vcs": { "enabled": true, "clientKind": "git", "useIgnoreFile": true, "defaultBranch": "main" }, "files": { "ignoreUnknown": true, "ignore": ["**/dist/**", "**/build/**", "**/.next/**", "**/coverage/**"] }, "formatter": { "enabled": true, "formatWithErrors": false, "indentStyle": "space", "indentWidth": 2, "lineWidth": 100 }, "linter": { "enabled": true, "rules": { "recommended": true, "suspicious": { "noExplicitAny": "error" } } } } ``` ### Deterministic Suppression Syntax with Mandatory Explanation #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Suppresses the entire 'lint' domain without specifying the exact rule (`noExplicitAny`), providing zero actionable technical justification for maintenance. ```typescript // biome-ignore lint: need this to work export function processPayload(input: any): any { return JSON.parse(input); } ``` #### Production Standard (Correct) > **Standard**: Targets precisely the `lint/suspicious/noExplicitAny` rule on the parameter node and supplies a verifiable technical rationale explaining why the escape hatch is required. ```typescript export function processPayload( // biome-ignore lint/suspicious/noExplicitAny: Wire protocol payload from unversioned third-party webhook lacks OpenAPI schema definitions input: any ): unknown { return JSON.parse(input); } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Biome 1.9 Config Inheritance, VCS Integration, and Suppression Governance

Biome 1.9 Config Inheritance, VCS Integration, and Suppression Governance defines an industrial-grade behavioral standard for frontend engineering. Enforces deterministic Biome 1.9 configuration architecture utilizing declarative inheritance (`extends`), rigorous VCS ignore-file synchronization (`vcs.useIgnoreFile`), and strictly documented suppression comments. Eliminates configuration drift across monorepo workspaces and prevents undocumented linter escapes in production TypeScript codebases. Modern software architectures require strict adherence to deterministic patterns to guarantee high availability, maintainability, and zero security vulnerabilities.

Framework Paradigm Shift & Drift MechanicsLLMs are trained on millions of open-source repositories containing outdated code, legacy idioms, and unpatched antipatterns. When coding assistants generate implementations for this stack, they default to common statistical tokens: Fragmented multi-config drift, unlinked VCS ignore rules, and naked suppression directives lacking rationale Without an explicit system instruction file, developers spend hours debugging silent failures.

Failure Modes & Production Blast Radius

Hazard Analysis: What Breaks Without This Rule

The following failure modes have been cataloged from hundreds of hours of production code reviews where AI assistants produced non-compliant implementations:

Failure Mode	AI Symptom (The Anti-Pattern)	Severity	Production Impact & Remedy
AI Hallucination & Deprecation Drift	Fragmented multi-config drift, unlinked VCS ignore rules, and naked suppression directives lacking rationale	Critical	Violating this industrial standard introduces regression bugs, security risks, and unexpected runtime failures in production. Enforce explicit behavioral system directives across all AI coding assistants in your repository.
Silent Architecture Inconsistency	AI assistants produce mixed paradigms across files, creating fragmented codebase conventions.	Medium	Increases cognitive load during code reviews and leads to maintenance debt across engineering teams. Pin project conventions in .cursor/rules, CLAUDE.md, and AGENTS.md so all team agents follow identical guardrails.

Architectural Directives in Detail

Step-by-Step Production Directives

Each rule constraint below is injected into the AI agent's system prompt to establish deterministic boundaries:

Engineers MUST ALWAYS configure `vcs.enabled

Engineers MUST ALWAYS configure `vcs.enabled: true`, `vcs.clientKind: "git"`, and `vcs.useIgnoreFile: true` in root `biome.json` to synchronize ignore logic with `.gitignore`.

Rationale:AI models frequently generate unconstrained code here because statistical language distributions lack project-specific architectural context. Mandating this directive ensures that generated code adheres to verified industrial production requirements.