1.0.2

.dockerignore

@@ -0,0 +1,10 @@
+target/
+fuzz/target/
+site/
+docs/
+benchmarks/
+logo/
+.git/
+.github/
+.cache/
+bindings/*/target/

.github/CONTRIBUTING.md

@@ -15,10 +15,12 @@ Thank you for your interest in contributing to **snpick**! We welcome contributi
 - [Code of Conduct](#code-of-conduct)
 
 ## Project Description
-`snpick` is a tool designed to identify **Multi-Nucleotide Variants (MNVs)** within the same codon in genomic sequences. MNVs occur when multiple Single Nucleotide Variants (SNVs) are present within the same codon, leading to the translation of a different amino acid. This tool addresses limitations in current annotation programs like **ANNOVAR** or **SnpEff**, which are primarily designed to work with individual SNVs and might overlook the actual amino acid changes resulting from MNVs.
+`snpick` is a fast, memory-efficient tool for extracting variable (SNP) sites from whole-genome **FASTA alignments**. It produces reduced alignments ready for phylogenetic inference with ascertainment-bias correction (ASC) in **IQ-TREE** and **RAxML**, and can optionally emit a VCF file. Its zero-copy, memory-mapped architecture scales to thousands of genomes in seconds with minimal RAM, where matrix-in-memory tools such as **snp-sites** struggle.
 
-### Current Limitations
-**IMPORTANT**: This script currently works only with **SNVs** against a reference genome. Insertions and deletions that modify the reading frame are not supported yet.
+### Scope
+- Input is a **FASTA alignment**: every sequence must have the same length. The first sequence is used as the reference for `REF`/`ALT` polarization.
+- Standard bases `A/C/G/T` (case-insensitive) define variability; IUPAC ambiguous bases (N, R, Y, …) are treated as missing data rather than alleles.
+- Gaps (`-`) are ignored by default and can be included as a 5th character with `-g`.
 
 ## How to Contribute
 We appreciate all contributions, whether it’s fixing bugs, proposing new features, improving the documentation, or suggesting a new direction for the tool.

.github/pull_request_template.md

@@ -1,4 +1,4 @@
-# Pull Request Template for get_MNV
+# Pull Request Template for SNPick
 
 ## Description
 Please include a summary of the changes made in this pull request. Mention any related issues or features that are being addressed.

.github/workflows/docker.yml

@@ -0,0 +1,40 @@
+name: Container
+
+on:
+  push:
+    tags: [ "[0-9]+.[0-9]+.[0-9]+" ]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  packages: write
+
+jobs:
+  docker:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Log in to GHCR
+        uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Docker metadata
+        id: meta
+        uses: docker/metadata-action@v5
+        with:
+          images: ghcr.io/${{ github.repository_owner }}/snpick
+          tags: |
+            type=ref,event=tag
+            type=raw,value=latest
+
+      - name: Build and push
+        uses: docker/build-push-action@v6
+        with:
+          context: .
+          push: true
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}

.github/workflows/docs.yml

@@ -0,0 +1,43 @@
+name: Docs
+
+on:
+  push:
+    branches: [ main ]
+    paths:
+      - 'docs/**'
+      - 'overrides/**'
+      - 'mkdocs.yml'
+      - 'CHANGELOG.md'
+      - '.github/CONTRIBUTING.md'
+      - '.github/workflows/docs.yml'
+  workflow_dispatch:
+
+permissions:
+  contents: write
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          # Full history so git-revision-date-localized can read commit dates.
+          fetch-depth: 0
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.x'
+          cache: pip
+
+      - name: Install Cairo/Pango (social cards)
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y libcairo2-dev libfreetype6-dev libffi-dev \
+            libjpeg-dev libpng-dev libz-dev pngquant
+
+      - name: Install MkDocs Material and plugins
+        run: pip install -r docs/requirements.txt
+
+      - name: Build and deploy to gh-pages
+        # GitHub Actions sets CI=true, which enables the social-cards plugin.
+        run: mkdocs gh-deploy --force

.github/workflows/release.yml

@@ -20,6 +20,7 @@ jobs:
     outputs:
       version: ${{ steps.version.outputs.version }}
       tag: ${{ steps.version.outputs.tag }}
+      skip: ${{ steps.tagcheck.outputs.skip }}
     steps:
       - uses: actions/checkout@v4
 
@@ -32,16 +33,17 @@ jobs:
           echo "📦 Version: $VERSION"
 
       - name: Check if tag already exists
+        id: tagcheck
         run: |
           if git ls-remote --tags origin | grep -q "refs/tags/${{ steps.version.outputs.tag }}$"; then
             echo "⚠️ Tag ${{ steps.version.outputs.tag }} already exists — skipping release."
-            echo "SKIP=true" >> "$GITHUB_ENV"
+            echo "skip=true" >> "$GITHUB_OUTPUT"
           fi
 
     # Build matrix for cross-platform binaries
   build:
     needs: release
-    if: needs.release.outputs.version != ''
+    if: needs.release.outputs.version != '' && needs.release.outputs.skip != 'true'
     strategy:
       fail-fast: false
       matrix:
@@ -94,6 +96,7 @@ jobs:
   # Create GitHub release with all binaries
   publish:
     needs: [release, build]
+    if: needs.release.outputs.skip != 'true'
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4

.github/workflows/rust.yml

@@ -2,27 +2,42 @@ name: Rust
 
 on:
   push:
-    branches: [ "main", "1.0.1" ]
+    branches: [ "main", "1.0.2" ]
   pull_request:
     branches: [ "main" ]
 
 env:
   CARGO_TERM_COLOR: always
 
 jobs:
-  build:
-    runs-on: ubuntu-latest
+  test:
+    name: Test (${{ matrix.os }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ ubuntu-latest, ubuntu-24.04-arm, macos-14, macos-15-intel ]
     steps:
-    - uses: actions/checkout@v4
+      - uses: actions/checkout@v4
+
+      - uses: dtolnay/rust-toolchain@stable
+        with:
+          components: clippy
 
-    - name: Clippy
-      run: cargo clippy -- -D warnings
+      - name: Clippy
+        run: cargo clippy -- -D warnings
 
-    - name: Build
-      run: cargo build --verbose
+      - name: Test
+        run: cargo test --verbose
 
-    - name: Test
-      run: cargo test --verbose
+      - name: Build (release)
+        run: cargo build --release
 
-    - name: Build (release)
-      run: cargo build --release
+  msrv:
+    name: MSRV 1.74
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dtolnay/rust-toolchain@1.74.0
+      - name: Build on the minimum supported Rust version
+        run: cargo build --verbose

.gitignore

@@ -3,3 +3,20 @@ test_*.fasta
 test_*.vcf
 *.vcf
 !src/
+
+# MkDocs build output
+site/
+
+# MkDocs Material social-cards / plugin cache
+.cache/
+
+# cargo-fuzz
+fuzz/target/
+fuzz/corpus/
+fuzz/artifacts/
+fuzz/Cargo.lock
+
+# binding crates
+bindings/*/target/
+bindings/*/Cargo.lock
+bindings/wasm/pkg/

CHANGELOG.md

@@ -0,0 +1,82 @@
+# Changelog
+
+All notable changes to SNPick are documented here. The format is based on
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project
+adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.0.2] - 2026-07-18
+
+### Added
+
+**Filtering & selection**
+- Per-site filtering: `--max-missing`, `--mac`, `--maf`, `--min-samples`,
+  `--max-alleles`. Filtered sites stay variable (never re-enter `fconst`), so ASC
+  correction remains valid.
+- `--keep-samples` / `--exclude-samples` (comma-separated IDs or `@file`) subset
+  the panel before the scan, so `fconst` is recomputed for the retained samples.
+- `--mask <BED>` (and `--mask-ref`) excludes regions from both the output and `fconst`.
+
+**Coordinates & references**
+- `--reference <ID>` chooses the REF/polarity sequence and the VCF `##reference`.
+- `--ref-coords` writes VCF `POS` as ungapped reference positions.
+- `--sites-output <TSV>` maps each site's alignment column to its reference position.
+
+**I/O & formats**
+- Transparent gzip/bgzip input, plus stdin (`-f -`) and stdout (`-o -`) streaming.
+- `--format {fasta,phylip,nexus}` for the reduced alignment.
+- `--stats-json <FILE>` (or `-`) writes a typed JSON run summary with the `fconst` array.
+
+**Robustness & QC**
+- `--dry-run` (stats only) and `--check` (composition audit) exit without writing.
+- `--on-invalid {ignore,warn,error}` guards against non-nucleotide input.
+- `--iupac-mode resolve` optionally resolves IUPAC codes to their bases.
+- Empty/duplicate sequence IDs are rejected (`--allow-dup-ids` to permit).
+- `-v`/`-vv` diagnostics; distinct exit codes (`2` bad input, `1` I/O).
+
+**Threading & VCF**
+- `-t, --threads <N>` pins the Rayon thread pool (deterministic wall-clock; output
+  is unaffected by thread count).
+- `--chrom <NAME>` sets the VCF `CHROM` / `##contig` name (default `1`).
+- `-q, --quiet` silences the `[snpick]` progress logs (errors still print).
+- A valid header-only VCF is written when `--vcf` is requested but there are no
+  variable sites, so pipelines declaring the `.vcf` output no longer break.
+
+**Packaging**
+- Published as a reusable Rust library crate, with Python (pyo3/maturin) and
+  WebAssembly bindings, and Docker/Apptainer container recipes.
+
+### Fixed
+- Silent SNP loss when a single-line FASTA record contained a blank line: such
+  records were read with misaligned byte offsets. They now use the
+  newline-skipping scanner.
+- Gap reference bases produced an invalid VCF `REF` of `-` under `--include-gaps`;
+  the `REF` is now rendered as `N` (a valid VCF base). ALT gaps stay `*` (the snp-sites
+  convention), so `REF` and `ALT` gap encodings differ by design.
+- All-gap columns were tallied in no category under `--include-gaps`, breaking the
+  reported `variable + constant + ambiguous == length` invariant.
+- Bare output filenames (`-o snps.fasta`, no directory) were rejected during path
+  resolution, breaking the documented quickstart.
+- The release workflow's "tag already exists" guard was never read, so merges
+  without a version bump re-published over existing tags.
+- The README's pre-built binary download command pointed at an asset name the
+  release never publishes (404).
+
+### Performance
+- VCF data rows are assembled in a reused byte buffer instead of one formatted
+  write per genotype field — a large speedup on many-sample inputs. Output is
+  byte-identical.
+
+## [1.0.1] - 2026-03-31
+
+- First Bioconda release.
+- Cross-platform Build & Release CI workflow (Linux/macOS, x86_64/aarch64).
+- README overhaul and benchmarks.
+
+## [1.0.0] - 2024-11-16
+
+- Initial release: zero-copy memory-mapped extraction of variable sites from
+  FASTA alignments, optional VCF v4.2 output, and ASC `fconst` reporting.
+
+[1.0.2]: https://github.com/PathoGenOmics-Lab/snpick/compare/1.0.1...1.0.2
+[1.0.1]: https://github.com/PathoGenOmics-Lab/snpick/compare/1.0.0...1.0.1
+[1.0.0]: https://github.com/PathoGenOmics-Lab/snpick/releases/tag/1.0.0