gpconf 0.3.0__py3-none-any.whl

gpconf/__init__.py

@@ -0,0 +1,6 @@
+"""gpconf -- runner for the GP/OMM conformance corpus (standard library only, Python 3.9+)."""
+
+__version__ = "0.3.0"
+
+from .tle import to_alpha5, from_alpha5, checksum  # noqa: F401
+from .reference import read_file  # noqa: F401

gpconf/__main__.py

@@ -0,0 +1,203 @@
+"""python -m gpconf: run a parser against the corpus and print a report; fetch: fetch the provider data the corpus
+does not ship; list: the cases; check-tle: check a TLE file a tool wrote."""
+import argparse
+import importlib
+import json
+import os
+import sys
+
+from . import __version__
+from . import locate
+from .runner import Runner, CommandParser, CorpusIncomplete
+
+
+def load_adapter(spec):
+    mod, _, attr = spec.partition(":")
+    sys.path.insert(0, os.getcwd())
+    m = importlib.import_module(mod)
+    obj = getattr(m, attr or "Parser")
+    return obj() if isinstance(obj, type) else obj
+
+
+def print_missing(results, unfetched, runner):
+    """Below the count line: what was not fetched, so that neither a case with no data nor a case that ran on part
+    of its data reads as a result it has not earned (D-148)."""
+    partial = [r for r in results if r.status != "not-fetched" and r.missing()]
+    if not unfetched and not partial:
+        return
+    if unfetched:
+        print(f"{len(unfetched)} case(s) have none of their provider files on disk and report not-fetched; "
+              "skip is reserved for a parser with no reader for a format or no hook for a check.")
+    if partial:
+        files = [f for r in partial for f in r.missing()]
+        print(f"{len(partial)} case(s) ran without {len(files)} of their provider files, so each result covers only the files on disk "
+              f"(column n/f): {', '.join(r.case_id for r in partial)}.")
+        if any("recapture" in os.path.basename(f) for f in files):
+            # corrected by D-150: a normal fetch never requests a re-capture, so a later run does not bring it
+            print("  A re-capture file is the same endpoint requested a second time when the corpus was built; the fetch requests it "
+                  "only with --include-recaptures, once its original is at least two hours old, so a normal fetch leaves these cases without it.")
+    # the fetch command only where a normal fetch would bring something: a missing re-capture it never requests (D-150)
+    if runner.fetch_hints and any("recapture" not in os.path.basename(f) for r in results for f in r.missing()):
+        print(f"Provider data is not shipped with the corpus; fetch it with {runner.hint()}.")
+
+
+def check_tle(args):
+    """check-tle FILE... [--against RECORDS] [--json OUT]: the writer checks applied to files a tool wrote."""
+    from . import writer as W
+    if not args.files:
+        print("check-tle needs at least one TLE file", file=sys.stderr)
+        return 2
+    against = W.load_against(args.against) if args.against else None
+    print(f"gpconf {__version__} | check-tle | {len(args.files)} file(s)" + (f" | round trip against {args.against}" if args.against else ""))
+    report, n_pass, n_fail = [], 0, 0
+    for path in args.files:
+        with open(path, "rb") as f:
+            text = f.read().decode("utf-8", "replace")
+        results = W.check_file(text, against)
+        print(f"\n{path}: {len(results)} record(s)" + ("" if results else " (no element line found)"))
+        for r in results:
+            ident = repr(r["catalog_field"]) + (f" -> {r['norad_cat_id']}" if r["norad_cat_id"] is not None else "")
+            head = "unpaired element line" if r.get("unpaired") else (r["name"] or "(no name line)")
+            print(f"  [{r['status']}] line {r['line_number']}: {head} | catalog field {ident}")
+            for p in r["problems"]:
+                print(f"         {p}")
+            for n in r["notes"]:
+                print(f"         note: {n}")
+            if r.get("round_trip"):
+                print("         round trip against the source record: " + ", ".join(f"{k} {v}" for k, v in r["round_trip"]["conventions"].items()))
+            if r.get("secondary_fields"):
+                print("         secondary fields (information): " + ", ".join(f"{k} {v}" for k, v in r["secondary_fields"].items() if k != "zero_ddot_sign"))
+            n_pass += r["status"] == "pass"
+            n_fail += r["status"] == "fail"
+        report.append({"file": path, "records": results})
+    print(f"\n{n_pass + n_fail} record(s): {n_pass} pass, {n_fail} fail"
+          + ("" if n_pass + n_fail else "; nothing to check"))
+    if args.json:
+        import datetime as _dt
+        with open(args.json, "w") as f:
+            json.dump({"gpconf": __version__, "command": "check-tle", "against": args.against,
+                       "generated_at": _dt.datetime.now(_dt.timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ"), "files": report}, f, indent=1, default=str)
+    return 1 if n_fail or not (n_pass + n_fail) else 0
+
+
+def main(argv=None):
+    argv = sys.argv[1:] if argv is None else list(argv)
+    if argv[:1] == ["fetch"]:  # its own options (tools/fetch.py's), parsed by gpconf/fetch.py (D-150)
+        from .fetch import run as fetch_run
+        return fetch_run(argv[1:], prog="gpconf fetch")
+    ap = argparse.ArgumentParser(prog="gpconf", description="GP/OMM conformance corpus runner",
+                                 epilog="gpconf fetch --help: the fetch subcommand's own options")
+    ap.add_argument("command", choices=["run", "list", "presets", "check-tle", "fetch"])
+    ap.add_argument("files", nargs="*", help="check-tle: TLE file(s) written by the tool under test")
+    ap.add_argument("--against", help="check-tle: the source records the lines were written from (CSV/JSON/XML/KVN/TLE); enables the round-trip check")
+    ap.add_argument("--preset", help="a shipped adapter by name: reference, naive, sgp4, pyephem, satellite.js, tle.js or tle.js-api (gpconf presets lists them)")
+    ap.add_argument("--module", help="Node presets: the library's entry file, for a checkout the working directory cannot import by name")
+    ap.add_argument("--adapter", help="python import path module:attr of a parser object or class")
+    ap.add_argument("--cmd", help="external command; raw bytes on stdin, JSON array on stdout; {fmt} substituted; exit 3 = unsupported format")
+    ap.add_argument("--vectors-cmd", help="external command for vector hooks (JSON {op,input} on stdin -> {result}|{error})")
+    ap.add_argument("--write-cmd", help="external TLE writer for the writer case: one JSON record on stdin, 2-3 TLE lines on stdout; exit 3 = unsupported, other non-zero = refused")
+    ap.add_argument("--root", help="corpus root (default: the clone this package sits in, else the corpus installed with it)")
+    ap.add_argument("--data", help=f"folder holding the fetched provider files (default: ${locate.DATA_ENV}, else the clone, else a per-user cache folder)")
+    ap.add_argument("--no-fetch-hint", action="store_true", help="do not name the command that fetches provider data, for a run that is "
+                    "offline by design, such as the GitHub Action's, whose data folder is empty and discarded with the job")
+    ap.add_argument("--case", action="append", help="case id (repeatable)")
+    ap.add_argument("--tag", action="append", help="test tag (repeatable)")
+    ap.add_argument("--json", help="write the full report to this file")
+    ap.add_argument("--verbose", "-v", action="store_true", help="print every item, not only failures and within-tolerance passes")
+    args = ap.parse_args(argv)
+
+    if args.command == "check-tle":  # needs no corpus: it checks the user's own file
+        return check_tle(args)
+    if args.command == "presets":
+        from .presets import listing
+        print("\n".join(listing()))
+        return 0
+    try:
+        loc = locate.resolve(args.root, args.data)
+    except locate.CorpusNotFound as e:
+        print(f"gpconf: {e}", file=sys.stderr)
+        return 2
+    root = loc["corpus"]
+    manifest = json.load(open(os.path.join(root, "manifest.json")))
+    if args.command == "list":
+        for c in manifest["cases"]:
+            print(f"{c['id']:40s} {c['kind']:12s} {', '.join(c['tests'])}")
+        return 0
+    chosen = [f for f in ("preset", "adapter", "cmd") if getattr(args, f)] + (["write-cmd"] if args.write_cmd and not args.cmd else [])
+    if not chosen:
+        ap.error("run needs --preset, --adapter, --cmd or --write-cmd")
+    if args.preset and len(chosen) > 1:
+        ap.error("--preset names the parser; it cannot be combined with --adapter, --cmd or --write-cmd")
+    if args.module and not args.preset:
+        ap.error("--module applies to the Node presets")
+    preset = None
+    if args.preset:
+        from .presets import load as load_preset, PresetUnavailable
+        try:
+            parser, preset = load_preset(args.preset, module=args.module)
+        except PresetUnavailable as e:
+            print(f"gpconf: {e}", file=sys.stderr)
+            return 2
+    elif args.cmd or args.write_cmd:
+        parser = CommandParser(args.cmd, args.vectors_cmd, write_cmd=args.write_cmd)
+    else:
+        parser = load_adapter(args.adapter)
+    parser_name = preset["label"] if preset else (args.cmd or args.write_cmd or args.adapter)
+    runner = Runner(parser, root=root, verbose=args.verbose, data=loc["data"], data_why=loc["data_why"], fetch_hints=not args.no_fetch_hint)
+    try:
+        results = runner.run(case_ids=args.case, tags=args.tag)
+    except CorpusIncomplete as e:
+        print(f"gpconf: {e}", file=sys.stderr)
+        return 2
+    print(f"gpconf {__version__} | corpus {manifest['corpus_version']} | parser: {parser_name}")
+    if runner.data != root:  # a clone's output is unchanged; elsewhere the reader is told where the provider files were looked for
+        print(f"provider data: {runner.data} ({runner.data_why})")
+    print()
+    print(f"{'case':40s} {'status':15s} exact  tol fail skip n/e n/f")
+    for r in results:
+        c = r.counts()
+        print(f"{r.case_id:40s} {r.status:15s} {c['pass']:5d} {c['pass-tolerance']:4d} {c['fail']:4d} {c['skip']:4d} {c['not-exercised']:3d} {c['not-fetched']:3d}")
+    print()
+    from .gates import compute_gates
+    gates = compute_gates(results, root, runner.data)
+    for g in gates:
+        print(f"gate {g['name']}: {g['headline']}")
+    print()
+    for r in results:
+        shown = [i for i in r.items if args.verbose or i.status in ("fail", "pass-tolerance")]
+        if shown:
+            print(f"== {r.case_id}")
+            for i in shown:
+                print(f"  [{i.status}] {i.check} ({i.file or '-'}): {i.detail}")
+    drifted = [(r.case_id, p) for r in results for p in r.drift]
+    if drifted:
+        print("\nSTABLE SOURCE DRIFT: " + ", ".join(f"{c}: {p}" for c, p in drifted)
+              + "\n  These stable-tier files differ from the tested snapshot; the frozen expected values were not applied to them and the parser was compared against the reference reader instead."
+              + (" Run " + runner.hint("--check-drift") + "." if runner.fetch_hints else ""))
+    modes = {m for r in results for m in r.modes.values()}
+    if "live" in modes:
+        print("\nnote: some sources hash differently from the tested snapshot; for those, values were compared against the corpus's own reference reader, not the human-verified snapshot.")
+    if args.json:
+        import datetime as _dt
+        with open(args.json, "w") as f:
+            json.dump({"gpconf": __version__, "corpus_version": manifest["corpus_version"], "parser": parser_name,
+                       **({"preset": {k: preset.get(k) for k in ("name", "library", "found", "tested_with", "runtime") if k != "runtime" or preset.get(k)}} if preset else {}),
+                       "generated_at": _dt.datetime.now(_dt.timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ"),
+                       "results": [r.as_dict() for r in results], "gates": gates}, f, indent=1, default=str)
+    failed = sum(1 for r in results if r.status == "fail")
+    tol = sum(1 for r in results if r.status == "pass-tolerance")
+    unfetched = [r for r in results if r.status == "not-fetched"]
+    print(f"\n{len(results)} case(s): {sum(1 for r in results if r.status == 'pass')} pass (exact), {tol} pass within tolerance, {failed} fail, "
+          f"{sum(1 for r in results if r.status == 'skip')} skip, {len(unfetched)} need fetched data, {sum(1 for r in results if r.status == 'not-exercised')} not exercised")
+    print_missing(results, unfetched, runner)
+    reused = {p: v for r in results for p, v in r.reused.items()}
+    if reused:  # D-157: the report says which provider files were copied from an earlier version's cache, not fetched
+        print(f"{len(reused)} provider file(s) were reused from corpus {', '.join(sorted(set(map(str, reused.values()))))}'s cache "
+              "rather than fetched: stable tier, bytes matching this version's recorded SHA-256.")
+    if tol:
+        print("'pass within tolerance' items list per-field count, mean signed difference and maximum, so a systematic bias is visible (see README, Tolerances).")
+    return 1 if failed else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

gpconf/adapters/__init__.py

@@ -0,0 +1,2 @@
+"""The adapters behind `gpconf run --preset` (D-151): reference, naive, sgp4 (python-sgp4) and pyephem (PyEphem).
+gpconf/presets.py names them, the library each exposes and the version each was tested against."""

gpconf/adapters/naive.py

@@ -0,0 +1,142 @@
+"""
+Preset `naive`: a demonstration of failure, not a parser anyone should use. It is the parser many projects
+actually have, written deliberately with the common shortcuts so that the runner's failures document what breaks
+in the migration:
+  * catalog number read with int() from five columns / assumed five characters wide
+  * two-digit year pivot present, but OBJECT_ID's year sliced unconditionally
+  * OMM epoch parsed with the single format '%Y-%m-%dT%H:%M:%S.%f'
+  * classification assumed to be 'U'
+  * KVN parsed as strict 'KEY = value' with float() on the value
+  * every CelesTrak CSV/JSON column assumed present
+  * TLE written with the catalog number through an integer format (five digits assumed, never refused)
+"""
+import csv
+import datetime as dt
+import io
+import json
+import xml.etree.ElementTree as ET
+
+
+def _year(yy):
+    yy = int(yy)
+    return 1900 + yy if yy >= 57 else 2000 + yy
+
+
+def _tle_epoch(field):
+    year = _year(field[:2])
+    day = float(field[2:])
+    return (dt.datetime(year, 1, 1) + dt.timedelta(days=day - 1)).strftime("%Y-%m-%dT%H:%M:%S.%f")
+
+
+def _exp(f):
+    f = f.strip()
+    return float(f"{f[:-2]}e{f[-2:]}".replace("-", "-0.", 1) if f.startswith("-") else f"0.{f[:-2]}e{f[-2:]}")
+
+
+class Parser:
+    def parse(self, raw, fmt):
+        text = raw.decode("utf-8")
+        if fmt in ("tle", "2le"):
+            return self._tle(text)
+        if fmt == "csv":
+            return [self._omm(r) for r in csv.DictReader(io.StringIO(text))]
+        if fmt == "json":
+            return [self._omm(r) for r in json.loads(text)]
+        if fmt == "xml":
+            root = ET.fromstring(text)
+            out = []
+            for seg in root.iter("segment"):
+                f = {}
+                for blk in ("metadata", "data/meanElements", "data/tleParameters"):
+                    for e in seg.find(blk):
+                        f[e.tag] = e.text
+                out.append(self._omm(f))
+            return out
+        if fmt == "kvn":
+            out, cur = [], None
+            for line in text.splitlines():
+                if not line.strip():
+                    continue
+                k, v = [x.strip() for x in line.split("=", 1)]
+                if k == "CCSDS_OMM_VERS":
+                    cur = {}
+                    out.append(cur)
+                cur[k] = v
+            return [self._omm(f) for f in out]
+        raise ValueError(fmt)
+
+    def _tle(self, text):
+        lines = text.splitlines()
+        out = []
+        for i, l in enumerate(lines):
+            if l.startswith("1 ") and lines[i + 1].startswith("2 "):
+                l1, l2 = l, lines[i + 1]
+                cat = int(l1[2:7])                    # breaks on Alpha-5
+                assert l1[7] == "U", "classification"  # breaks on 'C'
+                out.append({
+                    "norad_cat_id": cat, "object_name": (lines[i - 1].strip() if i and not lines[i - 1].startswith(("1 ", "2 ")) else None),
+                    "object_id": f"{_year(l1[9:11])}-{l1[11:17].strip()}",   # invents '1900-' + blanks for empty designator? no: _year('  ') raises
+                    "epoch": _tle_epoch(l1[18:32]), "mean_motion": float(l2[52:63]), "eccentricity": float("0." + l2[26:33]),
+                    "inclination": float(l2[8:16]), "ra_of_asc_node": float(l2[17:25]), "arg_of_pericenter": float(l2[34:42]),
+                    "mean_anomaly": float(l2[43:51]), "bstar": _exp(l1[53:61]), "mean_motion_dot": float(l1[33:43]),
+                    "mean_motion_ddot": _exp(l1[44:52]), "ephemeris_type": int(l1[62]), "classification_type": l1[7],
+                    "element_set_no": int(l1[64:68]), "rev_at_epoch": int(l2[63:68]),
+                })
+        return out
+
+    def _omm(self, f):
+        cat = int(f["NORAD_CAT_ID"])
+        assert len(f"{cat:05d}") == 5, "catalog number wider than five digits"   # breaks on 6- and 9-digit ids
+        epoch = dt.datetime.strptime(f["EPOCH"], "%Y-%m-%dT%H:%M:%S.%f")       # breaks on day-of-year / Z / no fraction
+        launch_year = int(f["OBJECT_ID"][:4])                                    # breaks on empty OBJECT_ID (and None)
+        assert f["CLASSIFICATION_TYPE"] == "U"                                   # breaks on 'C'
+        return {
+            "norad_cat_id": cat, "object_name": f["OBJECT_NAME"], "object_id": f["OBJECT_ID"], "epoch": epoch,
+            "mean_motion": float(f["MEAN_MOTION"]), "eccentricity": float(f["ECCENTRICITY"]), "inclination": float(f["INCLINATION"]),
+            "ra_of_asc_node": float(f["RA_OF_ASC_NODE"]), "arg_of_pericenter": float(f["ARG_OF_PERICENTER"]), "mean_anomaly": float(f["MEAN_ANOMALY"]),
+            "bstar": float(f["BSTAR"]), "mean_motion_dot": float(f["MEAN_MOTION_DOT"]), "mean_motion_ddot": float(f["MEAN_MOTION_DDOT"]),
+            "ephemeris_type": int(f["EPHEMERIS_TYPE"]), "classification_type": f["CLASSIFICATION_TYPE"],
+            "element_set_no": int(f["ELEMENT_SET_NO"]), "rev_at_epoch": int(f["REV_AT_EPOCH"]),
+        }
+
+    def write_tle(self, record):
+        """The writer many projects have: printf-style fields, the catalog number as an integer."""
+        r = record
+        sat = f"{int(r['norad_cat_id']):05d}"                       # six digits above 99999; '-0001' for -1; never refuses
+        t = dt.datetime.strptime(str(r["epoch"])[:26], "%Y-%m-%dT%H:%M:%S.%f")
+        doy = (t - dt.datetime(t.year, 1, 1)).total_seconds() / 86400.0 + 1
+        epoch = f"{t.year % 100:02d}{doy:012.8f}"
+        oid = r.get("object_id") or ""
+        desig = (oid[2:4] + oid[5:]) if oid else ""
+
+        def exp(v):
+            v = float(v or 0)
+            if v == 0:
+                return " 00000-0"
+            m, e = f"{abs(v):.4e}".split("e")
+            return ("-" if v < 0 else " ") + m.replace(".", "") + f"{int(e) + 1:+d}"
+
+        ndot = float(r.get("mean_motion_dot") or 0)
+        nd = ("-" if ndot < 0 else " ") + f"{abs(ndot):.8f}"[1:]          # ' .00004770' / '-.00003657'
+        l1 = f"1 {sat}U {desig:<8} {epoch} {nd} {exp(r.get('mean_motion_ddot'))} {exp(r.get('bstar'))} 0 {int(r.get('element_set_no') or 0):4d}"
+        l2 = (f"2 {sat} {float(r['inclination']):8.4f} {float(r['ra_of_asc_node']):8.4f} {float(r['eccentricity']) * 1e7:07.0f} "
+              f"{float(r['arg_of_pericenter']):8.4f} {float(r['mean_anomaly']):8.4f} {float(r['mean_motion']):11.8f}{int(r.get('rev_at_epoch') or 0):5d}")
+
+        def cs(l):
+            return str(sum(int(c) if c.isdigit() else (c == "-") for c in l) % 10)
+        return l1 + cs(l1), l2 + cs(l2)
+
+    def alpha5_decode(self, field):
+        return int(field)  # breaks on any letter
+
+    def alpha5_encode(self, n):
+        return f"{n:05d}"  # produces six digits above 99999, never a letter
+
+    def two_digit_year(self, yy):
+        return _year(yy)
+
+    def parse_catalog_id(self, text):
+        return int(text)  # accepts ten digits; no width check
+
+    def parse_epoch(self, text):
+        return dt.datetime.strptime(text, "%Y-%m-%dT%H:%M:%S.%f")

gpconf/adapters/node_preflight.mjs

@@ -0,0 +1,29 @@
+// Preflight for a Node preset (D-153, D-154): can the working directory import the library? Run by gpconf as
+// `node --input-type=module --eval <this source> -- <package>` before any case, so that a missing Node library is a
+// setup error, never a parse failure charged to the library. Prints one JSON object: ok, node, entry, version, error.
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const [name] = process.argv.slice(1);
+const target = process.env.GPCONF_NODE_MODULE;
+const out = { ok: false, node: process.versions.node };
+try {
+  await import(target ? pathToFileURL(target).href : name);
+  let entry = target || null;
+  if (!entry) {
+    try { entry = fileURLToPath(import.meta.resolve(name)); } catch { entry = null; }
+  }
+  out.entry = entry;
+  // the version: the nearest package.json above the entry that names the library (a maintainer's checkout included)
+  for (let d = entry ? dirname(entry) : null; d && d !== dirname(d); d = dirname(d)) {
+    const p = join(d, 'package.json');
+    if (!existsSync(p)) continue;
+    const pj = JSON.parse(readFileSync(p, 'utf8'));
+    if (pj.name === name) { out.version = pj.version; break; }
+  }
+  out.ok = true;
+} catch (e) {
+  out.error = `${e.code || e.name}: ${e.message}`.slice(0, 300);
+}
+process.stdout.write(JSON.stringify(out));

gpconf/adapters/pyephem_adapter.py

@@ -0,0 +1,55 @@
+"""Preset `pyephem`: PyEphem (the `ephem` package, an optional dependency, tested with 4.2.1). TLE and 2LE only;
+every other format is Unsupported.
+
+Exposes the library as-is: `ephem.readtle()` per element set. An element set `readtle()` refuses is dropped, as in
+the corpus's hand run of 2026-09-24 (corpus D-128; reported upstream as pyephem#296); this adapter does not yet report
+refusals through the runner's refusal channel (D-144), so the runner counts them as dropped. Moved into the package
+from the hand run's harness (D-151) with its parsing unchanged.
+"""
+import math
+
+try:
+    import ephem
+except ImportError as e:  # pragma: no cover
+    raise ImportError("this adapter needs PyEphem: pip install ephem") from e
+
+from gpconf.runner import Unsupported
+
+
+def _rec(s, name):
+    d = s._epoch.datetime()  # ephem.Date -> naive UTC datetime, microsecond resolution
+    return {
+        "norad_cat_id": s.catalog_number,
+        "object_name": name or None,
+        "epoch": d,
+        "mean_motion": s._n,
+        "eccentricity": s._e,
+        "inclination": math.degrees(s._inc),
+        "ra_of_asc_node": math.degrees(s._raan),
+        "arg_of_pericenter": math.degrees(s._ap),
+        "mean_anomaly": math.degrees(s._M),
+        "bstar": s._drag,
+        "mean_motion_dot": s._decay,
+        # mean_motion_ddot: PyEphem keeps no second derivative (no attribute on EarthSatellite); omitted on purpose
+        "rev_at_epoch": s._orbit,
+        # object_id, classification_type, element_set_no, ephemeris_type: not exposed by PyEphem
+    }
+
+
+class Parser:
+    def parse(self, raw, fmt):
+        if fmt not in ("tle", "2le"):
+            raise Unsupported(fmt)
+        lines = raw.decode("utf-8").splitlines()
+        out = []
+        for i, l in enumerate(lines):
+            if l.startswith("1 ") and i + 1 < len(lines) and lines[i + 1].startswith("2 "):
+                name = lines[i - 1].strip() if i and not lines[i - 1].startswith(("1 ", "2 ")) else ""
+                # readtle() rejects an empty name (db_tle returns -1 when the stripped name is empty), so a
+                # name-less 2LE pair gets the catalog field as its name; object_name is then not reported
+                call_name = name or l[2:7]
+                try:
+                    out.append(_rec(ephem.readtle(call_name, l, lines[i + 1]), name))
+                except Exception:  # noqa: BLE001 -- the library refused the element set: dropped, as in the hand run
+                    pass
+        return out

gpconf/adapters/reference.py

@@ -0,0 +1,75 @@
+"""Preset `reference`: the corpus's own readers, the control. It passes every case that exercises a parser, since it
+produced the expected values. Standard library only."""
+import datetime as dt
+
+from gpconf import reference as ref
+from gpconf import tle as tlemod
+from gpconf.runner import CORE_FIELDS, OPTIONAL_FIELDS
+
+FMT = {"tle": ref.read_tle_text, "2le": ref.read_tle_text}
+
+
+class Parser:
+    def parse(self, raw, fmt):
+        text = raw.decode("utf-8")
+        if fmt in ("tle", "2le"):
+            recs = ref.read_tle_text(text)
+        elif fmt == "csv":
+            recs, _ = ref.read_csv_text(text)
+        elif fmt == "json":
+            recs, _ = ref.read_json_text(text)
+        elif fmt == "xml":
+            recs, _ = ref.read_xml_text(text)
+        elif fmt == "kvn":
+            recs, _ = ref.read_kvn_text(text)
+        else:
+            from gpconf.runner import Unsupported
+            raise Unsupported(fmt)
+        out = []
+        for r in recs:
+            d = {k: r.get(k) for k in CORE_FIELDS + OPTIONAL_FIELDS if r.get(k) is not None or k in CORE_FIELDS}
+            out.append(d)
+        return out
+
+    def write_tle(self, record):
+        # the corpus's own renderer (CelesTrak conventions: eccentricity truncated, mantissas rounded half up);
+        # to_alpha5 raises for a catalog number the TLE field cannot carry, which is the correct answer
+        return tlemod.render(tlemod.omm_fields_from_record(record), mantissa_mode="round", ecc_mode="truncate")
+
+    def alpha5_decode(self, field):
+        if len(field) != 5 or field != field.strip():
+            raise ValueError("field must be five characters")
+        return tlemod.from_alpha5(field)
+
+    def alpha5_encode(self, n):
+        return tlemod.to_alpha5(n)
+
+    def two_digit_year(self, yy):
+        return ref.two_digit_year(yy)
+
+    def parse_catalog_id(self, text):
+        import re
+        s = text.strip()
+        if not re.fullmatch(r"\+?\d{1,9}", s):  # CCSDS: integer of up to nine digits; KVN allows a leading sign and zeros
+            raise ValueError(f"not a NORAD_CAT_ID: {text!r}")
+        return int(s)
+
+    def parse_epoch(self, text):
+        import re
+        m = re.fullmatch(r"(\d{4})-(?:(\d{2})-(\d{2})|(\d{3}))T(\d{2}):(\d{2}):(\d{2})(\.\d+)?Z?", text)
+        if not m:
+            raise ValueError(text)
+        s = text.rstrip("Z")
+        frac = m.group(8) or ""
+        base = s[: len(s) - len(frac)]
+        fmt = "%Y-%jT%H:%M:%S" if m.group(4) else "%Y-%m-%dT%H:%M:%S"
+        try:
+            t = dt.datetime.strptime(base, fmt)
+        except ValueError:
+            if base.endswith(":60"):  # leap second: valid per CCSDS, not representable in datetime
+                t = dt.datetime.strptime(base[:-3] + ":59", fmt)
+            else:
+                raise
+        if frac:
+            t = t + dt.timedelta(microseconds=int(round(float("0" + frac) * 1e6)))
+        return t

gpconf/adapters/satellitejs.mjs

@@ -0,0 +1,77 @@
+// Preset `satellite.js` (tested with 7.1.0): satellite.js as-is through the runner's command protocol. Raw bytes on
+// stdin, a JSON array of records on stdout, exit 3 for a format the library has no reader for. twoline2satrec for
+// tle and 2le, json2satrec for json; csv, xml and kvn are unsupported. Moved into the package from the corpus's
+// hand run (D-132), its parsing unchanged.
+// gpconf runs this file as `node --input-type=module --eval <this source> -- <arguments>` from the working directory,
+// so the library resolves as it would for a script in the user's project; a file outside the project could not import
+// it (D-154). GPCONF_NODE_MODULE, set by `--module PATH`, names the library's entry file instead.
+import { readFileSync } from 'node:fs';
+import { pathToFileURL } from 'node:url';
+
+const target = process.env.GPCONF_NODE_MODULE;
+const { twoline2satrec, json2satrec } = await import(target ? pathToFileURL(target).href : 'satellite.js');
+
+const [fmt] = process.argv.slice(1);
+const XPDOTP = 1440.0 / (2.0 * Math.PI);   // satellite.js constants.xpdotp
+const RAD2DEG = 180.0 / Math.PI;
+
+function isoEpoch(epochyr, epochdays) {
+  // the library's own pivot (io.js line 102); day-of-year form with microseconds, from the double the library kept
+  const year = epochyr < 57 ? epochyr + 2000 : epochyr + 1900;
+  let doy = Math.floor(epochdays);
+  let us = Math.round((epochdays - doy) * 86400e6);
+  if (us >= 86400e6) { us -= 86400e6; doy += 1; }
+  const h = Math.floor(us / 3600e6), m = Math.floor((us % 3600e6) / 60e6), s = Math.floor((us % 60e6) / 1e6), f = us % 1e6;
+  const p = (n, w) => String(n).padStart(w, '0');
+  return `${year}-${p(doy, 3)}T${p(h, 2)}:${p(m, 2)}:${p(s, 2)}.${p(f, 6)}`;
+}
+
+function record(s, name) {
+  const raw = s.satnum;                       // a string in this library, never decoded
+  // digits -> int (what any consumer must do); anything else (an Alpha-5 field) is passed through as the string the
+  // library returns, and the runner reports the value and its type (corpus D-131)
+  const id = /^\s*\d+\s*$/.test(raw) ? Number(raw) : raw;
+  const mm = s.nokozai ?? s.no_kozai ?? s.no; // the Kozai mean motion as parsed, if the library keeps it apart
+  return {
+    norad_cat_id: id,
+    _catalog_field: raw,
+    object_name: name || null,
+    epoch: isoEpoch(s.epochyr, s.epochdays),
+    mean_motion: mm * XPDOTP,
+    eccentricity: s.ecco,
+    inclination: s.inclo * RAD2DEG,
+    ra_of_asc_node: s.nodeo * RAD2DEG,
+    arg_of_pericenter: s.argpo * RAD2DEG,
+    mean_anomaly: s.mo * RAD2DEG,
+    bstar: s.bstar,
+    mean_motion_dot: s.ndot * XPDOTP * 1440.0,
+    mean_motion_ddot: s.nddot * XPDOTP * 1440.0 * 1440.0,
+    _mm_field: s.nokozai !== undefined ? 'nokozai' : (s.no_kozai !== undefined ? 'no_kozai' : 'no'),
+  };
+}
+
+const raw = readFileSync(0, 'utf8');
+const out = [];
+if (fmt === 'tle' || fmt === '2le') {
+  const lines = raw.split(/\r?\n/);
+  for (let i = 0; i < lines.length; i++) {
+    const l = lines[i];
+    if (l.startsWith('1 ') && i + 1 < lines.length && lines[i + 1].startsWith('2 ')) {
+      const name = i > 0 && !/^[12] /.test(lines[i - 1]) ? lines[i - 1].trim() : '';
+      try { out.push(record(twoline2satrec(l, lines[i + 1]), name)); }
+      catch (e) { process.stderr.write(`satellite.js refused line ${i + 1}: ${e && e.message}\n`); }
+    }
+  }
+} else if (fmt === 'json') {
+  let data;
+  try { data = JSON.parse(raw); } catch (e) { process.stderr.write(`not JSON: ${e.message}\n`); process.exit(1); }
+  for (const obj of Array.isArray(data) ? data : [data]) {
+    try { out.push(record(json2satrec(obj), obj.OBJECT_NAME)); }
+    catch (e) { process.stderr.write(`satellite.js refused record ${obj && obj.NORAD_CAT_ID}: ${e && e.message}\n`); }
+  }
+} else {
+  process.exit(3);
+}
+// NaN and Infinity have no JSON form: JSON.stringify writes null, which the runner reads as "absent"; say so on stderr
+for (const r of out) for (const [k, v] of Object.entries(r)) if (typeof v === 'number' && !Number.isFinite(v)) process.stderr.write(`non-finite ${k} for ${r.norad_cat_id}: ${v} -> null\n`);
+process.stdout.write(JSON.stringify(out));