Biome 1.9 Configuration Inheritance, VCS Alignment, and Deterministic Suppression

--- description: Biome 1.9 Configuration Inheritance, VCS Alignment, and Deterministic Suppression - Enforces strict Biome 1.9 configuration architecture across mono- and poly-repositories. Mandates deterministic configuration inheritance via relative extends, automatic Git-ignore synchronization through vcs configuration blocks, and syntactically validated inline rule suppressions with mandatory justification clauses. globs: biome.json, biome.jsonc, src/**/*.{ts,tsx,js,jsx} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/biome-1-9-config-inheritance-and-suppression-guardrails" --- # Biome 1.9 Configuration Inheritance, VCS Alignment, and Deterministic Suppression > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Fragmented monorepo formatting, Git-divergent linting passes, and unreasoned or legacy ESLint/Prettier suppression comments. ## System Constraints You are a Principal Architect enforcing Biome 1.9 tooling standards across modern TypeScript repositories. Mandate single-source configuration inheritance, zero drift between VCS and Biome ignore lists, and mathematically deterministic inline rule suppression with explanatory reasons. ## Strict Guidelines - Engineers MUST ALWAYS configure the 'vcs' block in root 'biome.json' with 'clientKind': 'git', 'enabled': true, and 'useIgnoreFile': true to prevent divergent file processing. - Engineers MUST NOT rely on deprecated '// eslint-disable*' or '// prettier-ignore' comments; all suppressions MUST use Biome 1.9 suppression syntax. - Inline suppressions MUST strictly supply a human-readable justification separated by a colon: '// biome-ignore <group>/<rule>: <explanation>'. - Package-level 'biome.json' files in monorepos MUST explicitly inherit shared foundations using 'extends': ['../../biome.json'] rather than re-declaring global formatter or linter baselines. - Engineers MUST NOT use blanket '// biome-ignore lint: <explanation>' suppressions; suppressions MUST target explicit rule paths (e.g., 'lint/suspicious/noExplicitAny'). - CI pipelines MUST execute 'biome ci' with '--error-on-warnings' to prevent suppression abuse and architectural drift. ## Bad vs Good Implementations ### Deterministic Rule Suppression Syntax #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Uses legacy ESLint suppression comments, omits the mandatory explanation clause on the noNonNullAssertion suppression, and applies a catastrophic blanket rule suppression without targeting a specific rule path. ```typescript // eslint-disable-next-line @typescript-eslint/no-explicit-any const untypedPayload: any = fetchRemotePayload(); // biome-ignore lint/style/noNonNullAssertion const authHeader = req.headers.authorization!; // biome-ignore lint: fixing later const rawData: any = JSON.parse(text); ``` #### Production Standard (Correct) > **Standard**: Adheres strictly to Biome 1.9 suppression grammar: targets specific rules (lint/<group>/<rule>) and provides mandatory architectural rationale after the colon delimiter. ```typescript // biome-ignore lint/suspicious/noExplicitAny: Third-party webhook payload schema is unversioned and dynamically resolved const untypedPayload: any = fetchRemotePayload(); // biome-ignore lint/style/noNonNullAssertion: Guarded by upstream AuthenticatedRoute middleware which terminates if header is absent const authHeader = req.headers.authorization!; // biome-ignore lint/suspicious/noExplicitAny: Sanitization barrier parses untrusted input before Zod validation const rawData: any = JSON.parse(text); ``` ### Monorepo Package Configuration Inheritance & VCS Alignment #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Package-level config re-declares formatter rules without extending root policy and omits VCS integration, leading to divergence between Git tracked files and Biome formatting targets. ```json { "$schema": "https://biomejs.dev/schemas/1.9.4/schema.json", "formatter": { "enabled": true, "indentStyle": "space", "indentWidth": 2 }, "linter": { "enabled": true } } ``` #### Production Standard (Correct) > **Standard**: Correctly establishes root configuration inheritance using 'extends', activates Git-ignore synchronization via the 'vcs' block, and scopes rule relaxations to test paths. ```json { "$schema": "https://biomejs.dev/schemas/1.9.4/schema.json", "extends": ["../../biome.json"], "vcs": { "enabled": true, "clientKind": "git", "useIgnoreFile": true }, "overrides": [ { "include": ["src/**/*.test.ts"], "linter": { "rules": { "suspicious": { "noExplicitAny": "off" } } } } ] } ```

Architectural Specification & Invariant Rationale

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

Biome 1.9 Configuration Inheritance, VCS Alignment, and Deterministic Suppression defines an industrial-grade behavioral standard for frontend engineering. Enforces strict Biome 1.9 configuration architecture across mono- and poly-repositories. Mandates deterministic configuration inheritance via relative extends, automatic Git-ignore synchronization through vcs configuration blocks, and syntactically validated inline rule suppressions with mandatory justification clauses. 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 monorepo formatting, Git-divergent linting passes, and unreasoned or legacy ESLint/Prettier suppression comments. 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 monorepo formatting, Git-divergent linting passes, and unreasoned or legacy ESLint/Prettier suppression comments.	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 in root 'biome.json' with 'clientKind'

Engineers MUST ALWAYS configure the 'vcs' block in root 'biome.json' with 'clientKind': 'git', 'enabled': true, and 'useIgnoreFile': true to prevent divergent file processing.

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.