Code Quality and Standards
Relevant source files
The following files were used as context for generating this wiki page:
Code quality in the guiltty project is maintained through a rigorous "Quality Gate" enforced both locally and in Continuous Integration (CI). This gate ensures that all contributions meet specific standards for formatting, static analysis, and test coverage to maintain the integrity of the pixel-level 2D graphics library.
The project emphasizes automated verification of technical invariants, such as preventing panics in public APIs and ensuring high test coverage for complex rasterization logic. These standards are applied across the entire workspace, including the core logic, backend implementations, and example binaries.
Quality Gate Requirements
The project defines a standard set of commands known as the "Quality Gate" that must pass for any task to be considered complete. This gate is applied to all crates within the workspace to ensure consistent code health.
| Requirement | Command | Threshold/Constraint |
|---|---|---|
| Formatting | cargo fmt --all -- --check | Must match stable defaults |
| Linting | cargo clippy --workspace --all-targets -- -D warnings | No warnings allowed |
| Coverage | cargo llvm-cov --workspace --summary-only --fail-under-lines 90 | Minimum 90% line coverage |
Sources: tasks/issue-16-consumability-assessment-from-iklo-guiltty-s.md:9, tasks/issue-8-chore-ci-hardening-follow-ups-caching-sha-pinned.md:9
CI Pipeline Flow
The following diagram illustrates the execution order and dependencies of the quality gate within the CI environment. Note that formatting is executed early as a "fail-fast" measure before more resource-intensive steps.
The CI process uses SHA-pinned actions for security and Swatinem/rust-cache to optimize build times. Formatting is intentionally placed before cache restoration because it is computationally cheap and should fail quickly if standards are not met.
Sources: tasks/issue-8-chore-ci-hardening-follow-ups-caching-sha-pinned.md:14-63, README.md:46-51
Formatting and Style Standards
The project adheres to strict formatting and stylistic guidelines to ensure readability and maintainability.
Rustfmt Configuration
The project uses rustfmt with default settings to avoid divergence between local environments and CI.
- Pinned Defaults: The
rustfmt.tomlfile explicitly pins the project to stable defaults to prevent a contributor's personal~/.rustfmt.tomlfrom affecting the codebase. - Workspace-wide: All crates in the workspace inherit these settings.
Sources: rustfmt.toml:1-6, README.md:52
Clippy and Static Analysis
Clippy is configured at the workspace level with specific thresholds for complexity to prevent the introduction of unmaintainable code.
| Lint Name | Action | Description |
|---|---|---|
too_many_lines | warn | Limits function length to prevent monolithic blocks |
excessive_nesting | warn | Limits deep nesting to maintain readability |
The project specifically excludes cognitive_complexity as a metric, favoring too_many_lines and excessive_nesting instead. Thresholds are configured in clippy.toml:
too-many-lines-threshold: 100 linesexcessive-nesting-threshold: 6 levels
Sources: Cargo.toml:16-22, clippy.toml:1-5
Architectural Quality Standards
The software architecture enforces specific patterns to ensure robustness, particularly in the guiltty-core crate.
Panic Boundaries and Error Handling
A core standard in the project is the handling of recoverable vs. non-recoverable errors.
- Recoverable Errors: Conditions like failed terminal writes or missing image files must return a
Result<T, Error>instead of panicking. This protects the public API boundary. - Non-Recoverable Invariants: Panics are reserved strictly for programmer-error invariants, such as dimension overflows that would lead to invalid memory states.
Testing Strategy
Testing is categorized into two main types to ensure both logic and protocol correctness:
- Unit Tests: Used extensively in
guiltty-corefor rasterization logic (e.g., Bresenham’s line algorithm, scanline polygon fill, and barycentric triangle tests). - Protocol Tests: Used in
guiltty-kittyto assert the structure of escape sequences and base64 payloads without requiring a real terminal.
Sources: tasks/plan.md:47-51, crates/guiltty-core/src/lib.rs:770-1114
Summary
guiltty maintains high code quality through a combination of strict workspace-level lints, mandatory 90% test coverage, and a "fail-fast" CI pipeline. By pinning toolchains via mise and standardizing formatting defaults, the project ensures consistency across different development environments while enforcing architectural safety through well-defined error boundaries.