python-delphi-lsp 3.6.0__cp310-abi3-win_amd64.whl

delphi_lsp/parse_artifacts.py

@@ -0,0 +1,969 @@
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import stat
+import tempfile
+from collections.abc import Mapping
+from dataclasses import dataclass
+from pathlib import Path
+from time import time_ns
+
+from .preprocessor import Preprocessor
+from .project_config import ProjectPathConfig
+from .semantic import (
+    ArrayTypeRef,
+    ClassOfTypeRef,
+    ClassTypeRef,
+    EnumTypeRef,
+    FileTypeRef,
+    GenericInstanceTypeRef,
+    InterfaceTypeRef,
+    Modifier,
+    NamedTypeRef,
+    PointerTypeRef,
+    ProcTypeRef,
+    RecordTypeRef,
+    ReferenceTypeRef,
+    Scope,
+    ScopeKind,
+    SetTypeRef,
+    SourceRange,
+    SubrangeTypeRef,
+    Symbol,
+    SymbolIndex,
+    SymbolKind,
+    TypeParameterRef,
+    TypeRef,
+    UnknownTypeRef,
+    Visibility,
+)
+from .semantic_builder import SemanticModel, SemanticProblem
+from .source_reader import read_source_text
+
+ARTIFACT_SCHEMA_VERSION = 1
+OUTLINE_PRODUCER_VERSION = "outline-model-v3"
+DEFAULT_ARTIFACT_CACHE_BYTES = 2 * 1024**3
+
+_MAX_ARTIFACT_BYTES = 256 * 1024**2
+_MAX_SYMBOLS_PER_ARTIFACT = 1_000_000
+_STALE_SHARD_GRACE_NS = 5 * 60 * 1_000_000_000
+_KEY_PREFIX = b"python-delphi-lsp-outline-artifact-v1\0"
+
+
+class ArtifactFormatError(ValueError):
+    """Raised internally when an untrusted artifact has an invalid shape."""
+
+
+@dataclass(frozen=True)
+class ArtifactDependency:
+    relative_path: str
+    content_hash: str
+
+    def to_mapping(self) -> dict[str, str]:
+        return {
+            "relative_path": self.relative_path,
+            "content_hash": self.content_hash,
+        }
+
+
+@dataclass(frozen=True)
+class ArtifactKey:
+    cache_key: str
+    relative_path: str
+    content_hash: str
+    effective_defines: tuple[str, ...]
+    effective_defines_hash: str
+    includes: tuple[ArtifactDependency, ...]
+    producer_version: str
+    schema_version: int = ARTIFACT_SCHEMA_VERSION
+
+    def to_mapping(self) -> dict[str, object]:
+        return {
+            "relative_path": self.relative_path,
+            "content_hash": self.content_hash,
+            "effective_defines": list(self.effective_defines),
+            "effective_defines_hash": self.effective_defines_hash,
+            "includes": [item.to_mapping() for item in self.includes],
+            "producer_version": self.producer_version,
+            "schema_version": self.schema_version,
+        }
+
+
+@dataclass(frozen=True)
+class CachedOutlineArtifact:
+    model: SemanticModel
+    lines_processed: int
+    symbols_discovered: int
+
+
+def artifact_cache_disabled() -> bool:
+    return os.environ.get("DELPHI_LSP_NO_ARTIFACT_CACHE") == "1"
+
+
+def artifact_key(
+    workspace_root: str | Path,
+    source_path: str | Path,
+    text: str,
+    defines: tuple[str, ...],
+    *,
+    include_paths: tuple[str, ...] = (),
+    project_config: ProjectPathConfig | None = None,
+    producer_version: str = OUTLINE_PRODUCER_VERSION,
+) -> ArtifactKey:
+    root = Path(workspace_root).expanduser().resolve()
+    source = Path(source_path).expanduser().resolve()
+    dependencies: dict[str, str] = {}
+    preprocessor = Preprocessor(
+        defines=defines,
+        include_paths=include_paths,
+        include_loader=_recording_include_loader(
+            root,
+            include_paths,
+            project_config,
+            dependencies,
+        ),
+        track_source_map=False,
+        collect_comments=False,
+    )
+    effective_defines = tuple(sorted(preprocessor.defines))
+    if "{$" in text or "(*$" in text:
+        preprocessor.process(text, str(source))
+
+    define_data = _canonical_json(list(effective_defines))
+    define_hash = hashlib.sha256(define_data).hexdigest()
+    dependency_items = tuple(
+        ArtifactDependency(relative_path=relative_path, content_hash=content_hash)
+        for relative_path, content_hash in sorted(dependencies.items())
+    )
+    relative_path = _relative_path(root, source)
+    content_hash = _text_hash(text)
+    material = {
+        "relative_path": relative_path,
+        "content_hash": content_hash,
+        "effective_defines_hash": define_hash,
+        "includes": [item.to_mapping() for item in dependency_items],
+        "producer_version": producer_version,
+        "schema_version": ARTIFACT_SCHEMA_VERSION,
+    }
+    digest = hashlib.sha256()
+    digest.update(_KEY_PREFIX)
+    digest.update(_canonical_json(material))
+    return ArtifactKey(
+        cache_key=digest.hexdigest(),
+        relative_path=relative_path,
+        content_hash=content_hash,
+        effective_defines=effective_defines,
+        effective_defines_hash=define_hash,
+        includes=dependency_items,
+        producer_version=producer_version,
+    )
+
+
+def _recording_include_loader(
+    root: Path,
+    include_paths: tuple[str, ...],
+    project_config: ProjectPathConfig | None,
+    dependencies: dict[str, str],
+):
+    search_paths = tuple(Path(path).expanduser().resolve() for path in include_paths)
+
+    def load(parent_file: str, include_name: str) -> tuple[str, str] | None:
+        include_path = Path(include_name.replace("\\", "/"))
+        parent = Path(parent_file).expanduser().resolve().parent
+        for base in (parent, *search_paths):
+            candidate = (base / include_path).resolve()
+            if (
+                project_config is not None
+                and project_config.excludes_workspace_path(candidate)
+            ):
+                continue
+            try:
+                if not candidate.is_file():
+                    continue
+                content = read_source_text(candidate)
+            except (OSError, UnicodeError):
+                continue
+            dependencies[_relative_path(root, candidate)] = _text_hash(content)
+            return content, str(candidate)
+        return None
+
+    return load
+
+
+class ArtifactStore:
+    """Sharded, bounded JSON storage for untrusted outline artifacts."""
+
+    def __init__(
+        self,
+        root: str | Path,
+        *,
+        max_bytes: int = DEFAULT_ARTIFACT_CACHE_BYTES,
+    ) -> None:
+        if isinstance(max_bytes, bool) or not isinstance(max_bytes, int) or max_bytes < 0:
+            raise ValueError("artifact cache byte budget must be non-negative")
+        self.root = Path(root)
+        self.max_bytes = max_bytes
+
+    def load(self, cache_key: str) -> Mapping[str, object] | None:
+        path = self.path_for_key(cache_key)
+        if self._has_unsafe_directory(path.parent):
+            return None
+        try:
+            descriptor = os.open(path, os.O_RDONLY | getattr(os, "O_NOFOLLOW", 0))
+            try:
+                info = os.fstat(descriptor)
+                if (
+                    not stat.S_ISREG(info.st_mode)
+                    or info.st_size > _MAX_ARTIFACT_BYTES
+                    or (
+                        os.name != "nt"
+                        and (info.st_uid != os.getuid() or info.st_mode & 0o077)
+                    )
+                ):
+                    return None
+                with os.fdopen(descriptor, "rb", closefd=False) as stream:
+                    raw = stream.read(_MAX_ARTIFACT_BYTES + 1)
+                if len(raw) > _MAX_ARTIFACT_BYTES:
+                    return None
+            finally:
+                os.close(descriptor)
+            payload = json.loads(raw.decode("utf-8"))
+        except (OSError, UnicodeError, ValueError, RecursionError):
+            return None
+        if (
+            not isinstance(payload, dict)
+            or payload.get("schema_version") != ARTIFACT_SCHEMA_VERSION
+            or payload.get("cache_key") != cache_key
+        ):
+            return None
+        return payload
+
+    def store(self, cache_key: str, payload: Mapping[str, object]) -> None:
+        path = self.path_for_key(cache_key)
+        self._ensure_directory(path.parent)
+        record = {
+            **dict(payload),
+            "schema_version": ARTIFACT_SCHEMA_VERSION,
+            "cache_key": cache_key,
+        }
+        data = _canonical_json(record)
+        if len(data) > _MAX_ARTIFACT_BYTES:
+            return
+        descriptor, temporary = tempfile.mkstemp(prefix=".artifact-", dir=path.parent)
+        try:
+            if os.name != "nt":
+                os.fchmod(descriptor, 0o600)
+            with os.fdopen(descriptor, "wb") as stream:
+                stream.write(data)
+                stream.flush()
+                os.fsync(stream.fileno())
+            os.replace(temporary, path)
+            if os.name != "nt":
+                os.chmod(path, 0o600)
+        finally:
+            try:
+                os.unlink(temporary)
+            except FileNotFoundError:
+                pass
+
+    def prune(self, live_keys: set[str]) -> None:
+        if not self.root.exists() or self._has_unsafe_directory(self.root):
+            return
+        retained: list[tuple[int, str, Path, int]] = []
+        observed_at = time_ns()
+        bucket_paths: list[Path] = []
+        try:
+            buckets = tuple(self.root.iterdir())
+        except OSError:
+            return
+        for bucket in buckets:
+            if bucket.is_symlink() or not bucket.is_dir():
+                continue
+            bucket_paths.append(bucket)
+            try:
+                shards = tuple(bucket.iterdir())
+            except OSError:
+                continue
+            for shard in shards:
+                if shard.is_symlink() or not shard.is_file() or shard.suffix != ".json":
+                    continue
+                cache_key = shard.stem
+                try:
+                    info = shard.stat(follow_symlinks=False)
+                except OSError:
+                    continue
+                if (
+                    cache_key not in live_keys
+                    and observed_at - info.st_mtime_ns >= _STALE_SHARD_GRACE_NS
+                ):
+                    try:
+                        shard.unlink()
+                    except OSError:
+                        pass
+                    continue
+                retained.append((info.st_mtime_ns, str(shard), shard, info.st_size))
+
+        retained_bytes = sum(item[3] for item in retained)
+        for _mtime, _name, shard, size in sorted(retained):
+            if retained_bytes <= self.max_bytes:
+                break
+            try:
+                shard.unlink()
+            except OSError:
+                continue
+            retained_bytes -= size
+        for bucket in bucket_paths:
+            try:
+                bucket.rmdir()
+            except OSError:
+                pass
+
+    def path_for_key(self, cache_key: str) -> Path:
+        _validate_cache_key(cache_key)
+        return self.root / cache_key[:2] / f"{cache_key}.json"
+
+    def _has_unsafe_directory(self, directory: Path) -> bool:
+        return any(path.is_symlink() for path in (self.root.parent, self.root, directory))
+
+    def _ensure_directory(self, directory: Path) -> None:
+        if self._has_unsafe_directory(directory):
+            raise OSError("artifact cache path is unsafe")
+        self.root.parent.mkdir(mode=0o700, parents=True, exist_ok=True)
+        for path in (self.root, directory):
+            if path.exists() and path.is_symlink():
+                raise OSError("artifact cache path is unsafe")
+            path.mkdir(mode=0o700, parents=True, exist_ok=True)
+            if os.name != "nt":
+                os.chmod(path, 0o700)
+
+
+def load_outline_artifact(
+    store: ArtifactStore,
+    key: ArtifactKey,
+    source_path: str,
+) -> CachedOutlineArtifact | None:
+    payload = store.load(key.cache_key)
+    if payload is None:
+        return None
+    try:
+        if (
+            payload.get("producer_version") != key.producer_version
+            or payload.get("key") != key.to_mapping()
+            or payload.get("source_path") != source_path
+        ):
+            return None
+        lines_processed = _non_negative_int(payload.get("lines_processed"))
+        symbols_discovered = _non_negative_int(payload.get("symbols_discovered"))
+        model = semantic_model_from_mapping(_mapping(payload.get("model")))
+    except (ArtifactFormatError, KeyError, TypeError, ValueError, RecursionError):
+        return None
+    return CachedOutlineArtifact(model, lines_processed, symbols_discovered)
+
+
+def store_outline_artifact(
+    store: ArtifactStore,
+    key: ArtifactKey,
+    source_path: str,
+    model: SemanticModel,
+    *,
+    lines_processed: int,
+    symbols_discovered: int,
+) -> None:
+    store.store(
+        key.cache_key,
+        {
+            "producer_version": key.producer_version,
+            "key": key.to_mapping(),
+            "source_path": source_path,
+            "lines_processed": lines_processed,
+            "symbols_discovered": symbols_discovered,
+            "model": semantic_model_to_mapping(model),
+        },
+    )
+
+
+def semantic_model_to_mapping(model: SemanticModel) -> dict[str, object]:
+    if model.references:
+        raise ValueError("outline artifacts do not support semantic references")
+    payload: dict[str, object] = {"unit_scope": _scope_to_mapping(model.unit_scope)}
+    if model.problems:
+        payload["problems"] = [
+            {
+                "message": problem.message,
+                "range": _range_to_mapping(problem.range),
+            }
+            for problem in model.problems
+        ]
+    return payload
+
+
+def semantic_model_from_mapping(payload: Mapping[str, object]) -> SemanticModel:
+    count = [0]
+    unit_scope = _scope_from_mapping(
+        _mapping(payload.get("unit_scope")),
+        parent=None,
+        inherited_owner=None,
+        symbol_count=count,
+    )
+    problem_payloads = _optional_list(payload.get("problems"))
+    if _optional_list(payload.get("references")):
+        raise ArtifactFormatError("outline artifact references must be empty")
+    problems = [
+        SemanticProblem(
+            message=_string(_mapping(item).get("message")),
+            range=_range_from_value(_mapping(item).get("range")),
+        )
+        for item in problem_payloads
+    ]
+    index = SymbolIndex()
+    index.register_unit(unit_scope.name, unit_scope)
+    return SemanticModel(unit_scope=unit_scope, index=index, problems=problems)
+
+
+def _scope_to_mapping(scope: Scope) -> dict[str, object]:
+    symbols = [symbol for items in scope.symbols.values() for symbol in items]
+    owner_index = next(
+        (index for index, symbol in enumerate(symbols) if symbol is scope.owner),
+        None,
+    )
+    payload: dict[str, object] = {
+        "kind": scope.kind.value,
+        "name": scope.name,
+        "symbols": [_symbol_to_mapping(symbol) for symbol in symbols],
+    }
+    if owner_index is not None:
+        payload["owner_index"] = owner_index
+    return payload
+
+
+def _scope_from_mapping(
+    payload: Mapping[str, object],
+    *,
+    parent: Scope | None,
+    inherited_owner: Symbol | None,
+    symbol_count: list[int],
+) -> Scope:
+    scope = Scope(
+        kind=ScopeKind(_string(payload.get("kind"))),
+        name=_string(payload.get("name")),
+        parent=parent,
+        owner=inherited_owner,
+    )
+    symbol_payloads = [_mapping(item) for item in _list(payload.get("symbols"))]
+    symbol_count[0] += len(symbol_payloads)
+    if symbol_count[0] > _MAX_SYMBOLS_PER_ARTIFACT:
+        raise ArtifactFormatError("outline artifact has too many symbols")
+    symbols: list[Symbol] = []
+    for item in symbol_payloads:
+        symbol = Symbol(
+            name=_string(item.get("name")),
+            kind=SymbolKind(_string(item.get("kind"))),
+            decl_range=(decl_range := _range_from_value(item.get("range"))),
+            name_range=(
+                decl_range
+                if item.get("name_range") is None
+                else _range_from_value(item.get("name_range"))
+            ),
+            scope=scope,
+            visibility=Visibility(
+                _string(item.get("visibility", Visibility.UNKNOWN.value))
+            ),
+            type_ref=(
+                UnknownTypeRef()
+                if item.get("type_ref") is None
+                else _type_ref_from_mapping(_mapping(item.get("type_ref")))
+            ),
+            modifiers={
+                Modifier(_string(value))
+                for value in _optional_list(item.get("modifiers"))
+            },
+            attributes=_string_mapping(item.get("attributes")),
+            doc=_string(item.get("doc", "")),
+            base_types=tuple(
+                _type_ref_from_mapping(_mapping(value))
+                for value in _optional_list(item.get("base_types"))
+            ),
+        )
+        scope.define(symbol)
+        symbols.append(symbol)
+
+    owner_index = payload.get("owner_index")
+    if owner_index is not None:
+        owner_ordinal = _integer(owner_index)
+        if owner_ordinal < 0 or owner_ordinal >= len(symbols):
+            raise ArtifactFormatError("outline scope owner is invalid")
+        scope.owner = symbols[owner_ordinal]
+
+    for symbol, item in zip(symbols, symbol_payloads, strict=True):
+        member_scope = item.get("member_scope")
+        if member_scope is not None:
+            symbol.member_scope = _scope_from_mapping(
+                _mapping(member_scope),
+                parent=scope,
+                inherited_owner=symbol,
+                symbol_count=symbol_count,
+            )
+        type_ref = item.get("type_ref")
+        if type_ref is not None:
+            symbol.type_ref = _type_ref_from_mapping(
+                _mapping(type_ref),
+                structured_scope=symbol.member_scope,
+            )
+        symbol.overloads = [
+            _standalone_symbol_from_mapping(
+                _mapping(overload),
+                scope,
+                symbol_count,
+            )
+            for overload in _optional_list(item.get("overloads"))
+        ]
+    return scope
+
+
+def _standalone_symbol_from_mapping(
+    payload: Mapping[str, object],
+    scope: Scope,
+    symbol_count: list[int],
+) -> Symbol:
+    symbol_count[0] += 1
+    if symbol_count[0] > _MAX_SYMBOLS_PER_ARTIFACT:
+        raise ArtifactFormatError("outline artifact has too many symbols")
+    symbol = Symbol(
+        name=_string(payload.get("name")),
+        kind=SymbolKind(_string(payload.get("kind"))),
+        decl_range=(decl_range := _range_from_value(payload.get("range"))),
+        name_range=(
+            decl_range
+            if payload.get("name_range") is None
+            else _range_from_value(payload.get("name_range"))
+        ),
+        scope=scope,
+        visibility=Visibility(
+            _string(payload.get("visibility", Visibility.UNKNOWN.value))
+        ),
+        type_ref=(
+            UnknownTypeRef()
+            if payload.get("type_ref") is None
+            else _type_ref_from_mapping(_mapping(payload.get("type_ref")))
+        ),
+        modifiers={
+            Modifier(_string(value))
+            for value in _optional_list(payload.get("modifiers"))
+        },
+        attributes=_string_mapping(payload.get("attributes")),
+        doc=_string(payload.get("doc", "")),
+        base_types=tuple(
+            _type_ref_from_mapping(_mapping(value))
+            for value in _optional_list(payload.get("base_types"))
+        ),
+    )
+    member_scope = payload.get("member_scope")
+    if member_scope is not None:
+        symbol.member_scope = _scope_from_mapping(
+            _mapping(member_scope),
+            parent=scope,
+            inherited_owner=symbol,
+            symbol_count=symbol_count,
+        )
+    type_ref = payload.get("type_ref")
+    if type_ref is not None:
+        symbol.type_ref = _type_ref_from_mapping(
+            _mapping(type_ref),
+            structured_scope=symbol.member_scope,
+        )
+    symbol.overloads = [
+        _standalone_symbol_from_mapping(_mapping(value), scope, symbol_count)
+        for value in _optional_list(payload.get("overloads"))
+    ]
+    return symbol
+
+
+def _symbol_to_mapping(symbol: Symbol) -> dict[str, object]:
+    payload: dict[str, object] = {
+        "name": symbol.name,
+        "kind": symbol.kind.value,
+        "range": _range_to_mapping(symbol.decl_range),
+    }
+    if symbol.name_range != symbol.decl_range:
+        payload["name_range"] = _range_to_mapping(symbol.name_range)
+    if symbol.visibility is not Visibility.UNKNOWN:
+        payload["visibility"] = symbol.visibility.value
+    if not isinstance(symbol.type_ref, UnknownTypeRef) or symbol.type_ref.reason:
+        payload["type_ref"] = _type_ref_to_mapping(symbol.type_ref)
+    if symbol.modifiers:
+        payload["modifiers"] = sorted(modifier.value for modifier in symbol.modifiers)
+    if symbol.attributes:
+        payload["attributes"] = dict(sorted(symbol.attributes.items()))
+    if symbol.doc:
+        payload["doc"] = symbol.doc
+    if symbol.overloads:
+        payload["overloads"] = [_symbol_to_mapping(item) for item in symbol.overloads]
+    if symbol.member_scope is not None:
+        payload["member_scope"] = _scope_to_mapping(symbol.member_scope)
+    if symbol.base_types:
+        payload["base_types"] = [
+            _type_ref_to_mapping(item) for item in symbol.base_types
+        ]
+    return payload
+
+
+def _range_to_mapping(source_range: SourceRange) -> list[object]:
+    return [
+        source_range.file_name,
+        source_range.start_line,
+        source_range.start_col,
+        source_range.end_line,
+        source_range.end_col,
+    ]
+
+
+def _range_from_value(value: object) -> SourceRange:
+    payload = _list(value)
+    if len(payload) != 5:
+        raise ArtifactFormatError("outline source range must have five values")
+    return SourceRange(
+        file_name=_string(payload[0]),
+        start_line=_positive_int(payload[1]),
+        start_col=_positive_int(payload[2]),
+        end_line=_positive_int(payload[3]),
+        end_col=_positive_int(payload[4]),
+    )
+
+
+def _type_ref_to_mapping(type_ref: TypeRef) -> dict[str, object]:
+    if isinstance(type_ref, UnknownTypeRef):
+        return {"kind": "unknown", "reason": type_ref.reason}
+    if isinstance(type_ref, NamedTypeRef):
+        return {"kind": "named", "name": type_ref.name, "unit_name": type_ref.unit_name}
+    if isinstance(type_ref, PointerTypeRef):
+        return {"kind": "pointer", "target": _type_ref_to_mapping(type_ref.target)}
+    if isinstance(type_ref, ClassOfTypeRef):
+        return {"kind": "class_of", "target": _type_ref_to_mapping(type_ref.target)}
+    if isinstance(type_ref, ReferenceTypeRef):
+        return {"kind": "reference", "target": _type_ref_to_mapping(type_ref.target)}
+    if isinstance(type_ref, FileTypeRef):
+        return {
+            "kind": "file",
+            "element_type": (
+                None
+                if type_ref.element_type is None
+                else _type_ref_to_mapping(type_ref.element_type)
+            ),
+        }
+    if isinstance(type_ref, GenericInstanceTypeRef):
+        return {
+            "kind": "generic",
+            "base": _type_ref_to_mapping(type_ref.base),
+            "args": [_type_ref_to_mapping(item) for item in type_ref.args],
+        }
+    if isinstance(type_ref, ArrayTypeRef):
+        return {
+            "kind": "array",
+            "element_type": _type_ref_to_mapping(type_ref.element_type),
+            "dimensions": [_type_ref_to_mapping(item) for item in type_ref.dimensions],
+            "is_dynamic": type_ref.is_dynamic,
+        }
+    if isinstance(type_ref, SetTypeRef):
+        return {"kind": "set", "element_type": _type_ref_to_mapping(type_ref.element_type)}
+    if isinstance(type_ref, SubrangeTypeRef):
+        return {"kind": "subrange", "lower": type_ref.lower, "upper": type_ref.upper}
+    if isinstance(type_ref, EnumTypeRef):
+        return {"kind": "enum", "name": type_ref.name, "members": list(type_ref.members)}
+    if isinstance(type_ref, RecordTypeRef):
+        return {
+            "kind": "record",
+            "name": type_ref.name,
+            "packed": type_ref.packed,
+            "has_scope": type_ref.scope is not None,
+        }
+    if isinstance(type_ref, ClassTypeRef):
+        return {
+            "kind": "class",
+            "name": type_ref.name,
+            "bases": [_type_ref_to_mapping(item) for item in type_ref.bases],
+            "is_abstract": type_ref.is_abstract,
+            "has_scope": type_ref.scope is not None,
+        }
+    if isinstance(type_ref, InterfaceTypeRef):
+        return {
+            "kind": "interface",
+            "name": type_ref.name,
+            "bases": [_type_ref_to_mapping(item) for item in type_ref.bases],
+            "has_scope": type_ref.scope is not None,
+        }
+    if isinstance(type_ref, TypeParameterRef):
+        return {"kind": "type_parameter", "name": type_ref.name}
+    if isinstance(type_ref, ProcTypeRef):
+        return {
+            "kind": "proc",
+            "name": type_ref.name,
+            "params": [_type_ref_to_mapping(item) for item in type_ref.params],
+            "return_type": (
+                None
+                if type_ref.return_type is None
+                else _type_ref_to_mapping(type_ref.return_type)
+            ),
+        }
+    raise ValueError(f"unsupported outline type reference: {type(type_ref).__name__}")
+
+
+def _type_ref_from_mapping(
+    payload: Mapping[str, object],
+    *,
+    structured_scope: Scope | None = None,
+) -> TypeRef:
+    kind = _string(payload.get("kind"))
+    if kind == "unknown":
+        return UnknownTypeRef(_string(payload.get("reason")))
+    if kind == "named":
+        unit_name = payload.get("unit_name")
+        return NamedTypeRef(
+            _string(payload.get("name")),
+            None if unit_name is None else _string(unit_name),
+        )
+    if kind == "pointer":
+        return PointerTypeRef(
+            _type_ref_from_mapping(
+                _mapping(payload.get("target")),
+                structured_scope=structured_scope,
+            )
+        )
+    if kind == "class_of":
+        return ClassOfTypeRef(
+            _type_ref_from_mapping(
+                _mapping(payload.get("target")),
+                structured_scope=structured_scope,
+            )
+        )
+    if kind == "reference":
+        return ReferenceTypeRef(
+            _type_ref_from_mapping(
+                _mapping(payload.get("target")),
+                structured_scope=structured_scope,
+            )
+        )
+    if kind == "file":
+        element = payload.get("element_type")
+        return FileTypeRef(
+            None
+            if element is None
+            else _type_ref_from_mapping(
+                _mapping(element),
+                structured_scope=structured_scope,
+            )
+        )
+    if kind == "generic":
+        base = _type_ref_from_mapping(
+            _mapping(payload.get("base")),
+            structured_scope=structured_scope,
+        )
+        if not isinstance(base, NamedTypeRef):
+            raise ArtifactFormatError("generic base must be a named type")
+        return GenericInstanceTypeRef(
+            base,
+            tuple(
+                _type_ref_from_mapping(
+                    _mapping(item),
+                    structured_scope=structured_scope,
+                )
+                for item in _list(payload.get("args"))
+            ),
+        )
+    if kind == "array":
+        return ArrayTypeRef(
+            element_type=_type_ref_from_mapping(
+                _mapping(payload.get("element_type")),
+                structured_scope=structured_scope,
+            ),
+            dimensions=tuple(
+                _type_ref_from_mapping(
+                    _mapping(item),
+                    structured_scope=structured_scope,
+                )
+                for item in _list(payload.get("dimensions"))
+            ),
+            is_dynamic=_boolean(payload.get("is_dynamic")),
+        )
+    if kind == "set":
+        return SetTypeRef(
+            _type_ref_from_mapping(
+                _mapping(payload.get("element_type")),
+                structured_scope=structured_scope,
+            )
+        )
+    if kind == "subrange":
+        return SubrangeTypeRef(_string(payload.get("lower")), _string(payload.get("upper")))
+    if kind == "enum":
+        return EnumTypeRef(
+            _string(payload.get("name")),
+            tuple(_string(item) for item in _list(payload.get("members"))),
+        )
+    if kind == "record":
+        return RecordTypeRef(
+            _string(payload.get("name")),
+            scope=(
+                structured_scope
+                if _boolean(payload.get("has_scope", False))
+                else None
+            ),
+            packed=_boolean(payload.get("packed")),
+        )
+    if kind == "class":
+        return ClassTypeRef(
+            _string(payload.get("name")),
+            scope=(
+                structured_scope
+                if _boolean(payload.get("has_scope", False))
+                else None
+            ),
+            bases=tuple(
+                _type_ref_from_mapping(
+                    _mapping(item),
+                    structured_scope=structured_scope,
+                )
+                for item in _list(payload.get("bases"))
+            ),
+            is_abstract=_boolean(payload.get("is_abstract")),
+        )
+    if kind == "interface":
+        return InterfaceTypeRef(
+            _string(payload.get("name")),
+            scope=(
+                structured_scope
+                if _boolean(payload.get("has_scope", False))
+                else None
+            ),
+            bases=tuple(
+                _type_ref_from_mapping(
+                    _mapping(item),
+                    structured_scope=structured_scope,
+                )
+                for item in _list(payload.get("bases"))
+            ),
+        )
+    if kind == "type_parameter":
+        return TypeParameterRef(_string(payload.get("name")))
+    if kind == "proc":
+        result = payload.get("return_type")
+        return ProcTypeRef(
+            _string(payload.get("name")),
+            params=tuple(
+                _type_ref_from_mapping(
+                    _mapping(item),
+                    structured_scope=structured_scope,
+                )
+                for item in _list(payload.get("params"))
+            ),
+            return_type=(
+                None
+                if result is None
+                else _type_ref_from_mapping(
+                    _mapping(result),
+                    structured_scope=structured_scope,
+                )
+            ),
+        )
+    raise ArtifactFormatError("outline type reference kind is invalid")
+
+
+def _relative_path(root: Path, path: Path) -> str:
+    try:
+        return path.relative_to(root).as_posix()
+    except ValueError:
+        return Path(os.path.relpath(path, root)).as_posix()
+
+
+def _text_hash(text: str) -> str:
+    return hashlib.sha256(text.encode("utf-8", errors="surrogatepass")).hexdigest()
+
+
+def _canonical_json(payload: object) -> bytes:
+    return json.dumps(
+        payload,
+        ensure_ascii=False,
+        sort_keys=True,
+        separators=(",", ":"),
+        allow_nan=False,
+    ).encode("utf-8", errors="surrogatepass")
+
+
+def _validate_cache_key(cache_key: str) -> None:
+    if (
+        len(cache_key) != 64
+        or any(character not in "0123456789abcdef" for character in cache_key)
+    ):
+        raise ValueError("artifact cache key is malformed")
+
+
+def _mapping(value: object) -> Mapping[str, object]:
+    if not isinstance(value, Mapping):
+        raise ArtifactFormatError("outline artifact value must be an object")
+    return value
+
+
+def _list(value: object) -> list[object]:
+    if not isinstance(value, list):
+        raise ArtifactFormatError("outline artifact value must be an array")
+    return value
+
+
+def _optional_list(value: object) -> list[object]:
+    return [] if value is None else _list(value)
+
+
+def _string(value: object) -> str:
+    if not isinstance(value, str):
+        raise ArtifactFormatError("outline artifact value must be a string")
+    return value
+
+
+def _string_mapping(value: object) -> dict[str, str]:
+    if value is None:
+        return {}
+    mapping = _mapping(value)
+    return {_string(key): _string(item) for key, item in mapping.items()}
+
+
+def _integer(value: object) -> int:
+    if isinstance(value, bool) or not isinstance(value, int):
+        raise ArtifactFormatError("outline artifact value must be an integer")
+    return value
+
+
+def _positive_int(value: object) -> int:
+    result = _integer(value)
+    if result < 1:
+        raise ArtifactFormatError("outline artifact position must be positive")
+    return result
+
+
+def _non_negative_int(value: object) -> int:
+    result = _integer(value)
+    if result < 0:
+        raise ArtifactFormatError("outline artifact count must be non-negative")
+    return result
+
+
+def _boolean(value: object) -> bool:
+    if not isinstance(value, bool):
+        raise ArtifactFormatError("outline artifact value must be a boolean")
+    return value
+
+
+__all__ = [
+    "ARTIFACT_SCHEMA_VERSION",
+    "DEFAULT_ARTIFACT_CACHE_BYTES",
+    "OUTLINE_PRODUCER_VERSION",
+    "ArtifactDependency",
+    "ArtifactKey",
+    "ArtifactStore",
+    "CachedOutlineArtifact",
+    "artifact_cache_disabled",
+    "artifact_key",
+    "load_outline_artifact",
+    "semantic_model_from_mapping",
+    "semantic_model_to_mapping",
+    "store_outline_artifact",
+]