gippa 1.0.0__py3-none-any.whl

gippa/__init__.py

@@ -0,0 +1,3 @@
+"""GIPPA: genome integrated prokaryotic proteomics analysis."""
+
+__version__ = "1.0.0"

gippa/annotate/__init__.py

@@ -0,0 +1 @@
+"""Module 1 tool wrappers: build tool inputs and parse tool outputs (never import the tool)."""

gippa/annotate/antismash.py

@@ -0,0 +1,82 @@
+"""antiSMASH 8.0.4 JSON parser: BGC regions (GIPPA_SPEC.md §7.1.1, §7.1.7; M2-18).
+
+``records[].id`` = contig; ``records[].areas[]`` ``start``/``end`` are 0-based half-open;
+``start > end`` on a circular record is origin-crossing and stored unwrapped (``end + length``),
+on a linear record it is corrupt input. Products keep antiSMASH order, duplicates collapsed.
+Core genes: ``locus_tag`` of CDS features wholly inside the area whose ``gene_kind`` qualifier
+contains exactly ``biosynthetic`` (M2-18 lead decision 1), in feature order.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from collections.abc import Mapping
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from gippa.model.coords import Interval, Replicon, check_interval
+
+# Biopython location parts: ``[a:b](±)``, fuzzy ``[<a:b]`` / ``[a:>b]``, inside ``join{…}``.
+_PART = re.compile(r"\[<?(\d+):>?(\d+)\]")
+
+
+@dataclass(frozen=True, slots=True)
+class BgcRegion:
+    contig: str
+    interval: Interval
+    products: tuple[str, ...]
+    core_genes: tuple[str, ...]
+
+
+def _area_interval(area: Mapping[str, Any], rep: Replicon) -> Interval:
+    start, end = int(area["start"]), int(area["end"])
+    if start > end:
+        if rep.topology != "circular":
+            raise ValueError(f"antiSMASH: area {rep.id}:{start}-{end} wraps on a linear contig")
+        end += rep.length
+    iv = Interval(rep.id, start, end, ".")
+    try:
+        check_interval(iv, rep)
+    except ValueError as exc:
+        raise ValueError(f"antiSMASH: area on contig {rep.id!r} out of range: {exc}") from exc
+    return iv
+
+
+def _inside(location: str, area: Interval, length: int) -> bool:
+    parts = [(int(a), int(b)) for a, b in _PART.findall(location)]
+    if not parts:
+        raise ValueError(f"antiSMASH: cannot parse CDS location {location!r}")
+    return all(
+        any(area.start <= a + s and b + s <= area.end for s in (0, length)) for a, b in parts
+    )
+
+
+def _core_genes(features: list[Mapping[str, Any]], area: Interval, length: int) -> tuple[str, ...]:
+    tags: dict[str, None] = {}
+    for f in features:
+        q = f.get("qualifiers", {})
+        if f.get("type") != "CDS" or "biosynthetic" not in q.get("gene_kind", []):
+            continue
+        if _inside(f["location"], area, length):
+            tags.update(dict.fromkeys(q.get("locus_tag", [])))
+    return tuple(tags)
+
+
+def parse_antismash_json(path: Path, replicons: Mapping[str, Replicon]) -> list[BgcRegion]:
+    """BGC regions of an antiSMASH JSON, in record then area order."""
+    data = json.loads(path.read_text())
+    out: list[BgcRegion] = []
+    for rec in data.get("records", []):
+        rid = rec["id"]
+        if rid not in replicons:
+            raise ValueError(f"antiSMASH: record {rid!r} not in the genome")
+        rep = replicons[rid]
+        for area in rec.get("areas", []):
+            iv = _area_interval(area, rep)
+            products = tuple(dict.fromkeys(area.get("products", [])))
+            out.append(
+                BgcRegion(rid, iv, products, _core_genes(rec.get("features", []), iv, rep.length))
+            )
+    return out

gippa/annotate/antismash_cmd.py

@@ -0,0 +1,35 @@
+"""antiSMASH command line (GIPPA_SPEC.md §7.1.1; M2-18).
+
+antiSMASH is AGPL-3.0: it is never imported, only run as a separate process (R5). Kept in sync
+with ``workflow/modules/local/antismash/main.nf``, whose task shell passes
+``--databases <db_dir>/antismash`` only when that path is a directory with content and otherwise
+leaves antiSMASH on the image's bundled databases. This supersedes M2-18 lead decisions 2 and 4
+(``--databases`` always passed and required) per #515.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+
+def antismash_command(gbff: Path, outdir: Path, threads: int, databases: Path | None) -> list[str]:
+    """``antismash --genefinding-tool none --minimal [--databases <db>] --cpus <n> --output-dir
+    <outdir> <gbff>``.
+
+    ``databases`` stays a required argument; ``None`` omits the flag (the databases of the image,
+    which is what ``gippa setup`` records under a container profile). Supersedes M2-18 lead
+    decisions 2 and 4 per #515.
+    """
+    flag = [] if databases is None else ["--databases", str(databases)]
+    return [
+        "antismash",
+        "--genefinding-tool",
+        "none",
+        "--minimal",
+        *flag,
+        "--cpus",
+        str(threads),
+        "--output-dir",
+        str(outdir),
+        str(gbff),
+    ]

