@voxgig/sdkgen 4.8.1 → 4.8.3

package/project/.sdk/tm/py/pkg/feature/secrets/voxgig_plugin/order.py

@@ -0,0 +1,171 @@
+# VENDORED: @voxgig/plugin 0.1.6 (python/voxgig_plugin/order.py)
+# Source: https://github.com/voxgig/plugin @ 8d8968afc0a2008fbd795b41ab166307d989f02a  [tag: sdk-20260904-1610-0]
+# License: MIT (c) voxgig - see repository LICENSE. Do not edit: resync from upstream.
+"""Ordering (section 7) - one rule, one place.
+
+sdkgen grew two special cases in `makeOptions` (`test`, then `station`)
+and the third was not far off. This sort is the whole replacement, and the
+tiers are in this order for a reason:
+
+  1 constraints   before/after edges, by ref or by name
+  2 bands         integer, lower first, default 0
+  3 declaration   ties break by `pos`
+
+CONSTRAINTS BEAT BANDS precisely so the correct tool wins when both are
+present. A band expresses a genuine cross-cutting layer; a constraint
+expresses a relationship between two specific things; and a band chosen by
+trial and error to fix an ordering bug is a bug wearing a number.
+"""
+
+from .types import fail
+from .ref import parse_ref
+
+
+def resolve_order(bindings, pin=None):
+    nodes = list(bindings)
+    byref = {b['ref']: b for b in nodes}
+
+    # Constraints are edges. A constraint naming an ABSENT binding is
+    # satisfied VACUOUSLY (section 7) - a plugin ordered `after: 'test'`
+    # must load in a host with no test plugin. That is sdkgen's __after__
+    # behaviour, kept.
+    edges = {b['ref']: [] for b in nodes}
+
+    for b in nodes:
+        block = b.get('order') or {}
+        # An ABSENT constraint and an EMPTY LIST are both "no constraint".
+        if declared(block.get('after')):
+            for target in targets(block['after'], nodes):
+                edges[target].append(b['ref'])
+        if declared(block.get('before')):
+            for target in targets(block['before'], nodes):
+                edges[b['ref']].append(target)
+
+    # Stable topological sort. Among ready nodes, band first (lower runs
+    # first), then `pos` - the position the DOCUMENT visibly states, not
+    # the order instances happened to load and not the incarnation `seq`.
+    indeg = {b['ref']: 0 for b in nodes}
+    for source in edges:
+        for target in edges[source]:
+            indeg[target] = indeg.get(target, 0) + 1
+
+    out = []
+    ready = [b for b in nodes if 0 == indeg[b['ref']]]
+
+    while 0 < len(ready):
+        ready.sort(key=lambda b: (band(b), b.get('pos') or 0))
+        nxt = ready.pop(0)
+        out.append(nxt['ref'])
+        for target in edges[nxt['ref']]:
+            indeg[target] -= 1
+            if 0 == indeg[target]:
+                ready.append(byref[target])
+
+    if len(out) != len(nodes):
+        stuck = [b['ref'] for b in nodes if b['ref'] not in out]
+        fail('plugin_order_cycle',
+             'before/after constraints cycle: ' + ' -> '.join(stuck),
+             {'cycle': stuck})
+
+    return applypin(out, edges, pin)
+
+
+def band(b):
+    block = b.get('order') or {}
+    value = block.get('band')
+    return value if isinstance(value, int) and not isinstance(value, bool) else 0
+
+
+def declared(spec):
+    """Was a constraint stated? An absent value and an EMPTY LIST are
+    both no-constraint - and an empty list is truthy in most languages,
+    which is exactly how this class of bug survives."""
+    if spec is None:
+        return False
+    if isinstance(spec, list):
+        return any('' != one for one in spec)
+    return '' != spec
+
+
+def targets(spec, nodes):
+    """Matching is by REF, or by NAME across all of that definition's
+    instances (section 7) - which is the whole reason the two spellings
+    exist."""
+    hit = []
+    # One spelling or a LIST of them. A list fans out to the union of what
+    # each names, so after: ['a','b'] means after BOTH, and the same
+    # instance named twice - once by name, once by ref - is one edge.
+    specs = spec if isinstance(spec, list) else [spec]
+    for one in specs:
+        for b in nodes:
+            if b['ref'] in hit:
+                continue
+            if b['ref'] == one:
+                hit.append(b['ref'])
+                continue
+            if parse_ref(b['ref'])['name'] == one:
+                hit.append(b['ref'])
+    return hit
+
+
+def applypin(order, edges, pin=None):
+    """A PIN IS NOT A CONSTRAINT (section 7).
+
+    Constraints and bands are negotiable by definition - they are what
+    plugins and documents say they want, and the sort's job is to satisfy
+    them all. A pin is the host stating a structural invariant of its own
+    architecture, which is a different kind of claim and must not lose a
+    tie to a document.
+
+    So a pin PLACES the binding at the named end, and an ordering that
+    would move it away is `plugin_order_pinned` - rejected, not honoured
+    into a broken wrap. Station's transport adapter must sit immediately
+    outside the base transport; an `order` list that moves it has to be an
+    error rather than a preference.
+    """
+    if None is pin:
+        return order
+    out = list(order)
+
+    # SORTED, not insertion order. A pin map is data - it can arrive from
+    # a host's own construction options in any order, and two names
+    # pinned to the same end are order-sensitive (`{b:'first',
+    # a:'first'}` and `{a:'first', b:'first'}` give different results).
+    # Python dicts are insertion-ordered and a Go map has no order at
+    # all, so leaving it unstated made the same declaration mean
+    # different things in different ports.
+    for name in sorted(pin):
+        want = pin[name]
+        idx = -1
+        for i, ref in enumerate(out):
+            if parse_ref(ref)['name'] == name:
+                idx = i
+                break
+        if -1 == idx:
+            continue
+
+        # `first`/`outermost` is index 0; `last`/`innermost` is the end.
+        # Section 6.2 makes the first chain binding outermost, which is
+        # why the vocabulary is positional and why the two spellings pair
+        # this way.
+        wantfirst = 'first' == want or 'outermost' == want
+        ref = out.pop(idx)
+        if wantfirst:
+            out.insert(0, ref)
+        else:
+            out.append(ref)
+
+    # Now check that the placement did not break a constraint. This is the
+    # half that makes a pin a rejection rather than an override: the host
+    # wins on position, but it does not get to silently discard a
+    # relationship a plugin declared.
+    at = {ref: i for i, ref in enumerate(out)}
+    for source in edges:
+        for target in edges[source]:
+            if at[source] > at[target]:
+                fail('plugin_order_pinned',
+                     'a pin would move a binding an ordering constrains: ' +
+                     source + ' must precede ' + target,
+                     {'before': source, 'after': target})
+
+    return out

