loomweave-plugin-python 1.3.1__py3-none-any.whl → 1.4.0__py3-none-any.whl

loomweave_plugin_python/__init__.py

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

loomweave_plugin_python/extractor.py

@@ -1058,7 +1058,10 @@ class _WalkState:
     seen_ids: set[str]
     file_path: str
     wardline_vocabulary: WardlineVocabulary | None = None
-    exported_names: set[str] = field(default_factory=set)
+    # ``None`` means no ``__all__`` was declared (triggers the public-surface
+    # heuristic); a set (possibly empty) means ``__all__`` was declared
+    # explicitly (clarion-4ec50f3d92).
+    exported_names: set[str] | None = None
     duplicate_entities_dropped: int = 0
 
 
@@ -1274,16 +1277,39 @@ def _attach_wardline_entity_metadata(
         }
 
 
-def _module_export_names(tree: ast.Module) -> set[str]:
-    exported: set[str] = set()
+def _module_export_names(tree: ast.Module) -> set[str] | None:
+    """Names declared in a module-level ``__all__``, or ``None`` when no
+    ``__all__`` is declared at all (clarion-4ec50f3d92).
+
+    The ``None`` vs empty-set distinction is load-bearing for the public-surface
+    fallback: an explicit ``__all__ = []`` declares an *empty* public surface
+    (no roots), whereas the *absence* of ``__all__`` triggers the PEP 8
+    public-surface heuristic in :func:`_function_tags` / :func:`_class_tags`.
+    Both plain (``__all__ = [...]``) and annotated (``__all__: list[str] = [...]``)
+    assignments count as a declaration so an annotated ``__all__`` is never
+    mistaken for an absent one. A non-literal value (``__all__ = a + b``, an
+    alias, a comprehension) or an annotation-only stub (``__all__: list[str]``
+    with no value) counts as a declaration but contributes no names — i.e. it is
+    treated as an explicit *empty* surface, which suppresses ``public-surface``;
+    this matches the prior behaviour for non-literal ``__all__`` (no names were
+    ever extracted from it). Bare ``__all__ += [...]`` (``ast.AugAssign`` without a
+    prior ``=`` assignment) is intentionally not handled: it is a runtime
+    ``NameError`` and so unreachable in valid Python."""
+    exported: set[str] | None = None
     for statement in tree.body:
-        if not isinstance(statement, ast.Assign):
+        if isinstance(statement, ast.Assign):
+            targets: list[ast.expr] = statement.targets
+            value: ast.expr | None = statement.value
+        elif isinstance(statement, ast.AnnAssign):
+            targets = [statement.target]
+            value = statement.value
+        else:
             continue
-        if not any(
-            isinstance(target, ast.Name) and target.id == "__all__" for target in statement.targets
-        ):
+        if not any(isinstance(target, ast.Name) and target.id == "__all__" for target in targets):
             continue
-        match statement.value:
+        if exported is None:
+            exported = set()
+        match value:
             case ast.List(elts=elts) | ast.Tuple(elts=elts) | ast.Set(elts=elts):
                 for elt in elts:
                     if isinstance(elt, ast.Constant) and isinstance(elt.value, str):
@@ -1321,16 +1347,18 @@ def _is_module_level(parents: list[ast.AST]) -> bool:
 def _function_tags(
     node: ast.FunctionDef | ast.AsyncFunctionDef,
     parents: list[ast.AST],
-    exported_names: set[str],
+    exported_names: set[str] | None,
 ) -> set[str]:
     tags: set[str] = set()
-    if _is_module_level(parents) and node.name == "main":
-        tags.add("entry-point")
-    if _is_module_level(parents) and node.name in exported_names:
-        tags.add("exported-api")
-    if node.name.startswith("test_") or any(
+    module_level = _is_module_level(parents)
+    is_test = node.name.startswith("test_") or any(
         isinstance(parent, ast.ClassDef) and parent.name.startswith("Test") for parent in parents
-    ):
+    )
+    if module_level and node.name == "main":
+        tags.add("entry-point")
+    if module_level:
+        tags.update(_module_surface_tag(node.name, exported_names, is_test=is_test))
+    if is_test:
         tags.add("test")
     decorator_names = _decorator_names(node)
     if any(_last_name(name) in _HTTP_ROUTE_DECORATOR_NAMES for name in decorator_names):
