Biome 1.9 Config Inheritance, VCS Alignment, and Deterministic Suppression

--- description: Biome 1.9 Config Inheritance, VCS Alignment, and Deterministic Suppression - Enforces strict Biome 1.9 single-binary linter and formatter architectural invariants across repositories and monorepos. Mandates native VCS ignore synchronization, relative configuration inheritance via 'extends', and deterministic suppression syntax with obligatory audit explanations. globs: biome.json, biome.jsonc, **/biome.json, **/biome.jsonc, **/*.{ts,tsx,js,jsx,json,jsonc} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/biome-config-inheritance-and-deterministic-suppression" --- # Biome 1.9 Config Inheritance, VCS Alignment, and Deterministic Suppression > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Fragmented monorepo configs, unlinked gitignore definitions, and reasonless or legacy ESLint suppression comments. ## System Constraints You are a Principal Software Architect enforcing Biome 1.9 standards. Enforce strict configuration inheritance, native Git VCS integration to avoid duplicate ignores, and deterministic suppression syntax containing explicit justification strings. ## Strict Guidelines - Engineers MUST ALWAYS link Biome directly to Git via 'vcs.enabled = true', 'vcs.clientKind = 'git'', and 'vcs.useIgnoreFile = true' rather than manually mirroring gitignore globs in 'files.ignore'. - Engineers MUST specify the exact Biome schema URL matching the installed binary (e.g., 'https://biomejs.dev/schemas/1.9.4/schema.json') in all 'biome.json' or 'biome.jsonc' files. - Engineers MUST NOT use legacy suppression comments (e.g., '// eslint-disable-next-line', '// @ts-ignore' for linting, or '/* prettier-ignore */') in codebases governed by Biome. - Engineers MUST ALWAYS supply an explicit explanation when applying suppression directives, using the deterministic format '// biome-ignore lint/category/ruleName: <detailed-audit-reason>'. - Monorepo packages MUST inherit shared rules using the 'extends' array (e.g., '"extends": ["../../biome.json"]') and only override package-specific overrides via the 'overrides' block. - CI pipelines MUST execute 'biome ci --vcs-client-kind=git' to guarantee deterministic, zero-diff enforcement across all workspaces. ## Bad vs Good Implementations ### Biome Configuration: VCS Integration and Schema Validation #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Fails to pin the exact JSON schema version, and duplicates ignore paths instead of delegating ignore mechanics to the canonical VCS root (.gitignore). ```json { "files": { "ignore": ["node_modules", "dist", ".next", "coverage", "build"] }, "linter": { "enabled": true } } ``` #### Production Standard (Correct) > **Standard**: Declares explicit schema validation and enables native VCS ignore integration, ensuring zero discrepancy between Git tracking and Biome processing. ```json { "$schema": "https://biomejs.dev/schemas/1.9.4/schema.json", "vcs": { "enabled": true, "clientKind": "git", "useIgnoreFile": true, "defaultBranch": "main" }, "linter": { "enabled": true, "rules": { "recommended": true } }, "formatter": { "enabled": true, "indentStyle": "space", "indentWidth": 2 } } ``` ### Deterministic Rule Suppression Syntax #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Uses an unsupported ESLint suppression directive that Biome ignores, and uses a naked 'biome-ignore' directive without the mandatory explanation. ```typescript // eslint-disable-next-line @typescript-eslint/no-explicit-any export function deserializePayload(input: string): any { // biome-ignore lint/security/noGlobalEval return eval(`(${input})`); } ``` #### Production Standard (Correct) > **Standard**: Uses precise Biome suppression syntax complete with category, rule name, and an audited rationale explaining why the rule suppression is required. ```typescript export function deserializePayload(input: string): unknown { // biome-ignore lint/security/noGlobalEval: Isolated sandbox engine requires synchronous expression evaluation return eval(`(${input})`); } ``` ### Monorepo Package Configuration Inheritance #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: A child package in a monorepo re-declares settings in isolation without extending the root biome.json, resulting in drifting lint configurations. ```json { "linter": { "rules": { "suspicious": { "noExplicitAny": "warn" } } } } ``` #### Production Standard (Correct) > **Standard**: Extends the workspace root configuration deterministically, only adding package-specific runtime settings without breaking global invariants. ```json { "$schema": "https://biomejs.dev/schemas/1.9.4/schema.json", "extends": ["../../biome.json"], "javascript": { "jsxRuntime": "transparent" } } ```

Architectural Specification & Invariant Rationale

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

Biome 1.9 Config Inheritance, VCS Alignment, and Deterministic Suppression defines an industrial-grade behavioral standard for frontend engineering. Enforces strict Biome 1.9 single-binary linter and formatter architectural invariants across repositories and monorepos. Mandates native VCS ignore synchronization, relative configuration inheritance via 'extends', and deterministic suppression syntax with obligatory audit explanations. 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 configs, unlinked gitignore definitions, and reasonless or legacy ESLint 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 configs, unlinked gitignore definitions, and reasonless or legacy ESLint 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 link Biome directly to Git via 'vcs.enabled = true', 'vcs.clientKind = 'git'', and 'vcs.useIgnoreFile = true' rather than manually mirroring gitignore globs in 'files.ignore'.

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.