package/project/.sdk/tm/py/pkg/feature/secrets/voxgig_plugin/point.py

@@ -0,0 +1,95 @@
+# VENDORED: @voxgig/plugin 0.1.6 (python/voxgig_plugin/point.py)
+# Source: https://github.com/voxgig/plugin @ 8d8968afc0a2008fbd795b41ab166307d989f02a  [tag: sdk-20260904-1610-0]
+# License: MIT (c) voxgig - see repository LICENSE. Do not edit: resync from upstream.
+"""Extension points (section 6). Three kinds, chosen because they are what
+the two existing systems actually needed, and no more.
+
+A PLUGIN NEVER MUTATES THE HOST. That inversion is what makes deactivation
+possible: sdkgen's `utility.fetcher = wrapped` is not undoable, but "this
+instance holds slot 3 of the request chain" is undoable in O(1). OSGi named
+it the whiteboard pattern in 2004, in a paper called *Listeners Considered
+Harmful*, and for exactly this reason.
+"""
+
+import functools
+
+from .types import fail
+
+
+# Section 6.1: "fan-out" is not one answer but four. In a language with
+# asynchrony, "call every binding" hides a decision - start them all and
+# wait, await each in turn, or do not wait - and a design that leaves it
+# unsaid gets four different answers from four ports, in the concurrency
+# behaviour of production code no corpus entry happens to cover.
+MODES = ['emit', 'parallel', 'serial', 'bail']
+
+
+def emit(bindings, mode, arg):
+    """Fan-out. Return values are ignored except in `bail`."""
+    if 'bail' == mode:
+        # Stops at the first binding that RETURNS A VALUE - the "handled,
+        # stop" case. A `None` RETURN DECLINES (section 6.1): python has
+        # one way to say nothing, and the model's rule is written to that
+        # rather than to JavaScript's null/undefined pair.
+        for b in bindings:
+            value = b['fn'](arg)
+            if None is not value:
+                return value
+        return None
+
+    errors = []
+    for b in bindings:
+        try:
+            b['fn'](arg)
+        except Exception as err:
+            # `emit` raises synchronously; the collecting modes gather.
+            if 'emit' == mode:
+                raise
+            errors.append(err)
+    return None if 'emit' == mode else errors
+
+
+def compose(bindings, base):
+    """Composition: b1(b2(b3(base))), FIRST BINDING OUTERMOST (section
+    6.2).
+
+    Recomputed by the host whenever the live set changes, and cached
+    between changes. Plugins receive `next` as an argument; they never see
+    or store the previous value of anything. A plugin that stashes `next`
+    and calls it after deactivation is a bug the host cannot prevent, and
+    this says so rather than pretending otherwise.
+    """
+    nxt = base
+    for i in range(len(bindings) - 1, -1, -1):
+        fn = bindings[i]['fn']
+        inner = nxt
+        # `inner=inner, fn=fn` binds the CURRENT values into the default
+        # arguments. Python closures capture the variable, not the value,
+        # so a plain closure here would leave every layer calling the last
+        # one - the single most common way to get this loop wrong.
+        nxt = (lambda *args, fn=fn, inner=inner: fn(inner, *args))
+    return nxt
+
+
+def provider(bindings, spec):
+    """At most one live implementation (section 6.3). The winner is the
+    highest band, ties broken by ref sort, and THE LOSERS ARE VISIBLE
+    rather than silently ignored."""
+    if 0 == len(bindings):
+        return {'winner': None, 'shadowed': []}
+
+    if spec.get('exclusive') and 1 < len(bindings):
+        refs = sorted(b['ref'] for b in bindings)
+        fail('plugin_point_exclusive',
+             'point is exclusive and has ' + str(len(bindings)) +
+             ' bindings: ' + ', '.join(refs),
+             {'refs': refs})
+
+    ranked = sorted(bindings, key=functools.cmp_to_key(rank))
+    return {'winner': ranked[0], 'shadowed': [b['ref'] for b in ranked[1:]]}
+
+
+def rank(a, b):
+    if a['band'] != b['band']:
+        return b['band'] - a['band']       # HIGHEST band wins
+    return -1 if a['ref'] < b['ref'] else (1 if a['ref'] > b['ref'] else 0)