gippa/annotate/bakta.py

@@ -0,0 +1,324 @@
+"""Defensive parser for Bakta 1.12.2 JSON (GIPPA_SPEC.md §7.1.1, §7.1.2, §6.5; M2-03).
+
+``parse_bakta_json`` returns the shared M3-01 ``GeneModel`` plus the contig sequences, the Bakta
+and DB versions and a count of skipped (unknown) feature types. Field-name variations are
+tolerated: a feature's contig is ``sequence`` or ``contig``; sequence records are ``sequences``
+or ``contigs`` with nucleotides in ``nt`` or ``sequence``. Bakta's 1-based closed ``start``/``stop``
+become 0-based half-open intervals; ``start > stop`` (``edge``) is unwrapped to ``end > length`` on
+circular replicons and is an error on linear ones. Every malformed input raises
+``BaktaParseError`` (a ``ValueError``) naming the feature.
+"""
+
+from __future__ import annotations
+
+import logging
+import re
+from collections import Counter
+from collections.abc import Mapping
+from dataclasses import dataclass
+from types import MappingProxyType
+from typing import TYPE_CHECKING, Any, Literal, cast
+
+from gippa.io._open import read_json
+from gippa.model.coords import (
+    Interval,
+    Replicon,
+    RepliconKind,
+    Strand,
+    from_one_based_closed,
+    interval_sort_key,
+)
+from gippa.model.genes import _NC_TYPES, Gene, GeneModel, GeneType, NcFeature
+
+if TYPE_CHECKING:
+    from _typeshed import StrPath
+
+DbType = Literal["full", "light", "unknown"]
+
+_HYPOTHETICAL = re.compile(r"^hypothetical protein")
+_COMP = str.maketrans("ACGTNacgtn", "TGCANtgcan")
+_GENE_TYPES = ("cds", "sorf")
+
+
+_log = logging.getLogger(__name__)
+
+
+class BaktaParseError(ValueError):
+    """Malformed or inconsistent Bakta JSON."""
+
+
+class AnnotationTableMismatch(ValueError):
+    """The JSON's ``genome.translation_table`` differs from the run's table (M11-16 item 3.4)."""
+
+
+def _check_table(data: Mapping[str, Any], table: int) -> None:
+    genome = data.get("genome")
+    recorded = genome.get("translation_table") if isinstance(genome, dict) else None
+    if recorded is None:
+        _log.info(
+            "annotation.table_unrecorded: the annotation JSON records no translation table; "
+            "assuming %d",
+            table,
+            extra={"event": "annotation.table_unrecorded", "data": {"translation_table": table}},
+        )
+        return
+    if not isinstance(recorded, int) or isinstance(recorded, bool):
+        raise BaktaParseError(
+            f"annotation JSON genome.translation_table must be an integer, got {recorded!r:.100}"
+        )
+    if recorded != table:
+        raise AnnotationTableMismatch(
+            f"annotation JSON was made with translation table {recorded}; this run uses {table}: "
+            f"re-run Bakta with --translation-table {table} or set "
+            f"annotation.translation_table: {recorded}"
+        )
+
+
+@dataclass(frozen=True, slots=True)
+class BaktaAnnotation:
+    model: GeneModel
+    sequences: Mapping[str, str]
+    bakta_version: str
+    db_version: str
+    db_type: DbType
+    skipped_types: Mapping[str, int]
+
+
+def _revcomp(s: str) -> str:
+    return s.translate(_COMP)[::-1]
+
+
+def interval_nt(seq: str, iv: Interval) -> str:
+    """Strand-aware, origin-aware nucleotides of ``iv`` (``end`` may exceed ``len(seq)``)."""
+    n = len(seq)
+    s = seq[iv.start : iv.end] if iv.end <= n else seq[iv.start :] + seq[: iv.end - n]
+    return _revcomp(s) if iv.strand == "-" else s
+
+
+def _record_nt(rec: Mapping[str, Any], cid: str) -> str | None:
+    nt = rec.get("nt")
+    if nt is None:
+        nt = rec.get("sequence")
+    if nt is not None and not isinstance(nt, str):
+        raise BaktaParseError(f"sequence {cid!r}: nt must be a string, got {type(nt).__name__}")
+    return nt or None
+
+
+def _replicons_from_json(
+    records: list[Any],
+    replicons: Mapping[str, Replicon] | None,
+    genome: Mapping[str, str] | None,
+) -> tuple[dict[str, Replicon], dict[str, str]]:
+    reps: dict[str, Replicon] = {}
+    seqs: dict[str, str] = {}
+    for rec in records:
+        if not isinstance(rec, dict) or not rec.get("id"):
+            raise BaktaParseError(f"sequence record without id: {rec!r:.200}")
+        cid = str(rec["id"])
+        nt = _record_nt(rec, cid)
+        if replicons is not None and cid not in replicons:
+            raise BaktaParseError(f"sequence {cid!r} is not among the given replicons")
+        if nt is None and genome is not None and cid in genome:
+            nt = genome[cid]
+        if nt is not None:
+            seqs[cid] = nt
+        elif replicons is None:
+            raise BaktaParseError(
+                f"sequence {cid!r} has no nucleotides in the JSON and no genome was given"
+            )
+        kind = str(rec.get("type", "")).lower()
+        topology = str(rec.get("topology") or "linear").lower()
+        if topology not in ("circular", "linear"):
+            raise BaktaParseError(f"sequence {cid!r}: unknown topology {topology!r}")
+        length = replicons[cid].length if replicons is not None else len(seqs[cid])
+        declared = rec.get("length")
+        if declared is not None and declared != length:
+            raise BaktaParseError(
+                f"sequence {cid!r}: JSON length {declared!r} != genome sequence length {length}"
+            )
+        if cid in seqs and len(seqs[cid]) != length:
+            raise BaktaParseError(
+                f"sequence {cid!r}: nucleotide length {len(seqs[cid])} != replicon length {length}"
+            )
+        reps[cid] = Replicon(
+            cid,
+            length,
+            "circular" if topology == "circular" else "linear",
+            cast(RepliconKind, kind if kind in ("chromosome", "plasmid") else "unknown"),
+        )
+    if replicons is None:
+        return reps, seqs
+    for cid in replicons:
+        if cid not in seqs and genome is not None and cid in genome:
+            seqs[cid] = genome[cid]
+    return dict(replicons), seqs
+
+
+def _int(f: Mapping[str, Any], key: str, name: str) -> int:
+    v = f.get(key)
+    if isinstance(v, bool) or not isinstance(v, int):
+        raise BaktaParseError(f"feature {name!r}: {key} must be an int, got {v!r}")
+    return v
+
+
+def _opt_str(f: Mapping[str, Any], key: str, name: str) -> str | None:
+    v = f.get(key)
+    if v is not None and not isinstance(v, str):
+        raise BaktaParseError(f"feature {name!r}: {key} must be a string, got {type(v).__name__}")
+    return v
+
+
+def _expert(f: Mapping[str, Any], name: str) -> tuple[str, ...]:
+    raw = f.get("expert")
+    if raw is None:
+        return ()
+    if not isinstance(raw, list) or not all(isinstance(e, dict) for e in raw):
+        raise BaktaParseError(
+            f"feature {name!r}: expert must be a list of objects, got {raw!r:.200}"
+        )
+    out: list[str] = []
+    for e in raw:
+        src = e.get("type") or e.get("source")
+        if src and str(src) not in out:
+            out.append(str(src))
+    return tuple(out)
+
+
+def _interval(
+    f: Mapping[str, Any], name: str, replicons: Mapping[str, Replicon], *, coding: bool
+) -> Interval:
+    contig = f.get("sequence", f.get("contig"))
+    if contig is None:
+        raise BaktaParseError(f"feature {name!r}: no 'sequence' or 'contig' field")
+    if contig not in replicons:
+        raise BaktaParseError(f"feature {name!r}: unknown contig {contig!r}")
+    raw = f.get("strand")
+    if raw not in ("+", "-"):
+        if coding or raw not in (None, "?", "."):
+            raise BaktaParseError(f"feature {name!r}: invalid strand {raw!r}")
+        raw = "."
+    start, stop = _int(f, "start", name), _int(f, "stop", name)
+    try:
+        return from_one_based_closed(contig, start, stop, cast(Strand, raw), replicons[contig])
+    except ValueError as exc:
+        raise BaktaParseError(f"feature {name!r}: {exc}") from exc
+
+
+def _gene(f: Mapping[str, Any], replicons: Mapping[str, Replicon], seqs: Mapping[str, str]) -> Gene:
+    if not f.get("locus"):
+        raise BaktaParseError(f"{f.get('type')} feature without locus: {f!r:.200}")
+    locus = str(f["locus"])
+    iv = _interval(f, locus, replicons, coding=True)
+    ftype = cast(GeneType, str(f["type"]).lower())
+    if ftype == "cds" and (f.get("pseudo") or "pseudogene" in f):
+        ftype = "pseudogene"
+    xrefs = f.get("db_xrefs") or []
+    if not isinstance(xrefs, list | tuple):
+        raise BaktaParseError(f"feature {locus!r}: db_xrefs must be a list, got {xrefs!r}")
+    nt = _opt_str(f, "nt", locus) or (
+        interval_nt(seqs[iv.contig], iv) if iv.contig in seqs else None
+    )
+    product = f.get("product") or ""
+    hypothetical = (
+        bool(f["hypothetical"]) if "hypothetical" in f else bool(_HYPOTHETICAL.match(product))
+    )
+    rep = replicons[iv.contig]
+    at_end = rep.topology == "linear" and (iv.start == 0 or iv.end == rep.length)
+    aa = _opt_str(f, "aa", locus) or ""
+    start_type = f.get("start_type")
+    # Pyrodigal partial start ("Edge") is not a start codon (M3-01 Q3).
+    start_codon = None if start_type == "Edge" else start_type or (nt[:3] if nt else None)
+    return Gene(
+        locus_tag=locus,
+        feature_type=ftype,
+        interval=iv,
+        aa=aa[:-1] if aa.endswith("*") else aa,
+        nt=nt,
+        start_codon=start_codon,
+        gene=f.get("gene"),
+        product=product,
+        partial=bool(f.get("truncated")) or at_end,
+        hypothetical=hypothetical,
+        db_xrefs=tuple(str(x) for x in xrefs),
+        expert=_expert(f, locus),
+    )
+
+
+def _nc(f: Mapping[str, Any], replicons: Mapping[str, Replicon]) -> NcFeature:
+    fid = str(f.get("id") or f.get("locus") or "")
+    anticodon = f.get("anti_codon")
+    return NcFeature(
+        id=fid,
+        type=_NC_TYPES[str(f["type"]).lower()],
+        interval=_interval(f, fid, replicons, coding=False),
+        gene=f.get("gene"),
+        product=f.get("product") or "",
+        amino_acid=f.get("amino_acid"),
+        anticodon=str(anticodon).upper().replace("U", "T") if anticodon else None,
+        nt=_opt_str(f, "nt", fid),
+    )
+
+
+def _versions(data: Mapping[str, Any]) -> tuple[str, str, DbType]:
+    version = data.get("version")
+    if not isinstance(version, dict):
+        return "", "", "unknown"
+    raw_db = version.get("db")
+    db: dict[str, Any] = raw_db if isinstance(raw_db, dict) else {}
+    db_type = str(db.get("type", "")).lower()
+    return (
+        str(version.get("bakta") or ""),
+        str(db.get("version") or ""),
+        cast(DbType, db_type if db_type in ("full", "light") else "unknown"),
+    )
+
+
+def parse_bakta_json(
+    path: StrPath,
+    replicons: Mapping[str, Replicon] | None = None,
+    genome: Mapping[str, str] | None = None,
+    *,
+    translation_table: int | None = None,
+) -> BaktaAnnotation:
+    """Parse a (possibly gzipped) Bakta JSON; ``replicons`` (preflight's table) wins if given.
+
+    With ``translation_table``, a recorded ``genome.translation_table`` that differs raises
+    ``AnnotationTableMismatch``; an unrecorded one is assumed equal (logged at INFO).
+    """
+    data = read_json(path)
+    if not isinstance(data, dict):
+        raise BaktaParseError(f"{path}: top-level JSON must be an object")
+    if translation_table is not None:
+        _check_table(data, translation_table)
+    records = data.get("sequences", data.get("contigs")) or []
+    reps, seqs = _replicons_from_json(records, replicons, genome)
+    genes: list[Gene] = []
+    features: list[NcFeature] = []
+    skipped: Counter[str] = Counter()
+    seen: set[str] = set()
+    for f in data.get("features") or []:
+        if not isinstance(f, dict):
+            raise BaktaParseError(f"feature must be an object: {f!r:.200}")
+        t = str(f.get("type", "")).lower()
+        if t in _GENE_TYPES:
+            g = _gene(f, reps, seqs)
+            if g.locus_tag in seen:
+                raise BaktaParseError(f"duplicate locus tag {g.locus_tag}")
+            seen.add(g.locus_tag)
+            genes.append(g)
+        elif t in _NC_TYPES:
+            features.append(_nc(f, reps))
+        else:
+            skipped[str(f.get("type", ""))] += 1
+    order = {c: k for k, c in enumerate(reps)}
+    genes.sort(key=lambda g: interval_sort_key(g.interval, order, g.locus_tag))
+    features.sort(key=lambda x: interval_sort_key(x.interval, order, x.id))
+    bakta_version, db_version, db_type = _versions(data)
+    return BaktaAnnotation(
+        model=GeneModel(replicons=reps, genes=tuple(genes), features=tuple(features)),
+        sequences=MappingProxyType(seqs),
+        bakta_version=bakta_version,
+        db_version=db_version,
+        db_type=db_type,
+        skipped_types=MappingProxyType(dict(skipped)),
+    )

