loomweave-plugin-python 1.3.1__tar.gz → 1.5.1__tar.gz

{loomweave_plugin_python-1.3.1 → loomweave_plugin_python-1.5.1}/.gitignore

@@ -64,7 +64,10 @@ CLAUDE.md
 
 # Developer config / local tooling — not part of the solution
 .agents/
+/.worktrees/
 
 # Local tool/federation config — not part of the solution
 .mcp.json
 loomweave.yaml
+.wardline
+dist-reconcile/

{loomweave_plugin_python-1.3.1 → loomweave_plugin_python-1.5.1}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: loomweave-plugin-python
-Version: 1.3.1
+Version: 1.5.1
 Summary: Loomweave Python language plugin — v1.0 release
 Author-email: John Morrissey <qacona@gmail.com>
 Classifier: Development Status :: 4 - Beta
@@ -59,6 +59,47 @@ pytest plugins/python
 
 CI runs the same four gates in the `python-plugin` job.
 
+## Interpreter discovery
+
+`pyright-langserver` type-checks against whatever `python` it finds — the
+plugin points it at the project's own interpreter deterministically, rather
+than trusting whatever happened to be first on the launching process's
+`PATH` (clarion-5cf9643de9). `discover_project_interpreter`
+(`src/loomweave_plugin_python/interpreter.py`) walks a fixed order and stops
+at the first usable candidate — a **regular** file (`Path.is_file()`) that
+passes `os.access(path, os.X_OK)`:
+
+| Rung | Source | Pinned? |
+|---|---|---|
+| 1 | `LOOMWEAVE_PYTHON_INTERPRETER` env var names an executable file | yes |
+| 2 | `<project_root>/.venv/bin/python` | yes |
+| 3 | `$VIRTUAL_ENV/bin/python` | yes |
+| 4 | `$CONDA_PREFIX/bin/python` | yes |
+| 5 | first `python` / `python3` on `PATH` | no |
+| 6 | nothing found | no |
+
+An empty env value counts as unset at every rung. The returned path is
+absolute and lexically normalised but **never symlink-resolved** — a venv's
+`bin/python` is typically a symlink to the base interpreter, and pyright
+needs the symlink path to stay inside the venv's `site-packages`.
+
+This order is a cross-language contract shared with the Rust host
+(`crates/loomweave-core/src/plugin/interpreter.rs`); the host runs the same
+discovery and, for a `[capabilities.runtime.pyright]` plugin, exports its
+pinned answer to the child as `LOOMWEAVE_PYTHON_INTERPRETER` (unless the
+operator already set it). The plugin's own discovery therefore sees the
+host's choice at rung 1 whenever the host found one.
+
+When discovery lands on rung 5 or 6 (no project-owned interpreter), an
+otherwise-`complete` calls/references facet is honestly demoted to
+`degraded` with reason `interpreter_unpinned` — cross-module call/reference
+targets may be missing because pyright resolved against a guessed
+interpreter, even though nothing else went wrong. Fix it by creating
+`.venv` in the project root or setting `LOOMWEAVE_PYTHON_INTERPRETER` to the
+project's interpreter. See
+[ADR-058](../../docs/loomweave/adr/ADR-058-project-interpreter-discovery.md)
+for the full design and the `interpreter_unpinned` coverage semantics.
+
 ## Design references
 
 - [WP3 plan](../../docs/implementation/sprint-1/wp3-python-plugin.md) — task

loomweave_plugin_python-1.5.1/README.md

