loomweave-plugin-python 1.0.0__tar.gz

loomweave_plugin_python-1.0.0/.gitignore

@@ -0,0 +1,48 @@
+.filigree/
+/target
+**/*.rs.bk
+Cargo.lock.bak
+
+# SQLite working files (project-level .loomweave/ is tracked per ADR-005)
+*.db-journal
+*.db-wal
+
+# Rust-analyzer / IDE caches
+/.idea
+/.vscode
+
+# Python (plugins/python/)
+.venv/
+__pycache__/
+*.egg-info/
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+.claude/
+
+.env
+
+# Smoke-test result artifacts (per-run; archived separately at tag-cut)
+tests/e2e/external-operator-smoke-results-*.md
+
+# Generated skill fingerprint (rewritten by `loomweave install --skills`).
+.agents/skills/loomweave-workflow/.fingerprint
+
+# Loomweave runtime artifacts — the index DB, per-project instance fingerprint,
+# and analyze lock change on every run, so they are not tracked
+# (see .loomweave/.gitignore).
+.loomweave/loomweave.db
+.loomweave/instance_id
+.loomweave/loomweave.lock
+
+# Documentation site build output (mkdocs `site_dir`, web/mkdocs.yml).
+/site-build/
+
+# Filigree-managed docs — a running filigree process rewrites its managed
+# instruction blocks in these every session; untracked to avoid diff churn
+# (filigree regenerates them on demand).
+AGENTS.md
+CLAUDE.md
+.agents/skills/filigree-workflow/SKILL.md

loomweave_plugin_python-1.0.0/PKG-INFO

@@ -0,0 +1,73 @@
+Metadata-Version: 2.4
+Name: loomweave-plugin-python
+Version: 1.0.0
+Summary: Loomweave Python language plugin — v1.0 release
+Author-email: John Morrissey <qacona@gmail.com>
+Classifier: Development Status :: 4 - Beta
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.11
+Requires-Dist: packaging>=24
+Requires-Dist: pyright==1.1.409
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == 'dev'
+Requires-Dist: mypy>=1.11; extra == 'dev'
+Requires-Dist: pip-audit>=2.9; extra == 'dev'
+Requires-Dist: pre-commit>=3.8; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Requires-Dist: types-pyyaml>=6.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# 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.
+
+## 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.0.0/README.md

@@ -0,0 +1,49 @@
+# 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.
+
+## 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.0.0/plugin.toml

@@ -0,0 +1,71 @@
+[plugin]
+name = "loomweave-plugin-python"
+plugin_id = "python"
+version = "1.0.0"
+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.
+executable = "loomweave-plugin-python"
+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.
+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
+# only lands the declaration).
+expected_entities_per_file = 5000
+# Wardline semantic extraction reads the NG-25 vocabulary descriptor without
+# importing Wardline, then emits source-observed decorator metadata on entities.
+wardline_aware = true
+# v0.1 rejects `true` at initialize with LMWV-INFRA-MANIFEST-UNSUPPORTED-CAPABILITY.
+reads_outside_project_root = false
+
+[capabilities.runtime.pyright]
+pin = "1.1.409"
+
+[ontology]
+# Sprint 2 B.2: classes + modules join the kind set. B.3 (ADR-026) adds
+# the first edge kind, `contains`. B.4* adds scan-time `calls` edges.
+# B.5* adds scan-time `references` edges. Phase 3 Task 3 adds scan-time
+# `imports` candidate edges.
+entity_kinds = ["function", "class", "module"]
+edge_kinds = ["contains", "calls", "references", "imports"]
+# Per ADR-022: uppercase `LMWV-{PLUGIN_ID_UPPER}-`. Reserved at parse
+# against the LMWV-INFRA-* and LMWV-FACT-* namespaces.
+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). 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.7.0"
+
+[integrations.wardline]
+expected_descriptor_version = "wardline-generic-2"
+
+[ontology.roles]
+file_scope = ["module"]
+callable = ["function"]
+syntax_degraded_module = ["module"]
+
+# SEI signature declaration (ADR-038 REQ-C-01 / Wave 1). The plugin emits a
+# versioned `signature` object per function/class entity, stored verbatim by the
+# core and compared by string equality as the matcher's move-case input. Modules
+# and packages declare no signature (the move case abstains for them — fail
+# closed). A `schema_version` bump voids cached signature equality.
+[signature]
+schema_version = 1
+
+[signature.schemas.function]
+v = 1
+fields = ["params", "return_ann"]
+
+[signature.schemas.class]
+v = 1
+fields = ["bases"]

loomweave_plugin_python-1.0.0/pyproject.toml

@@ -0,0 +1,104 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "loomweave-plugin-python"
+version = "1.0.0"
+description = "Loomweave Python language plugin — v1.0 release"
+readme = "README.md"
+requires-python = ">=3.11"
+authors = [{ name = "John Morrissey", email = "qacona@gmail.com" }]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+]
+dependencies = [
+    "packaging>=24",
+    "pyright==1.1.409",
+    "pyyaml>=6.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "pytest-cov>=5.0",
+    "ruff>=0.6",
+    "mypy>=1.11",
+    "pre-commit>=3.8",
+    "pip-audit>=2.9",
+    "build>=1.2",
+    "types-PyYAML>=6.0",
+]
+
+[project.scripts]
+loomweave-plugin-python = "loomweave_plugin_python.__main__:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/loomweave_plugin_python"]
+
+[tool.hatch.build.targets.wheel.shared-data]
+# Route plugin.toml into <install-prefix>/share/loomweave/plugins/<suffix>/ so
+# WP2's L9 install-prefix fallback finds it. The <suffix> is produced by
+# `discovery.rs::strip_prefix("loomweave-plugin-")` on the binary name, so for
+# loomweave-plugin-python the suffix is "python" — the target directory must
+# match that basename exactly.
+"plugin.toml" = "share/loomweave/plugins/python/plugin.toml"
+
+[tool.ruff]
+target-version = "py311"
+line-length = 100
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = ["ALL"]
+ignore = [
+    "D",      # pydocstyle relaxed per ADR-023
+    "COM812", # conflicts with ruff format
+    "ISC001", # conflicts with ruff format
+    "CPY",    # copyright headers are not our convention
+    "ANN401", # Any is legitimate for JSON-RPC payload fields (shape is open)
+    "TRY003", # short composed exception messages are fine
+]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**" = [
+    "S101",    # assert is the whole point of tests
+    "PLR2004", # magic numbers are fine in test expectations
+    "ANN",     # type annotations optional in tests
+    "INP001",  # tests/ is a namespace package
+    "S108",    # hard-coded /tmp paths are test fixtures, not real I/O
+    "E501",    # long assert messages in test failures are fine
+]
+
+[tool.ruff.lint.mccabe]
+# Dispatch loops naturally exceed the default 10; 15 matches our Rust clippy.toml.
+max-complexity = 15
+
+[tool.ruff.lint.pylint]
+max-returns = 10
+max-branches = 15
+
+[tool.ruff.format]
+# defaults: double quotes, space indent, trailing commas where appropriate
+
+[tool.mypy]
+python_version = "3.11"
+strict = true
+warn_unused_configs = true
+files = ["src", "tests"]
+
+[[tool.mypy.overrides]]
+module = "yaml"
+ignore_missing_imports = true
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "--strict-markers --cov=loomweave_plugin_python --cov-report=term-missing --cov-fail-under=85"
+pythonpath = ["src"]
+markers = [
+    "pyright: requires pyright-langserver on PATH or in the active virtualenv",
+    "slow: exercises subprocess or scale behavior that is slower than unit tests",
+]

loomweave_plugin_python-1.0.0/src/loomweave_plugin_python/__init__.py

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

loomweave_plugin_python-1.0.0/src/loomweave_plugin_python/__main__.py

@@ -0,0 +1,15 @@
+"""Entry point for the ``loomweave-plugin-python`` executable.
+
+Installs stdout discipline (``stdout_guard``) and hands control to the
+JSON-RPC server loop. ``sys.exit`` threads the server's exit code out to
+the host process.
+"""
+
+from __future__ import annotations
+
+import sys
+
+from loomweave_plugin_python.server import main
+
+if __name__ == "__main__":
+    sys.exit(main())

loomweave_plugin_python-1.0.0/src/loomweave_plugin_python/call_resolver.py

@@ -0,0 +1,65 @@
+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
+
+
+@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)
+
+
+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()

loomweave_plugin_python-1.0.0/src/loomweave_plugin_python/entity_id.py

@@ -0,0 +1,75 @@
+"""L2 3-segment EntityId assembler matching WP1's Rust ``entity_id()`` byte-for-byte.
+
+Per ADR-003 + ADR-022, every Loomweave entity has a 3-segment ID of the
+form ``{plugin_id}:{kind}:{canonical_qualified_name}``.
+
+Validation (mirrors ``crates/loomweave-core/src/entity_id.rs``):
+
+- ``plugin_id`` and ``kind`` must match the identifier grammar
+  ``[a-z][a-z0-9_]*`` (ADR-022).
+- No segment may contain a literal ``:`` (reserved separator).
+- No segment may be empty.
+
+The shared fixture ``fixtures/entity_id.json`` (Task 5) drives the
+cross-language parity check: both the Rust assembler and this Python
+assembler consume the same fixture rows and must produce identical
+strings byte-for-byte.
+"""
+
+from __future__ import annotations
+
+import re
+
+_GRAMMAR = re.compile(r"^[a-z][a-z0-9_]*$")
+
+
+class EntityIdError(ValueError):
+    """Base class for all ``entity_id()`` validation failures."""
+
+
+class EmptySegmentError(EntityIdError):
+    """A segment (``plugin_id``, ``kind``, or ``canonical_qualified_name``) was empty."""
+
+    def __init__(self, field: str) -> None:
+        super().__init__(f"segment {field} empty")
+        self.field = field
+
+
+class GrammarViolationError(EntityIdError):
+    """A segment did not match the ADR-022 grammar ``[a-z][a-z0-9_]*``."""
+
+    def __init__(self, field: str, value: str) -> None:
+        super().__init__(f"segment {field} violates ADR-022 grammar [a-z][a-z0-9_]*: {value!r}")
+        self.field = field
+        self.value = value
+
+
+class SegmentContainsColonError(EntityIdError):
+    """A segment contained the reserved ``:`` separator (UQ-WP1-07)."""
+
+    def __init__(self, field: str, value: str) -> None:
+        super().__init__(f"segment {field} contains reserved ':' separator: {value!r}")
+        self.field = field
+        self.value = value
+
+
+def _validate_grammar(field: str, value: str) -> None:
+    """Mirror ``validate_grammar`` in the Rust side — empty, colon, then regex."""
+    if not value:
+        raise EmptySegmentError(field)
+    if ":" in value:
+        raise SegmentContainsColonError(field, value)
+    if not _GRAMMAR.fullmatch(value):
+        raise GrammarViolationError(field, value)
+
+
+def entity_id(plugin_id: str, kind: str, canonical_qualified_name: str) -> str:
+    """Assemble the 3-segment EntityId string with full validation."""
+    _validate_grammar("plugin_id", plugin_id)
+    _validate_grammar("kind", kind)
+    qn_field = "canonical_qualified_name"
+    if not canonical_qualified_name:
+        raise EmptySegmentError(qn_field)
+    if ":" in canonical_qualified_name:
+        raise SegmentContainsColonError(qn_field, canonical_qualified_name)
+    return f"{plugin_id}:{kind}:{canonical_qualified_name}"