v1.2.0: GRCh36 fallback fix, database auto-refresh, version-tag guard

- GRCh36 safety guard: non-confident GRCh36 detection no longer falls
  back to GRCh37. Covers both the end-of-stream flush path and the
  buffer-limit path (large FTDNA files with sparse probe SNPs).
  ClinVar is correctly skipped for GRCh36 data.
- Database auto-refresh: the analysis pipeline checks database ages
  before running. Databases older than 7 days with a changed remote
  signal are refreshed automatically. --no-update to skip. Network
  failures warn and continue.
- Version-tag drift guard: pre-push hook asserts pushed v* tags match
  pyproject.toml version.
- Corpas exome VCF attribution with paper DOI and CC-BY/CC0 license.
- pyproject.toml version corrected (was 1.1.0 on v1.1.1 release).
- Changelog dates corrected to match actual release timestamps.

Author: dial481

.pre-commit-config.yaml

@@ -33,3 +33,11 @@ repos:
         pass_filenames: false
         always_run: true
         stages: [pre-push]
+
+      - id: version-tag-match
+        name: version-tag-match (pyproject.toml == pushed tag)
+        entry: scripts/check_version_tag.sh
+        language: script
+        pass_filenames: false
+        always_run: true
+        stages: [pre-push]

CHANGELOG.md

@@ -2,9 +2,39 @@
 
 All notable changes are documented here. Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); the project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [Unreleased]
+## [1.2.0] — 2026-06-07
 
