Deterministic Biome 1.9 Monorepo Inheritance, VCS Integration, and Explicit Rule Suppression

--- description: Deterministic Biome 1.9 Monorepo Inheritance, VCS Integration, and Explicit Rule Suppression - Biome 1.9 replaces traditional multi-tool JavaScript/TypeScript toolchains with a high-performance single-binary engine. In production monorepos, engineers must enforce root configuration inheritance using exact relative extends paths, integrate native VCS ignore hooks to eliminate duplicate ignore manifests, and mandate structured, deterministic suppression comments containing both rule names and mandatory rationale. globs: biome.json, biome.jsonc, apps/**/biome.json, packages/**/biome.json, **/*.{ts,tsx,js,jsx,json,jsonc} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/biome-1-9-monorepo-inheritance-vcs-guardrails" --- # Deterministic Biome 1.9 Monorepo Inheritance, VCS Integration, and Explicit Rule Suppression > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Fragmented multi-tier ESLint/Prettier configs, divergent gitignore patterns, and naked linter suppressions ## System Constraints You are a Principal Software Architect enforcing Biome 1.9 invariants across frontend projects and monorepos. You must mandate strict configuration inheritance via root biome.json, native VCS ignore file alignment, deterministic formatting rules, and strict biome-ignore suppression syntax requiring an explicit justification explanation. ## Strict Guidelines - Engineers MUST ALWAYS reference the root configuration using `"extends": ["../../biome.json"]` in nested package configurations rather than duplicating linter and formatter rules. - Engineers MUST ALWAYS configure `"vcs": { "enabled": true, "clientKind": "git", "useIgnoreFile": true }` in the root `biome.json` to prevent discrepancies between Git tracking and linter execution. - Engineers MUST NOT use unanchored or vague suppression comments; all inline suppressions MUST conform to the exact Biome 1.9 deterministic syntax: `// biome-ignore <category>/<ruleName>(<optionalCheck>): <explanation>`. - Engineers MUST NOT introduce legacy `.eslintignore`, `.prettierignore`, or ESLint/Prettier configuration files into Biome-governed workspaces. - Engineers MUST set `"formatter": { "enabled": true, "formatWithErrors": false }` to prevent corrupted AST nodes from producing invalid code modifications on syntax errors. - Codebases SHOULD pin `"$schema": "https://biomejs.dev/schemas/1.9.4/schema.json"` at the top of every `biome.json` file to enable deterministic JSON schema validation across IDEs and CI. ## Bad vs Good Implementations ### Configuration Architecture: Root vs Package Configuration with VCS Hook #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Fails to leverage native VCS ignore file integration, duplicating ignore manifests manually, and omits strict monorepo inheritance hooks. ```json { "$schema": "https://biomejs.dev/schemas/1.9.4/schema.json", "files": { "ignore": ["dist", "node_modules", ".next", "coverage"] }, "linter": { "enabled": true, "rules": { "recommended": true } } } ``` #### Production Standard (Correct) > **Standard**: Integrates VCS gitignore deterministically, defines root formatting rules safely prohibiting formatting syntax with errors, and enables consistent linting. ```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 }, "linter": { "enabled": true, "rules": { "recommended": true, "correctness": { "noUnusedVariables": "error" } } } } ``` ### Rule Suppression Syntax: Explicit Rule Suppressions with Mandatory Explanations #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Uses deprecated ESLint syntax which Biome completely ignores, and uses bare `biome-ignore` without the required rule specifier or mandatory explanation rationale. ```typescript // eslint-disable-next-line const dynamicToken: any = extractToken(); // biome-ignore const unvalidatedInput = rawRequest.body; ``` #### Production Standard (Correct) > **Standard**: Adheres strictly to Biome 1.9 deterministic syntax specifying the exact category, rule name, and colon-delimited human-readable explanation. ```typescript // biome-ignore lint/suspicious/noExplicitAny: Protocol deserializer requires dynamic shape before schema validation const dynamicToken: any = extractToken(); // biome-ignore lint/security/noDangerouslySetInnerHtml: Sanitized server-rendered SVG markup const unvalidatedInput = rawRequest.body; ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Deterministic Biome 1.9 Monorepo Inheritance, VCS Integration, and Explicit Rule Suppression

Deterministic Biome 1.9 Monorepo Inheritance, VCS Integration, and Explicit Rule Suppression defines an industrial-grade behavioral standard for frontend engineering. Biome 1.9 replaces traditional multi-tool JavaScript/TypeScript toolchains with a high-performance single-binary engine. In production monorepos, engineers must enforce root configuration inheritance using exact relative extends paths, integrate native VCS ignore hooks to eliminate duplicate ignore manifests, and mandate structured, deterministic suppression comments containing both rule names and mandatory rationale. 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-tier ESLint/Prettier configs, divergent gitignore patterns, and naked linter 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	Fragmented multi-tier ESLint/Prettier configs, divergent gitignore patterns, and naked linter 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 reference the root configuration using `"extends"

Engineers MUST ALWAYS reference the root configuration using `"extends": ["../../biome.json"]` in nested package configurations rather than duplicating linter and formatter rules.

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.