moonbit-genbank

MoonBit GenBank/INSDC flat-file parser for small bioinformatics tools, teaching examples, and data-conversion pipelines.

The library focuses on annotated sequence records rather than broad bioinformatics algorithms. It parses LOCUS metadata, FEATURES entries, ORIGIN sequence text, common feature locations, qualifiers, CDS translation checks, and compact JSON export.

Why this project

MoonBit already has early bioinformatics ecosystem work, but GenBank flat-file annotation parsing is still a useful standalone building block. Keeping this package focused makes it suitable for:

• validating small submitted sequence records
• querying genes and CDS annotations in teaching examples
• converting GenBank snippets to JSON for web or CLI tools
• extending toward INSDC feature-table edge cases over time

This repository is developed as an original MoonBit OSC2026 project. No source code is copied from existing GenBank parsers.

Features

• LOCUS parsing: record name, length, molecule type, topology, division, date
• FEATURES parsing: feature key, location expression, slash qualifiers
• Location support: point/range, nested join(...) and order(...), nested complement(...), partial markers, between-base positions, one-of(...), and remote accessions
• ORIGIN cleanup: sequence lines are normalized to uppercase bases
• Queries: feature key filtering, qualifier lookup, span overlap checks
• CDS validation: extracts feature sequence, handles complement strands, and compares computed translation with /translation
• Sequence statistics: base counts and GC percentage for ORIGIN
• Record audit: sequence length, source feature, bounds, remote locations, between-base locations, and CDS translation findings
• JSON export: compact stable representation for downstream tooling
• Runnable demo CLI: summary output by default and JSON output with --json

Quick Start

moon check --deny-warn
moon test --deny-warn
moon run cmd/main
moon run cmd/main -- --json

Library Example

///|
test "parse a minimal record" {
  let text =
    #|LOCUS       DEMO0001        12 bp    DNA     linear   SYN 28-JUL-2026
    #|DEFINITION  Minimal MoonBit GenBank demo record.
    #|ACCESSION   DEMO0001
    #|FEATURES             Location/Qualifiers
    #|     source          1..12
    #|                     /organism="synthetic construct"
    #|     CDS             1..12
    #|                     /gene="demo"
    #|                     /translation="MAIV"
    #|ORIGIN
    #|        1 atggccattgta
    #|//
  let record = parse_record(text)
  inspect(record.accession, content="DEMO0001")
  inspect(record.features_by_key("CDS").length(), content="1")
  inspect(record.check_cds_translations()[0].ok, content="true")
}

API Surface

The main package exposes:

• parse_record(text) -> Record raise GenBankError
• parse_records(text) -> Array[Record] raise GenBankError
• parse_locus(line) -> Locus raise GenBankError
• parse_location(text) -> Location raise GenBankError
• GenBankError::message
• Record::features_by_key
• Record::features_with_qualifier
• Feature::qualifier
• Feature::overlaps
• Record::sequence_for
• Record::check_cds_translations
• Record::sequence_stats
• Record::validate
• Record::to_json_string
• ValidationIssue::is_error
• ValidationIssue::to_json_string
• translate_dna
• reverse_complement

Generated public interfaces are committed in pkg.generated.mbti.

Scope

Implemented:

• single-record GenBank flat files
• multi-record streams separated by //
• common feature-table qualifiers
• multi-line qualifier values
• nested range, join, order, and complement locations
• fuzzy, between-base, and remote location segments
• standard genetic code translation
• IUPAC ambiguity bases in ORIGIN and reverse-complement operations

Planned extension points:

• richer feature-table normalization and structured metadata fields
• selectable genetic codes and codon-start handling
• streaming/file-reading CLI once the async filesystem API is stabilized for all supported MoonBit targets

Real benchmarks

examples/u49845.gb and examples/af165912.gb are fixed NCBI GenBank snapshots covering partial locations, reverse-strand features, multiline qualifiers, and multiline join expressions. Their source URLs and checksums are documented in BENCHMARKS.md.

Validation

The CI workflow installs the latest MoonBit toolchain and runs on Linux, macOS, and Windows:

• moon fmt followed by git diff --exit-code
• moon info followed by git diff --exit-code
• moon check --target all --deny-warn
• moon test --target all --deny-warn

Locally, this repository was checked with:

moon check --deny-warn
moon test --deny-warn
moon info

The current local Windows environment has no system C compiler, so native --target all execution is delegated to CI, where gcc is installed explicitly.

License

Apache-2.0.