loomweave-plugin-python 1.0.0__py3-none-any.whl

loomweave_plugin_python/qualname.py

@@ -0,0 +1,48 @@
+"""L7 qualname reconstruction matching Python's ``__qualname__`` semantics.
+
+Python's ``__qualname__`` is only bound at runtime, after the function or
+class definition has been executed; Loomweave's static analyser has to
+reconstruct the same string from the AST and the chain of parent scopes.
+
+Rules (CPython language reference, "``__qualname__``"):
+
+- Module-level function/class: qualname == name.
+- Class-nested (class body contains a function/class): qualname prepends
+  the enclosing class names joined by ``.`` with no separator marker.
+- Function-nested (function body contains a function/class): qualname
+  prepends ``parent.<locals>.`` — the ``<locals>`` marker distinguishes a
+  closure from a method.
+
+The L7 lock-in (``wp3-python-plugin.md §L7``) is that Loomweave reconstructs
+the same bare Python ``__qualname__`` semantics that Wardline stores in its
+``FingerprintEntry.qualified_name`` field. Loomweave entity names prepend the
+dotted module path elsewhere; ADR-018 requires cross-product joins to translate
+between those shapes instead of comparing strings directly.
+
+Sprint 1 covers ``FunctionDef`` and ``AsyncFunctionDef`` as emitted
+entities; ``ClassDef`` is recognised as a parent scope only (class
+entities are WP3-feature-complete scope).
+"""
+
+from __future__ import annotations
+
+import ast
+
+Scope = ast.FunctionDef | ast.AsyncFunctionDef | ast.ClassDef
+
+
+def reconstruct_qualname(node: Scope, parents: list[ast.AST]) -> str:
+    """Return Python's ``__qualname__`` for ``node`` given its AST parent chain.
+
+    ``parents`` is ordered from outermost (typically the ``ast.Module``) to
+    the immediate parent. Non-scope ancestors (e.g. ``Module``,
+    ``ast.If`` bodies, ``ast.With`` bodies) are skipped — they do not
+    contribute to ``__qualname__``.
+    """
+    name = node.name
+    for ancestor in reversed(parents):
+        if isinstance(ancestor, (ast.FunctionDef, ast.AsyncFunctionDef)):
+            name = f"{ancestor.name}.<locals>.{name}"
+        elif isinstance(ancestor, ast.ClassDef):
+            name = f"{ancestor.name}.{name}"
+    return name

loomweave_plugin_python/reference_resolver.py

@@ -0,0 +1,70 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Literal, NotRequired, Protocol, TypedDict
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+    from pathlib import Path
+
+    from loomweave_plugin_python.call_resolver import Finding
+
+
+ReferenceSiteKind = Literal["name", "annotation"]
+
+
+@dataclass(frozen=True)
+class ReferenceSite:
+    from_id: str
+    line: int
+    character: int
+    end_line: int
+    end_character: int
+    source_byte_start: int
+    source_byte_end: int
+    kind: ReferenceSiteKind
+
+
+class ReferencesEdgeProperties(TypedDict):
+    candidates: list[str]
+
+
+class ReferencesRawEdge(TypedDict):
+    kind: Literal["references"]
+    from_id: str
+    to_id: str
+    source_byte_start: int
+    source_byte_end: int
+    confidence: Literal["resolved", "ambiguous"]
+    properties: NotRequired[ReferencesEdgeProperties]
+
+
+@dataclass
+class ReferenceResolutionResult:
+    edges: list[ReferencesRawEdge] = field(default_factory=list)
+    reference_sites_total: int = 0
+    references_resolved_total: int = 0
+    references_skipped_external_total: int = 0
+    references_skipped_cap_total: int = 0
+    unresolved_reference_sites_total: int = 0
+    pyright_query_latency_ms: list[int] = field(default_factory=list)
+    pyright_index_parse_latency_ms: list[int] = field(default_factory=list)
+    findings: list[Finding] = field(default_factory=list)
+
+
+class ReferenceResolver(Protocol):
+    def resolve_references(
+        self,
+        file_path: str | Path,
+        sites: Sequence[ReferenceSite],
+    ) -> ReferenceResolutionResult: ...
+
+
+class NoOpReferenceResolver:
+    def resolve_references(
+        self,
+        file_path: str | Path,
+        sites: Sequence[ReferenceSite],
+    ) -> ReferenceResolutionResult:
+        _ = (file_path, sites)
+        return ReferenceResolutionResult()