gippa/annotate/bakta_cmd.py

@@ -0,0 +1,64 @@
+"""Bakta 1.12.2 command line and database selection (GIPPA_SPEC.md §7.1.1, §5.2; M2-03).
+
+Builds ``bakta --db DB --output OUT --prefix P --threads N --keep-contig-headers
+[--complete] [--translation-table T] --replicons replicons.tsv [--regions regions.gff3]
+[extra args] genome.norm.fa``.
+Bakta itself is never imported (R5); it runs as a separate process.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from pathlib import Path
+from typing import Literal
+
+DbType = Literal["full", "light"]
+
+
+def bakta_db_path(db_setting: str, db_dir: Path) -> tuple[Path, DbType]:
+    """Resolve ``annotation.bakta.db``: ``auto`` picks ``bakta/db`` if present, else ``db-light``.
+
+    ``full``/``light`` select the matching directory under ``db_dir/bakta``; anything else is a
+    path to a Bakta DB, typed ``light`` when its name contains ``light``.
+    """
+    base = db_dir / "bakta"
+    if db_setting == "auto":
+        return (base / "db", "full") if (base / "db").is_dir() else (base / "db-light", "light")
+    if db_setting == "full":
+        return base / "db", "full"
+    if db_setting == "light":
+        return base / "db-light", "light"
+    path = Path(db_setting)
+    return path, "light" if "light" in path.name else "full"
+
+
+def bakta_command(
+    *,
+    genome: Path,
+    outdir: Path,
+    prefix: str,
+    db: Path,
+    threads: int,
+    all_circular: bool,
+    complete: bool | Literal["auto"],
+    replicons_tsv: Path,
+    regions_gff3: Path | None,
+    extra_args: Sequence[str],
+    translation_table: int,
+) -> list[str]:
+    """Bakta argv; ``--replicons`` always, ``--complete`` iff forced or (auto) all circular.
+
+    ``--translation-table T`` only when ``T != 11`` (Bakta's default; M11-16 D2), right before
+    ``--replicons``.
+    """
+    cmd = ["bakta", "--db", str(db), "--output", str(outdir), "--prefix", prefix]
+    cmd += ["--threads", str(threads), "--keep-contig-headers"]
+    use_complete = all_circular if complete == "auto" else bool(complete)
+    cmd += ["--complete"] if use_complete else []
+    cmd += [] if translation_table == 11 else ["--translation-table", str(translation_table)]
+    cmd += ["--replicons", str(replicons_tsv)]
+    if regions_gff3 is not None:
+        cmd += ["--regions", str(regions_gff3)]
+    cmd += [str(a) for a in extra_args]
+    cmd.append(str(genome))
+    return cmd

gippa/annotate/bakta_layers.py

@@ -0,0 +1,108 @@
+"""Pure layers derived from a parsed Bakta annotation (GIPPA_SPEC.md §7.1.2, §9.3; M2-04).
+
+Ribosomal-protein set (CAI reference), 16S rRNA selection and anti-Shine-Dalgarno 9-mer, tRNA
+copy numbers per anticodon (tAI), db_xref splitting, ``annotation_source`` and origin-aware
+nearest genes (TE6). No file I/O; the ``parse_bakta`` step in ``gippa.steps.annotation`` writes.
+"""
+
+from __future__ import annotations
+
+import re
+from collections import Counter
+from collections.abc import Sequence
+from typing import Literal
+
+from gippa.model.coords import Interval, Replicon
+from gippa.model.genes import Gene, NcFeature
+
+RIBOSOMAL_PRODUCT: re.Pattern[str] = re.compile(r"^(30S|50S) ribosomal protein")
+RIBOSOMAL_GENE: re.Pattern[str] = re.compile(r"^(rps|rpl|rpm)[A-Z]")
+DEFAULT_ANTI_SD = "ACCTCCTTA"
+ANTI_SD_DEFAULT_FLAG = "anti_sd_default"
+
+_DNA9 = re.compile(r"^[ACGT]{9}$")
+
+AnnotationSource = Literal["bakta_full", "bakta_light", "user"]
+
+
+def is_ribosomal_protein(g: Gene) -> bool:
+    """§7.1.2: product ``^(30S|50S) ribosomal protein`` or gene ``^(rps|rpl|rpm)[A-Z]``."""
+    return bool(RIBOSOMAL_PRODUCT.match(g.product or "")) or bool(
+        g.gene and RIBOSOMAL_GENE.match(g.gene)
+    )
+
+
+def rrna16s(features: Sequence[NcFeature]) -> list[NcFeature]:
+    """The 16S rRNA copies (product contains ``16S`` or gene ``rrs``), in input order."""
+    return [f for f in features if f.type == "rrna" and ("16S" in f.product or f.gene == "rrs")]
+
+
+def anti_sd(rrna16s_nts: Sequence[str], configured: str = "auto") -> tuple[str, tuple[str, ...]]:
+    """Anti-SD 9-mer and run flags (§7.1.2, §5.2).
+
+    ``configured`` other than ``auto`` must match ``^[ACGT]{9}$`` and is used as is. Otherwise
+    the most common 3' 9-mer across 16S copies (ties: first copy in input order; copies shorter
+    than 9 nt are skipped) is used if it contains ``CCTCC``, else the E. coli default and the
+    ``anti_sd_default`` flag.
+    """
+    if configured != "auto":
+        if not _DNA9.match(configured):
+            raise ValueError(
+                f"annotation.ostir.anti_sd must be 'auto' or 9 nt ACGT: {configured!r}"
+            )
+        return configured, ()
+    tails = [s[-9:].upper() for s in rrna16s_nts if len(s) >= 9]
+    if tails:
+        counts = Counter(tails)  # insertion-ordered: most_common keeps first-seen order on ties
+        best = counts.most_common(1)[0][0]
+        if "CCTCC" in best:
+            return best, ()
+    return DEFAULT_ANTI_SD, (ANTI_SD_DEFAULT_FLAG,)
+
+
+def trna_counts(features: Sequence[NcFeature]) -> dict[str, int]:
+    """tRNA gene copies per anticodon (§7.1.2), keys sorted."""
+    counts = Counter(f.anticodon for f in features if f.type == "trna" and f.anticodon)
+    return {k: counts[k] for k in sorted(counts)}
+
+
+def split_xrefs(genes: Sequence[Gene]) -> list[tuple[str, str, str]]:
+    """``(locus_tag, db, id)`` per db_xref; db is text before the first ``:``; GO keeps it."""
+    rows: list[tuple[str, str, str]] = []
+    for g in genes:
+        for x in g.db_xrefs:
+            db, _, ident = x.partition(":")
+            rows.append((g.locus_tag, db, x if db == "GO" else ident))
+    return rows
+
+
+def annotation_source(db_type: str) -> AnnotationSource:
+    """§9.3 enum from the Bakta DB type (M2 lead decision 7): ``user`` when unknown."""
+    if db_type == "full":
+        return "bakta_full"
+    if db_type == "light":
+        return "bakta_light"
+    return "user"
+
+
+def _gap(a: Interval, b: Interval, rep: Replicon) -> int:
+    """Gap in bp between two intervals (0 when overlapping or adjacent); wraps if circular."""
+    if rep.topology != "circular":
+        return max(0, b.start - a.end, a.start - b.end)
+    n = rep.length
+    la, lb = a.end - a.start, b.end - b.start
+    if (b.start - a.start) % n < la or (a.start - b.start) % n < lb:
+        return 0
+    return min((b.start - a.end) % n, (a.start - b.end) % n)
+
+
+def nearest_genes(
+    feature: NcFeature, genes: Sequence[Gene], replicon: Replicon, n: int = 2
+) -> list[tuple[str, int]]:
+    """The ``n`` genes on ``feature``'s contig closest to it: ``(locus_tag, gap_bp)`` ascending.
+
+    Ties keep the input order. Circular replicons are origin-aware; linear contigs never wrap.
+    """
+    on = [g for g in genes if g.interval.contig == feature.interval.contig]
+    dist = [(g.locus_tag, _gap(feature.interval, g.interval, replicon)) for g in on]
+    return sorted(dist, key=lambda x: x[1])[:n]