From a9e80858d43922d70f8cba5a27c092ca8515746e Mon Sep 17 00:00:00 2001 From: Jared Knowles Date: Mon, 3 Aug 2026 11:37:15 -0400 Subject: [PATCH] docs: correct coverage_window scope and the stale CLAUDE.md Current State block (#25) F-7: inst/schemas/provenance-v1.json described coverage_window as mapping each *observed* balance_subtype, but the query at R/balance_caveats.R has no predicate tied to the query's codes and always returns every subtype in the mounted corpus. Took option (b) of the two the review offered -- change the doc, not the code. Reporting all windows is the better product behaviour (it answers 'is there a family I missed?'), it is what cog-api#26 already forwards verbatim, and option (a) would make the block empty for a 0-row result. Reworded to say the windows are corpus-wide and that 'truncated' is the query-scoped field. Pinned by a new test either way. F-10: the 'Current State' block was self-contradictory after a partial update -- headed 2026-04-27, claiming branch main @ d65e9fe, with a 2026-08-03 test count measured on feat/cog-balances-25 underneath it, and listing README.md / _pkgdown.yml as outstanding when both exist and _pkgdown.yml was edited by this branch. All numbers below re-measured on the final tree after every other fix in this wave, not before: 788 tests (testthat::test_local()), 14 exports (NAMESPACE), 14 man/*.Rd, 2 vignettes, no docs/ (pkgdown::build_site() genuinely still outstanding, as is the .Rbuildignore fixture entry -- both kept in the list). The related deferred README.md item is closed with no change, per the review's ruling: README.md enumerates no verbs at all, so naming cog_balances would make it the only non-cog_spending verb mentioned. --- CLAUDE.md | 18 ++++++++++-------- inst/schemas/provenance-v1.json | 2 +- 2 files changed, 11 insertions(+), 9 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 6a88b54..5fdb610 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -60,19 +60,20 @@ USCOGDATA_URL (local path or https://) Any value without `://` is treated as a local path by `.is_local_path()` and reads `manifest.json` directly from disk (no HTTP, no TTL cache). -## Current State (2026-04-27) +## Current State (2026-08-03) **Version:** 0.1.0 (pre-release) -**Branch:** `main`, commit `d65e9fe` -**Tests:** 764 PASS / 0 FAIL / 0 SKIP (measured `testthat::test_local()`, 2026-08-03, on the tree including the balance_caveats schema test) +**Branch:** `feat/cog-balances-25`, commit `fde62eb` +**Tests:** 788 PASS / 0 FAIL / 0 SKIP / 0 WARN (measured `testthat::test_local()`, 2026-08-03, after the final-review fix wave) **CI:** Gitea Actions green (`.gitea/workflows/ci.yml`) ### Completed (Tasks 2.1–2.7) -All 10 exported verbs implemented and tested: +All **14** exports implemented and tested (measured from `NAMESPACE`): `cog_spending`, `cog_revenue`, `cog_balances`, `cog_explain`, `cog_geographic_rollup`, `cog_find_peers`, `cog_peer_compare`, -`cog_gov_search`, `cog_mirror`, plus `cog_categories`. +`cog_gov_search`, `cog_mirror`, `cog_categories`, `cog_recipes`, +`cog_manifest`, `cog_basket_resolution`, `cog_basket_unresolved`. Bundled fixture corpus at `inst/extdata/fixture_corpus/` (years 2011, 2012, 2019, 2020 — measured via DuckDB `read_parquet(hive_partitioning=1)`, @@ -80,9 +81,10 @@ Bundled fixture corpus at `inst/extdata/fixture_corpus/` (years ### Remaining to v0.1 release -1. **Task 2.8 — Docs:** roxygen `@param`/`@return`/`@examples` on all exports; - full `README.md`; `_pkgdown.yml`; `devtools::document()` + `pkgdown::build_site()`. - Vignettes can be stubbed for v0.1. +1. **Task 2.8 — Docs:** mostly done — all 14 exports have a `man/*.Rd`, + `README.md` and `_pkgdown.yml` exist, and `vignettes/` carries + `total-spending.Rmd` + `population-denominators.Rmd`. Outstanding: + `pkgdown::build_site()` has never been run (no `docs/`). 2. **Phase 3 — cog_explorer bridge:** create `cog_explorer/examples/hello_world_uscogdata.Rmd` (installs from Gitea, runs diff --git a/inst/schemas/provenance-v1.json b/inst/schemas/provenance-v1.json index a430cd5..b7e942b 100644 --- a/inst/schemas/provenance-v1.json +++ b/inst/schemas/provenance-v1.json @@ -55,7 +55,7 @@ }, "balance_caveats": { "type": ["object", "null"], - "description": "Present only on cog_balances() results (null/absent for cog_spending()/cog_revenue()). `not_gaap` is always TRUE and `not_gaap_note` explains that Census holdings are gross -- no liabilities are netted -- so they are NOT comparable to a GAAP fund balance. `coverage_window` maps each observed balance_subtype to its measured [min year, max year] in the mounted corpus (never hardcoded). `truncated` lists the subtypes whose coverage_window does not fully span the requested years.", + "description": "Present only on cog_balances() results (null/absent for cog_spending()/cog_revenue()). `not_gaap` is always TRUE and `not_gaap_note` explains that Census holdings are gross -- no liabilities are netted -- so they are NOT comparable to a GAAP fund balance. `coverage_window` maps EVERY balance_subtype present in the mounted corpus -- not only the ones this query observed -- to its measured [min year, max year] there (never hardcoded), so a caller can see which families exist and over what span before deciding they missed one. `truncated` is the query-scoped field: it lists only the subtypes this result actually observed whose coverage_window does not fully span the requested years.", "properties": { "not_gaap": { "type": "boolean" }, "not_gaap_note": { "type": "string" },