loomweave_plugin_python/server.py

@@ -0,0 +1,310 @@
+"""WP2 L4 JSON-RPC server speaking Content-Length framing.
+
+Implements the five L4 methods — ``initialize``, ``initialized``,
+``analyze_file``, ``shutdown``, ``exit`` — exactly matching the Rust host's
+typed request/response contracts in ``crates/loomweave-core/src/plugin/protocol.rs``.
+
+Response shapes (required by the Rust host's typed deserialise path):
+
+- ``initialize`` → ``{name, version, ontology_version, capabilities}``
+  (``InitializeResult``; WP2 scrub commit ``1ac32b1`` validates
+  ``ontology_version`` is non-empty).
+- ``analyze_file`` → ``{entities: [...]}`` (``AnalyzeFileResult``).
+- ``shutdown`` → ``{}`` (empty ``ShutdownResult`` struct — *not* ``null``).
+- ``initialized`` / ``exit`` — notifications, no response.
+
+Task 2 shipped the dispatch skeleton with ``analyze_file`` returning an empty
+entity list. The current plugin advertises its Wardline descriptor state during
+``initialize`` and emits Wardline-derived semantic signals when a compatible
+descriptor is available.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import IO, Any
+
+from loomweave_plugin_python import __version__
+from loomweave_plugin_python.extractor import extract_with_stats
+from loomweave_plugin_python.pyright_session import PyrightRunState, PyrightSession
+from loomweave_plugin_python.stdout_guard import install_stdio
+from loomweave_plugin_python.wardline_descriptor import WardlineVocabulary, load_wardline_descriptor
+
+ONTOLOGY_VERSION = "0.7.0"
+
+# Plugin-side Content-Length sanity cap. Matches the host's ADR-021 §2b
+# default (8 MiB) so the plugin never emits a frame the host would kill us
+# for. Oversize outbound payloads trip this before reaching the wire.
+MAX_CONTENT_LENGTH = 8 * 1024 * 1024
+MAX_FILES_PER_PYRIGHT_SESSION = 25
+
+# JSON-RPC 2.0 error codes (§5.1) plus LSP-style server extensions.
+_ERR_INVALID_REQUEST = -32600
+_ERR_METHOD_NOT_FOUND = -32601
+_ERR_INTERNAL = -32603
+_ERR_NOT_INITIALIZED = -32002
+
+
+class ProtocolError(RuntimeError):
+    """Unrecoverable framing or envelope error; the server loop exits."""
+
+
+@dataclass
+class ServerState:
+    """Handshake + shutdown + project-root state across the dispatch loop."""
+
+    initialized: bool = False
+    shutdown_requested: bool = False
+    project_root: Path | None = field(default=None)
+    pyright: PyrightSession | None = field(default=None)
+    pyright_files_since_restart: int = 0
+    pyright_run_state: PyrightRunState = field(default_factory=PyrightRunState)
+    wardline_vocabulary: WardlineVocabulary | None = field(default=None)
+
+
+def read_frame(stream: IO[bytes]) -> dict[str, Any] | None:
+    """Read one Content-Length-framed JSON object. Returns ``None`` on EOF."""
+    headers: dict[str, str] = {}
+    while True:
+        line = stream.readline()
+        if not line:
+            return None
+        if line in (b"\r\n", b"\n"):
+            break
+        try:
+            decoded = line.decode("ascii").rstrip("\r\n")
+        except UnicodeDecodeError as exc:
+            msg = "malformed non-ASCII header line"
+            raise ProtocolError(msg) from exc
+        if ":" not in decoded:
+            msg = f"malformed header line: {decoded!r}"
+            raise ProtocolError(msg)
+        name, value = decoded.split(":", 1)
+        headers[name.strip().lower()] = value.strip()
+
+    raw_length = headers.get("content-length")
+    if raw_length is None:
+        msg = "missing Content-Length header"
+        raise ProtocolError(msg)
+    try:
+        length = int(raw_length)
+    except ValueError as exc:
+        msg = f"Content-Length not an integer: {raw_length!r}"
+        raise ProtocolError(msg) from exc
+    if length < 0 or length > MAX_CONTENT_LENGTH:
+        msg = f"Content-Length out of range: {length}"
+        raise ProtocolError(msg)
+
+    body = stream.read(length)
+    if len(body) != length:
+        msg = f"short read: expected {length} bytes, got {len(body)}"
+        raise ProtocolError(msg)
+
+    try:
+        parsed = json.loads(body)
+    except json.JSONDecodeError as exc:
+        msg = f"invalid JSON body: {exc}"
+        raise ProtocolError(msg) from exc
+
+    if not isinstance(parsed, dict):
+        msg = f"expected JSON object at frame root, got {type(parsed).__name__}"
+        raise ProtocolError(msg)
+    return parsed
+
+
+def write_frame(stream: IO[bytes], payload: dict[str, Any]) -> None:
+    """Serialise ``payload`` as one Content-Length-framed JSON frame."""
+    body = json.dumps(payload, separators=(",", ":"), ensure_ascii=False).encode("utf-8")
+    if len(body) > MAX_CONTENT_LENGTH:
+        msg = f"outbound frame exceeds MAX_CONTENT_LENGTH ({len(body)} > {MAX_CONTENT_LENGTH})"
+        raise ProtocolError(msg)
+    header = f"Content-Length: {len(body)}\r\n\r\n".encode("ascii")
+    stream.write(header)
+    stream.write(body)
+    stream.flush()
+
+
+def _success(request_id: Any, result: Any) -> dict[str, Any]:
+    return {"jsonrpc": "2.0", "id": request_id, "result": result}
+
+
+def _error(request_id: Any, code: int, message: str) -> dict[str, Any]:
+    return {
+        "jsonrpc": "2.0",
+        "id": request_id,
+        "error": {"code": code, "message": message},
+    }
+
+
+def handle_initialize(params: dict[str, Any], state: ServerState) -> dict[str, Any]:
+    """Return the plugin's identity + capabilities; capture ``project_root``."""
+    root_raw = params.get("project_root")
+    if isinstance(root_raw, str) and root_raw:
+        state.project_root = Path(root_raw).resolve()
+    wardline = load_wardline_descriptor(state.project_root)
+    state.wardline_vocabulary = wardline.vocabulary
+    if wardline.status == "absent":
+        sys.stderr.write(
+            "loomweave-plugin-python: Wardline vocabulary descriptor unavailable; "
+            "continuing without Wardline annotation metadata\n",
+        )
+    return {
+        "name": "loomweave-plugin-python",
+        "version": __version__,
+        "ontology_version": ONTOLOGY_VERSION,
+        "capabilities": {"wardline": wardline.as_capability()},
+    }
+
+
+def _resolve_module_path(file_path_raw: str, state: ServerState) -> str:
+    """Compute the entity ``module_path`` relative to ``project_root``.
+
+    The host sends absolute paths (see ``crates/loomweave-cli/src/analyze.rs``
+    — ``project_root`` is canonicalised and file entries are built by
+    ``entry.path()`` joins). To produce the expected L7 qualified names
+    (``pkg.module.func`` rather than ``tmp.xyz.demo.func``), the plugin
+    relativises each incoming path against the ``project_root`` captured
+    at ``initialize``.
+    """
+    path = Path(file_path_raw)
+    if state.project_root is not None and path.is_absolute():
+        try:
+            return str(path.resolve().relative_to(state.project_root))
+        except ValueError:
+            # Outside project_root — host's jail should have caught this.
+            # Fall back to the raw path so the host's logs show the drift.
+            return file_path_raw
+    return file_path_raw
+
+
+def handle_analyze_file(params: dict[str, Any], state: ServerState) -> dict[str, Any]:
+    """Read the requested file, extract entities + edges, return AnalyzeFileResult shape."""
+    empty_stats = {
+        "unresolved_call_sites_total": 0,
+        "unresolved_call_sites": [],
+        "reference_sites_total": 0,
+        "references_resolved_total": 0,
+        "references_skipped_external_total": 0,
+        "references_skipped_cap_total": 0,
+        "unresolved_reference_sites_total": 0,
+        "pyright_query_latency_ms": [],
+        "pyright_index_parse_latency_ms": [],
+        "extractor_parse_latency_ms": 0,
+    }
+    file_path_raw = params.get("file_path")
+    if not isinstance(file_path_raw, str):
+        return {"entities": [], "edges": [], "stats": empty_stats}
+    path = Path(file_path_raw)
+    if state.pyright is None:
+        state.pyright = PyrightSession(
+            state.project_root or path.parent,
+            run_state=state.pyright_run_state,
+        )
+    try:
+        source = path.read_text(encoding="utf-8")
+    except (OSError, UnicodeDecodeError) as exc:
+        sys.stderr.write(f"loomweave-plugin-python: cannot read {file_path_raw}: {exc}\n")
+        return {"entities": [], "edges": [], "stats": empty_stats}
+    # Emit source.file_path exactly as received so the host's jail check
+    # (which canonicalises against project_root) sees the original path.
+    # Derive qualified-name dotting from the project-relative form.
+    module_prefix = _resolve_module_path(file_path_raw, state)
+    result = extract_with_stats(
+        source,
+        file_path_raw,
+        module_prefix_path=module_prefix,
+        call_resolver=state.pyright,
+        reference_resolver=state.pyright,
+        wardline_vocabulary=state.wardline_vocabulary,
+    )
+    state.pyright_files_since_restart += 1
+    if state.pyright_files_since_restart >= MAX_FILES_PER_PYRIGHT_SESSION:
+        state.pyright.close()
+        state.pyright = None
+        state.pyright_files_since_restart = 0
+    stats = {
+        "unresolved_call_sites_total": result.stats.unresolved_call_sites_total,
+        "unresolved_call_sites": result.stats.unresolved_call_sites,
+        "reference_sites_total": result.stats.reference_sites_total,
+        "references_resolved_total": result.stats.references_resolved_total,
+        "references_skipped_external_total": result.stats.references_skipped_external_total,
+        "references_skipped_cap_total": result.stats.references_skipped_cap_total,
+        "unresolved_reference_sites_total": result.stats.unresolved_reference_sites_total,
+        "pyright_query_latency_ms": result.stats.pyright_query_latency_ms,
+        "pyright_index_parse_latency_ms": result.stats.pyright_index_parse_latency_ms,
+        "extractor_parse_latency_ms": result.stats.extractor_parse_latency_ms,
+    }
+    return {
+        "entities": result.entities,
+        "edges": result.edges,
+        "stats": stats,
+        "findings": result.stats.findings,
+    }
+
+
+Handler = Callable[[dict[str, Any], ServerState], dict[str, Any]]
+
+_HANDLERS: dict[str, Handler] = {
+    "initialize": handle_initialize,
+    "analyze_file": handle_analyze_file,
+}
+
+
+def dispatch(frame: dict[str, Any], state: ServerState) -> dict[str, Any] | None:
+    """Process one frame; return the response envelope to send, or ``None``."""
+    method = frame.get("method")
+    params_raw = frame.get("params")
+    params: dict[str, Any] = params_raw if isinstance(params_raw, dict) else {}
+    request_id = frame.get("id")
+
+    if method == "initialized":
+        state.initialized = True
+        return None
+    if method == "exit":
+        return None
+    if method == "shutdown":
+        state.shutdown_requested = True
+        if state.pyright is not None:
+            state.pyright.close()
+            state.pyright = None
+        return _success(request_id, {})
+    if not isinstance(method, str):
+        return _error(request_id, _ERR_INVALID_REQUEST, f"invalid method: {method!r}")
+    if method == "analyze_file" and not state.initialized:
+        return _error(request_id, _ERR_NOT_INITIALIZED, "analyze_file before initialized")
+    handler = _HANDLERS.get(method)
+    if handler is None:
+        return _error(request_id, _ERR_METHOD_NOT_FOUND, f"method not found: {method}")
+    try:
+        result = handler(params, state)
+    except Exception as exc:  # noqa: BLE001 - dispatch boundary: any handler bug becomes a response
+        return _error(request_id, _ERR_INTERNAL, f"handler failed: {exc}")
+    return _success(request_id, result)
+
+
+def serve(stdin: IO[bytes], stdout: IO[bytes]) -> int:
+    """Run the dispatch loop until EOF or ``exit`` notification."""
+    state = ServerState()
+    while True:
+        frame = read_frame(stdin)
+        if frame is None:
+            return 0
+        method = frame.get("method")
+        response = dispatch(frame, state)
+        if response is not None:
+            write_frame(stdout, response)
+        if method == "exit":
+            return 0 if state.shutdown_requested else 1
+
+
+def main() -> int:
+    """Install stdout discipline, run the server loop, translate errors to exit codes."""
+    stdin, stdout = install_stdio()
+    try:
+        return serve(stdin, stdout)
+    except ProtocolError:
+        return 1

