sphinx-codelinks 2.0.0__tar.gz → 2.1.0__tar.gz

{sphinx_codelinks-2.0.0 → sphinx_codelinks-2.1.0}/PKG-INFO

@@ -1,19 +1,20 @@
 Metadata-Version: 2.4
 Name: sphinx-codelinks
-Version: 2.0.0
+Version: 2.1.0
 Summary: Fast Source Code Traceability for Sphinx-Needs
 Author-email: team useblocks <info@useblocks.com>
 Maintainer-email: Marco Heinemann <marco.heinemann@useblocks.com>, Jui-Wen Chen <jui-wen.chen@useblocks.com>
 Requires-Python: >=3.11,<4
 Description-Content-Type: text/markdown
+Classifier: Typing :: Typed
 License-File: LICENSE
 Requires-Dist: comment-parser>=1.2.4
 Requires-Dist: ignore-python>=0.3.3
 Requires-Dist: typer>=0.16.0
 Requires-Dist: jsonschema
 Requires-Dist: sphinx>=7.4,<10
-Requires-Dist: sphinx-needs>=9.0.0,<10
-Requires-Dist: ub-project>=1.1.0,<2
+Requires-Dist: sphinx-needs>=9.2.0,<10
+Requires-Dist: ub-project>=1.2.0,<2
 Requires-Dist: jinja2
 Requires-Dist: pygments
 Requires-Dist: docutils>=0.21
@@ -28,7 +29,7 @@ Requires-Dist: tree-sitter-rust>=0.23.0
 Requires-Dist: tree-sitter-go>=0.23.0
 Requires-Dist: tree-sitter-json>=0.24.8
 Requires-Dist: tree-sitter-bash>=0.25.1
-Requires-Dist: furo>=2024.5.6 ; extra == "docs"
+Requires-Dist: furo>=2025.12.19 ; extra == "docs"
 Requires-Dist: myst-parser>=4.0.0 ; extra == "docs"
 Requires-Dist: sphinx-ai-index>=1.0.0,<2 ; extra == "docs"
 Requires-Dist: sphinx-design>=0.6.1 ; extra == "docs"

{sphinx_codelinks-2.0.0 → sphinx_codelinks-2.1.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "sphinx-codelinks"
-version = "2.0.0"
+version = "2.1.0"
 description = "Fast Source Code Traceability for Sphinx-Needs"
 authors = [{ name = "team useblocks", email = "info@useblocks.com" }]
 maintainers = [
@@ -15,6 +15,7 @@ readme = "README.md"
 # locks, builds and publishes -- the gap shows up only as an install failure for a user on
 # an interpreter inside it.
 requires-python = ">=3.11,<4"
+classifiers = ["Typing :: Typed"]
 dependencies = [
   "comment-parser>=1.2.4",
   "ignore-python>=0.3.3",
@@ -27,8 +28,8 @@ dependencies = [
   # edge. uv never validates a specifier it resolves through `workspace = true` (uv#9811),
   # so the floor is the only statement of what was actually tested, and the cap is what
   # stops a future major being co-installed with a wheel written against this one.
-  "sphinx-needs>=9.0.0,<10",
-  "ub-project>=1.1.0,<2",
+  "sphinx-needs>=9.2.0,<10",
+  "ub-project>=1.2.0,<2",
   "jinja2",
   "pygments",
   "docutils>=0.21",             # the `typing` group's series
@@ -64,7 +65,7 @@ libclang = ["libclang>=16"]
 # the root there re-exports each member's extra (`docs-mounts = ["sphinx-mounts[docs]"]`),
 # because `uv sync --extra` resolves against the workspace root rather than the member.
 docs = [
-  "furo>=2024.5.6",
+  "furo>=2025.12.19",
   "myst-parser>=4.0.0",
   "sphinx-ai-index>=1.0.0,<2",
   "sphinx-design>=0.6.1",
@@ -84,9 +85,10 @@ Changelog = "https://github.com/useblocks/sphinx-needs/blob/master/packages/sphi
 requires = ["flit_core >=3.4,<4"]
 build-backend = "flit_core.buildapi"
 
-# Deliberately NO `[tool.flit.sdist]`: this distribution carries no non-Python payload, so
-# flit's module-only sdist is byte-for-byte the shape already published on PyPI, and
-# nothing downstream builds from it -- the git pins in the wild clone the repository.
+# Deliberately NO `[tool.flit.sdist]`: this distribution carries nothing outside the module
+# (its `py.typed` marker included, which flit ships as part of it), so flit's module-only
+# sdist is the shape already published on PyPI, and nothing downstream builds from it --
+# the git pins in the wild clone the repository.
 # Everything else -- ruff, ty, pytest and the dependency groups -- is the ROOT's, and
 # `tools/src/sn_tools/check_workspace.py` check (7) refuses those tables here: a member
 # `[tool.ruff]` does not extend the root's configuration, it replaces it.

{sphinx_codelinks-2.0.0 → sphinx_codelinks-2.1.0}/src/sphinx_codelinks/__init__.py

@@ -2,7 +2,7 @@
 
 from sphinx_codelinks.sphinx_extension.source_tracing import setup
 
-__version__ = "2.0.0"
+__version__ = "2.1.0"
 
 __all__ = [
     "__version__",

{sphinx_codelinks-2.0.0 → sphinx_codelinks-2.1.0}/src/sphinx_codelinks/analyse/analyse.py

@@ -9,6 +9,7 @@ from tree_sitter import Node as TreeSitterNode
 from tree_sitter import Parser, Query
 
 from sphinx_codelinks.analyse import multiline_parser, utils
+from sphinx_codelinks.analyse.entity import CodeScope, code_scope, scope_language
 from sphinx_codelinks.analyse.models import (
     MarkedContentType,
     MultilineNeed,
@@ -363,9 +364,14 @@ class SourceAnalyse:
             # ``c`` is a LibclangComment duck-typing the tree-sitter Node
             # interface SourceComment reads (``.text`` / ``.start_point.row``);
             # the Node-only path (find_associated_scope) is guarded by
-            # ``is_libclang`` so it never runs on these.
+            # ``is_libclang`` so it never runs on these. The cast is that duck typing,
+            # which is why ty, seeing two unrelated classes, has to be told.
             src_comments = [
-                SourceComment(cast("TreeSitterNode", c), c.column) for c in comments
+                SourceComment(
+                    cast("TreeSitterNode", c),  # ty: ignore[disjoint-cast]
+                    c.column,
+                )
+                for c in comments
             ]
             src_file = SourceFile(src_path.absolute())
             src_file.add_comments(src_comments)
@@ -415,11 +421,13 @@ class SourceAnalyse:
         src_comment: SourceComment,
         first_row: int | None = None,
         first_column: int | None = None,
+        *,
+        scope: CodeScope | None = None,
     ) -> list[NeedIdRefs]:
         """Extract need-ids-refs from a comment.
 
         ``text`` starts at ``first_row`` and ``first_column`` (by default the
-        comment's own row and column).
+        comment's own row and column). ``scope`` is the named ``tagged_scope``.
         """
         if first_row is None:
             first_row = src_comment.node.start_point.row
@@ -463,6 +471,7 @@ class SourceAnalyse:
                     tagged_scope,
                     need_ids,
                     marker,
+                    scope=scope,
                 )
             )
         return anchors
@@ -573,11 +582,13 @@ class SourceAnalyse:
         oneline_comment_style: OneLineCommentStyle,
         first_row: int | None = None,
         first_column: int | None = None,
+        *,
+        scope: CodeScope | None = None,
     ) -> list[OneLineNeed]:
         """Extract the one-line needs of a comment.
 
         ``text`` starts at ``first_row`` and ``first_column`` (by default the
-        comment's own row and column).
+        comment's own row and column). ``scope`` is the named ``tagged_scope``.
         """
         if first_row is None:
             first_row = src_comment.node.start_point.row
@@ -621,6 +632,7 @@ class SourceAnalyse:
                     src_comment,
                     tagged_scope,
                     resolved,  # int arguments were deleted  # ty: ignore[invalid-argument-type]
+                    scope=scope,
                 )
             )
         return oneline_needs
@@ -689,11 +701,7 @@ class SourceAnalyse:
             ),
             run.comments[0],
         )
