const-cbor 0.3.0

A const-first, no_std, allocation-free CBOR (RFC 8949) codec with no dependencies and no unsafe.
Documentation
# Testing

## Testing Philosophy

Tests must establish:

1. RFC 8949 correctness
2. Safety against malformed input
3. Stability of public behavior
4. Confidence for optimization work

Correctness must be proven before optimization.

Every discovered bug must become a regression test.

---

# Required Test Categories

The implementation should include:

## Unit Tests

Test individual components and internal behavior.

Examples:

- byte handling
- integer encoding
- parsing states
- error cases
- utility functions

---

## RFC Example Tests

Implement examples and behaviors derived from RFC 8949.

Tests should reference the relevant RFC requirements where practical.

---

## Roundtrip Tests

Verify:

- encode → decode correctness
- decode → encode behavior where applicable
- preservation of semantic meaning

---

## Malformed Input Tests

Test invalid CBOR inputs, including:

- truncated data
- invalid initial bytes
- invalid lengths
- invalid additional information
- malformed structures
- invalid UTF-8
- invalid numeric encodings

Malformed input must never panic.

---

## Canonical Encoding Tests

Verify:

- canonical ordering
- deterministic output
- canonical numeric representation
- canonical floating-point behavior

---

## Regression Tests

Every bug fix must include a regression test.

Regression tests should prevent the same class of failure from returning.

---

## Property Tests

Use property-based testing where useful.

Examples:

- encoding/decoding invariants
- parser correctness
- boundary conditions
- generated valid values

---

## Fuzz Testing

Fuzzing should target:

- decoders
- parsers
- malformed input handling
- boundary cases
- unsafe code paths

Fuzzing must verify:

- no panics
- no undefined behavior
- deterministic errors
- memory safety

---

# Benchmarks

Performance-sensitive changes require benchmarks.

Benchmark at minimum:

- encoding
- decoding
- streaming decoding
- canonical encoding
- integer encoding
- tag decoding
- map decoding
- allocation count
- binary size
- branch behavior where measurable

---

# Optimization Validation

Every optimization should be measured before and after implementation.

Measurements should consider:

- runtime performance
- allocations
- binary size
- generated code quality
- maintainability

Do not accept complexity without measurable improvement.

---

# Continuous Validation

Tests should run across relevant configurations.

Verify:

- default configuration
- no_std configuration
- alloc-enabled configuration
- optional feature combinations

Every feature must compile and remain independently testable.

---

# Testing SOP (Mandatory)

Every feature — existing or new — must pass through this procedure.
Regressions cannot slip in because a feature is only considered complete
after its tests exist and are green.

## 1. Test before you extend

No new feature work starts until the existing suite is green across the
full feature matrix:

```
cargo test
cargo test --features float
cargo test --features std
cargo test --all-features
cargo clippy --all-features --all-targets -- -D warnings
cargo fmt --check
```

## 2. Exhaustive coverage per feature

A feature is "exhaustively tested" when all of the following hold:

1. **Happy path** — every public method works on representative inputs,
   verified byte-for-byte against RFC 8949 expected encodings.
2. **Every error variant** — each `Error` the feature can produce is
   asserted with an exact-match test (`matches!`/`assert_eq`), not just
   `is_err()`.
3. **Boundary values** — at every width boundary (23/24, 255/256,
   u32/u64, i64::MIN, SKIP_LIMIT ± 1, capacity N and N+1).
4. **Malformed input** — truncated prefixes of valid encodings *at every
   byte offset*; reserved fields; wrong-type payloads. Nothing may panic.
5. **Failure atomicity** — failed calls leave encoder cursors and decoder
   positions unchanged where documented.
6. **Roundtrip** — encode → decode → encode is identity for all shapes
   the feature supports, including a deterministic pseudo-random property
   harness (`tests/property_roundtrip.rs`).
7. **Feature interaction** — combinations with `raw`, `stream`,
   `diagnostic`, and float-disabled builds behave as documented.

## 3. Coverage gates

- Tool: `cargo llvm-cov`.
- Gate: **>= 90% line coverage** on `--all-features`, enforced in CI
  (`--fail-under-lines 90`). Target 95–100%.
- Justified exclusions (defensive-only branches unreachable from any
  input) must be called out in review notes, not padded with fake tests.

## 4. New features follow the same SOP

For each new feature:

1. Read the governing RFC sections first; list MUST/MUST NOT/SHOULD.
2. Write conformance vectors from the RFC before implementation.
3. Implement behind its own feature flag, additive to all others.
4. Apply §2 exhaustively, then re-measure coverage (§3).
5. Wire the feature into the CI matrix.

## 5. Fuzzing

`fuzz/fuzz_targets/decode.rs` asserts malformed input never panics.
CI runs a bounded fuzz session (`cargo fuzz run decode -- -runs=100000`);
local development should run longer sessions before releases.