Main

.Rbuildignore

@@ -8,3 +8,9 @@
 ^figs$
 ^manuscripts$
 ^\.travis\.yml$
+^doc$
+^Meta$
+^\.github$
+^.*\.Rcheck$
+^superNetballR_.*\.tar\.gz$
+^changelog\.md$

.github/copilot-instructions.md

@@ -0,0 +1,82 @@
+# netballR — Copilot Instructions
+
+## Package overview
+
+`netballR` is an R package (R ≥ 4.1.0) that downloads Champion Data netball match feeds and transforms them into tidy data frames. It wraps the Champion Data `/data/<comp_id>/...` HTTP API, which requires no authentication.
+
+## Build, test, and lint commands
+
+```sh
+make document   # regenerate docs + NAMESPACE via roxygen2 — run after any roxygen change
+make test       # run test suite (testthat, stops on failure)
+make check      # build tarball then R CMD check --as-cran
+make install    # install package locally
+```
+
+Run a single test file:
+```sh
+Rscript -e "testthat::test_file('tests/testthat/test-downloadMatch.R')"
+```
+
+After adding or renaming exported functions, always run `make document` before `make check` — NAMESPACE is generated by roxygen2 and must not be edited manually.
+
+## Architecture
+
+Two discovery pathways feed the same download workflow:
+
+```
+listCompetitions(source)                          ─┐
+  listCompetitionsNetballAus()   ─ "netball_aus"   │
+  listCompetitionsNetballNZ()    ─ "netball_nz"    │
+  listCompetitionsEnglandNetball()─"england_netball"├─→ downloadFixture(comp_id)
+  listCompetitionsWorldCup(year) ─ "nwc20XX"       │       ↓
+  listAllCompetitions()          ─ all sources     ─┘  downloadMatch(comp_id, round_id, game_id)
+                                                           ↓
+anzc_comp_ids (dataset) ──────────────────────────→ tidyMatch() / tidyPlayers()
+                                                           ↓
+                                               matchPoints() / ladders()          # 2020+ super-shot
+                                               matchPoints_pre_2020() / ladders_pre_2020()  # pre-2020 / ANZ
+```
+
+- All catalogue functions share the same underlying generic: `listCompetitions(source)` → `fetch_application_settings(path)` → `extract_competitions(payload, source)`.
+- Source names (`"netball_aus"`, `"nwc2019"`, etc.) are friendly identifiers that map to Champion Data application paths via `.application_source_map`. `"nwc2019"` maps to `"VitalityNetballWorldCup2019"` internally.
+- World Cup catalogues (`nwc2015`, `nwc2019`, `nwc2023`) return `NA` for `competition_name` — their payloads have `id` + `full_names` only.
+- The same `comp_id` can appear in multiple catalogues (e.g. Constellation Cup in both `netball_aus` and `netball_nz`). `listAllCompetitions(deduplicate = TRUE)` handles this; source order in `sources` determines which row wins.
+
+## Key conventions
+
+### Naming
+- **Exported functions**: `camelCase` (`downloadMatch`, `tidyMatch`, `matchPoints`, `listCompetitionsNetballAus`, `listAllCompetitions`).
+- **Internal helpers**: `snake_case` (`build_application_settings_url`, `extract_competitions`, `fetch_application_settings`, `resolve_application_source`).
+- **Adding a new catalogue source**: add an entry to `.application_source_map` in `R/competitions.R` and add a named wrapper function. The friendly key (e.g. `"nwc2019"`) becomes the public-facing `source` argument and appears in the `application_source` column of results.
+
+### Documentation
+- All exported functions have roxygen2 comments with `@param`, `@return`, `@details`, and `\dontrun{}` examples.
+- Column names in `@return` use `\describe{}`/`\item{}`.
+- After edits to roxygen blocks, run `make document`.
+- `globalVariables()` declarations for all dplyr/tidyr column names live in `R/netballR-package.R` — add new column names there to silence `R CMD check` notes.
+
+### HTTP pattern
+All HTTP calls use `httr::RETRY("GET", ..., times = 3, pause_base = 1, terminate_on = c(400, 401, 403, 404), quiet = TRUE)` followed by `httr::stop_for_status()`. Never use bare `httr::GET`.
+
+### Error handling
+User-facing errors use `stop(..., call. = FALSE)`. Validation helpers (`validate_identifier`, `validate_positive_whole_number`) live in `R/downloadMatch.R` and should be reused for any new ID parameters.
+
+### Scoring era split
+- 2020+ Super Netball uses `goal_from_zone1` (1 pt) and `goal_from_zone2` (2 pts) — handled by `matchPoints()` / `ladders()`.
+- Pre-2020 and ANZ Championship use `goals` — handled by `matchPoints_pre_2020()` / `ladders_pre_2020()`.
+- Adding new scoring logic? Add it as a new function pair, not by changing the existing ones.
+
+### Pipe
+Use the native pipe `|>` (R 4.1+). Do not use `%>%` from magrittr.
+
+### Null coalescing
+The `%||%` operator is defined in `R/downloadMatch.R` (`#' @noRd`) and is available across the package.
+
+## Testing
+
+- Tests live in `tests/testthat/test-*.R`, one file per source file.
+- Shared test fixtures are in `tests/testthat/helper-fixtures.R` as factory functions (`make_sample_match()`, `make_modern_match_stats()`, etc.).
+- Internal (unexported) functions are tested via `netballR:::function_name` triple-colon access.
+- Tests do **not** make real HTTP calls — validation is tested at the URL-builder and extractor layer.
+- Use `testthat::expect_error(..., regexp)` to assert specific error messages from validation helpers.

