Code Coverage

This project requires 100% line coverage for new code, with explicit coverage-ignore annotations only allowed under rare circumstances and with human permission.

This is implemented as a ratchet which counts the number of lines annotated as not requiring coverage. If the number of excluded lines exceeds the ratchet value, or if there are any uncovered lines without a // coverage-ignore annotation, the coverage check fails.

The ratchet is not a budget

The coverage-ignore count in .github/coverage-ratchet.json tracks excluded lines and can only decrease. Just because previous work reduced the count does not mean you have implicit permission to add new uncovered lines. Think of the ratchet as immediately ratcheting down after any reduction — the slack is gone.

You may not add // coverage-ignore annotations without explicit human permission. If you think code is genuinely untestable, your first move should be to refactor it for testability, not to annotate it. See references/patterns.md for testability refactoring examples.

Writing good tests

Tests should catch real bugs, not mirror the implementation.

• Validate against independent sources: if you can obtain the correct answer some other way - e.g. checking it against an externally defined source, or calculating it through some simpler more expensive method - then you should validate against that in the test.
• Think in terms of what could go wrong: a test that would still pass after introducing a bug is not testing anything. Figure out ways in which the code could genuinely be wrong and write tests that would catch that if it were.