@@ -0,0 +1,90 @@
+# loomweave-plugin-python
+
+The Python language plugin for [Loomweave](../../README.md). Extracts Python
+entities from source files and serves them to the Loomweave core over the
+JSON-RPC protocol defined in [WP2 L4](../../docs/implementation/sprint-1/wp2-plugin-host.md#l4--json-rpc-method-set--content-length-framing).
+
+**Status**: Python structural extractor. It emits modules, classes, functions,
+`contains`, `calls`, `references`, `imports`, and versioned entity signatures
+for Stable Entity Identity (SEI) matching. It also reads Wardline's NG-25
+trust-vocabulary descriptor without importing Wardline and emits source-observed
+Wardline decorator metadata/tags on decorated entities when a descriptor is
+available.
+
+## Install (development)
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+pip install -e '.[dev]'
+```
+
+This places `loomweave-plugin-python` on your `$PATH` and installs the
+dev-time toolchain (`ruff`, `mypy`, `pytest`, `pytest-cov`, `pre-commit`).
+
+## ADR-023 tooling gates
+
+Every commit must pass all four:
+
+```bash
+ruff check plugins/python
+ruff format --check plugins/python
+mypy --strict plugins/python
+pytest plugins/python
+```
+
+CI runs the same four gates in the `python-plugin` job.
+
+## Interpreter discovery
+
+`pyright-langserver` type-checks against whatever `python` it finds — the
+plugin points it at the project's own interpreter deterministically, rather
+than trusting whatever happened to be first on the launching process's
+`PATH` (clarion-5cf9643de9). `discover_project_interpreter`
+(`src/loomweave_plugin_python/interpreter.py`) walks a fixed order and stops
+at the first usable candidate — a **regular** file (`Path.is_file()`) that
+passes `os.access(path, os.X_OK)`:
+
+| Rung | Source | Pinned? |
+|---|---|---|
+| 1 | `LOOMWEAVE_PYTHON_INTERPRETER` env var names an executable file | yes |
+| 2 | `<project_root>/.venv/bin/python` | yes |
+| 3 | `$VIRTUAL_ENV/bin/python` | yes |
+| 4 | `$CONDA_PREFIX/bin/python` | yes |
+| 5 | first `python` / `python3` on `PATH` | no |
+| 6 | nothing found | no |
+
+An empty env value counts as unset at every rung. The returned path is
+absolute and lexically normalised but **never symlink-resolved** — a venv's
+`bin/python` is typically a symlink to the base interpreter, and pyright
+needs the symlink path to stay inside the venv's `site-packages`.
+
+This order is a cross-language contract shared with the Rust host
+(`crates/loomweave-core/src/plugin/interpreter.rs`); the host runs the same
+discovery and, for a `[capabilities.runtime.pyright]` plugin, exports its
+pinned answer to the child as `LOOMWEAVE_PYTHON_INTERPRETER` (unless the
+operator already set it). The plugin's own discovery therefore sees the
+host's choice at rung 1 whenever the host found one.
+
+When discovery lands on rung 5 or 6 (no project-owned interpreter), an
+otherwise-`complete` calls/references facet is honestly demoted to
+`degraded` with reason `interpreter_unpinned` — cross-module call/reference
+targets may be missing because pyright resolved against a guessed
+interpreter, even though nothing else went wrong. Fix it by creating
+`.venv` in the project root or setting `LOOMWEAVE_PYTHON_INTERPRETER` to the
+project's interpreter. See
+[ADR-058](../../docs/loomweave/adr/ADR-058-project-interpreter-discovery.md)
+for the full design and the `interpreter_unpinned` coverage semantics.
+
+## Design references
+
+- [WP3 plan](../../docs/implementation/sprint-1/wp3-python-plugin.md) — task
+  ledger, lock-ins, and UQ resolutions.
+- [ADR-003](../../docs/loomweave/adr/ADR-003-entity-id-scheme.md) — 3-segment
+  `EntityId` format this plugin produces.
+- [ADR-018](../../docs/loomweave/adr/ADR-018-identity-reconciliation.md) —
+  cross-product identity join with Wardline.
+- [ADR-022](../../docs/loomweave/adr/ADR-022-core-plugin-ontology.md) —
+  manifest schema and ontology-boundary enforcement.
+- [ADR-023](../../docs/loomweave/adr/ADR-023-tooling-baseline.md) — the four
+  Python gates and the `pre-commit` setup.

{loomweave_plugin_python-1.3.1 → loomweave_plugin_python-1.5.1}/plugin.toml

@@ -1,7 +1,7 @@
 [plugin]
 name = "loomweave-plugin-python"
 plugin_id = "python"
-version = "1.3.1"
+version = "1.5.1"
 protocol_version = "1.0"
 # Bare basename per ADR-021 §Layer 1 + WP2 scrub commit eb0a41d — the host
 # refuses manifests whose `executable` carries any path component.
@@ -10,10 +10,11 @@ language = "python"
 extensions = ["py"]
 
 [capabilities.runtime]
-# Plugin's declared RSS envelope (MiB). Effective prlimit is
-# min(this, core default 2 GiB). Pyright's Node-based language server
-# inherits this limit from the plugin process, so B.4* declares the core
-# ceiling rather than the Sprint-1 CPython-only working set.
+# Plugin's declared RSS envelope (MiB). For plugins declaring
+# [capabilities.runtime.pyright] this documents resident memory only: the
+# host applies its 8 GiB language-server RLIMIT_AS ceiling
+# (LANGUAGE_SERVER_MAX_AS_MIB, ADR-021 §2d amendment) because pyright's
+# Node/V8 process reserves virtual space far beyond its RSS.
 expected_max_rss_mb = 2048
 # Triggers LMWV-INFRA-PLUGIN-ENTITY-OVERRUN-WARNING well before the 500k
 # core cap (warning emission itself is deferred to Tier B — Sprint 1
@@ -47,16 +48,41 @@ edge_kinds = ["contains", "calls", "references", "imports", "inherits_from", "de
 rule_id_prefix = "LMWV-PY-"
 # Bumps per ADR-027 when the entity/edge/rule set shifts. Phase 3 Task 3 is a
 # MINOR bump (additive `imports` edge kind); 0.8.0 is the additive
-# `inherits_from` + `decorates` MINOR bump (clarion-43416be550). NOTE:
+# `inherits_from` + `decorates` MINOR bump (clarion-43416be550); 0.9.0 is the
+# additive `public-surface` reachability-root tag (clarion-4ec50f3d92) — a
+# no-`__all__` library's public defs/classes are now tagged as roots; 0.10.0
+# adds module-level `exported-api` for explicit `__all__` re-export/imported-name
+# surfaces without double-counting local function/class exports, including
+# literal `__all__ += [...]` extensions; 0.11.0 adds manual main-guard,
+# runner-wrapper, `sys.argv`, and argparse `cli-command` tagging; 0.12.0
+# declares the complete static classifier set so supported-empty results are
+# distinguishable from unsupported classifiers and forces unchanged files to
+# re-dispatch. Classifier declarations do not create entity-tag rows. NOTE:
 # ADR-007's summary-cache key is the 5-tuple (entity_id, content_hash,
 # prompt_template_id, model_tier, guidance_fingerprint) — ontology_version is
 # handshake-validation, NOT a cache-key component. New edge rows miss the
 # cache by component-1 of the 5-tuple organically (no edges live in the
 # 5-tuple yet anyway).
-ontology_version = "0.8.0"
+ontology_version = "0.12.0"
+classifier_tags = [
+    "cli-command",
+    "data-model",
+    "entry-point",
+    "exported-api",
+    "framework-handler",
+    "http-route",
+    "public-surface",
+    "test",
+]
 
 [integrations.wardline]
 expected_descriptor_version = "wardline-generic-2"
+# The dual-accept set, as `schema@version` PAIRS. A version-only list would
+# destroy the schema/version association the gate rests on (re-admitting
+# "version alone unlocks v2 parsing"). A space-separated STRING, never a TOML
+# array: manifest.rs:137 deserialises this table as BTreeMap<String, String>,
+# so an array value is a hard manifest-parse failure.
+accepted_descriptors = "wardline.vocabulary/v1@wardline-generic-2 wardline.vocabulary/v2@wardline-generic-3"
 
 [ontology.roles]
 file_scope = ["module"]

{loomweave_plugin_python-1.3.1 → loomweave_plugin_python-1.5.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "loomweave-plugin-python"
-version = "1.3.1"
+version = "1.5.1"
 description = "Loomweave Python language plugin — v1.0 release"
 readme = "README.md"
 requires-python = ">=3.11"

{loomweave_plugin_python-1.3.1 → loomweave_plugin_python-1.5.1}/src/loomweave_plugin_python/__init__.py

@@ -1,3 +1,3 @@
 """loomweave-plugin-python — Python language plugin for Loomweave."""
 
-__version__ = "1.3.1"
+__version__ = "1.5.1"

loomweave_plugin_python-1.5.1/src/loomweave_plugin_python/call_resolver.py

@@ -0,0 +1,140 @@
+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
+
+
+class CallsEdgeProperties(TypedDict):
+    candidates: list[str]
+
+
+class CallsRawEdge(TypedDict):
+    kind: Literal["calls"]
+    from_id: str
+    to_id: str
+    source_byte_start: int
+    source_byte_end: int
+    confidence: Literal["resolved", "ambiguous"]
+    properties: NotRequired[CallsEdgeProperties]
+
+
+class Finding(TypedDict):
+    subcode: str
+    severity: Literal["info", "warning", "error"]
+    message: str
+    metadata: dict[str, object]
+
+
+class UnresolvedCallSite(TypedDict):
+    caller_entity_id: str
+    site_ordinal: int
+    source_byte_start: int
+    source_byte_end: int
+    callee_expr: str
+
+
+class FacetCoverageWire(TypedDict):
+    """Wire shape of one resolution facet's coverage claim (host contract)."""
+
+    status: Literal["complete", "degraded"]
+    reason: NotRequired[str]
+    transient: bool
+    collateral: bool
+
+
+class ResolutionCoverageWire(TypedDict):
+    calls: FacetCoverageWire
+    references: FacetCoverageWire
+
+
+@dataclass(frozen=True)
+class FacetCoverage:
+    """How much of one resolution facet (calls / references) a file received.
+
+    The resolver degrades to EMPTY evidence -- not an error -- when pyright is
+    unavailable, times out, or has been poisoned for the rest of the run. The
+    host cannot tell that apart from a genuinely call-free file, so it treated
+    the empty result as a completed analysis and its incremental skip pinned
+    the hole for as long as the file's bytes stayed unchanged
+    (clarion-3e517d4aff). This claim rides every ``analyze_file`` result so the
+    host can re-dispatch a ``degraded`` + ``transient`` file next run and name
+    the hole on its read surface.
+
+    ``transient`` is True when re-running the unchanged file could plausibly
+    recover coverage (resolver timeout, crash, poison, unavailable binary) and
+    False for content-determined limits a re-run would hit again (syntax
+    error, per-file site cap, nesting too complex).
+
+    ``collateral`` (clarion-7fc41105ea, ADR-057) is decided by which catch-site
+    built the claim, never by message text. Self-inflicted (``False``) means
+    ONLY: ``pyright_timeout`` on this file's own budget, or
+    ``pyright_transport_failure`` -- pyright died while THIS file's request was
+    in flight (``pyright_local_read_error``, a read error on an unrelated
+    target while pyright stayed alive, is also this file's gap). Everything
+    else is collateral (``True``): ``pyright_restarting`` (found dead on
+    arrival), ``pyright_spawn_failed`` (deferred spawn), and the run-disabled
+    tokens ``pyright_unavailable`` / ``pyright_poisoned`` /
+    ``pyright_restart_cap_exceeded``. The full vocabulary is documented at the
+    top of ``pyright_session.py``.
+    """
+
+    status: Literal["complete", "degraded"] = "complete"
+    reason: str | None = None
+    transient: bool = False
+    # The hole predates this file (pyright already dead, spawn deferred, run
+    # disabled by an EARLIER file's failure): collateral, not this file's
+    # doing. The host dispatches collateral files first so the troublemaker
+    # goes last, and keeps a prior self-inflicted mark sticky across a
+    # collateral run.
+    collateral: bool = False
+
+    @classmethod
+    def degraded(cls, reason: str, *, transient: bool, collateral: bool = False) -> FacetCoverage:
+        return cls(status="degraded", reason=reason, transient=transient, collateral=collateral)
+
+    @property
+    def is_degraded(self) -> bool:
+        return self.status == "degraded"
+
+    def to_wire(self) -> FacetCoverageWire:
+        wire: FacetCoverageWire = {
+            "status": self.status,
+            "transient": self.transient,
+            "collateral": self.collateral,
+        }
+        if self.reason is not None:
+            wire["reason"] = self.reason
+        return wire
+
+
+@dataclass
+class CallResolutionResult:
+    edges: list[CallsRawEdge] = field(default_factory=list)
+    unresolved_call_sites_total: int = 0
+    unresolved_call_sites: list[UnresolvedCallSite] = field(default_factory=list)
+    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)
+    coverage: FacetCoverage = field(default_factory=FacetCoverage)
+
+
+class CallResolver(Protocol):
+    def resolve_calls(
+        self,
+        file_path: str | Path,
+        function_ids: Sequence[str],
+    ) -> CallResolutionResult: ...
+
+
+class NoOpCallResolver:
+    def resolve_calls(
+        self,
+        file_path: str | Path,
+        function_ids: Sequence[str],
+    ) -> CallResolutionResult:
+        _ = (file_path, function_ids)
+        return CallResolutionResult()