Code Quality Standards
Relevant source files
The following files were used as context for generating this wiki page:
Code quality within the web-projects monorepo is maintained through a combination of automated linting, unified formatting rules, strict TypeScript configurations, and a multi-layered testing strategy. These standards ensure consistency across various applications (Astro, Next.js) and packages (TypeScript, Rust) while providing clear guidance for both human contributors and AI agents.
The core philosophy emphasizes "Zero runtime dependencies" for core libraries and automated verification of documentation examples to ensure the source of truth remains accurate.
Sources: CLAUDE.md:61-93, packages/color-contrast/CLAUDE.md:1-12
Linting and Formatting
The repository utilizes Biome as the primary engine for checking and fixing code formatting and linting issues for JavaScript and TypeScript files. This replaces the traditional ESLint/Prettier stack with a unified toolchain.
Core Requirements
- JavaScript/TypeScript: Single quotes are required for strings; space indentation is used throughout the project.
- Astro Files: These are excluded from Biome and instead rely on the Astro VSCode extension for formatting.
- Markdown: Strict rules are enforced via Cursor rules and
markdownlint. A critical requirement is that all fenced code blocks must include language specifiers to preventMD040warnings.
| Tool | Purpose | Command |
|---|---|---|
| Biome | Formatting and Linting | biome check . / biome check . --write |
| TypeScript | Type Safety | turbo run check-types |
| Static Check | Combined verification | turbo run static-check |
Sources: AGENTS.md:16-24, CLAUDE.md:75-87, package.json:20-22
Testing Strategy
The project employs a multi-tiered testing architecture that varies based on the component type. Tests are co-located with source files (e.g., foo.test.ts next to foo.ts) rather than in a centralized __tests__ directory.
Test Categories
- Unit Testing: Powered by Vitest (or
bun:test) for UI components and logic. - E2E Testing: Handled by Playwright for user-facing applications like
dotori-note. - Rust Testing: Uses the standard
cargo testframework. - Doctests: A specialized test suite ensures that API documentation (MDX) remains in sync with actual implementation by extracting and executing code blocks.
Automated Quality Flow
The following diagram illustrates how code quality is enforced during the development lifecycle:
The flow ensures that linting happens at the commit level, while heavy testing and type-checking occur via Turborepo orchestration.
Sources: AGENTS.md:26-30, CLAUDE.md:94-106, package.json:17-19, apps/dotori-note/tests/heading-autolink.spec.ts:1-10
Documentation Integrity (Doctests)
To prevent documentation rot, the project implements a "Doctest" system. This system treats MDX files as the single source of truth for the Library API.
Doctest Mechanism
The doctest.test.ts file extracts TypeScript code blocks from MDX documentation and evaluates them against the actual library exports. It compares the result of expressions with // expected comments.
Git Hooks and Automation
Lefthook is used to manage git hooks, specifically ensuring that Biome checks run before any code is committed. This prevents "dirty" code from entering the repository.
Commands for Quality Maintenance
lefthook install: Sets up the local git hooks.turbo run static-check: Executes both TypeScript type-checking and Biome linting across the entire monorepo.prepare: Automatically runslefthook installafter package installation.
Sources: AGENTS.md:26-30, package.json:17-23
Conclusion
Code Quality Standards in this repository are defined by strict automation and a "test-close-to-code" philosophy. By integrating formatting checks into the git workflow and validating documentation through executable tests, the project maintains high technical accuracy and developer velocity. Standardizing on Bun and Biome provides a modern, high-performance foundation for these quality gates.