ts/address quality audit

.github/workflows/ci.yml

@@ -21,3 +21,12 @@ jobs:
           components: rustfmt, clippy
       - uses: Swatinem/rust-cache@v2
       - run: make ci
+      - name: Install cargo-llvm-cov
+        uses: taiki-e/install-action@cargo-llvm-cov
+      - name: Generate coverage report
+        run: cargo llvm-cov --all-features --lcov --output-path lcov.info
+      - name: Upload coverage reports to Codecov
+        uses: codecov/codecov-action@v5
+        with:
+          token: ${{ secrets.CODECOV_TOKEN }}
+          slug: tcrypt25519/fuzzy_date

CONTRIBUTING.md

@@ -0,0 +1,30 @@
+# Contributing
+
+Thanks for your interest in contributing to `fuzzy_date`.
+
+## Style
+
+- Format with `cargo fmt` before committing (`make fmt`).
+- Fix all clippy warnings — the project runs clippy at `deny` level (`make clippy`).
+- Add or update rustdoc comments for any public items you add or change.
+- Keep changes focused; one logical change per commit/PR.
+
+## Tests
+
+- Every bug fix should include a regression test.
+- Every new parsing rule or API surface should have unit tests.
+- Run the full suite before opening a PR: `make ci` (format-check + clippy + tests + docs).
+
+## Opening a PR
+
+1. Fork the repository and create a feature branch from `main`.
+2. Run `make ci` locally and confirm it passes.
+3. Open a PR against `main` with a short description of what and why.
+
+## Expectations
+
+- Keep it small: PRs that are easier to review get merged faster.
+- The crate has no runtime dependencies beyond `serde` and `thiserror`; please
+  avoid introducing new ones without discussion.
+- Minimum supported Rust version is tracked in `Cargo.toml` (`rust-version`);
+  do not use features newer than that without bumping it.

Makefile

@@ -15,10 +15,13 @@ doctest: ## Run doc tests
 .PHONY: test-all
 test-all: test doctest ## Run all tests including doctests
 
-.PHONY: check
-check: ## Run Cargo check
+.PHONY: cargo-check
+cargo-check: ## Run cargo check (type-check without linking)
 	cargo check --all-targets --all-features
 
+.PHONY: check
+check: fmt-check clippy test-all doc ## Run fmt-check, clippy, all tests, and docs in one command
+
 .PHONY: fmt
 fmt: ## Format code
 	cargo fmt --all
@@ -35,8 +38,12 @@ clippy: ## Run clippy
 doc: ## Build documentation
 	RUSTDOCFLAGS="-D warnings" cargo doc --no-deps --all-features
 
+.PHONY: coverage
+coverage: ## Generate HTML coverage report with cargo-llvm-cov (install: cargo install cargo-llvm-cov)
+	cargo llvm-cov --all-features --open
+
 .PHONY: ci
-ci: fmt-check clippy test-cargo ## Run all CI checks
+ci: fmt-check clippy test-cargo doc ## Run all CI checks
 
 .PHONY: clippy-fix
 clippy-fix: ## Run clippy with automatic fixes

README.md

@@ -2,6 +2,14 @@
 
 A Rust crate for dates with varying precision: year-only, year+month, or full date.
 
+## Quick Start
+
+1. Add the dependency: `fuzzy_date = "0.1"` in `[dependencies]`.
+2. Parse a string: `"2026-02".parse::<FuzzyDate>()?`
+3. Query bounds: `.lower_bound()` and `.upper_bound_inclusive()` return `(year, month, day)` tuples.
+4. Check containment: `month.contains(&day_date)`.
+5. Serde: values serialize/deserialize as ISO strings automatically.
+
 ## Background
 
 Real-world date data often isn't complete. Vendors, forms, and manual records
@@ -77,5 +85,28 @@ storage, `to_columns()` / `from_columns()` map to three nullable columns
 
 Ranges parse as `{start}/{end}` — e.g. `2020-03/2026-02-13`.
 
