openmodus 0.0.1__py3-none-any.whl

modus/init_analysis/semantic_ir.py

@@ -0,0 +1,582 @@
+"""Language-neutral typed semantic facts emitted by compiler providers.
+
+The wire contract is intentionally JSONL-friendly: every line is one ``node``,
+``edge`` or ``diagnostic`` record.  Keeping the provider boundary process based
+isolates compiler crashes and version conflicts from the Modus process.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from collections.abc import Iterable, Mapping
+from dataclasses import dataclass, field
+from typing import Any, Literal, cast
+
+from .semantic_contracts import AnalysisContext, CoverageReceipt, ObservationDisposition
+
+NODE_KINDS = frozenset(
+    {
+        "repository",
+        "build-unit",
+        "deployable-service",
+        "component",
+        "endpoint",
+        "function",
+        "method",
+        "type",
+        "rpc-service",
+        "topic",
+        "db",
+        "table",
+        "cache",
+        "keyspace",
+        "config-key",
+        "state-machine",
+        "state",
+    }
+)
+RELATIONS = frozenset(
+    {
+        "contains",
+        "implements",
+        "injects",
+        "calls",
+        "exposes",
+        "invokes",
+        "publishes",
+        "consumes",
+        "reads",
+        "writes",
+        "invalidates",
+        "configured_by",
+        "transitions_to",
+    }
+)
+RESOLUTIONS = frozenset({"exact", "candidate", "heuristic", "unresolved"})
+BINDING_KINDS = frozenset(
+    {
+        "declared-exact",
+        "runtime-exact",
+        "runtime-candidate",
+        "heuristic",
+        "unresolved",
+    }
+)
+ANALYSIS_COMPLETENESS = frozenset({"complete", "partial", "fallback"})
+LANGUAGES = frozenset(
+    {"python", "go", "java", "cpp", "javascript", "typescript", "tsx", "generic", "external"}
+)
+
+
+def stable_id(prefix: str, *parts: object) -> str:
+    body = "\x1f".join(str(part) for part in parts)
+    return f"{prefix}:{hashlib.sha256(body.encode('utf-8')).hexdigest()[:24]}"
+
+
+def canonical_json(value: Any) -> str:
+    return json.dumps(
+        value,
+        ensure_ascii=False,
+        sort_keys=True,
+        separators=(",", ":"),
+        allow_nan=False,
+    )
+
+
+@dataclass(frozen=True)
+class SourceAnchor:
+    file: str
+    line: int
+    column: int = 1
+    end_line: int | None = None
+    end_column: int | None = None
+    column_encoding: str = "unknown"
+
+    def __post_init__(self) -> None:
+        if not self.file or self.file.startswith("/") or ".." in self.file.split("/"):
+            raise ValueError("source anchor file must be a repository-relative path")
+        if self.line < 1 or self.column < 1:
+            raise ValueError("source anchor positions are one-based")
+        if self.end_line is not None and self.end_line < self.line:
+            raise ValueError("source anchor end line may not precede its start")
+        if self.end_column is not None and self.end_column < 1:
+            raise ValueError("source anchor end column is one-based")
+        if self.column_encoding not in {"unknown", "utf8-byte", "utf16", "unicode-codepoint"}:
+            raise ValueError("unsupported source column encoding")
+
+    def to_dict(self) -> dict[str, Any]:
+        result: dict[str, Any] = {
+            "file": self.file.replace("\\", "/"),
+            "line": self.line,
+            "column": self.column,
+            "columnEncoding": self.column_encoding,
+        }
+        result["endLine"] = self.end_line if self.end_line is not None else self.line
+        result["endColumn"] = self.end_column if self.end_column is not None else self.column
+        return result
+
+    @classmethod
+    def from_dict(cls, value: Mapping[str, Any]) -> SourceAnchor:
+        return cls(
+            file=str(value["file"]),
+            line=int(value["line"]),
+            column=int(value.get("column", 1)),
+            end_line=int(value["endLine"]) if value.get("endLine") is not None else None,
+            end_column=(int(value["endColumn"]) if value.get("endColumn") is not None else None),
+            column_encoding=str(value.get("columnEncoding") or "unknown"),
+        )
+
+
+@dataclass(frozen=True)
+class Provenance:
+    provider: str
+    provider_version: str
+    context_digest: str
+    rule_pack: str = ""
+
+    def __post_init__(self) -> None:
+        if not self.provider or not self.provider_version:
+            raise ValueError("provider and provider version are required")
+        if len(self.context_digest) != 64 or any(
+            item not in "0123456789abcdef" for item in self.context_digest
+        ):
+            raise ValueError("context digest must be a lowercase SHA-256 digest")
+
+    def to_dict(self) -> dict[str, str]:
+        result = {
+            "provider": self.provider,
+            "providerVersion": self.provider_version,
+            "contextDigest": self.context_digest,
+        }
+        if self.rule_pack:
+            result["rulePack"] = self.rule_pack
+        return result
+
+    @classmethod
+    def from_dict(cls, value: Mapping[str, Any]) -> Provenance:
+        return cls(
+            provider=str(value["provider"]),
+            provider_version=str(value["providerVersion"]),
+            context_digest=str(value["contextDigest"]),
+            rule_pack=str(value.get("rulePack", "")),
+        )
+
+
+@dataclass(frozen=True)
+class SemanticNode:
+    id: str
+    kind: str
+    language: str
+    qualified_name: str
+    build_unit_id: str
+    source_anchors: tuple[SourceAnchor, ...] = ()
+    deployable_id: str = ""
+    attributes: Mapping[str, Any] = field(default_factory=dict)
+    provenance: Provenance | None = None
+    symbol_id: str = ""
+    analysis_completeness: str = "complete"
+    analysis_context_id: str = ""
+
+    def __post_init__(self) -> None:
+        if self.kind not in NODE_KINDS:
+            raise ValueError(f"unsupported semantic node kind: {self.kind}")
+        if self.language not in LANGUAGES:
+            raise ValueError(f"unsupported semantic node language: {self.language}")
+        if not self.id or not self.qualified_name or not self.build_unit_id:
+            raise ValueError("semantic node id, qualifiedName and buildUnitId are required")
+        if self.analysis_completeness not in ANALYSIS_COMPLETENESS:
+            raise ValueError(f"unsupported analysis completeness: {self.analysis_completeness}")
+
+    def to_dict(self) -> dict[str, Any]:
+        result = {
+            "recordKind": "node",
+            "id": self.id,
+            "kind": self.kind,
+            "language": self.language,
+            "qualifiedName": self.qualified_name,
+            "buildUnitId": self.build_unit_id,
+            "symbolId": self.symbol_id or self.id,
+            "analysisContextId": self.analysis_context_id,
+            "analysisCompleteness": self.analysis_completeness,
+            "sourceAnchors": [item.to_dict() for item in self.source_anchors],
+            "attributes": dict(self.attributes),
+        }
+        if self.deployable_id:
+            result["deployableId"] = self.deployable_id
+        if self.provenance is not None:
+            result["provenance"] = self.provenance.to_dict()
+        return result
+
+    @classmethod
+    def from_dict(cls, value: Mapping[str, Any]) -> SemanticNode:
+        return cls(
+            id=str(value["id"]),
+            kind=str(value["kind"]),
+            language=str(value["language"]),
+            qualified_name=str(value["qualifiedName"]),
+            build_unit_id=str(value["buildUnitId"]),
+            source_anchors=tuple(
+                SourceAnchor.from_dict(item) for item in value.get("sourceAnchors", ())
+            ),
+            deployable_id=str(value.get("deployableId", "")),
+            attributes=dict(value.get("attributes") or {}),
+            provenance=(
+                Provenance.from_dict(value["provenance"]) if value.get("provenance") else None
+            ),
+            symbol_id=str(value.get("symbolId") or value["id"]),
+            analysis_context_id=str(value.get("analysisContextId", "")),
+            analysis_completeness=str(value.get("analysisCompleteness", "complete")),
+        )
+
+
+@dataclass(frozen=True)
+class SemanticEdge:
+    id: str
+    source: str
+    target: str
+    relation: str
+    resolution: str
+    operation: str = ""
+    call_site: SourceAnchor | None = None
+    dispatch: str = ""
+    contract_key: str = ""
+    evidence: tuple[str, ...] = ()
+    attributes: Mapping[str, Any] = field(default_factory=dict)
+    provenance: Provenance | None = None
+    binding_kind: str = ""
+    analysis_completeness: str = "complete"
+    analysis_context_id: str = ""
+    declaration_resolution: str = ""
+    dispatch_resolution: str = ""
+
+    def __post_init__(self) -> None:
+        if self.relation not in RELATIONS:
+            raise ValueError(f"unsupported semantic edge relation: {self.relation}")
+        if self.resolution not in RESOLUTIONS:
+            raise ValueError(f"unsupported semantic edge resolution: {self.resolution}")
+        if not self.id or not self.source or not self.target:
+            raise ValueError("semantic edge id, from and to are required")
+        binding_kind = self.binding_kind or _default_binding_kind(self.resolution)
+        if binding_kind not in BINDING_KINDS:
+            raise ValueError(f"unsupported semantic binding kind: {binding_kind}")
+        if self.analysis_completeness not in ANALYSIS_COMPLETENESS:
+            raise ValueError(f"unsupported analysis completeness: {self.analysis_completeness}")
+        if self.declaration_resolution and self.declaration_resolution not in RESOLUTIONS:
+            raise ValueError("invalid declaration resolution")
+        if self.declaration_resolution and self.declaration_resolution != self.resolution:
+            raise ValueError("legacy resolution must mirror declaration resolution")
+        if self.dispatch_resolution not in {
+            "",
+            "not-analyzed",
+            "singleton",
+            "candidates",
+            "unresolved",
+            "non-applicable",
+        }:
+            raise ValueError("invalid dispatch resolution")
+        expected = {"runtime-exact": "singleton", "runtime-candidate": "candidates"}.get(
+            binding_kind
+        )
+        if expected and self.dispatch_resolution and self.dispatch_resolution != expected:
+            raise ValueError("binding kind conflicts with dispatch resolution")
+
+    @property
+    def declaration_precision(self) -> str:
+        """Precision of the statically named declaration, independently of dispatch."""
+        return self.declaration_resolution or self.resolution
+
+    @property
+    def dispatch_precision(self) -> str:
+        """A singleton is conditional on execution; it is never a must-execute claim."""
+        return self.dispatch_resolution or {
+            "runtime-exact": "singleton",
+            "runtime-candidate": "candidates",
+            "unresolved": "unresolved",
+        }.get(self.binding_kind, "not-analyzed")
+
+    def to_dict(self) -> dict[str, Any]:
+        result = {
+            "recordKind": "edge",
+            "id": self.id,
+            "from": self.source,
+            "to": self.target,
+            "relation": self.relation,
+            "resolution": self.resolution,
+            "bindingKind": self.binding_kind or _default_binding_kind(self.resolution),
+            "analysisContextId": self.analysis_context_id,
+            "declarationResolution": self.declaration_precision,
+            "dispatchResolution": self.dispatch_precision,
+            "analysisCompleteness": self.analysis_completeness,
+            "operation": self.operation,
+            "dispatch": self.dispatch,
+            "contractKey": self.contract_key,
+            "evidence": list(self.evidence),
+            "attributes": dict(self.attributes),
+        }
+        if self.call_site is not None:
+            result["callSite"] = self.call_site.to_dict()
+        if self.provenance is not None:
+            result["provenance"] = self.provenance.to_dict()
+        return result
+
+    @classmethod
+    def from_dict(cls, value: Mapping[str, Any]) -> SemanticEdge:
+        return cls(
+            id=str(value["id"]),
+            source=str(value["from"]),
+            target=str(value["to"]),
+            relation=str(value["relation"]),
+            resolution=str(value["resolution"]),
+            operation=str(value.get("operation", "")),
+            call_site=(
+                SourceAnchor.from_dict(value["callSite"]) if value.get("callSite") else None
+            ),
+            dispatch=str(value.get("dispatch", "")),
+            contract_key=str(value.get("contractKey", "")),
+            evidence=tuple(str(item) for item in value.get("evidence", ())),
+            attributes=dict(value.get("attributes") or {}),
+            provenance=(
+                Provenance.from_dict(value["provenance"]) if value.get("provenance") else None
+            ),
+            analysis_context_id=str(value.get("analysisContextId", "")),
+            declaration_resolution=str(value.get("declarationResolution", "")),
+            dispatch_resolution=str(value.get("dispatchResolution", "")),
+            binding_kind=str(
+                value.get("bindingKind") or _default_binding_kind(str(value["resolution"]))
+            ),
+            analysis_completeness=str(value.get("analysisCompleteness", "complete")),
+        )
+
+
+def _default_binding_kind(resolution: str) -> str:
+    return {
+        "exact": "declared-exact",
+        "candidate": "runtime-candidate",
+        "heuristic": "heuristic",
+        "unresolved": "unresolved",
+    }[resolution]
+
+
+@dataclass(frozen=True)
+class SemanticDiagnostic:
+    code: str
+    message: str
+    severity: Literal["info", "warning", "error"]
+    provider: str
+    build_unit_id: str = ""
+    subject: str = ""
+
+    def to_dict(self) -> dict[str, str]:
+        return {
+            "recordKind": "diagnostic",
+            "code": self.code,
+            "message": self.message,
+            "severity": self.severity,
+            "provider": self.provider,
+            "buildUnitId": self.build_unit_id,
+            "subject": self.subject,
+        }
+
+
+@dataclass(frozen=True)
+class SemanticFacts:
+    nodes: tuple[SemanticNode, ...] = ()
+    edges: tuple[SemanticEdge, ...] = ()
+    diagnostics: tuple[SemanticDiagnostic, ...] = ()
+    contexts: tuple[AnalysisContext, ...] = ()
+    dispositions: tuple[ObservationDisposition, ...] = ()
+    coverage_receipts: tuple[CoverageReceipt, ...] = ()
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "schemaVersion": 1,
+            "nodes": [item.to_dict() for item in self.nodes],
+            "edges": [item.to_dict() for item in self.edges],
+            "diagnostics": [item.to_dict() for item in self.diagnostics],
+            "contexts": [item.to_dict() for item in self.contexts],
+            "dispositions": [item.to_dict() for item in self.dispositions],
+            "coverageReceipts": [item.to_dict() for item in self.coverage_receipts],
+        }
+
+
+def parse_jsonl(lines: Iterable[str]) -> SemanticFacts:
+    nodes: list[SemanticNode] = []
+    edges: list[SemanticEdge] = []
+    diagnostics: list[SemanticDiagnostic] = []
+    contexts = []
+    dispositions = []
+    receipts = []
+    for position, line in enumerate(lines, start=1):
+        if not line.strip():
+            continue
+        try:
+            value = json.loads(line)
+        except json.JSONDecodeError as exc:
+            raise ValueError(f"provider JSONL line {position} is invalid: {exc}") from exc
+        if not isinstance(value, Mapping):
+            raise ValueError(f"provider JSONL line {position} must be an object")
+        kind = value.get("recordKind")
+        if kind == "node":
+            node = SemanticNode.from_dict(value)
+            nodes.append(node)
+        elif kind == "edge":
+            edge = SemanticEdge.from_dict(value)
+            edges.append(edge)
+        elif kind == "diagnostic":
+            severity = str(value.get("severity", "warning"))
+            if severity not in {"info", "warning", "error"}:
+                raise ValueError(f"provider diagnostic severity is invalid on line {position}")
+            diagnostics.append(
+                SemanticDiagnostic(
+                    code=str(value.get("code", "provider.unknown")),
+                    message=str(value.get("message", "")),
+                    severity=cast(Literal["info", "warning", "error"], severity),
+                    provider=str(value.get("provider", "unknown")),
+                    build_unit_id=str(value.get("buildUnitId", "")),
+                    subject=str(value.get("subject", "")),
+                )
+            )
+        elif kind == "analysis-context":
+            contexts.append(AnalysisContext.from_dict(value))
+        elif kind == "disposition":
+            dispositions.append(ObservationDisposition.from_dict(value))
+        elif kind == "coverage-receipt":
+            receipts.append(CoverageReceipt.from_dict(value))
+        else:
+            raise ValueError(f"provider JSONL line {position} has unknown recordKind {kind!r}")
+    return normalize_facts(
+        SemanticFacts(
+            tuple(nodes),
+            tuple(edges),
+            tuple(diagnostics),
+            tuple(contexts),
+            tuple(dispositions),
+            tuple(receipts),
+        )
+    )
+
+
+def observation_context(item: SemanticNode | SemanticEdge) -> str:
+    return item.analysis_context_id or (item.provenance.context_digest if item.provenance else "")
+
+
+def normalize_facts(facts: SemanticFacts) -> SemanticFacts:
+    """Quarantine contradictory identities; identical retransmissions are idempotent.
+
+    Processing receipts cover every emitted record. Conflicting payloads are
+    never resolved by arrival order or by selecting a cosmetically better node.
+    """
+    dispositions = list(facts.dispositions)
+    diagnostics = list(facts.diagnostics)
+    accepted: dict[str, list[Any]] = {"node": [], "edge": []}
+    existing = {
+        (
+            row.record_kind,
+            row.record_id,
+            row.context_id,
+            row.status,
+            row.content_digest if row.status == "conflict" else "",
+        )
+        for row in dispositions
+    }
+    previous_duplicates: dict[tuple[str, str, str], int] = {}
+    for row in dispositions:
+        if row.status == "duplicate":
+            duplicate_key = (row.record_kind, row.record_id, row.context_id)
+            previous_duplicates[duplicate_key] = previous_duplicates.get(duplicate_key, 0) + 1
+    for kind, records in (("node", facts.nodes), ("edge", facts.edges)):
+        groups: dict[tuple[str, str], list[Any]] = {}
+        for item in records:
+            groups.setdefault((observation_context(item), item.id), []).append(item)
+        for (context, identity), items in sorted(groups.items()):
+            payloads = {canonical_json(item.to_dict()) for item in items}
+            conflict = len(payloads) > 1
+            if not conflict:
+                accepted[kind].append(items[0])
+            else:
+                diagnostics.append(
+                    SemanticDiagnostic(
+                        "semantic.identity-conflict",
+                        f"Conflicting {kind} observations: {identity}",
+                        "warning",
+                        "semantic-contract",
+                        subject=identity,
+                    )
+                )
+            # A normalization pass is idempotent for its already-receipted inputs.
+            for index, item in enumerate(
+                sorted(items, key=lambda row: canonical_json(row.to_dict()))
+            ):
+                digest = hashlib.sha256(canonical_json(item.to_dict()).encode()).hexdigest()
+                status = "conflict" if conflict else "accepted" if index == 0 else "duplicate"
+                receipt = ObservationDisposition(
+                    kind,
+                    identity,
+                    status,
+                    "semantic.identity-conflict"
+                    if conflict
+                    else "semantic.identical-duplicate"
+                    if index
+                    else "",
+                    context,
+                    digest,
+                )
+                key = (kind, identity, context, status, digest if conflict else "")
+                if (
+                    status == "duplicate"
+                    and index > previous_duplicates.get((kind, identity, context), 0)
+                ) or (status != "duplicate" and key not in existing):
+                    dispositions.append(receipt)
+                    existing.add(key)
+    nodes = tuple(accepted["node"])
+    node_keys = {(observation_context(item), item.id) for item in nodes}
+    edges = []
+    for edge in accepted["edge"]:
+        context = observation_context(edge)
+        if (context, edge.source) not in node_keys or (context, edge.target) not in node_keys:
+            dispositions.append(
+                ObservationDisposition(
+                    "edge", edge.id, "rejected", "semantic.missing-endpoint", context
+                )
+            )
+            diagnostics.append(
+                SemanticDiagnostic(
+                    "semantic.missing-endpoint",
+                    f"Edge has no accepted endpoint: {edge.id}",
+                    "warning",
+                    "semantic-contract",
+                    subject=edge.id,
+                )
+            )
+        else:
+            edges.append(edge)
+    return SemanticFacts(
+        nodes,
+        tuple(edges),
+        tuple(diagnostics),
+        facts.contexts,
+        tuple(dispositions),
+        facts.coverage_receipts,
+    )
+
+
+__all__ = [
+    "ANALYSIS_COMPLETENESS",
+    "BINDING_KINDS",
+    "LANGUAGES",
+    "NODE_KINDS",
+    "RELATIONS",
+    "RESOLUTIONS",
+    "Provenance",
+    "SemanticDiagnostic",
+    "SemanticEdge",
+    "SemanticFacts",
+    "SemanticNode",
+    "SourceAnchor",
+    "canonical_json",
+    "parse_jsonl",
+    "normalize_facts",
+    "observation_context",
+    "stable_id",
+]