package/project/.sdk/tm/py/pkg/feature/secrets/voxgig_plugin/ref.py

@@ -0,0 +1,116 @@
+# VENDORED: @voxgig/plugin 0.1.6 (python/voxgig_plugin/ref.py)
+# Source: https://github.com/voxgig/plugin @ 8d8968afc0a2008fbd795b41ab166307d989f02a  [tag: sdk-20260904-1610-0]
+# License: MIT (c) voxgig - see repository LICENSE. Do not edit: resync from upstream.
+"""Identity: name+tag, written `name$tag` (section 4).
+
+The four pure functions, and the whole of what `ref` pins. They are the
+first thing a new port implements and the first corpus section it passes.
+"""
+
+import re
+
+from .types import fail
+
+# Section 4: `^[a-zA-Z@][a-zA-Z0-9.~_\-/]*$`, max 1024.
+#
+# `\Z`, NOT `$`. PYTHON'S `$` ALSO MATCHES BEFORE A TRAILING NEWLINE, so
+# `^...$` accepts "abc\n" as a plugin name - and nothing else in the
+# grammar, in this file, or (until `ref/name#trailing-newline`) in the
+# corpus would ever say so. The anchors in the design's grammar mean
+# STRING start and end; ruby needs `\A`/`\z` for the same reason, and
+# worse, since its `^`/`$` match at every line boundary.
+NAME_RE = re.compile(r'^[a-zA-Z@][a-zA-Z0-9.~_\-/]*\Z')
+
+# Section 4: `^[a-zA-Z0-9.~_-]+$`, max 1024, or empty.
+#
+# The asymmetry with a name is deliberate: a tag MAY start with a digit
+# because auto-tagging assigns integer tags (`stripe$1`), and a tag admits
+# neither `@` nor `/` because a name is a package specifier and a tag is
+# not.
+TAG_RE = re.compile(r'^[a-zA-Z0-9.~_-]+\Z')
+
+MAX = 1024
+
+
+def check_name(name):
+    if not isinstance(name, str):
+        return False
+    if 0 == len(name) or MAX < len(name):
+        return False
+    return None is not NAME_RE.match(name)
+
+
+def check_tag(tag):
+    if not isinstance(tag, str):
+        return False
+    # The empty tag is an ordinary tag (section 4 rule 2). The
+    # single-instance case writes no tag and never learns tags exist.
+    if 0 == len(tag):
+        return True
+    if MAX < len(tag):
+        return False
+    return None is not TAG_RE.match(tag)
+
+
+def parse_ref(text):
+    """`name$tag` -> the pair. Canonicalizing: `stripe$` and `stripe` both
+    give tag ''."""
+    if not isinstance(text, str):
+        fail('plugin_bad_name', 'ref must be a string')
+
+    # Split on the FIRST `$`. Nothing in the grammar decides this - `$` is
+    # in neither character class - so the corpus is the arbiter (section 4
+    # rule 5), and it picks the split that blames the part actually at
+    # fault: `a$b$c` is a good name with a bad tag, not the reverse.
+    cut = text.find('$')
+    name = text if -1 == cut else text[:cut]
+    tag = '' if -1 == cut else text[cut + 1:]
+
+    if not check_name(name):
+        fail('plugin_bad_name', 'invalid plugin name: ' + name, {'name': name})
+    if not check_tag(tag):
+        fail('plugin_bad_tag', 'invalid plugin tag: ' + tag,
+             {'name': name, 'tag': tag})
+
+    return {'name': name, 'tag': tag}
+
+
+def format_ref(name, tag=None):
+    """The pair -> `name$tag`. An empty tag NEVER writes the separator,
+    which is the half of canonicalization format_ref owns: parse tolerates
+    `stripe$`, format never produces it, so a round trip is idempotent."""
+    tag = '' if None is tag else tag
+    if not check_name(name):
+        fail('plugin_bad_name', 'invalid plugin name: ' + str(name),
+             {'name': name})
+    if not check_tag(tag):
+        fail('plugin_bad_tag', 'invalid plugin tag: ' + str(tag),
+             {'name': name, 'tag': tag})
+    return name if '' == tag else name + '$' + tag
+
+
+def canon_ref(text):
+    """The canonical spelling of a ref. Section 4 rule 5: ports must
+    canonicalize before comparison."""
+    ref = parse_ref(text)
+    return format_ref(ref['name'], ref['tag'])
+
+
+def try_ref(text):
+    """The canonical ref this string denotes, or None if it denotes none -
+    the TOLERANT half of `canon_ref`, and the one a requirement name needs.
+
+    A REQUIREMENT NAME IS A CAPABILITY NAME FIRST (section 11.1), and
+    capability names are free-form: the design puts no grammar on them, so
+    `2fa` and `my cap` are perfectly good ones and neither is a well-formed
+    ref. `canon_ref` RAISES on those, so asking it "is this a ref?" made a
+    legal document kill the host. Answering None is the whole difference.
+    """
+    if not isinstance(text, str):
+        return None
+    cut = text.find('$')
+    name = text if -1 == cut else text[:cut]
+    tag = '' if -1 == cut else text[cut + 1:]
+    if not check_name(name) or not check_tag(tag):
+        return None
+    return name if '' == tag else name + '$' + tag