+## Rejected formats
+
+| Format           | Example          | Reason                                          |
+|------------------|------------------|-------------------------------------------------|
+| `MM-DD-YYYY`     | `02-13-2026`     | Hyphens require year-first; ambiguous with ISO  |
+| `DD/MM/YYYY`     | `13/02/2026`     | Day-first slash not supported                   |
+| `YYYYMMDD`       | `20260213`       | No separator; parsed as bare year or error      |
+| Mixed delimiters | `2026-02/13`     | Any mix of `-` and `/` is rejected immediately  |
+| With time        | `2026-02-13T10:00` | Time components are not accepted              |
+
 For fuller examples including ranges, database integration, construction, and
 error handling, see [docs/examples.md](docs/examples.md).
+
+## Security and Validation
+
+Parsing is pure computation — no `unsafe` code, no I/O, no external calls.
+
+Every component is validated before a `FuzzyDate` is constructed:
+
+- Year must be 1–9999.
+- Month must be 1–12.
+- Day must be valid for the given month and year (leap years handled correctly).
+
+A `FuzzyDate` value is always well-formed; the type system makes invalid dates
+unrepresentable through the public API.

docs/spec.md

@@ -19,3 +19,34 @@ helpers for lower/upper bounds.
 
 - `cargo test` to run the included tests.
 - Use `FuzzyDate::from_str("1991-08")?` or `"08/1991"`, etc.
+
+## Error Behavior
+
+`FromStr` returns `ParseError`, an enum with these variants:
+
+| Variant                          | When raised                                              |
+|----------------------------------|----------------------------------------------------------|
+| `EmptyInput`                     | Input is empty or all whitespace                         |
+| `InvalidFormat(String)`          | Unrecognized structure, mixed delimiters, non-digit tokens |
+| `InvalidYear(u16)`               | Year is 0 or exceeds 9999                               |
+| `InvalidMonth(u8)`               | Month is 0 or exceeds 12                                |
+| `InvalidDay { month, day, year }`| Day does not exist in the given month/year              |
+
+All errors are diagnostic — each carries enough context to identify the offending
+value. Parsing is pure computation: no I/O, no allocation beyond the error message.
+
+## Module Architecture
+
+The crate is organized into four private modules with a single public re-export layer:
+
+| Module    | Role                                                                              |
+|-----------|-----------------------------------------------------------------------------------|
+| `lib`     | Public API: `FuzzyDate`, `ParseError`, `FromStr`, `Ord`, serde impls             |
+| `types`   | Validated newtypes: `Year`, `Month`, `Day` (backed by `NonZeroU16`/`NonZeroU8`)  |
+| `consts`  | Named constants: month lengths, `MAX_YEAR`, `DAYS_IN_MONTH`, separator chars     |
+| `range`   | `FuzzyDateRange` and `RangeError`                                                 |
+| `prelude` | Internal re-exports shared across modules                                         |
+
+Dependency direction is strictly one-way: `lib` and `range` import from `types` and
+`consts`; no leaf module imports from `lib` or `range`. This keeps compilation
+incremental and prevents circular dependencies.

src/lib.rs

@@ -315,6 +315,20 @@ impl FuzzyDate {
     /// Uses a strict byte-by-byte walk: month and day fields are at most 2 ASCII
     /// digits; any other byte in those positions is an immediate error.  The year
     /// field consumes all remaining bytes, which must all be ASCII digits.
+    ///
+    /// # Why byte-by-byte instead of split('/')?
+    ///
+    /// The two slash formats are structurally ambiguous at the second field: `MM/DD/YYYY`
+    /// has a 1-2 digit day followed by another `/`, while `MM/YYYY` has the year there
+    /// with no second `/`.  A simple `split('/')` gives 2 or 3 parts, but that forces
+    /// a heap allocation and still requires per-field length checks.
+    ///
+    /// The byte walker resolves the ambiguity without allocating by peeking ahead:
+    /// - If the second numeric run has 3+ digits, it must be the year → `MM/YYYY`.
+    /// - If after 1-2 digits the next byte is `/`, the run is a day → `MM/DD/YYYY`.
+    /// - If the input ends after 1-2 digits, the run is also the year → `MM/YYYY`.
+    ///
+    /// Any other byte is an immediate error, keeping the state machine exhaustive.
     fn parse_slash_date(s: &str) -> Result<Self, ParseError> {
         let b = s.as_bytes();
         let err = || ParseError::InvalidFormat(s.to_string());