-## [1.1.1] — 2026-06-07
+### Fixed
+- `pyproject.toml` version corrected to match release (was `1.1.0` on
+  the v1.1.1 release).
+- **GRCh36 fallback bug.** Non-confident GRCh36 detection (e.g., 3/4
+  probe SNPs matched) was falling back to GRCh37 as the effective build,
+  silently bypassing the ClinVar safety guard and annotating GRCh36
+  positions against GRCh37 coordinates. Fixed in both the end-of-stream
+  `flush()` path AND the buffer-limit path (large files where probe SNPs
+  appear past the 100K-variant buffer cap). The pipeline now uses GRCh36
+  as the effective build whenever detection points to GRCh36, even
+  non-confidently or with a single probe SNP match.
+
+### Added
+- **Auto-refresh stale databases.** `analyze`, `methylation`, and
+  `pharmacogenomics` now check database file ages before running. If any
+  database is older than 7 days and the remote signal (MD5/ETag) has
+  changed, the database is refreshed automatically. If the network is
+  unreachable, a warning is printed and analysis continues with the stale
+  cache. SNPedia is excluded (no remote download). Use `--no-update` to
+  skip the freshness check entirely.
+- Corpas family exome VCF attribution in `test_data/edge_cases/README.md`
+  with paper DOI (Corpas et al., *BMC Genomics* 2015,
+  doi:10.1186/s12864-015-1973-7). Licensing table in `test_data/README.md`
+  updated. Every genotype fixture in the repo now has documented
+  provenance and license.
+- **Version-tag drift guard.** Pre-push hook
+  (`scripts/check_version_tag.sh`) asserts any pushed `v*` tag matches
+  the version in `pyproject.toml`. Prevents the class of bug where a
+  release ships with a stale version string.
+
+## [1.1.1] — 2026-06-06
 
 ### Changed
 - Relocated real genotype test data (`test_data/real/` and
@@ -1202,7 +1232,7 @@ All notable changes are documented here. Format follows [Keep a Changelog](https
 - GitHub Actions CI matrix on Python 3.11 and 3.12.
 
 
-[Unreleased]: https://github.com/dial481/allelix/compare/v1.1.1...HEAD
+[1.2.0]: https://github.com/dial481/allelix/compare/v1.1.1...v1.2.0
 [1.1.1]: https://github.com/dial481/allelix/compare/v1.1.0...v1.1.1
 [1.1.0]: https://github.com/dial481/allelix/compare/v1.0.0...v1.1.0
 [1.0.0]: https://github.com/dial481/allelix/releases/tag/v1.0.0

allelix/cli.py

@@ -6,6 +6,7 @@
 
 import logging
 import sys
+import time
 from pathlib import Path
 from typing import TYPE_CHECKING, NamedTuple
 
@@ -128,6 +129,50 @@ def _ready_annotators(
     return resolved, ready, not_ready
 
 
+_STALENESS_SECONDS = 7 * 24 * 60 * 60  # 7 days
+
+
+def _maybe_refresh_databases(data_dir: Path) -> None:
+    """Check database mtimes; refresh any that are stale and have a changed remote signal.
+
+    Only runs for annotators that download data (SNPedia excluded).
+    If the network is unreachable, warns and continues with stale caches.
+    """
+    now = time.time()
+    annotators = get_annotators(data_dir)
+    for annotator in annotators:
+        with annotator:
+            if not annotator.requires_download or not annotator.is_ready():
+                continue
+            db_files = list(data_dir.glob(f"{annotator.name}*sqlite*"))
+            if not db_files:
+                continue
+            newest_mtime = max(f.stat().st_mtime for f in db_files)
+            age = now - newest_mtime
+            if age <= _STALENESS_SECONDS:
+                continue
+
+            remote = annotator.fetch_remote_signal()
+            if remote is None:
+                age_days = int(age / 86400)
+                console.print(
+                    f"[yellow]{annotator.display_name} database is {age_days} days old. "
+                    "Run `allelix db update` when online.[/yellow]"
+                )
+                continue
+
+            cached = annotator.cached_remote_signal()
+            if cached == remote:
+                continue
+
+            console.print(f"[bold]Updating {annotator.display_name}…[/bold]")
+            _run_setup(annotator)
+            console.print(
+                f"[green]✓ {annotator.display_name} updated[/green] "
+                f"(version {annotator.version() or '(unknown)'})"
+            )
+
+
 def _format_from_path(output: Path, override: str | None) -> str:
     if override:
         return override.lower()
@@ -158,7 +203,11 @@ def _run_analysis_command(
     exclude_sources: frozenset[str] | None = None,
     gwas_all: bool = False,
     diff_path: Path | None = None,
+    no_update: bool = False,
 ) -> None:
+    resolved = resolve_data_dir(data_dir)
+    if not no_update:
+        _maybe_refresh_databases(resolved)
     parser = _resolve_parser(file_path, fmt)
     _, ready, not_ready = _ready_annotators(
         data_dir, include_benign=include_benign, gwas_filter_traits=not gwas_all
@@ -458,6 +507,12 @@ def stats(file_path: Path, fmt: str | None) -> None:
         "Not a monitoring tool — use for version-to-version validation."
     ),
 )
+_NO_UPDATE_OPT = click.option(
+    "--no-update",
+    is_flag=True,
+    default=False,
+    help="Skip the pre-analysis database freshness check.",
+)
 _BUILD_OPT = click.option(
     "--build",
     type=click.Choice(["grch37", "grch38", "auto"], case_sensitive=False),
@@ -551,6 +606,7 @@ def _emit_build_diagnostics(result: object) -> None:
 @_GWAS_ALL_OPT
 @_EXCLUDE_SNPEDIA_OPT
 @_DIFF_OPT
+@_NO_UPDATE_OPT
 def analyze(
     file_path: Path,
     fmt: str | None,
@@ -566,6 +622,7 @@ def analyze(
     gwas_all: bool,
     exclude_snpedia: bool,
     diff_path: Path | None,
+    no_update: bool,
 ) -> None:
     """Annotate a genotype file against all ready reference databases."""
     _run_analysis_command(
@@ -584,6 +641,7 @@ def analyze(
         exclude_sources=frozenset({"snpedia"}) if exclude_snpedia else None,
         gwas_all=gwas_all,
         diff_path=diff_path,
+        no_update=no_update,
     )
 
 
@@ -738,6 +796,7 @@ def compare(file1: Path, file2: Path, fmt1: str | None, fmt2: str | None) -> Non
 @_GWAS_ALL_OPT
 @_EXCLUDE_SNPEDIA_OPT
 @_DIFF_OPT
+@_NO_UPDATE_OPT
 def methylation(
     file_path: Path,
     fmt: str | None,
@@ -753,6 +812,7 @@ def methylation(
     gwas_all: bool,
     exclude_snpedia: bool,
     diff_path: Path | None,
+    no_update: bool,
 ) -> None:
     """Methylation-pathway-focused report (MTHFR, MTR, MTRR, COMT, CBS, …)."""
     excluded: set[str] = set()
@@ -776,6 +836,7 @@ def methylation(
         exclude_sources=frozenset(excluded) if excluded else None,
         gwas_all=gwas_all,
         diff_path=diff_path,
+        no_update=no_update,
     )
 
 
@@ -794,6 +855,7 @@ def methylation(
 @_GWAS_ALL_OPT
 @_EXCLUDE_SNPEDIA_OPT
 @_DIFF_OPT
+@_NO_UPDATE_OPT
 def pharmacogenomics(
     file_path: Path,
     fmt: str | None,
@@ -809,6 +871,7 @@ def pharmacogenomics(
     gwas_all: bool,
     exclude_snpedia: bool,
     diff_path: Path | None,
+    no_update: bool,
 ) -> None:
     """Pharmacogenomics-focused report (annotations from PharmGKB-style sources)."""
     excluded: set[str] = set()
@@ -832,6 +895,7 @@ def pharmacogenomics(
         exclude_sources=frozenset(excluded) if excluded else None,
         gwas_all=gwas_all,
         diff_path=diff_path,
+        no_update=no_update,
     )
 
 

allelix/reports/_pipeline.py

@@ -19,6 +19,7 @@
 from typing import TYPE_CHECKING
 
 from allelix.utils.build_detect import (
+    BUILD_GRCH36,
     BUILD_GRCH37,
     BUILD_GRCH38,
     KNOWN_SNP_POSITIONS,
@@ -325,9 +326,17 @@ def feed(self, variant: Variant) -> tuple[bool, list[Variant]]:
                 self._buffer.clear()
                 return True, batch
         if len(self._buffer) >= _DETECTION_BUFFER_LIMIT:
-            # Stream is unusually large with no known SNPs hit; fall back so we
-            # don't OOM. Detection failed → use header build, then GRCh37.
-            self.effective = self.header_build or BUILD_GRCH37
+            # Buffer full before detection converged. Run partial detection
+            # so the GRCh36 safety guard can fire (same logic as flush()).
+            result = detect_build(self._buffer)
+            if result.build is not None:
+                self.detected = result.build
+            self.matched_count = result.matched
+            self.inspected_count = result.inspected
+            if result.build == BUILD_GRCH36:
+                self.effective = BUILD_GRCH36
+            else:
+                self.effective = self.header_build or BUILD_GRCH37
             batch = [replace(v, build=self.effective) for v in self._buffer]
             self._buffer.clear()
             return True, batch
@@ -343,10 +352,15 @@ def flush(self) -> list[Variant]:
             self.detected = result.build
             self.effective = result.build
         else:
-            # Fall back to header → default. Surface partial counts.
-            self.effective = self.header_build or BUILD_GRCH37
             if result.build is not None:
                 self.detected = result.build
+            # GRCh36 must fail safe: there is no GRCh36 ClinVar cache,
+            # so falling back to GRCh37 would silently query wrong
+            # coordinates and bypass the GRCh36 safety guard.
+            if result.build == BUILD_GRCH36:
+                self.effective = BUILD_GRCH36
+            else:
+                self.effective = self.header_build or BUILD_GRCH37
         self.matched_count = result.matched
         self.inspected_count = result.inspected
         out = [replace(v, build=self.effective) for v in self._buffer]

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "allelix"
-version = "1.1.0"
+version = "1.2.0"
 description = "Open-source genotype analysis toolkit. Format-agnostic ingestion, database-agnostic annotation, offline-first."
 readme = "README.md"
 requires-python = ">=3.11"

scripts/check_version_tag.sh

@@ -0,0 +1,27 @@
+#!/usr/bin/env bash
+# Pre-push guard: if a version tag (v*) is being pushed, assert it
+# matches pyproject.toml. Prevents the 1.1.0-on-v1.1.1 class of bug.
+#
+# Pre-push hooks receive lines on stdin:
+#   <local ref> <local sha> <remote ref> <remote sha>
+
+pyproject_version=$(python3 -c "
+import tomllib, pathlib
+d = tomllib.loads(pathlib.Path('pyproject.toml').read_text())
+print(d['project']['version'])
+")
+
+while read -r local_ref local_sha remote_ref remote_sha; do
+    tag="${local_ref#refs/tags/}"
+    case "$tag" in
+        v*)
+            expected="v${pyproject_version}"
+            if [ "$tag" != "$expected" ]; then
+                echo "ERROR: pushing tag '$tag' but pyproject.toml says version '${pyproject_version}' (expected tag '$expected')" >&2
+                exit 1
+            fi
+            ;;
+    esac
+done
+
+exit 0

test_data/README.md

@@ -55,7 +55,8 @@ formats.
 
 | Source | License | Notes |
 |---|---|---|
-| openSNP genotype files (real/, transcoded/, plus the synthetic source for baselines) | [CC0 1.0 Universal](https://creativecommons.org/publicdomain/zero/1.0/) | Public domain. |
+| openSNP genotype files (real/, transcoded/, edge_cases/, plus the synthetic source for baselines) | [CC0 1.0 Universal](https://creativecommons.org/publicdomain/zero/1.0/) | Public domain. |
+| Corpas family exome VCF (edge_cases/unsupported_23andme_exome_vcf.txt) | CC-BY / CC0 (see [Corpas et al. 2015](https://doi.org/10.1186/s12864-015-1973-7)) | Deliberately public-released by subjects. Attributed to satisfy CC-BY. |
 | ClinVar (in databases/) | NCBI public domain | Restore via `allelix db update`. |
 | GWAS Catalog (in databases/) | NCBI/EBI public domain | Same. |
 | PharmGKB (in databases/) | [CC BY-SA 4.0](https://creativecommons.org/licenses/by-sa/4.0/) | Attribution required if reports are redistributed. |

test_data/edge_cases/README.md

@@ -59,13 +59,24 @@ what it tests, and the expected parser behavior.
 - **Expected behavior:** `allelix stats` returns `Error: No parser recognized`.
 
 ### `unsupported_23andme_exome_vcf.txt`
-- **Source:** openSNP user1, file 3302. Provenance: CC0.
-- **What it is:** 23andMe whole-exome VCF (a research-only deliverable,
-  distinct from 23andMe's standard chip export). VCF format, not supported
-  by Allelix v1.x (VCF is on the v2 roadmap).
+- **Source:** Corpas family "Corpasome" release; dataset via figshare,
+  project tag "Corpasome". Originally deposited on openSNP as user1,
+  file 3302.
+- **Citation:** Corpas M et al., "Crowdsourced direct-to-consumer genomic
+  analysis of a family quartet," *BMC Genomics* 2015.
+  doi:10.1186/s12864-015-1973-7
+- **License:** Released CC-BY by the family (2013); described as CC0 in
+  the 2015 paper. Attributed here to satisfy CC-BY.
+- **What it is:** Whole-exome variant calls (~115k variants) from a
+  GATK HaplotypeCaller pipeline. VCF format, not supported by Allelix
+  v1.x (VCF is on the v2 roadmap).
 - **What it tests:** Unsupported format rejected cleanly even when the
   filename suggests it might be 23andMe.
 - **Expected behavior:** `allelix stats` returns `Error: No parser recognized`.
+- **Note:** This is the only named-individual dataset in the repo. The
+  Corpas family deliberately released their genomic data to the public.
+  Replacement with a synthetic or fully anonymous exome VCF is tracked
+  as a follow-up.
 
 ### `mhg_grch38_with_grch37_header.txt`
 - **Source:** Synthetic MHG (Tempus) fixture. Hand-built from the project's