@@ -1340,11 +1368,38 @@ def _function_tags(
     return tags
 
 
-def _class_tags(node: ast.ClassDef, parents: list[ast.AST], exported_names: set[str]) -> set[str]:
+def _module_surface_tag(name: str, exported_names: set[str] | None, *, is_test: bool) -> set[str]:
+    """Root tag for a module-level public entity (clarion-4ec50f3d92).
+
+    With a declared ``__all__`` (``exported_names is not None``) only listed
+    names are ``exported-api`` — the declaration is **authoritative**: a name the
+    author explicitly exported is an exported root regardless of its spelling
+    (so a ``Test``/``test_``-named or underscore-prefixed name listed in
+    ``__all__`` still gets ``exported-api``). With no ``__all__`` at all
+    (``None``) every non-underscore, non-test module-level def/class is the
+    module's public surface by PEP 8 convention, tagged ``public-surface``: a
+    reachability root of lower confidence than a declared export. It is a
+    fail-toward-live posture for public code invoked from outside the static call
+    graph (a library's consumers, or an app's framework-dispatched / DI / CLI
+    handlers), so a codebase that does not exhaustively declare ``__all__`` is not
+    read as mostly dead. ``is_test`` gates only this inferred fallback — test
+    entities are already roots via the ``test`` tag and are not a module's public
+    API; it never suppresses a declared export."""
+    if exported_names is None:
+        if is_test or name.startswith("_"):
+            return set()
+        return {"public-surface"}
+    return {"exported-api"} if name in exported_names else set()
+
+
+def _class_tags(
+    node: ast.ClassDef, parents: list[ast.AST], exported_names: set[str] | None
+) -> set[str]:
     tags: set[str] = set()
-    if _is_module_level(parents) and node.name in exported_names:
-        tags.add("exported-api")
-    if node.name.startswith("Test"):
+    is_test = node.name.startswith("Test")
+    if _is_module_level(parents):
+        tags.update(_module_surface_tag(node.name, exported_names, is_test=is_test))
+    if is_test:
         tags.add("test")
     decorator_names = _decorator_names(node)
     base_names = [_expr_qualified_name(base) for base in node.bases]

loomweave_plugin_python/server.py

@@ -34,7 +34,7 @@ from loomweave_plugin_python.pyright_session import PyrightRunState, PyrightSess
 from loomweave_plugin_python.stdout_guard import install_stdio
 from loomweave_plugin_python.wardline_descriptor import WardlineVocabulary, load_wardline_descriptor
 
-ONTOLOGY_VERSION = "0.8.0"
+ONTOLOGY_VERSION = "0.9.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

{loomweave_plugin_python-1.3.1.data → loomweave_plugin_python-1.4.0.data}/data/share/loomweave/plugins/python/plugin.toml

@@ -1,7 +1,7 @@
 [plugin]
 name = "loomweave-plugin-python"
 plugin_id = "python"
-version = "1.3.1"
+version = "1.4.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.
@@ -47,13 +47,15 @@ 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. 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.9.0"
 
 [integrations.wardline]
 expected_descriptor_version = "wardline-generic-2"

{loomweave_plugin_python-1.3.1.dist-info → loomweave_plugin_python-1.4.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: loomweave-plugin-python
-Version: 1.3.1
+Version: 1.4.0
 Summary: Loomweave Python language plugin — v1.0 release
 Author-email: John Morrissey <qacona@gmail.com>
 Classifier: Development Status :: 4 - Beta

{loomweave_plugin_python-1.3.1.dist-info → loomweave_plugin_python-1.4.0.dist-info}/RECORD

@@ -1,17 +1,17 @@
-loomweave_plugin_python/__init__.py,sha256=F2hCKasKT9GVx-LeFB-lrVGCATmp3bUJPMsqp3sGmac,95
+loomweave_plugin_python/__init__.py,sha256=hs4dysFpi1-vI4oTjEZT2tpWkWjGUjVASqb-5pZ32gM,95
 loomweave_plugin_python/__main__.py,sha256=oy1S1Ru7WdX6jcAVhsqNI25LxAbQq3jHBlETBt20fyM,376
 loomweave_plugin_python/call_resolver.py,sha256=V6w5AEmWgjkKuWdgUPJTXStOavmmbyvjP0PQOeT3xkU,1692
 loomweave_plugin_python/entity_id.py,sha256=l7_5yyh6WVH9xIzrQVCDb2GmBMhovOVmuQezcZIVf8k,2691
-loomweave_plugin_python/extractor.py,sha256=3S98y0CTjapmNnkU_-E5ySUXDeGyXjzQQsIZGhxB3HM,56261
+loomweave_plugin_python/extractor.py,sha256=U5c4LZgD5oBF3r2gFVeEetaPy38bqbRGqBPGpzLe34A,59490
 loomweave_plugin_python/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 loomweave_plugin_python/pyright_session.py,sha256=QWgXlOSgmN29iZ059sJE6hIbogi2mSCR3aTMFITXoyY,67579
 loomweave_plugin_python/qualname.py,sha256=gk6N2e4tMvufnPgpVZLv--c9_9gW5y9YvJIwUArffFg,2102
 loomweave_plugin_python/reference_resolver.py,sha256=hfcKX3WcDL26vEq7Ahdouq7WBs7mqCNy-rBvl8t97iI,2698
-loomweave_plugin_python/server.py,sha256=_MdaoRE1D-4VMvqLw79JyIvBmyqpU540Grk9FIBXSZg,12329
+loomweave_plugin_python/server.py,sha256=kzqXIYpdvJuoBvXIYuhNhYxAdAR8y53g_gnRwWXdlZw,12329
 loomweave_plugin_python/stdout_guard.py,sha256=tUzcXyvXuy3-dXB81_xCNk8KWE3mqtsWSge81KPDhKg,2007
 loomweave_plugin_python/wardline_descriptor.py,sha256=9rU-DhN1USpsHW9hS6YeWFRgGL4xgBeG41Yr1LfK-M4,8136
-loomweave_plugin_python-1.3.1.data/data/share/loomweave/plugins/python/plugin.toml,sha256=pl20Cy5kCXJTUuAj9xoyVCEAMaIxEYZFzIpsR_tREG0,3580
-loomweave_plugin_python-1.3.1.dist-info/METADATA,sha256=TDhOrbMSA_cv8r0qtWuS5OoZugP_y9YdhytrSZ8YLaI,2751
-loomweave_plugin_python-1.3.1.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
-loomweave_plugin_python-1.3.1.dist-info/entry_points.txt,sha256=X1DQOYU5o1z2lBOJoh9JgQR5pg9fd_Yd8KozTHdfZqA,82
-loomweave_plugin_python-1.3.1.dist-info/RECORD,,
+loomweave_plugin_python-1.4.0.data/data/share/loomweave/plugins/python/plugin.toml,sha256=NqBhIqUVl4UMmueS-tNJUarkhoX68NqvRStO70L4HGE,3740
+loomweave_plugin_python-1.4.0.dist-info/METADATA,sha256=8R-BVHqL2iBXXs1umMRTAK9nzaX1VMWivkQ_Xr4C8JQ,2751
+loomweave_plugin_python-1.4.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+loomweave_plugin_python-1.4.0.dist-info/entry_points.txt,sha256=X1DQOYU5o1z2lBOJoh9JgQR5pg9fd_Yd8KozTHdfZqA,82
+loomweave_plugin_python-1.4.0.dist-info/RECORD,,