-        tagged_scope: TreeSitterNode | None = None
-        if not getattr(src_comment.node, "is_libclang", False):
-            tagged_scope = utils.find_associated_scope(
-                src_comment.node, self.analyse_config.comment_type
-            )
+        tagged_scope, scope = self._associate(src_comment, filepath)
         lineno = block.open_row + 1
         remote_url = self.git_remote_url
         if self.git_remote_url and self.git_commit_rev:
@@ -713,15 +721,6 @@ class SourceAnalyse:
             if block.content_start is not None
             else None
         )
-        scope = (
-            {
-                "kind": tagged_scope.type,
-                "start": tagged_scope.start_point.row + 1,
-                "end": tagged_scope.end_point.row + 1,
-            }
-            if tagged_scope is not None
-            else None
-        )
         source: dict[str, Any] = {
             "project": self.name,
             "path": _relative_posix(filepath, self.project_path),
@@ -742,6 +741,25 @@ class SourceAnalyse:
             block.need,
             block.markup,
             source,
+            scope=scope,
+        )
+
+    def _associate(
+        self, src_comment: SourceComment, filepath: Path
+    ) -> tuple[TreeSitterNode | None, CodeScope | None]:
+        """The entity a comment of ``filepath`` is attached to: its node and its
+        ``scope`` object.
+
+        A libclang comment has no tree-sitter node, so it is attached to nothing.
+        """
+        if getattr(src_comment.node, "is_libclang", False):
+            return None, None
+        comment_type = self.analyse_config.comment_type
+        association = utils.associate(src_comment.node, comment_type)
+        if association is None or not association.node.text:
+            return None, None
+        return association.node, code_scope(
+            association, comment_type, scope_language(comment_type, filepath)
         )
 
     def extract_marked_content(self) -> None:
@@ -756,12 +774,7 @@ class SourceAnalyse:
             )
             if not filepath:
                 continue
-            if getattr(src_comment.node, "is_libclang", False):
-                tagged_scope: TreeSitterNode | None = None
-            else:
-                tagged_scope = utils.find_associated_scope(
-                    src_comment.node, self.analyse_config.comment_type
-                )
+            tagged_scope, scope = self._associate(src_comment, filepath)
             for text, first_row, first_column in _scanned_texts(
                 src_comment, claimed.get(id(src_comment))
             ):
@@ -774,6 +787,7 @@ class SourceAnalyse:
                             src_comment,
                             first_row,
                             first_column,
+                            scope=scope,
                         )
                     )
                 if self.analyse_config.get_oneline_needs:
@@ -786,6 +800,7 @@ class SourceAnalyse:
                             self.analyse_config.oneline_comment_style,
                             first_row,
                             first_column,
+                            scope=scope,
                         )
                     )