package/project/.sdk/tm/py/pkg/feature/secrets/voxgig_plugin/resolve.py

@@ -0,0 +1,59 @@
+# VENDORED: @voxgig/plugin 0.1.6 (python/voxgig_plugin/resolve.py)
+# Source: https://github.com/voxgig/plugin @ 8d8968afc0a2008fbd795b41ab166307d989f02a  [tag: sdk-20260904-1610-0]
+# License: MIT (c) voxgig - see repository LICENSE. Do not edit: resync from upstream.
+"""Dynamic resolution (section 10.2) - name to candidate module ids.
+
+PURE. It returns the ids a host WOULD try, in order; it does not load
+anything. That separation is what lets the corpus pin resolution in every
+language including those with no dynamic loading at all, and it is why
+section 15.4 puts real module loading in per-port integration tests rather
+than here.
+"""
+
+DEFAULT_SOURCES = [
+    {'kind': 'module',
+     'prefix': ['@voxgig/plugin-', 'voxgig-plugin-', 'plugin-', '']},
+]
+
+
+def resolve_candidates(name, sources=None):
+    out = []
+
+    # A SCOPED NAME RESOLVES VERBATIM ONLY (section 10.2). `@acme/thing`
+    # is already a package id; prefixing it produces
+    # `@voxgig/plugin-@acme/thing`, which is not a thing that can exist.
+    if name.startswith('@'):
+        return [name]
+
+    entries = sources if sources else DEFAULT_SOURCES
+
+    for src in entries:
+        if 'module' == src.get('kind'):
+            prefixes = src.get('prefix') or ['']
+            if 0 == len(prefixes):
+                prefixes = ['']
+            for prefix in prefixes:
+                found = prefix + name
+                if found not in out:
+                    out.append(found)
+        elif 'path' == src.get('kind'):
+            found = src['dir'].rstrip('/') + '/' + name
+            if found not in out:
+                out.append(found)
+
+    return out
+
+
+def resolve_from(location):
+    """A MODULE PATH IS NOT A NAME (section 10.2). The ref grammar starts
+    a name with a letter or `@`, so `./local/thing` is not a ref and never
+    reaches candidate generation - seneca allows a path where a plugin
+    name goes, and this design deliberately does not, because a ref is an
+    ADDRESS WITHIN A HOST and a path is a LOCATION ON A DISK.
+
+    Loading from an explicit location is a separate field that bypasses
+    candidate generation entirely: `from` is passed to the resolver
+    verbatim, and a resolver that cannot honour a location raises
+    plugin_resolve_failed.
+    """
+    return [location]

