@shundoo-ai/dsh-cosmic 1.0.19 → 1.0.21

package/skills/cosmic-build/scripts/plugin_corpus/build_index.py

@@ -0,0 +1,403 @@
+#!/usr/bin/env python3
+"""Build or incrementally update the L0 plugin-corpus index of a Cosmic library tree.
+
+The index records binary facts only: every JAR with its hash and manifest version, every class
+with its hash, hierarchy and annotation types, declared members, and, for the corpus layers,
+the members, classes and dynamic class names each class refers to. It never decompiles, never
+modifies the libraries and never contacts a service.
+
+Usage::
+
+    build_index.py --lib-root <cosmic>/mservice-cosmic/lib --workspace <corpus workspace>
+
+Each immediate subdirectory of ``--lib-root`` that contains JARs becomes a layer named after it
+(bos, biz, cus, trd for a Cosmic installation). ``--refs-layer`` selects the layers whose
+references are stored (default biz and cus); the other layers keep classes and members, which
+is what resolving a reference needs. A rerun reuses every JAR whose size and modification time
+are unchanged, and every JAR whose content hash is unchanged.
+
+The workspace must be outside the repository and outside anything a tested agent can read; it
+holds ``l0-index.sqlite`` and ``l0-index-summary.json``.
+"""
+
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+import os
+import sqlite3
+import sys
+import time
+import zipfile
+from concurrent.futures import ProcessPoolExecutor
+from pathlib import Path
+
+import jvm_classfile
+
+SCHEMA_VERSION = 1
+DB_NAME = "l0-index.sqlite"
+SUMMARY_NAME = "l0-index-summary.json"
+DEFAULT_REFS_LAYERS = ("biz", "cus")
+# References into java.* are counted per class instead of stored: the corpus questions are about
+# platform and business APIs, and those rows would roughly double the table. javax.* and com.sun.*
+# are kept because third-party JARs in the library tree define many of them.
+JAVA_PREFIX = "java."
+
+_TABLES = """
+CREATE TABLE IF NOT EXISTS meta(key TEXT PRIMARY KEY, value TEXT);
+CREATE TABLE IF NOT EXISTS strings(id INTEGER PRIMARY KEY, value TEXT NOT NULL UNIQUE);
+CREATE TABLE IF NOT EXISTS jars(
+    id INTEGER PRIMARY KEY, path TEXT NOT NULL UNIQUE, layer TEXT NOT NULL, size INTEGER NOT NULL,
+    mtime_ns INTEGER NOT NULL, sha256 TEXT NOT NULL, implementation_version TEXT, bundle_version TEXT,
+    class_count INTEGER NOT NULL, error_count INTEGER NOT NULL, skipped_count INTEGER NOT NULL,
+    refs_indexed INTEGER NOT NULL, status TEXT NOT NULL, indexed_at TEXT NOT NULL);
+CREATE TABLE IF NOT EXISTS classes(
+    id INTEGER PRIMARY KEY, jar_id INTEGER NOT NULL, name_id INTEGER NOT NULL, super_id INTEGER,
+    access INTEGER NOT NULL, major INTEGER NOT NULL, sha256 TEXT NOT NULL, annotations TEXT,
+    deprecated INTEGER NOT NULL, source_file TEXT, entry TEXT NOT NULL, java_refs INTEGER);
+CREATE TABLE IF NOT EXISTS interfaces(class_id INTEGER NOT NULL, iface_id INTEGER NOT NULL);
+CREATE TABLE IF NOT EXISTS members(
+    class_id INTEGER NOT NULL, kind TEXT NOT NULL, name_id INTEGER NOT NULL, desc_id INTEGER NOT NULL,
+    access INTEGER NOT NULL, annotations TEXT, deprecated INTEGER NOT NULL);
+CREATE TABLE IF NOT EXISTS refs(
+    class_id INTEGER NOT NULL, kind TEXT NOT NULL, owner_id INTEGER NOT NULL, name_id INTEGER,
+    desc_id INTEGER);
+CREATE TABLE IF NOT EXISTS errors(jar_id INTEGER NOT NULL, entry TEXT, message TEXT NOT NULL);
+"""
+_INDEXES = """
+CREATE INDEX IF NOT EXISTS classes_name ON classes(name_id);
+CREATE INDEX IF NOT EXISTS classes_jar ON classes(jar_id);
+CREATE INDEX IF NOT EXISTS interfaces_class ON interfaces(class_id);
+CREATE INDEX IF NOT EXISTS members_class ON members(class_id);
+CREATE INDEX IF NOT EXISTS refs_class ON refs(class_id);
+CREATE INDEX IF NOT EXISTS refs_target ON refs(owner_id, name_id, desc_id);
+CREATE INDEX IF NOT EXISTS errors_jar ON errors(jar_id);
+"""
+
+
+class CorpusIndexError(RuntimeError):
+    """A usage or workspace problem reported to the caller as a structured error."""
+
+    def __init__(self, code: str, message: str):
+        super().__init__(message)
+        self.code = code
+
+
+def _hash_file(path: str) -> str:
+    digest = hashlib.sha256()
+    with open(path, "rb") as stream:
+        for block in iter(lambda: stream.read(1 << 20), b""):
+            digest.update(block)
+    return digest.hexdigest()
+
+
+def _manifest_versions(jar: zipfile.ZipFile) -> tuple[str | None, str | None]:
+    try:
+        text = jar.read("META-INF/MANIFEST.MF").decode("utf-8", "replace")
+    except KeyError:
+        return None, None
+    attributes: dict[str, str] = {}
+    key = None
+    for line in text.replace("\r\n", "\n").split("\n"):
+        if line.startswith(" ") and key:
+            attributes[key] += line[1:]
+        elif ":" in line:
+            key, _, value = line.partition(":")
+            attributes[key.strip()] = value.strip()
+    return attributes.get("Implementation-Version") or None, attributes.get("Bundle-Version") or None
+
+
+def parse_jar(task: tuple[str, str | None, bool]) -> dict:
+    """Worker: hash one JAR and, unless its hash is unchanged, parse its classes."""
+    path, known_sha, with_refs = task
+    sha = _hash_file(path)
+    if known_sha == sha:
+        return {"path": path, "sha256": sha, "unchanged": True}
+    classes: list[dict] = []
+    errors: list[tuple[str | None, str]] = []
+    skipped = 0
+    try:
+        with zipfile.ZipFile(path) as jar:
+            implementation, bundle = _manifest_versions(jar)
+            for info in jar.infolist():
+                entry = info.filename
+                if not entry.endswith(".class"):
+                    continue
+                # Multi-release overlays and module/package descriptors are not classes a plugin
+                # extends or calls; they are counted, not indexed.
+                if entry.startswith("META-INF/") or entry.endswith(("module-info.class", "package-info.class")):
+                    skipped += 1
+                    continue
+                data = jar.read(info)
+                try:
+                    parsed = jvm_classfile.parse_class(data)
+                except jvm_classfile.ClassFormatError as exc:
+                    errors.append((entry, str(exc)[:300]))
+                    continue
+                parsed["entry"] = entry
+                parsed["sha256"] = hashlib.sha256(data).hexdigest()
+                if not with_refs:
+                    parsed["memberRefs"] = parsed["classRefs"] = parsed["dynamicClassNames"] = None
+                classes.append(parsed)
+    except (zipfile.BadZipFile, OSError) as exc:
+        return {"path": path, "sha256": sha, "unreadable": str(exc)[:300]}
+    return {"path": path, "sha256": sha, "implementationVersion": implementation, "bundleVersion": bundle,
+            "classes": classes, "errors": errors, "skipped": skipped, "refsIndexed": with_refs}
+
+
+class _Strings:
+    """Intern repeated names in the strings table; ids are assigned here and flushed in bulk."""
+
+    def __init__(self, db: sqlite3.Connection):
+        self.db = db
+        self.ids = {value: key for key, value in db.execute("SELECT id, value FROM strings")}
+        self.next_id = max(self.ids.values(), default=0) + 1
+        self.pending: list[tuple[int, str]] = []
+
+    def id(self, value: str | None) -> int | None:
+        if value is None:
+            return None
+        known = self.ids.get(value)
+        if known is not None:
+            return known
+        key = self.next_id
+        self.next_id += 1
+        self.ids[value] = key
+        self.pending.append((key, value))
+        return key
+
+    def flush(self) -> None:
+        if self.pending:
+            self.db.executemany("INSERT INTO strings(id, value) VALUES (?, ?)", self.pending)
+            self.pending = []
+
+
+def resolve_layers(lib_root: str | None, explicit: list[str]) -> dict[str, Path]:
+    layers: dict[str, Path] = {}
+    if lib_root:
+        root = Path(lib_root).expanduser().resolve()
+        if not root.is_dir():
+            raise CorpusIndexError("CORPUS_LIB_ROOT_INVALID", f"Library root is not a directory: {root}")
+        for child in sorted(root.iterdir()):
+            if child.is_dir() and any(child.glob("*.jar")):
+                layers[child.name] = child
+    for item in explicit:
+        name, separator, directory = item.partition("=")
+        path = Path(directory).expanduser().resolve()
+        if not separator or not name or not path.is_dir():
+            raise CorpusIndexError("CORPUS_LAYER_INVALID", f"Use --layer NAME=DIRECTORY with an existing directory: {item}")
+        layers[name] = path
+    if not layers:
+        raise CorpusIndexError("CORPUS_LAYERS_EMPTY", "No layer directory with JARs was found")
+    return layers
+
+
+def _protected_roots() -> list[Path]:
+    """The skill package and, when present, the git checkout that contains this script."""
+    here = Path(__file__).resolve()
+    roots = [here.parents[2]]  # the app-build skill package, which tested agents can read
+    for parent in here.parents:
+        if (parent / ".git").exists():
+            roots.append(parent)
+            break
+    return roots
+
+
+def _workspace(path: str) -> Path:
+    workspace = Path(path).expanduser().resolve()
+    for root in _protected_roots():
+        if workspace == root or root in workspace.parents:
+            raise CorpusIndexError("CORPUS_WORKSPACE_INSIDE_REPOSITORY",
+                                   f"The corpus workspace must be outside {root}: {workspace}")
+    workspace.mkdir(parents=True, exist_ok=True)
+    return workspace
+
+
+def _connect(db_path: Path) -> tuple[sqlite3.Connection, bool]:
+    fresh = not db_path.exists()
+    db = sqlite3.connect(str(db_path))
+    db.execute("PRAGMA journal_mode=WAL")
+    db.execute("PRAGMA synchronous=NORMAL")
+    db.executescript(_TABLES)
+    version = db.execute("SELECT value FROM meta WHERE key='schemaVersion'").fetchone()
+    if version and int(version[0]) != SCHEMA_VERSION:
+        db.close()
+        raise CorpusIndexError("CORPUS_SCHEMA_MISMATCH",
+                          f"{db_path} uses schema {version[0]}; move it aside to rebuild with schema {SCHEMA_VERSION}")
+    db.execute("INSERT OR REPLACE INTO meta(key, value) VALUES ('schemaVersion', ?)", (str(SCHEMA_VERSION),))
+    if not fresh:
+        db.executescript(_INDEXES)
+    return db, fresh
+
+
+def _delete_jar_rows(db: sqlite3.Connection, jar_id: int) -> None:
+    for table in ("refs", "members", "interfaces"):
+        db.execute(f"DELETE FROM {table} WHERE class_id IN (SELECT id FROM classes WHERE jar_id=?)", (jar_id,))
+    db.execute("DELETE FROM classes WHERE jar_id=?", (jar_id,))
+    db.execute("DELETE FROM errors WHERE jar_id=?", (jar_id,))
+
+
+def _store_result(db: sqlite3.Connection, strings: _Strings, next_class: list[int], layer: str, stat: os.stat_result,
+                  existing: dict | None, result: dict) -> str:
+    now = time.strftime("%Y-%m-%dT%H:%M:%S%z")
+    if result.get("unchanged"):
+        db.execute("UPDATE jars SET size=?, mtime_ns=? WHERE id=?", (stat.st_size, stat.st_mtime_ns, existing["id"]))
+        return "unchanged"
+    if existing:
+        _delete_jar_rows(db, existing["id"])
+        jar_id = existing["id"]
+    else:
+        jar_id = db.execute("SELECT COALESCE(MAX(id), 0) + 1 FROM jars").fetchone()[0]
+    classes = result.get("classes") or []
+    errors = result.get("errors") or []
+    if "unreadable" in result:
+        errors = [(None, result["unreadable"])]
+    row = (jar_id, result["path"], layer, stat.st_size, stat.st_mtime_ns, result["sha256"],
+           result.get("implementationVersion"), result.get("bundleVersion"), len(classes), len(errors),
+           result.get("skipped", 0), 1 if result.get("refsIndexed") else 0,
+           "unreadable" if "unreadable" in result else "indexed", now)
+    db.execute("INSERT OR REPLACE INTO jars(id, path, layer, size, mtime_ns, sha256, implementation_version, "
+               "bundle_version, class_count, error_count, skipped_count, refs_indexed, status, indexed_at) "
+               "VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)", row)
+    class_rows, interface_rows, member_rows, ref_rows = [], [], [], []
+    for parsed in classes:
+        class_id = next_class[0]
+        next_class[0] += 1
+        member_refs = parsed["memberRefs"]
+        java_refs = None
+        if member_refs is not None:
+            java_refs = 0
+            for kind, owner, name, descriptor in member_refs:
+                if owner.startswith(JAVA_PREFIX):
+                    java_refs += 1
+                    continue
+                ref_rows.append((class_id, kind, strings.id(owner), strings.id(name), strings.id(descriptor)))
+            ref_rows.extend((class_id, "C", strings.id(name), None, None)
+                            for name in parsed["classRefs"] if not name.startswith(JAVA_PREFIX))
+            ref_rows.extend((class_id, "S", strings.id(name), None, None) for name in parsed["dynamicClassNames"])
+        class_rows.append((class_id, jar_id, strings.id(parsed["name"]), strings.id(parsed["super"]),
+                           parsed["access"], parsed["major"], parsed["sha256"],
+                           " ".join(parsed["annotations"]) or None, 1 if parsed["deprecated"] else 0,
+                           parsed["sourceFile"], parsed["entry"], java_refs))
+        interface_rows.extend((class_id, strings.id(name)) for name in parsed["interfaces"])
+        for kind, members in (("F", parsed["fields"]), ("M", parsed["methods"])):
+            member_rows.extend((class_id, kind, strings.id(name), strings.id(descriptor), access,
+                                " ".join(annotations) or None, 1 if deprecated else 0)
+                               for name, descriptor, access, annotations, deprecated in members)
+    strings.flush()
+    db.executemany("INSERT INTO classes VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)", class_rows)
+    db.executemany("INSERT INTO interfaces VALUES (?, ?)", interface_rows)
+    db.executemany("INSERT INTO members VALUES (?, ?, ?, ?, ?, ?, ?)", member_rows)
+    db.executemany("INSERT INTO refs VALUES (?, ?, ?, ?, ?)", ref_rows)
+    db.executemany("INSERT INTO errors VALUES (?, ?, ?)", [(jar_id, entry, message) for entry, message in errors])
+    return "changed" if existing else "new"
+
+
+def summarize(db: sqlite3.Connection) -> dict:
+    layers = {}
+    for layer, jars, classes, errors, unreadable in db.execute(
+            "SELECT layer, COUNT(*), SUM(class_count), SUM(error_count), SUM(status='unreadable') "
+            "FROM jars GROUP BY layer ORDER BY layer"):
+        layers[layer] = {"jars": jars, "classes": classes or 0, "classErrors": errors or 0, "unreadableJars": unreadable or 0}
+    duplicates = {"fqcns": 0, "conflicting": 0, "byLayers": {}, "conflictingExamples": []}
+    for name, copies, hashes, layer_set in db.execute(
+            "SELECT s.value, COUNT(*), COUNT(DISTINCT c.sha256), GROUP_CONCAT(DISTINCT j.layer) "
+            "FROM classes c JOIN jars j ON j.id = c.jar_id JOIN strings s ON s.id = c.name_id "
+            "GROUP BY c.name_id HAVING COUNT(*) > 1"):
+        duplicates["fqcns"] += 1
+        key = "+".join(sorted(layer_set.split(",")))
+        bucket = duplicates["byLayers"].setdefault(key, {"fqcns": 0, "conflicting": 0})
+        bucket["fqcns"] += 1
+        if hashes > 1:
+            duplicates["conflicting"] += 1
+            bucket["conflicting"] += 1
+            if len(duplicates["conflictingExamples"]) < 20:
+                duplicates["conflictingExamples"].append({"class": name, "copies": copies, "distinctHashes": hashes,
+                                                          "layers": sorted(layer_set.split(","))})
+    refs = {kind: count for kind, count in db.execute("SELECT kind, COUNT(*) FROM refs GROUP BY kind")}
+    return {"schemaVersion": SCHEMA_VERSION, "layers": layers, "duplicateClasses": duplicates, "storedRefs": refs}
+
+
+def build(lib_root: str | None, layer_args: list[str], workspace: str, refs_layers: list[str],
+          workers: int | None) -> dict:
+    started = time.monotonic()
+    layers = resolve_layers(lib_root, layer_args)
+    unknown = sorted(set(refs_layers) - set(layers) - {"all"})
+    if unknown:
+        raise CorpusIndexError("CORPUS_REFS_LAYER_UNKNOWN", f"--refs-layer names no indexed layer: {', '.join(unknown)}")
+    with_refs = set(layers) if "all" in refs_layers else set(refs_layers)
+    target = _workspace(workspace)
+    db_path = target / DB_NAME
+    db, fresh = _connect(db_path)
+    try:
+        scanned: dict[str, tuple[str, os.stat_result]] = {}
+        for layer, directory in layers.items():
+            for jar in sorted(directory.glob("*.jar")):
+                scanned[str(jar.resolve())] = (layer, jar.stat())
+        existing = {path: {"id": key, "size": size, "mtime_ns": mtime, "sha256": sha, "refs": refs, "layer": layer}
+                    for key, path, size, mtime, sha, refs, layer in
+                    db.execute("SELECT id, path, size, mtime_ns, sha256, refs_indexed, layer FROM jars")}
+        counts = {"new": 0, "changed": 0, "unchanged": 0, "removed": 0}
+        for path in sorted(set(existing) - set(scanned)):
+            _delete_jar_rows(db, existing[path]["id"])
+            db.execute("DELETE FROM jars WHERE id=?", (existing[path]["id"],))
+            counts["removed"] += 1
+        tasks = []
+        for path, (layer, stat) in scanned.items():
+            known = existing.get(path)
+            needs_refs = layer in with_refs
+            reusable = known and known["layer"] == layer and bool(known["refs"]) == needs_refs
+            if reusable and known["size"] == stat.st_size and known["mtime_ns"] == stat.st_mtime_ns:
+                counts["unchanged"] += 1
+                continue
+            tasks.append((path, known["sha256"] if reusable else None, needs_refs))
+        strings = _Strings(db)
+        next_class = [db.execute("SELECT COALESCE(MAX(id), 0) + 1 FROM classes").fetchone()[0]]
+        pool = ProcessPoolExecutor(max_workers=workers or min(8, os.cpu_count() or 1)) if workers != 0 else None
+        try:
+            results = pool.map(parse_jar, tasks, chunksize=2) if pool else map(parse_jar, tasks)
+            for done, result in enumerate(results, start=1):
+                layer, stat = scanned[result["path"]]
+                outcome = _store_result(db, strings, next_class, layer, stat, existing.get(result["path"]), result)
+                counts[outcome] += 1
+                if done % 200 == 0:
+                    db.commit()
+        finally:
+            if pool:
+                pool.shutdown()
+        if fresh:
+            db.executescript(_INDEXES)
+        meta = {"libRoot": str(Path(lib_root).expanduser().resolve()) if lib_root else None,
+                "layers": json.dumps({name: str(path) for name, path in layers.items()}),
+                "refsLayers": json.dumps(sorted(with_refs)), "updatedAt": time.strftime("%Y-%m-%dT%H:%M:%S%z")}
+        db.executemany("INSERT OR REPLACE INTO meta(key, value) VALUES (?, ?)", list(meta.items()))
+        db.commit()
+        summary = {"status": True, "database": str(db_path), "jars": counts, "refsLayers": sorted(with_refs),
+                   **summarize(db), "elapsedSec": round(time.monotonic() - started, 1)}
+    finally:
+        db.close()
+    (target / SUMMARY_NAME).write_text(json.dumps(summary, ensure_ascii=False, indent=2), encoding="utf-8")
+    return summary
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description=__doc__.split("\n\n")[0])
+    parser.add_argument("--lib-root", help="Library root whose JAR subdirectories become layers")
+    parser.add_argument("--layer", action="append", default=[], help="Extra or overriding layer as NAME=DIRECTORY")
+    parser.add_argument("--workspace", required=True, help="Corpus workspace outside the repository")
+    parser.add_argument("--refs-layer", action="append", help="Layer whose references are stored; 'all' for every layer")
+    parser.add_argument("--workers", type=int, help="Parser processes (default: min(8, CPU count); 0 parses in-process)")
+    args = parser.parse_args(argv)
+    try:
+        summary = build(args.lib_root, args.layer, args.workspace, args.refs_layer or list(DEFAULT_REFS_LAYERS),
+                        args.workers)
+    except CorpusIndexError as exc:
+        print(json.dumps({"status": False, "errorCode": exc.code, "message": str(exc)}, ensure_ascii=False))
+        return 2
+    print(json.dumps(summary, ensure_ascii=False, indent=2))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/skills/cosmic-build/scripts/plugin_corpus/jvm_classfile.py