.github/dependabot.yml

@@ -0,0 +1,13 @@
+version: 2
+
+updates:
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    labels:
+      - "dependencies"
+      - "github-actions"
+    open-pull-requests-limit: 5
+    commit-message:
+      prefix: "ci"

.github/workflows/R-CMD-check.yaml

@@ -0,0 +1,43 @@
+name: R-CMD-check
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  R-CMD-check:
+    runs-on: ${{ matrix.config.os }}
+
+    strategy:
+      fail-fast: false
+      matrix:
+        config:
+          - os: ubuntu-latest
+            r: release
+          - os: macos-latest
+            r: release
+          - os: windows-latest
+            r: release
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: r-lib/actions/setup-r@v2
+        with:
+          r-version: ${{ matrix.config.r }}
+          use-public-rspm: true
+
+      - uses: r-lib/actions/setup-r-dependencies@v2
+        with:
+          extra-packages: any::rcmdcheck
+          needs: check
+
+      - uses: r-lib/actions/check-r-package@v2
+        with:
+          args: 'c("--no-manual", "--as-cran")'

.gitignore

@@ -15,7 +15,7 @@
 *.html
 *.RData
 *.rds
-*.rda
+# *.rda excluded: R package data files in data/ must be committed
 *.tex
 *.fdb_latexmk
 *.fls
@@ -37,3 +37,6 @@ data-raw/*
 docker/*
 /scripts/strip-libs.sh
 /Rmd/sn-get-data.Rmd
+doc
+Meta
+*.Rcheck

DESCRIPTION

@@ -1,18 +1,30 @@
-Package: superNetballR
-Title: Downloads and tidies super netball statistics
-Version: 0.1.0
-Authors@R: person("Steve", "Lane", email = "lane.s@unimelb.edu.au", role = c("aut", "cre"))
-Description: This package provides functions to easily download and manipulate data from super netball matches.
-Depends: R (>= 3.4.0)
+Package: netballR
+Title: Download and Tidy Netball Match Statistics
+Version: 0.5.0
+Authors@R: c(
+    person("Steve", "Lane", email = "lane.s@unimelb.edu.au", role = "aut"),
+    person("Craig", "Moyle", email = "craig.moyle@mantelgroup.com.au",
+           role = c("aut", "cre"))
+  )
+Description: Tools to download Champion Data match feeds for netball
+    competitions and transform team and player statistics into tidy data
+    frames for analysis.
+Depends: R (>= 4.1.0)
 License: MIT + file LICENSE
 Encoding: UTF-8
 LazyData: true
-Suggests: knitr,
+Suggests: ggplot2,
+    knitr,
     rmarkdown,
-    here
+    shiny,
+    testthat (>= 3.0.0)
 VignetteBuilder: knitr
-Imports: dplyr,
+Imports: dplyr (>= 1.1.0),
     httr,
-    tidyr,
-    purrr
-RoxygenNote: 6.0.1
+    purrr,
+    tidyr
+URL: https://craigmoyle.github.io/netballR/,
+    https://github.com/craigmoyle/netballR
+BugReports: https://github.com/craigmoyle/netballR/issues
+Config/testthat/edition: 3
+Config/roxygen2/version: 8.0.0

Makefile

@@ -1,28 +1,32 @@
 # Makefile
-# Time-stamp: <2018-04-08 09:52:43 (slane)>
-.PHONY: all document build test check checking install winbuild site
+.PHONY: all build check checking clean document install site test winbuild
 
-all: document build check install site
+PKG_TARBALL := $(shell Rscript -e "desc <- read.dcf('DESCRIPTION')[1, ]; cat(sprintf('%s_%s.tar.gz', desc[['Package']], desc[['Version']]))")
 
-checking: document build test check
+all: document test check install
+
+checking: document test check
 
 document:
-	Rscript -e "devtools::document()"
+	Rscript -e "roxygen2::roxygenise()"
 
 build:
-	Rscript -e "devtools::build()"
+	R CMD build .
 
 test:
-	Rscript -e "devtools::test()"
+	Rscript -e "testthat::test_local('.', reporter = 'summary', stop_on_failure = TRUE)"
 
-check:
-	Rscript -e "devtools::check()"
+check: build
+	R CMD check --no-manual --as-cran $(PKG_TARBALL)
 
 install:
-	Rscript -e "devtools::install(build_vignettes = TRUE, upgrade_dependencies = FALSE)"
+	R CMD INSTALL .
 
 winbuild:
-	Rscript -e "devtools::build_win(version = 'R-devel', quiet = TRUE)"
+	@echo "Use the GitHub Actions R-CMD-check workflow for Windows validation."
 
 site:
-	Rscript -e "pkgdown::clean_site(); pkgdown::build_site()"
+	Rscript -e "pkgdown::build_site()"
+
+clean:
+	rm -rf *.tar.gz *.Rcheck

NAMESPACE

@@ -1,9 +1,18 @@
 # Generated by roxygen2: do not edit by hand
 
+export(downloadFixture)
 export(downloadMatch)
 export(ladders)
+export(ladders_pre_2020)
+export(listAllCompetitions)
+export(listCompetitions)
+export(listCompetitionsEnglandNetball)
+export(listCompetitionsNetballAus)
+export(listCompetitionsNetballNZ)
+export(listCompetitionsWorldCup)
 export(matchPoints)
+export(matchPoints_pre_2020)
 export(matchResults)
+export(shinyNetballR)
 export(tidyMatch)
 export(tidyPlayers)
-importFrom(dplyr,"%>%")