loomweave_plugin_python/stdout_guard.py

@@ -0,0 +1,62 @@
+"""Stdout discipline for JSON-RPC plugins (WP2 UQ-WP2-08 plugin-side resolution).
+
+The Loomweave plugin protocol reserves ``stdout`` for Content-Length-framed
+JSON-RPC frames. A stray ``print()`` or library-emitted message on stdout
+would corrupt the framing parser on the host side and trip either the
+Content-Length ceiling or the JSON decoder.
+
+``install_stdio()`` captures the real ``stdin``/``stdout`` byte streams,
+replaces ``sys.stdout`` with a guard that raises ``StdoutGuardError`` on
+any write, and returns the captured ``(stdin, stdout)`` pair for the
+server to use. Callers must invoke this exactly once, before reading or
+writing any framed data.
+"""
+
+from __future__ import annotations
+
+import sys
+from typing import IO
+
+
+class StdoutGuardError(RuntimeError):
+    """Raised when Python code writes to the guarded stdout after ``install_stdio``."""
+
+
+class _GuardedTextStdout:
+    """``sys.stdout`` replacement that refuses every write.
+
+    Only implements the attributes and methods CPython routinely looks up
+    on ``sys.stdout`` — enough to surface the guard error clearly instead of
+    failing with ``AttributeError`` first.
+    """
+
+    encoding = "utf-8"
+    errors = "strict"
+
+    def write(self, _data: str) -> int:
+        msg = (
+            "plugin stdout is reserved for JSON-RPC framing; "
+            "write to sys.stderr for diagnostics or raise an exception"
+        )
+        raise StdoutGuardError(msg)
+
+    def writelines(self, _lines: object) -> None:
+        self.write("")
+
+    def flush(self) -> None:
+        return
+
+    def isatty(self) -> bool:
+        return False
+
+    def fileno(self) -> int:
+        msg = "guarded stdout has no fileno"
+        raise StdoutGuardError(msg)
+
+
+def install_stdio() -> tuple[IO[bytes], IO[bytes]]:
+    """Reserve stdout for JSON-RPC; return the real ``(stdin, stdout)`` byte streams."""
+    real_stdin = sys.stdin.buffer
+    real_stdout = sys.stdout.buffer
+    sys.stdout = _GuardedTextStdout()
+    return real_stdin, real_stdout

