duckhts-development

Files (4)

• SKILL.md
• repo-workflow.md · references/
• rewrite-porting.md · references/
• testing-checklist.md · references/

SKILL.md (first lines)

# DuckHTS development

## Authorities

Follow repository `AGENTS.md`; repository instructions win over this skill. Consult `ARCHITECTURE.md` for component boundaries, `STYLE.md` for code conventions, and the relevant entry in `design/README.md` for design changes—not the whole stack for every edit.

- `functions.yaml` is the only hand-maintained public SQL catalog.
- Extension source is under `src/`; R package integration is under `r/Rduckhts/`.
- `.sync/` pinned mirrors precede secondary sources for compatibility work.
- `r/duckhtsbench` owns benchmark/corpus artifact identity, derivation, staging, and receipts.

## Completion gates

Every user-visible change updates root `NEWS.md`; update `r/Rduckhts/NEWS.md` only for package-visible changes. Public features normally need SQL conformance and R tinytests.

Use affected tests while iterating. Before handing off extension-source changes, run the repository's integration gates, including:

```bash
cd /root/duckhts/r/Rduckhts
Rscript bootstrap.R /root/duckhts
THREADS=4 make test
```

Never run `R CMD INSTALL .` from `r/Rduckhts/`; build and install a tarball. New translation units must enter `src/duckhts_sources.tsv` so native, Unix R, and Windows R builds agree.

For public function/signature/docs changes: edit `functions.yaml`, run `python3 scripts/render_function_catalog.py`, bootstrap Rduckhts, and verify generated package/catalog output. Do not commit the local `community-extensions/` sync copy. Render README files only from their corresponding `.Rmd`.

Use deterministic, offline extension builds. Pin/checksum vendors and patch through ledgered files; do not edit vendored source directly. Preserve core fixtures and clean generated test output.

## Compatibility rewrites

For mosdepth/bcftools/samtools/VEP-like behavior, record upstream version/commit, supported subset, output/error contract, unsupported features, attribution, and exact comparison commands. Read `.sync/` first and validate continuously against pinned upstream behavior. Baseline SQL/tinytest coverage is not a substitute for upstream conformance. Use `references/rewrite-porting.md` for the full rewrite/porting checklist and documentation obligations.

## Native invariants

Keep ownership explicit and bound input-driven allocation. Mutable htslib handles, iterators, and caches are per-thread. Do not conflate htslib decompression workers with DuckDB parallelism. Preserve declared VCF-header typing; broken headers require explicit repair layers. Keep coverage counting models on separate surfaces: fixed-width bins use arithmetic, `cgranges` is for irregular interval joins only, and each counting model gets its own function with R wrappers, `functions.yaml` entries, and benchmarks (Phase-10 guidance in `AGENTS.md`).

CSQ/ANN/BCSQ typing rules live in `src/vep_parser.c`, seeded from bcftools mirror behavior; unresolved fields default to `String`, and extending the rules requires updating both SQL and R tests. For WisecondorX/dedup-style streaming work, `FILE_OFFSET` ordering in `read_bam()` matters for exact streaming order reproduction.

For wasm-specific debugging, use `duckhts-wasm-debugging`.

From sounkou-bioinfo/pi-skills, MIT.

More from sounkou-bioinfo/pi-skills