@@ -0,0 +1,281 @@
+"""Read the structure of a JVM class file for the plugin corpus index.
+
+The corpus holds roughly 670k classes, so running javap per class is far too slow; this module
+reads the class file format directly with no JDK. It keeps what the index needs: the class's
+names and hierarchy, declared members, annotation types, and the members, classes and
+dynamic class names it refers to.
+
+Method bodies are not decoded. A member reference is read from the constant pool, so it means
+"this class names that member somewhere" (a call, a field access or a method handle) rather
+than a count of call sites. The owner of a reference is the static receiver type the compiler
+wrote at the use site; resolving it to the declaring class needs the whole hierarchy and is
+the index consumer's job.
+
+Names are returned in binary form with dots: ``kd.bos.algo.DataSet$Listener``.
+"""
+
+from __future__ import annotations
+
+import re
+import struct
+
+_U2 = struct.Struct(">H")
+_U2U2 = struct.Struct(">HH")
+_HEAD = struct.Struct(">HHH")
+_MEMBER = struct.Struct(">HHHH")
+_ATTRIBUTE = struct.Struct(">HI")
+
+_ANNOTATION_ATTRIBUTES = ("RuntimeVisibleAnnotations", "RuntimeInvisibleAnnotations")
+_REF_KINDS = {9: "F", 10: "M", 11: "I"}
+# A string constant that names a platform or business class, e.g. for reflection or a plugin
+# registered by class name. Package-only strings and ordinary field keys do not match.
+_DYNAMIC_CLASS_RE = re.compile(r"^kd(?:\.[a-z_][\w]*)+\.[A-Z][\w$]*$")
+_PRIMITIVES = {"B": "byte", "C": "char", "D": "double", "F": "float", "I": "int", "J": "long",
+               "S": "short", "Z": "boolean", "V": "void"}
+
+ACC_INTERFACE = 0x0200
+ACC_ABSTRACT = 0x0400
+ACC_ANNOTATION = 0x2000
+
+
+class ClassFormatError(ValueError):
+    """The bytes are not a class file this reader can parse."""
+
+
+def _utf8(raw: bytes) -> str:
+    try:
+        return raw.decode("utf-8")
+    except UnicodeDecodeError:
+        # Modified UTF-8 writes NUL as C0 80 and supplementary characters as surrogate pairs.
+        try:
+            return raw.replace(b"\xc0\x80", b"\x00").decode("utf-8", "surrogatepass")
+        except UnicodeDecodeError:
+            return raw.decode("utf-8", "replace")
+
+
+def _skip_element_value(data: bytes, pos: int) -> int:
+    tag = data[pos]
+    pos += 1
+    if tag in b"BCDFIJSZsc":
+        return pos + 2
+    if tag == 0x65:  # 'e': enum type and constant name
+        return pos + 4
+    if tag == 0x40:  # '@': nested annotation
+        return _skip_annotation_body(data, pos + 2)
+    if tag == 0x5B:  # '[': array of element values
+        count = _U2.unpack_from(data, pos)[0]
+        pos += 2
+        for _ in range(count):
+            pos = _skip_element_value(data, pos)
+        return pos
+    raise ClassFormatError(f"unknown annotation element tag {tag}")
+
+
+def _skip_annotation_body(data: bytes, pos: int) -> int:
+    """Skip the element pairs of an annotation whose type index was already read."""
+    pairs = _U2.unpack_from(data, pos)[0]
+    pos += 2
+    for _ in range(pairs):
+        pos = _skip_element_value(data, pos + 2)
+    return pos
+
+
+def _annotation_types(data: bytes, pos: int, values: list) -> list[str]:
+    count = _U2.unpack_from(data, pos)[0]
+    pos += 2
+    names = []
+    for _ in range(count):
+        descriptor = values[_U2.unpack_from(data, pos)[0]]
+        if isinstance(descriptor, str) and descriptor.startswith("L") and descriptor.endswith(";"):
+            names.append(descriptor[1:-1].replace("/", "."))
+        pos = _skip_annotation_body(data, pos + 2)
+    return names
+
+
+def descriptor_types(descriptor: str) -> tuple[list[str], str]:
+    """Split a method or field descriptor into parameter types and a return type.
+
+    Types use Java notation with dots and keep ``$`` for nested classes:
+    ``(Ljava/lang/String;[I)V`` -> (["java.lang.String", "int[]"], "void"). A field descriptor
+    has no parameters and its type is returned as the "return" type.
+    """
+    def read(pos: int) -> tuple[str, int]:
+        dims = 0
+        while descriptor[pos] == "[":
+            dims += 1
+            pos += 1
+        code = descriptor[pos]
+        if code == "L":
+            end = descriptor.index(";", pos)
+            name = descriptor[pos + 1:end].replace("/", ".")
+            pos = end + 1
+        elif code in _PRIMITIVES:
+            name = _PRIMITIVES[code]
+            pos += 1
+        else:
+            raise ClassFormatError(f"bad descriptor {descriptor!r}")
+        return name + "[]" * dims, pos
+
+    try:
+        if not descriptor.startswith("("):
+            return [], read(0)[0]
+        params = []
+        pos = 1
+        while descriptor[pos] != ")":
+            name, pos = read(pos)
+            params.append(name)
+        return params, read(pos + 1)[0]
+    except (IndexError, ValueError) as exc:
+        raise ClassFormatError(f"bad descriptor {descriptor!r}") from exc
+
+
+def simple_type(java_type: str) -> str:
+    """``kd.bos.algo.DataSet$Listener[]`` -> ``Listener[]``, as API pages write parameter types."""
+    array = ""
+    while java_type.endswith("[]"):
+        array += "[]"
+        java_type = java_type[:-2]
+    return java_type.rsplit(".", 1)[-1].rsplit("$", 1)[-1] + array
+
+
+def parse_class(data: bytes) -> dict:
+    """Parse one class file. Raises ClassFormatError for anything it cannot read."""
+    if len(data) < 10 or data[:4] != b"\xca\xfe\xba\xbe":
+        raise ClassFormatError("missing class file magic")
+    try:
+        return _parse(data)
+    except (struct.error, IndexError, KeyError, TypeError, AttributeError) as exc:
+        raise ClassFormatError(f"truncated or inconsistent class file: {exc}") from exc
+
+
+def _parse(data: bytes) -> dict:
+    major = _U2.unpack_from(data, 6)[0]
+    count = _U2.unpack_from(data, 8)[0]
+    tags = [0] * count
+    values: list = [None] * count
+    pos = 10
+    index = 1
+    while index < count:
+        tag = data[pos]
+        if tag == 1:
+            length = _U2.unpack_from(data, pos + 1)[0]
+            values[index] = _utf8(data[pos + 3:pos + 3 + length])
+            pos += 3 + length
+        elif tag in (7, 8, 16, 19, 20):
+            values[index] = _U2.unpack_from(data, pos + 1)[0]
+            pos += 3
+        elif tag in (9, 10, 11, 12, 17, 18):
+            values[index] = _U2U2.unpack_from(data, pos + 1)
+            pos += 5
+        elif tag in (3, 4):
+            pos += 5
+        elif tag in (5, 6):
+            # Long and double constants take two pool slots.
+            tags[index] = tag
+            index += 2
+            pos += 9
+            continue
+        elif tag == 15:
+            values[index] = (data[pos + 1], _U2.unpack_from(data, pos + 2)[0])
+            pos += 4
+        else:
+            raise ClassFormatError(f"unknown constant pool tag {tag}")
+        tags[index] = tag
+        index += 1
+
+    def class_name(class_index: int) -> str:
+        return values[values[class_index]].replace("/", ".")
+
+    access, this_index, super_index = _HEAD.unpack_from(data, pos)
+    pos += 6
+    name = class_name(this_index)
+    super_name = class_name(super_index) if super_index else None
+    interface_count = _U2.unpack_from(data, pos)[0]
+    pos += 2
+    interfaces = [class_name(_U2.unpack_from(data, pos + 2 * i)[0]) for i in range(interface_count)]
+    pos += 2 * interface_count
+
+    def read_members(pos: int) -> tuple[list[tuple], int]:
+        member_count = _U2.unpack_from(data, pos)[0]
+        pos += 2
+        members = []
+        for _ in range(member_count):
+            member_access, name_index, descriptor_index, attribute_count = _MEMBER.unpack_from(data, pos)
+            pos += 8
+            annotations: list[str] = []
+            deprecated = False
+            for _ in range(attribute_count):
+                attribute_index, length = _ATTRIBUTE.unpack_from(data, pos)
+                pos += 6
+                attribute = values[attribute_index]
+                if attribute in _ANNOTATION_ATTRIBUTES:
+                    annotations.extend(_annotation_types(data, pos, values))
+                elif attribute == "Deprecated":
+                    deprecated = True
+                pos += length
+            members.append((values[name_index], values[descriptor_index], member_access,
+                            tuple(annotations), deprecated or "java.lang.Deprecated" in annotations))
+        return members, pos
+
+    fields, pos = read_members(pos)
+    methods, pos = read_members(pos)
+
+    annotations: list[str] = []
+    deprecated = False
+    source_file = None
+    attribute_count = _U2.unpack_from(data, pos)[0]
+    pos += 2
+    for _ in range(attribute_count):
+        attribute_index, length = _ATTRIBUTE.unpack_from(data, pos)
+        pos += 6
+        attribute = values[attribute_index]
+        if attribute in _ANNOTATION_ATTRIBUTES:
+            annotations.extend(_annotation_types(data, pos, values))
+        elif attribute == "Deprecated":
+            deprecated = True
+        elif attribute == "SourceFile":
+            source_file = values[_U2.unpack_from(data, pos)[0]]
+        pos += length
+
+    member_refs = set()
+    class_refs = set()
+    dynamic_classes = set()
+    for index in range(1, count):
+        tag = tags[index]
+        if tag in _REF_KINDS:
+            class_index, nat_index = values[index]
+            owner = values[values[class_index]]
+            if owner.startswith("["):
+                continue  # clone() and friends on an array type
+            name_index, descriptor_index = values[nat_index]
+            member_refs.add((_REF_KINDS[tag], owner.replace("/", "."), values[name_index], values[descriptor_index]))
+        elif tag == 7:
+            referenced = values[values[index]]
+            if referenced.startswith("["):
+                element = referenced.lstrip("[")
+                if not (element.startswith("L") and element.endswith(";")):
+                    continue
+                referenced = element[1:-1]
+            referenced = referenced.replace("/", ".")
+            if referenced != name:
+                class_refs.add(referenced)
+        elif tag == 8:
+            text = values[values[index]]
+            if _DYNAMIC_CLASS_RE.match(text):
+                dynamic_classes.add(text)
+
+    return {
+        "name": name,
+        "major": major,
+        "access": access,
+        "super": super_name,
+        "interfaces": interfaces,
+        "annotations": annotations,
+        "deprecated": deprecated or "java.lang.Deprecated" in annotations,
+        "sourceFile": source_file,
+        "fields": fields,
+        "methods": methods,
+        "memberRefs": sorted(member_refs),
+        "classRefs": sorted(class_refs),
+        "dynamicClassNames": sorted(dynamic_classes),
+    }