Enforce sequence coordinate bounds

[theferrit32]

Some recent work done on clinvar validation surfaced a small set of discrepancies which informed this change.

htslib does not enforce coordinates are in bounds for the sequence. This seems like intentional and defined behavior. And pysam mostly delegates to htslib for fetches (but disallows negative coords and start>end), and seqrepo delegates to pysam, and vrs-python currently delegates to seqrepo.

Entry points that now check bounds:

• AlleleTranslator.translate_from with fmt="hgvs", "spdi", "beacon" or "gnomad", or with no fmt, which tries each format in turn. The check runs before the Allele is built. On gnomAD it runs before the
  reference comparison, so the error isn't reported as a reference mismatch.
• CnvTranslator.translate_from (fmt="hgvs"). This path never fetches sequence, so it previously had no protection at all.
• normalize() called directly on an Allele with a LiteralSequenceExpression state and a SequenceReference. The check runs before any fetch.
• vrs-annotate / the VCF annotator. It goes through the gnomAD path, so out-of-bounds records now get VRS_Error instead of allele IDs.
• DataProxy.validate_location_bounds(sequence_id, start, end) is itself a new public method that clients can call.

At a high level these are the layers and their bounds handling (prior to this branch which changes vrs-python):

(begin ai)

htslib (faidx_fetch_seq) (converted to interbase for ease of comparison)

s = 'ABCD'
(1) fetch(s, 0, 4)      -> 'ABCD'
(2) fetch(s, -1, 3)     -> 'ABC'    # negative start clamped to 0
(3) fetch(s, 3, 1)      -> 'A'      # start clamped down to end
(4) fetch(s, 1, 100)    -> 'BCD'    # end clamped to length
(5) fetch(s, 100, 101)  -> ''
(6) fetch(s, 100, 100)  -> n/a      # inclusive-end API: can't express a zero-width interval

The only signal that anything was clamped is the length htslib reports back for what it
actually fetched. The samtools faidx command prints a "Truncated sequence" warning to
stderr but still exits 0.

pysam (FastaFile.fetch), compared with htslib

(1) fetch(s, 0, 4)      -> 'ABCD'
(2) fetch(s, -1, 3)     -> ValueError: start out of range (-1)                  # new: rejects negatives
(3) fetch(s, 3, 1)      -> ValueError: invalid coordinates: start (3) > stop (1)  # new: rejects reversed
(4) fetch(s, 1, 100)    -> 'BCD'    # passed to htslib; the clamped length it reports is discarded
(5) fetch(s, 100, 101)  -> ''       # same result, but pysam returns it itself; htslib is never called
(6) fetch(s, 100, 100)  -> ''       # zero-width also returned early by pysam

seqrepo (SeqRepo.fetch), compared with pysam

No differences: start/end are passed straight through.

(1) fetch(s, 0, 4)      -> 'ABCD'
(2) fetch(s, -1, 3)     -> ValueError: start out of range (-1)
(3) fetch(s, 3, 1)      -> ValueError: invalid coordinates: start (3) > stop (1)
(4) fetch(s, 1, 100)    -> 'BCD'
(5) fetch(s, 100, 101)  -> ''
(6) fetch(s, 100, 100)  -> ''

vrs-python main, local proxy (SeqRepoDataProxy.get_sequence), compared with seqrepo

No differences: get_sequence passes start/end straight through, and nothing else on
main checks location bounds.

The one related check, validate_ref_seq, runs only on the gnomAD (VCF-style) input
path. It compares the fetched reference with the input REF.

• A non-empty REF fails as a misleading "Reference mismatch … correct ref is ''" rather
  than a bounds error.
• With require_validation=False (the vrs-annotate default), that failure is only a
  logged warning, and an Allele is still returned.

HGVS, SPDI and beacon inputs never compare against the reference, and neither do
normalize() or translate_to. An out-of-bounds location from those paths is accepted
silently and given a permanent identifier.

That is why the ClinVar issue went unnoticed on SeqRepo. NP_001346993.1:p.Ter194del
(a protein of 193 aa) parses to a deletion at [193, 194), normalization's fetch returns
'', and a ga4gh:VA Allele is produced. It only surfaced because RefgetStore raised an
error on the same fetch. The comparison between the two backends then showed different
object types: ga4gh:VA on SeqRepo, and on RefgetStore the harness's CNV fallback,
ga4gh:CX.

(1) fetch(s, 0, 4)      -> 'ABCD'
(2) fetch(s, -1, 3)     -> ValueError: start out of range (-1)
(3) fetch(s, 3, 1)      -> ValueError: invalid coordinates: start (3) > stop (1)
(4) fetch(s, 1, 100)    -> 'BCD'
(5) fetch(s, 100, 101)  -> ''
(6) fetch(s, 100, 100)  -> ''