package/project/.sdk/tm/py/pkg/feature/secrets/voxgig_plugin/types.py

@@ -0,0 +1,87 @@
+# VENDORED: @voxgig/plugin 0.1.6 (python/voxgig_plugin/types.py)
+# Source: https://github.com/voxgig/plugin @ 8d8968afc0a2008fbd795b41ab166307d989f02a  [tag: sdk-20260904-1610-0]
+# License: MIT (c) voxgig - see repository LICENSE. Do not edit: resync from upstream.
+"""Shared types. Deliberately small: the design's section 19 budget says
+the library owns naming, configuration, lifecycle, ordering, binding and
+teardown, and nothing else.
+
+PYTHON IS THE OTHER HALF OF P4'S PROVING PAIR (section 18): "the closest
+dynamic analogue that is not JavaScript". It raises where the canonical
+raises and go returns, so the interesting differences here are not about
+errors — they are about the places JavaScript's coercion rules and
+Python's disagree, and `True == 1` is the first of them.
+"""
+
+import json
+
+
+# Section 5.1's seven statuses, and no more. A port that adds an eighth is
+# diverging. `loading` and `closing` are observable only from inside a
+# callback or from another thread.
+STATUSES = ['declared', 'loaded', 'pending', 'live', 'failed',
+            'loading', 'closing']
+
+
+# Section 12's detail fields, IN THIS FIXED ORDER.
+#
+# The order is part of the contract, not a formatting preference. An
+# earlier draft named six fields while other sections promised
+# diagnostics that had nowhere to go, which would have left each port
+# inventing its own order and breaking message parity.
+DETAIL_ORDER = [
+    'host', 'ref', 'name', 'tag', 'point', 'key', 'capability',
+    'range', 'version', 'match', 'candidates', 'cycle', 'holders',
+    'refs', 'path', 'cause',
+]
+
+
+def compactjson(value):
+    """JSON.stringify's output: compact, and NOT ascii-escaped.
+
+    `ensure_ascii=True` would render a non-ASCII value as `\\uXXXX` where
+    every other port prints the character, which breaks section 12
+    message parity on exactly the inputs least likely to be tested.
+    """
+    return json.dumps(value, separators=(',', ':'), ensure_ascii=False)
+
+
+def formaterror(code, text, details=None):
+    """`plugin/<code>: <text> [<key>=<value> ...]`
+
+    Values render as COMPACT JSON, so a value containing a space or a
+    bracket cannot break the parse, and a list renders as a JSON array.
+    The bracket is absent entirely when no field applies.
+    """
+    details = details or {}
+    parts = []
+    for key in DETAIL_ORDER:
+        if key not in details:
+            continue
+        parts.append(key + '=' + compactjson(details[key]))
+    tail = '' if 0 == len(parts) else ' [' + ' '.join(parts) + ']'
+    return 'plugin/' + code + ': ' + text + tail
+
+
+class PluginError(Exception):
+    """Every error carries a section 12 code. Ports compare by CODE and
+    never by message: wording is a port's own business, and pinning the
+    words would make every translation a corpus change. The FORMAT,
+    however, is pinned - a parseable message is what makes a log
+    searchable across twenty languages."""
+
+    def __init__(self, code, text, details=None):
+        super().__init__(formaterror(code, text, details))
+        self.code = code
+        self.text = text
+        self.details = details or {}
+
+
+def fail(code, text, details=None):
+    raise PluginError(code, text, details)
+
+
+def codeof(err):
+    """The section 12 code of an error, or '' for one this library did not
+    raise. The corpus compares by code, so the driver needs one place
+    that knows how to read it."""
+    return getattr(err, 'code', '')

