refactor: add repository QC, method registry, and shared utilities

Author: Thokas99

.github/workflows/quality-control.yml

@@ -0,0 +1,54 @@
+name: Repository quality control
+
+on:
+  push:
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  structural-checks:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v7
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Set up Ruby and website dependencies
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: "3.3"
+          bundler-cache: true
+          working-directory: website
+
+      - name: Set up R
+        uses: r-lib/actions/setup-r@v2
+        with:
+          r-version: "release"
+
+      - name: Check Python, paths, files, links, and registry
+        run: |
+          python scripts/check_repository.py
+          python scripts/build_method_registry.py --check
+
+      - name: Check YAML and Quarto front matter
+        run: ruby scripts/check_quarto_yaml.rb
+
+      - name: Check R syntax
+        run: Rscript scripts/check_r_syntax.R
+
+      - name: Build the website
+        working-directory: website
+        run: |
+          bundle exec ruby scripts/build_notebook_search.rb
+          bundle exec ruby scripts/build_downloads.rb
+          bundle exec jekyll build --baseurl "/Useful_code"
+
+      - name: Check generated website links
+        run: python scripts/check_repository.py --site website/_site

CODE_MAP/method_registry.tsv

@@ -34,6 +34,8 @@ reuse the useful parts.
 Useful code keeps readable analytical workflows together with the parameters,
 diagnostics, and implementation details that make them useful when reopened.
 The website groups the notebooks by analysis area and links back to the files.
+The generated registry in `CODE_MAP/method_registry.tsv` makes the active
+notebook collection searchable by script.
 
 ## Browse the methods
 
@@ -60,12 +62,31 @@ Before reusing a notebook:
 4. Adapt paths and other dataset-specific assumptions.
 5. Validate the outputs on your own data and study design.
 
+## Repository checks and registry
+
+GitHub Actions runs lightweight checks on pushes and pull requests: YAML and
+Quarto front matter, Markdown links, Python and R syntax, reusable-template
+paths, large files, registry consistency, and the website build. It does not
+run the bioinformatics analyses.
+
+Regenerate the notebook registry after changing the active catalog with:
+
+```bash
+python3 scripts/build_method_registry.py
+```
+
+Use `--check` in CI or before committing to confirm that the tracked TSV is
+current.
+
 ## Repository structure
 
+    functions/        small reusable R and Python implementation primitives
     templates/       reusable notebooks
     examples/        project-specific analyses and context
     cheatsheets/     compact references
     miscellaneous/   reporting prompts and reusable documentation material
+    scripts/          repository maintenance and registry checks
+    CODE_MAP/         searchable repository metadata
     website/         Jekyll catalog website
     docs/            architecture and refactor documentation
     archive/         superseded historical material

README.md

@@ -0,0 +1,11 @@
+#' Standardize a numeric vector using base R's scale behavior.
+#'
+#' @param x A numeric vector.
+#' @return A numeric vector with the scaled values.
+zscore <- function(x) {
+  if (!is.numeric(x)) {
+    stop("x must be numeric.", call. = FALSE)
+  }
+
+  as.numeric(scale(x))
+}

functions/R/zscore.R

@@ -0,0 +1,23 @@
+# Shared functions
+
+`functions/` contains small, standalone implementation primitives that are
+useful across more than one notebook. The analytical notebooks remain
+self-contained where sourcing a repository-relative file would make copying
+them harder.
+
+R:
+
+```r
+source("functions/R/zscore.R")
+zscore(values)
+```
+
+Python:
+
+```python
+from functions.python.write_tsv import write_tsv
+
+write_tsv(table, "output/table.tsv")
+```
+
+These helpers do not replace the notebook workflows or package documentation.

functions/README.md

@@ -0,0 +1,23 @@
+"""Small helper for writing dataframe-like objects as TSV files."""
+
+from pathlib import Path
+from typing import Any, Union
+
+
+def write_tsv(table: Any, path: Union[str, Path]) -> None:
+    """Write a dataframe-like object as a headered TSV.
+
+    The object must provide a pandas-compatible ``to_csv`` method. Parent
+    directories are created, but table contents and output names stay with the
+    caller.
+    """
+
+    if not hasattr(table, "to_csv"):
+        raise TypeError("table must provide a to_csv method")
+
+    output_path = Path(path)
+    if output_path.exists() and output_path.is_dir():
+        raise IsADirectoryError(output_path)
+
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+    table.to_csv(output_path, sep="\t", index=False)