Biome 1.9 Configuration Inheritance, VCS Integration, and Strict Suppression Syntax

--- description: Biome 1.9 Configuration Inheritance, VCS Integration, and Strict Suppression Syntax - Enforces deterministic Biome 1.9 single-binary linter and formatter configuration standards across monorepo and standalone codebases. Mandates centralized configuration inheritance via extends, strict VCS ignore integration to prevent artifact pollution, and strictly formatted inline suppression comments with mandatory explanatory rationales. globs: biome.json, biome.jsonc, **/*.ts, **/*.tsx, **/*.js, **/*.jsx, **/*.json alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/biome-1-9-config-inheritance-vcs-suppression-guardrail" --- # Biome 1.9 Configuration Inheritance, VCS Integration, and Strict Suppression Syntax > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Configuration Drift, Phantom VCS Linting, and Naked Inline Rule Suppressions ## System Constraints You are a Principal Software Architect enforcing strict Biome 1.9 toolchain standards. Biome replaces Prettier and ESLint with an ultra-fast, single-binary architecture. You must mandate centralized configuration inheritance, strict VCS integration, and compliant inline suppression syntax across all workspace configurations and source files. ## Strict Guidelines - Engineers MUST ALWAYS configure `vcs` in root `biome.json` with `enabled: true`, `clientKind: "git"`, and `useIgnoreFile: true` to avoid parsing build outputs, caches, and untracked artifacts. - Engineers MUST ALWAYS format inline rule suppressions as `// biome-ignore <group>/<rule>: <explanation>` or `// biome-ignore lint/<group>/<rule>: <explanation>`—naked suppressions without an explicit colon and substantive rationale are strictly forbidden. - Engineers MUST NOT maintain duplicate rule blocks across workspace packages; monorepo subprojects MUST use `"extends": ["//biome.base.json"]` or valid relative paths to inherit shared base configurations. - Code SHOULD leverage the `overrides` array inside `biome.json` for directory-level rule alterations (such as relaxed rules for tests or scripts) rather than propagating scattered inline suppressions. - Services MUST execute `biome check --write` via CI and pre-commit hooks to simultaneously format, lint, and organize imports deterministically in a single pass. - Components NEVER rely on deprecated ESLint directive comments (`// eslint-disable-next-line`) or Prettier ignore pragmas (`// prettier-ignore`); all suppression directives must explicitly target Biome syntax. ## Bad vs Good Implementations ### Biome 1.9 Monorepo Root Configuration (biome.json) #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Fails to declare VCS integration, causing Biome to traverse gitignored paths unless manually mirrored in `files.ignore`. Lacks monorepo inheritance hooks and deterministic formatter settings. ```json { "$schema": "https://biomejs.dev/schemas/1.9.4/schema.json", "files": { "ignore": ["node_modules", "dist", "build", ".next"] }, "linter": { "enabled": true, "rules": { "recommended": true } } } ``` #### Production Standard (Correct) > **Standard**: Leverages native VCS integration to inherit `.gitignore` automatically, configures unified formatting, import organization, and strict linting rules at the workspace root. ```json { "$schema": "https://biomejs.dev/schemas/1.9.4/schema.json", "vcs": { "enabled": true, "clientKind": "git", "useIgnoreFile": true, "defaultBranch": "main" }, "formatter": { "enabled": true, "formatWithErrors": false, "indentStyle": "space", "indentWidth": 2, "lineWidth": 100 }, "organizeImports": { "enabled": true }, "linter": { "enabled": true, "rules": { "recommended": true, "suspicious": { "noExplicitAny": "error" } } } } ``` ### Deterministic Rule Suppression Syntax #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Uses obsolete ESLint directives that Biome ignores, and uses a naked Biome suppression without the mandatory colon and explanatory justification. ```typescript // eslint-disable-next-line @typescript-eslint/no-explicit-any export function deserializePayload(input: string): any { // biome-ignore lint/suspicious/noExplicitAny const raw: any = JSON.parse(input); return raw; } ``` #### Production Standard (Correct) > **Standard**: Suppresses the rule using standard Biome 1.9 syntax including rule name, delimiter colon, and an explicit, auditable rationale. ```typescript export function deserializePayload(input: string): unknown { // biome-ignore lint/suspicious/noExplicitAny: Dynamic untyped third-party webhook payload requires downcasting before schema validation const raw: any = JSON.parse(input); return raw; } ``` ### Workspace Package Sub-configuration Inheritance #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Redefines rules and formatter settings in a monorepo sub-package instead of inheriting from the root, causing config fragmentation. ```json { "$schema": "https://biomejs.dev/schemas/1.9.4/schema.json", "formatter": { "indentStyle": "space", "indentWidth": 2 }, "linter": { "rules": { "recommended": true } } } ``` #### Production Standard (Correct) > **Standard**: Inherits directly from the root `biome.json` using `extends` and isolates test-specific overrides to scoped file globs. ```json { "$schema": "https://biomejs.dev/schemas/1.9.4/schema.json", "extends": ["../../biome.json"], "overrides": [ { "include": ["**/*.spec.ts", "**/*.test.ts"], "linter": { "rules": { "suspicious": { "noExplicitAny": "off" } } } } ] } ```

Architectural Specification & Invariant Rationale

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

Biome 1.9 Configuration Inheritance, VCS Integration, and Strict Suppression Syntax defines an industrial-grade behavioral standard for frontend engineering. Enforces deterministic Biome 1.9 single-binary linter and formatter configuration standards across monorepo and standalone codebases. Mandates centralized configuration inheritance via extends, strict VCS ignore integration to prevent artifact pollution, and strictly formatted inline suppression comments with mandatory explanatory rationales. 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: Configuration Drift, Phantom VCS Linting, and Naked Inline Rule Suppressions 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	Configuration Drift, Phantom VCS Linting, and Naked Inline Rule Suppressions	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` in root `biome.json` with `enabled

Engineers MUST ALWAYS configure `vcs` in root `biome.json` with `enabled: true`, `clientKind: "git"`, and `useIgnoreFile: true` to avoid parsing build outputs, caches, and untracked artifacts.

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.