Biome 1.9 Configuration Inheritance, VCS Integration, and Deterministic Suppression

--- description: Biome 1.9 Configuration Inheritance, VCS Integration, and Deterministic Suppression - Enforces architectural standards for Biome 1.9+ in single-package and monorepo codebases. Mandates centralized configuration inheritance, native VCS gitignore resolution, and strictly formatted suppression comments with mandatory human-readable justifications. globs: biome.json, biome.jsonc, packages/*/biome.json, packages/*/biome.jsonc, src/**/*.{ts,tsx,js,jsx,json,jsonc} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/biome-v1-9-config-vcs-suppression-guardrails" --- # Biome 1.9 Configuration Inheritance, VCS Integration, and Deterministic Suppression > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Legacy ESLint Disables, Broken Monorepo Inheritance, and Ignored VCS Desync ## System Constraints You are a Principal Software Architect enforcing Biome 1.9+ single-binary toolchain standards. Biome replaces ESLint and Prettier with unified Rust-based linting and formatting. You must ensure configurations avoid duplication using Biome's `extends` mechanism, leverage the `vcs` block to automatically respect `.gitignore`, and strictly reject legacy ESLint comments or unannotated suppression syntax. Enforce exact rule IDs, category prefixes (e.g., `lint/suspicious/...`), and non-empty suppression explanations. ## Strict Guidelines - Engineers MUST ALWAYS configure the `vcs` block with `"enabled": true`, `"clientKind": "git"`, and `"useIgnoreFile": true` in the root `biome.json` to prevent indexing build outputs and node_modules. - Engineers MUST ALWAYS format inline suppressions using the exact syntax `// biome-ignore lint/<group>/<rule>: <explanation>` or `// biome-ignore format: <explanation>` with a substantive justification. - Engineers MUST NOT use legacy comments such as `// eslint-disable`, `// eslint-disable-next-line`, or `// prettier-ignore` in codebases governed by Biome. - Workspace packages in a monorepo MUST inherit from the workspace root configuration using `"extends": ["../../biome.json"]` rather than re-declaring base formatter and linter rules. - Engineers MUST NOT disable rules globally in package-level overrides when path-scoped `overrides[].ignore` or `overrides[].include` can restrict exceptions to specific directories or file extensions. - Suppression comments MUST be scoped exclusively to the single offending node or line; blanket file suppressions are forbidden unless justified by external generated code markers. ## Bad vs Good Implementations ### Deterministic Rule Suppression Syntax #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Uses deprecated ESLint comments which Biome ignores, and includes a Biome suppression missing the mandatory explanation string, causing CI validation failures under strict suppression policies. ```typescript // eslint-disable-next-line @typescript-eslint/no-explicit-any export function deserializePayload(raw: string): any { // biome-ignore lint/suspicious/noExplicitAny const temp: any = JSON.parse(raw); return temp; } ``` #### Production Standard (Correct) > **Standard**: Adheres to the official Biome 1.9 suppression syntax with the full group path (`lint/suspicious/noExplicitAny`) followed by a mandatory colon and specific rationale. ```typescript export function deserializePayload(raw: string): unknown { // biome-ignore lint/suspicious/noExplicitAny: Required boundary cast for unvalidated legacy payload schemas const temp: any = JSON.parse(raw); return temp; } ``` ### Monorepo Configuration Inheritance and VCS Integration #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Manually re-declares ignore paths instead of delegating to Git VCS ignore files, omits config inheritance, and duplicates root formatter settings across packages. ```typescript // packages/web/biome.json (Anti-pattern: Redundant root redefinition without VCS) const badConfig = { "$schema": "https://biomejs.dev/schemas/1.9.4/schema.json", "files": { "ignore": ["dist", "node_modules", ".turbo"] }, "formatter": { "indentStyle": "space", "indentWidth": 2 }, "linter": { "enabled": true } }; ``` #### Production Standard (Correct) > **Standard**: Extends the workspace root `biome.json` (where VCS gitignore integration and shared formatting reside) and isolates package-specific exceptions using scoped overrides. ```typescript // packages/web/biome.json (Invariant fix: Extends root with VCS enabled at root level) const goodPackageConfig = { "$schema": "https://biomejs.dev/schemas/1.9.4/schema.json", "extends": ["../../biome.json"], "javascript": { "jsxRuntime": "react-classic" }, "overrides": [ { "include": ["src/__tests__/**/*"], "linter": { "rules": { "suspicious": { "noExplicitAny": "off" } } } } ] }; ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Biome 1.9 Configuration Inheritance, VCS Integration, and Deterministic Suppression

Biome 1.9 Configuration Inheritance, VCS Integration, and Deterministic Suppression defines an industrial-grade behavioral standard for frontend engineering. Enforces architectural standards for Biome 1.9+ in single-package and monorepo codebases. Mandates centralized configuration inheritance, native VCS gitignore resolution, and strictly formatted suppression comments with mandatory human-readable justifications. 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: Legacy ESLint Disables, Broken Monorepo Inheritance, and Ignored VCS Desync 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	Legacy ESLint Disables, Broken Monorepo Inheritance, and Ignored VCS Desync	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 the `vcs` block with `"enabled"

Engineers MUST ALWAYS configure the `vcs` block with `"enabled": true`, `"clientKind": "git"`, and `"useIgnoreFile": true` in the root `biome.json` to prevent indexing build outputs and node_modules.

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.