package/project/.sdk/tm/py/pkg/feature/secrets/voxgig_plugin/version.py

@@ -0,0 +1,112 @@
+# VENDORED: @voxgig/plugin 0.1.6 (python/voxgig_plugin/version.py)
+# Source: https://github.com/voxgig/plugin @ 8d8968afc0a2008fbd795b41ab166307d989f02a  [tag: sdk-20260904-1610-0]
+# License: MIT (c) voxgig - see repository LICENSE. Do not edit: resync from upstream.
+"""Versions and ranges (section 11.2).
+
+TWO FIELDS AND ONE PREDICATE. A capability declares `version`, a concrete
+version. A requirement declares `range`. A requirement is satisfied when
+the names match, the `match` passes, and:
+
+  the provider's `version` falls inside the requirement's `range`.
+
+That is the whole rule. There is no third field and no second comparison -
+an earlier draft added a provider-side `compat` range, which left three
+values and no statement of how they combine, and three defensible
+readings of one declaration is worse than the ambiguity it was introduced
+to fix.
+"""
+
+import re
+
+from .types import fail
+
+# `\Z`, NOT `$` — the same trap as the ref grammar. Python's `$` also
+# matches before a trailing newline, so `^...$` accepts "2.1\n" as a
+# range. Pinned by `version/rangebad#trailing-newline`.
+VERSION_RE = re.compile(r'^(\d+)(?:\.(\d+))?(?:\.(\d+))?\Z')
+
+# A COMPONENT IS BOUNDED, and the bound is the model's, not the host
+# language's. Python integers are unbounded and JavaScript's stop being
+# exact past 2^53, so `4294967296.0.0` compared as an ordinary number in
+# one port and lost precision in another. 2^31-1 is the smallest bound
+# every target language holds exactly, which makes it the model's.
+COMPONENT_MAX = 2147483647
+
+
+def component(digits, whole, field):
+    value = int(digits)
+    if COMPONENT_MAX < value:
+        fail('plugin_bad_range',
+             'version component out of range in ' + whole + ': ' + digits,
+             {field: whole})
+    return value
+
+
+def parse_range(text):
+    """Two forms and no more (section 11.2):
+
+      '2.1'    >= 2.1.0 and < 3.0.0
+      '~2.1'   >= 2.1.0 and < 2.2.0
+    """
+    if not isinstance(text, str) or 0 == len(text):
+        fail('plugin_bad_range', 'invalid range: ' + str(text),
+             {'range': text})
+
+    tilde = text.startswith('~')
+    body = text[1:] if tilde else text
+    found = VERSION_RE.match(body)
+    if None is found:
+        fail('plugin_bad_range', 'invalid range: ' + text, {'range': text})
+
+    major = component(found.group(1), text, 'range')
+    minor = (0 if None is found.group(2)
+             else component(found.group(2), text, 'range'))
+    patch = (0 if None is found.group(3)
+             else component(found.group(3), text, 'range'))
+
+    lo = [major, minor, patch]
+    hi = [major, minor + 1, 0] if tilde else [major + 1, 0, 0]
+    return {'lo': lo, 'hi': hi}
+
+
+def parse_version(text):
+    if not isinstance(text, str):
+        fail('plugin_bad_range', 'invalid version: ' + str(text),
+             {'version': text})
+    found = VERSION_RE.match(text)
+    if None is found:
+        fail('plugin_bad_range', 'invalid version: ' + text,
+             {'version': text})
+    return [
+        component(found.group(1), text, 'version'),
+        (0 if None is found.group(2)
+         else component(found.group(2), text, 'version')),
+        (0 if None is found.group(3)
+         else component(found.group(3), text, 'version')),
+    ]
+
+
+def satisfies(version, text):
+    """The one satisfaction predicate: lo <= version < hi."""
+    value = parse_version(version)
+    span = parse_range(text)
+    return 0 <= cmp(value, span['lo']) and 0 > cmp(value, span['hi'])
+
+
+def satisfiesq(version, text):
+    """satisfies for the internal callers that treat an unparseable
+    version or range as "does not satisfy" - Capability and Graph, both of
+    which run over data the corpus has already admitted."""
+    try:
+        return satisfies(version, text)
+    except Exception:
+        return False
+
+
+def cmp(a, b):
+    for i in range(3):
+        x = a[i] if i < len(a) else 0
+        y = b[i] if i < len(b) else 0
+        if x != y:
+            return -1 if x < y else 1
+    return 0