loomweave_plugin_python/wardline_descriptor.py

@@ -0,0 +1,197 @@
+"""Wardline NG-25 vocabulary descriptor reader.
+
+This module deliberately reads descriptor files without importing Wardline.
+Wardline remains authoritative for the vocabulary; Loomweave records only the
+source-observed decorator facts it can derive from that descriptor.
+
+Two contract details below (``PROJECT_DESCRIPTOR_PATH`` and the descriptor
+``version`` semantics) are Loomweave-side assumptions pending Wardline's
+"Pre-Rust core hardening" Task B, which has not yet published the canonical
+project-local descriptor location or the ``schema: wardline.vocabulary/v1``
+format-version field. The parser ignores unknown top-level keys, so a future
+``schema`` field is tolerated without change; acting on it (format-version
+compatibility decisions) is deferred until Task B pins the contract. Confirm
+both assumptions against the Wardline descriptor ADR when it lands
+(tracked: filigree clarion-6ab5668d82).
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from importlib import metadata
+from pathlib import Path
+from typing import Any, Literal, cast
+
+import yaml
+
+# PO-confirm against Wardline Task B (descriptor ADR) — canonical project-local
+# location and descriptor-version semantics are not yet pinned by Wardline.
+# Tracked: filigree clarion-6ab5668d82.
+EXPECTED_DESCRIPTOR_VERSION = "wardline-generic-2"
+PROJECT_DESCRIPTOR_PATH = Path(".wardline/vocabulary.yaml")
+
+DescriptorSource = Literal["project", "package"]
+DescriptorStatus = Literal["enabled", "version_skew", "absent"]
+
+
+@dataclass(frozen=True)
+class DescriptorEntry:
+    canonical_name: str
+    group: int
+    attrs: dict[str, str]
+
+
+@dataclass(frozen=True)
+class WardlineVocabulary:
+    version: str
+    source: DescriptorSource
+    confidence_basis: Literal["descriptor", "descriptor_version_skew"]
+    entries_by_name: dict[str, DescriptorEntry]
+
+    def entry_for_decorator(self, qualified_name: str) -> DescriptorEntry | None:
+        return self.entries_by_name.get(qualified_name.rsplit(".", 1)[-1])
+
+
+@dataclass(frozen=True)
+class WardlineDescriptorState:
+    status: DescriptorStatus
+    expected_version: str = EXPECTED_DESCRIPTOR_VERSION
+    descriptor_version: str | None = None
+    source: DescriptorSource | None = None
+    reason: str | None = None
+    vocabulary: WardlineVocabulary | None = None
+
+    def as_capability(self) -> dict[str, str]:
+        if self.status == "absent":
+            capability = {"status": "absent"}
+            if self.reason:
+                capability["reason"] = self.reason
+            return capability
+        capability = {
+            "status": self.status,
+            "descriptor_version": self.descriptor_version or "",
+            "source": self.source or "",
+        }
+        if self.status == "version_skew":
+            capability["expected_version"] = self.expected_version
+        return capability
+
+
+class _DescriptorError(ValueError):
+    pass
+
+
+def load_wardline_descriptor(project_root: Path | None) -> WardlineDescriptorState:
+    """Resolve and parse the Wardline descriptor, degrading on every failure."""
+    project_text = _read_project_descriptor(project_root)
+    if project_text is not None:
+        return _state_from_text(project_text, "project")
+
+    package_text = _read_package_descriptor()
+    if package_text is not None:
+        return _state_from_text(package_text, "package")
+
+    return WardlineDescriptorState(status="absent", reason="not_found")
+
+
+def _read_project_descriptor(project_root: Path | None) -> str | None:
+    if project_root is None:
+        return None
+    path = project_root / PROJECT_DESCRIPTOR_PATH
+    if not path.is_file():
+        return None
+    try:
+        return path.read_text(encoding="utf-8")
+    except OSError:
+        return None
+
+
+def _read_package_descriptor() -> str | None:
+    try:
+        files = metadata.files("wardline")
+    except metadata.PackageNotFoundError:
+        return None
+    if files is None:
+        return None
+    for package_file in files:
+        if str(package_file).replace("\\", "/").endswith("wardline/core/vocabulary.yaml"):
+            try:
+                return cast("str", cast("Any", package_file.locate()).read_text(encoding="utf-8"))
+            except OSError:
+                return None
+    return None
+
+
+def _state_from_text(text: str, source: DescriptorSource) -> WardlineDescriptorState:
+    try:
+        descriptor = yaml.safe_load(text)
+        vocabulary = _parse_descriptor(descriptor, source)
+    except (OSError, yaml.YAMLError, _DescriptorError):
+        return WardlineDescriptorState(status="absent", reason="invalid_descriptor")
+    if vocabulary.version != EXPECTED_DESCRIPTOR_VERSION:
+        return WardlineDescriptorState(
+            status="version_skew",
+            descriptor_version=vocabulary.version,
+            source=source,
+            vocabulary=WardlineVocabulary(
+                version=vocabulary.version,
+                source=source,
+                confidence_basis="descriptor_version_skew",
+                entries_by_name=vocabulary.entries_by_name,
+            ),
+        )
+    return WardlineDescriptorState(
+        status="enabled",
+        descriptor_version=vocabulary.version,
+        source=source,
+        vocabulary=vocabulary,
+    )
+
+
+def _parse_descriptor(descriptor: Any, source: DescriptorSource) -> WardlineVocabulary:
+    if not isinstance(descriptor, dict):
+        msg = "descriptor root must be a mapping"
+        raise _DescriptorError(msg)
+    version = descriptor.get("version")
+    entries = descriptor.get("entries")
+    if not isinstance(version, str) or not isinstance(entries, list):
+        msg = "descriptor must carry string version and list entries"
+        raise _DescriptorError(msg)
+
+    entries_by_name: dict[str, DescriptorEntry] = {}
+    for raw_entry in entries:
+        entry = _parse_entry(raw_entry)
+        if entry.canonical_name in entries_by_name:
+            msg = f"duplicate Wardline descriptor entry: {entry.canonical_name}"
+            raise _DescriptorError(msg)
+        entries_by_name[entry.canonical_name] = entry
+    return WardlineVocabulary(
+        version=version,
+        source=source,
+        confidence_basis="descriptor",
+        entries_by_name=entries_by_name,
+    )
+
+
+def _parse_entry(raw_entry: Any) -> DescriptorEntry:
+    if not isinstance(raw_entry, dict):
+        msg = "descriptor entry must be a mapping"
+        raise _DescriptorError(msg)
+    canonical_name = raw_entry.get("canonical_name")
+    group = raw_entry.get("group")
+    attrs = raw_entry.get("attrs")
+    if not isinstance(canonical_name, str) or not isinstance(group, int):
+        msg = "descriptor entry must carry canonical_name and group"
+        raise _DescriptorError(msg)
+    if not isinstance(attrs, dict):
+        msg = "descriptor entry attrs must be a mapping"
+        raise _DescriptorError(msg)
+    for key, value in attrs.items():
+        if not isinstance(key, str) or not isinstance(value, str):
+            msg = "descriptor attrs must map strings to strings"
+            raise _DescriptorError(msg)
+    return DescriptorEntry(
+        canonical_name=canonical_name,
+        group=group,
+        attrs=cast("dict[str, str]", dict(attrs)),
+    )