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 ranges, start..end, join(...), complement(...), partial markers such as <1..>90
• 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
• 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::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
• simple range, join, and complement locations
• standard genetic code translation

Planned extension points:

• multi-record streams
• fuzzy locations and remote accessions
• richer feature-table normalization
• selectable genetic codes
• file-reading CLI once native toolchain setup is available in common development environments

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.