sphinx-codelinks 1.1.0__tar.gz → 1.3.0__tar.gz

{sphinx_codelinks-1.1.0 → sphinx_codelinks-1.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sphinx-codelinks
-Version: 1.1.0
+Version: 1.3.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>
@@ -8,12 +8,12 @@ Requires-Python: >= 3.12
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: comment-parser>=1.2.4
-Requires-Dist: gitignore-parser>=0.1.11
+Requires-Dist: ignore-python>=0.3.3
 Requires-Dist: typer>=0.16.0
 Requires-Dist: click < 8.2
 Requires-Dist: jsonschema
-Requires-Dist: sphinx>=7.4,<9
-Requires-Dist: sphinx-needs>=4.2.0
+Requires-Dist: sphinx>=7.4,<10
+Requires-Dist: sphinx-needs>=5,<9
 Requires-Dist: jinja2
 Requires-Dist: pygments
 Requires-Dist: docutils
@@ -23,6 +23,9 @@ Requires-Dist: tree-sitter-python>=0.23.6
 Requires-Dist: tree-sitter~=0.25.1
 Requires-Dist: tree-sitter-c-sharp>=0.23.1
 Requires-Dist: tree-sitter-yaml>=0.7.1
+Requires-Dist: tree-sitter-rust>=0.23.0
+Requires-Dist: tree-sitter-go>=0.23.0
+Requires-Dist: tree-sitter-json>=0.24.8
 
 # Sphinx CodeLinks
 

{sphinx_codelinks-1.1.0 → sphinx_codelinks-1.3.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "sphinx-codelinks"
-version = "1.1.0"
+version = "1.3.0"
 description = "Fast Source Code Traceability for Sphinx-Needs"
 authors = [{ name = "team useblocks", email = "info@useblocks.com" }]
 maintainers = [
@@ -12,12 +12,12 @@ readme = "README.md"
 requires-python = ">= 3.12"
 dependencies = [
   "comment-parser>=1.2.4",
-  "gitignore-parser>=0.1.11",
+  "ignore-python>=0.3.3",
   "typer>=0.16.0",
   "click < 8.2",                # click 8.2.* produces empty errors if no args are given
   "jsonschema",
-  "sphinx>=7.4,<9",
-  "sphinx-needs>=4.2.0",        # unconstrained versions, to be pinned by user or Sphinx
+  "sphinx>=7.4,<10",
+  "sphinx-needs>=5,<9",
   "jinja2",
   "pygments",
   "docutils",                   # constrained by user or Sphinx
@@ -29,70 +29,48 @@ dependencies = [
   "tree-sitter~=0.25.1",
   "tree-sitter-c-sharp>=0.23.1",
   "tree-sitter-yaml>=0.7.1",
+  "tree-sitter-rust>=0.23.0",
+  "tree-sitter-go>=0.23.0",
+  "tree-sitter-json>=0.24.8",
 ]
 
 [build-system]
 requires = ["flit_core >=3.4,<4"]
 build-backend = "flit_core.buildapi"
 
-[tool.rye]
-managed = true
-dev-dependencies = [
-  "types-docutils",
-  "types-Pygments",
+[dependency-groups]
+testing = [
+  "pytest>=8.2.2",
+  "pytest-cov>=5.0.0",
+  "pytest-docker>=3.1.2",
   "syrupy>=4.9.1",
-  "furo>=2024.5.6",
+  "psutil>=7.0.0",
   "moto ~= 5.0",
-  "mypy>=1.12.1",
+  "toml>=0.10.2",
+  "furo>=2024.5.6",
+]
+docs = [
+  "furo>=2024.5.6",
   "myst-parser>=4.0.0",
-  "pydantic ~= 2.9",
-  "pip-licenses>=5.0.0",
-  "psutil>=7.0.0",
-  "pytest-cov>=5.0.0",
-  "pytest>=8.2.2",
-  "simple-build>=0.0.2",
   "sphinx-design>=0.6.1",
-  "types-psutil>=7.0.0.20250218",
-  "uv>=0.5.5",
-  "pytest-docker>=3.1.2",
-  "shiv>=1.0.8",
-  "insta-science>=0.2.1",
-  "types-jsonschema>=4.23.0.20241208",
-  "toml>=0.10.2",
   "sphinx-code-tabs>=0.5.5",
   "sphinxcontrib-typer>=0.5.1",
   "sphinxcontrib-video>=0.4.1",
 ]
+mypy = [
+  "mypy>=1.12.1",
+  "pydantic ~= 2.9",
+  "types-docutils",
+  "types-Pygments",
+  "types-psutil>=7.0.0.20250218",
+  "types-jsonschema>=4.23.0.20241208",
+]
+ruff = ["ruff>=0.8.0"]
+build = ["simple-build>=0.0.2", "shiv>=1.0.8"]
 
 [project.scripts]
 codelinks = "sphinx_codelinks.cmd:app"
 
-[tool.rye.scripts]
-# linting and formatting
-"mypy:all" = "mypy ."
-"rye:lint" = "rye lint"
-"rye:format" = "rye format"
-"check" = { chain = ["rye:format", "rye:lint", "mypy:all"] }
-# docs html
-"docs:rm" = "rm -rf docs/_build/html"
-"docs" = "sphinx-build -nW --keep-going -b html -T -c docs docs/source docs/_build/html"
-"docs:clean" = { chain = ["docs:rm", "docs"] }
-# needextend demo
-"analyse" = "codelinks analyse tests/data/configs/minimum_config.toml"
-"analyse:rm" = "rm -rf output/marked_content.json"
-"write" = "codelinks write rst output/marked_content.json --outpath tests/data/needextend_demo/needextend.rst"
-"write:rm" = "rm -rf tests/data/needextend_demo/needextend.rst"
-"demo:rm" = "rm -rf tests/data/needextend_demo/_build"
-"demo:build" = "sphinx-build -nW --keep-going -b html -T -c tests/data/needextend_demo tests/data/needextend_demo tests/data/needextend_demo/_build/html"
-"demo:clean" = { chain = [
-  "demo:rm",
-  "analyse:rm",
-  "write:rm",
-  "analyse",
-  "write",
-  "demo:build",
-] }
-
 [tool.ruff.lint]
 extend-select = [
   # "ANN",
@@ -131,15 +109,6 @@ force-sort-within-sections = true
   "PLR2004", # magic-value-comparison - valueable for tests
   "S101",    # assert - needed for tests
 ]
-"**/build_hooks_*/**" = [
-  "S607", # start-process-with-partial-path - pyarmor call in rye context
-  "S603", # subprocess-without-shell-equals-true - pyarmor call
-]
-"scripts/*.py" = [
-  "T201", # print - used for output
-  "S607", # start-process-with-partial-path - pyarmor call in rye context
-  "S603", # subprocess-without-shell-equals-true - build scripts
-]
 "src/sphinx_codelinks/sphinx_extension/debug.py" = [
   "T201",  # print - used for output
   "UP047", # on-pep695-generic-function - it's generic

{sphinx_codelinks-1.1.0 → sphinx_codelinks-1.3.0}/src/sphinx_codelinks/analyse/analyse.py

@@ -1,7 +1,6 @@
 from collections.abc import Generator
 from dataclasses import dataclass
 import json
-import logging
 from pathlib import Path
 from typing import Any, TypedDict
 
@@ -26,14 +25,14 @@ from sphinx_codelinks.config import (
     OneLineCommentStyle,
     SourceAnalyseConfig,
 )
+from sphinx_codelinks.logger import get_logger
 
-# initialize logger
-logger = logging.getLogger(__name__)
-logger.setLevel(logging.INFO)
-# log to the console
-console = logging.StreamHandler()
-console.setLevel(logging.INFO)
-logger.addHandler(console)
+logger = get_logger(__name__)
+
+
+def _count(n: int, noun: str) -> str:
+    """Format ``n noun`` with a naive (append-s) plural for progress summaries."""
+    return f"{n} {noun}" if n == 1 else f"{n} {noun}s"
 
 
 class AnalyseWarningType(TypedDict):
@@ -57,7 +56,10 @@ class SourceAnalyse:
     def __init__(
         self,
         analyse_config: SourceAnalyseConfig,
+        *,
+        name: str = "",
     ) -> None:
+        self.name = name
         self.analyse_config = analyse_config
         self.src_files: list[SourceFile] = []
         self.src_comments: list[SourceComment] = []
@@ -65,7 +67,11 @@ class SourceAnalyse:
         self.oneline_needs: list[OneLineNeed] = []
         self.marked_rst: list[MarkedRst] = []
         self.all_marked_content: list[NeedIdRefs | OneLineNeed | MarkedRst] = []
-        self.git_root: Path | None = utils.locate_git_root(self.analyse_config.src_dir)
+        # Use explicitly configured git_root if provided, otherwise auto-detect
+        if self.analyse_config.git_root is not None:
+            self.git_root: Path | None = self.analyse_config.git_root.resolve()
+        else:
+            self.git_root = utils.locate_git_root(self.analyse_config.src_dir)
         self.git_remote_url: str | None = (
             utils.get_remote_url(self.git_root) if self.git_root else None
         )
@@ -106,9 +112,6 @@ class SourceAnalyse:
             self.src_files.append(src_file)
             self.src_comments.extend(src_comments)
 
-        logger.info(f"Source files loaded: {len(self.src_files)}")
-        logger.info(f"Source comments extracted: {len(self.src_comments)}")
-
     def extract_marker(
         self,
         text: str,
@@ -127,6 +130,7 @@ class SourceAnalyse:
                 yield marker, need_ids, row_offset, start_column, end_column
             row_offset += 1
 
+    # @Extract need ID references from code comments, IMPL_LNK_1, impl, [FE_LNK]
     def extract_anchors(
         self,
         text: str,
@@ -197,20 +201,21 @@ class SourceAnalyse:
                 if not src_comment.source_file:
                     row_offset += 1
                     continue
-                self.oneline_warnings.append(
-                    AnalyseWarning(
-                        str(src_comment.source_file.filepath),
-                        src_comment.node.start_point.row + row_offset + 1,
-                        resolved.msg,
-                        MarkedContentType.need,
-                        resolved.sub_type.value,
-                    )
+                lineno = src_comment.node.start_point.row + row_offset + 1
+                warning = AnalyseWarning(
+                    str(src_comment.source_file.filepath),
+                    lineno,
+                    resolved.msg,
+                    MarkedContentType.need,
+                    resolved.sub_type.value,
                 )
+                self.oneline_warnings.append(warning)
                 row_offset += 1
                 continue
             yield resolved, row_offset
             row_offset += 1
 
+    # @Extract one-line traceability needs from comments, IMPL_ONE_1, impl, [FE_DEF, FE_CMT]
     def extract_oneline_needs(
         self,
         text: str,
@@ -258,6 +263,7 @@ class SourceAnalyse:
             )
         return oneline_needs
 
+    # @Extract marked reStructuredText blocks from comments, IMPL_MRST_1, impl, [FE_RST_EXTRACTION]
     def extract_marked_rst(
         self,
         text: str,
@@ -346,13 +352,6 @@ class SourceAnalyse:
                 if marked_rst:
                     self.marked_rst.append(marked_rst)
 
-        if self.analyse_config.get_need_id_refs:
-            logger.info(f"Need-id-refs extracted: {len(self.need_id_refs)}")
-        if self.analyse_config.get_oneline_needs:
-            logger.info(f"Oneline needs extracted: {len(self.oneline_needs)}")
-        if self.analyse_config.get_rst:
-            logger.info(f"Marked rst extracted: {len(self.marked_rst)}")
-
     def merge_marked_content(self) -> None:
         self.all_marked_content.extend(self.need_id_refs)
         self.oneline_needs.sort(key=lambda x: x.source_map["start"]["row"])
@@ -371,9 +370,23 @@ class SourceAnalyse:
         ]
         with output_path.open("w") as f:
             json.dump(to_dump, f)
-        logger.info(f"Marked content dumped to {output_path}")
 
     def run(self) -> None:
         self.create_src_objects()
         self.extract_marked_content()
         self.merge_marked_content()
+        self._log_summary()
+
+    def _log_summary(self) -> None:
+        """Emit a per-project marker (default-visible) plus a -v breakdown."""
+        label = f"codelinks [{self.name}]" if self.name else "codelinks"
+        logger.info(
+            f"{label}: {_count(len(self.src_files), 'file')}, "
+            f"{_count(len(self.all_marked_content), 'marker')}"
+        )
+        logger.debug(
+            f"{label}: {_count(len(self.src_comments), 'comment')}, "
+            f"{_count(len(self.oneline_needs), 'oneline need')}, "
+            f"{_count(len(self.need_id_refs), 'id-ref')}, "
+            f"{_count(len(self.marked_rst), 'marked-rst block')}"
+        )

{sphinx_codelinks-1.1.0 → sphinx_codelinks-1.3.0}/src/sphinx_codelinks/analyse/oneline_parser.py

@@ -1,17 +1,8 @@
 from dataclasses import dataclass
 from enum import Enum
-import logging
 
 from sphinx_codelinks.config import ESCAPE, UNIX_NEWLINE, OneLineCommentStyle
 
-# initialize logger
-logger = logging.getLogger(__name__)
-logger.setLevel(logging.INFO)
-# log to the console
-console = logging.StreamHandler()
-console.setLevel(logging.INFO)
-logger.addHandler(console)
-
 
 class WarningSubTypeEnum(str, Enum):
     """Enum for warning sub types."""
@@ -31,6 +22,7 @@ class OnelineParserInvalidWarning:
     msg: str
 
 
+# @One-line comment parser for traceability markers, IMPL_OLP_1, impl, [FE_DEF, FE_CMT]
 def oneline_parser(  # noqa: PLR0912, PLR0911 # handel warnings
     oneline: str, oneline_config: OneLineCommentStyle
 ) -> dict[str, str | list[str] | int] | OnelineParserInvalidWarning | None:
@@ -53,7 +45,7 @@ def oneline_parser(  # noqa: PLR0912, PLR0911 # handel warnings
 
     # extract the string wrapped by start and end
     start_idx = start_idx + len(oneline_config.start_sequence)
-    string = oneline[start_idx:end_idx]
+    string = oneline[start_idx:end_idx].strip()
 
     # numbers of needs_fields which are required
     cnt_required_fields = oneline_config.get_cnt_required_fields()

{sphinx_codelinks-1.1.0 → sphinx_codelinks-1.3.0}/src/sphinx_codelinks/analyse/projects.py

@@ -1,5 +1,4 @@
 import json
-import logging
 from pathlib import Path
 from typing import cast
 
@@ -9,14 +8,9 @@ from sphinx_codelinks.analyse.analyse import (
     SourceAnalyse,
 )
 from sphinx_codelinks.config import CodeLinksConfig, CodeLinksProjectConfigType
+from sphinx_codelinks.logger import get_logger
 
-# initialize logger
-logger = logging.getLogger(__name__)
-logger.setLevel(logging.INFO)
-# log to the console
-console = logging.StreamHandler()
-console.setLevel(logging.INFO)
-logger.addHandler(console)
+logger = get_logger(__name__)
 
 
 class AnalyseProjects:
@@ -32,7 +26,7 @@ class AnalyseProjects:
 
     def run(self) -> None:
         for project, config in self.projects_configs.items():
-            src_analyse = SourceAnalyse(config["analyse_config"])
+            src_analyse = SourceAnalyse(config["analyse_config"], name=project)
             src_analyse.run()
             self.projects_analyse[project] = src_analyse
 
@@ -46,7 +40,7 @@ class AnalyseProjects:
         }
         with output_path.open("w") as f:
             json.dump(to_dump, f)
-        logger.info(f"Marked content dumped to {output_path}")
+        logger.debug(f"codelinks: marked content dumped to {output_path}")
 
     @classmethod
     def load_warnings(cls, warnings_dir: Path) -> list[AnalyseWarning] | None:

{sphinx_codelinks-1.1.0 → sphinx_codelinks-1.3.0}/src/sphinx_codelinks/analyse/utils.py

@@ -1,6 +1,5 @@
 from collections.abc import ByteString, Callable
 import configparser
-import logging
 from pathlib import Path
 from typing import TypedDict
 from urllib.request import pathname2url
@@ -10,23 +9,44 @@ from tree_sitter import Language, Parser, Point, Query, QueryCursor
 from tree_sitter import Node as TreeSitterNode
 
 from sphinx_codelinks.config import UNIX_NEWLINE, CommentCategory
+from sphinx_codelinks.logger import get_logger
 from sphinx_codelinks.source_discover.config import CommentType
 
-# Language-specific node types for scope detection
+# Language-specific node types for scope detection.
+#
+# YAML and JSONC are intentionally absent. They are data formats, not code, so a
+# comment associates with the surrounding data structure (key/value pair, list
+# item, or scalar) rather than with an enclosing or following declaration. That
+# needs a different algorithm (inline same-row association first, scalar targets,
+# grammar-specific traversal), implemented in find_yaml_associated_structure and
+# find_jsonc_associated_structure and dispatched from find_associated_scope.
+# Those bespoke finders never read this table (only find_next_scope and
+# find_enclosing_scope do), so an entry here would be dead.
 SCOPE_NODE_TYPES = {
+    # @Python Scope Node Types, IMPL_PY_2, impl, [FE_PY]
     CommentType.python: {"function_definition", "class_definition"},
+    # @C and C++ Scope Node Types, IMPL_C_2, impl, [FE_C_SUPPORT, FE_CPP]
     CommentType.cpp: {"function_definition", "class_definition"},
     CommentType.cs: {"method_declaration", "class_declaration", "property_declaration"},
-    CommentType.yaml: {"block_mapping_pair", "block_sequence_item", "document"},
+    # @Rust Scope Node Types, IMPL_RUST_2, impl, [FE_RUST];
+    CommentType.rust: {
+        "function_item",
+        "struct_item",
+        "enum_item",
+        "impl_item",
+        "trait_item",
+        "mod_item",
+    },
+    # @Go Scope Node Types, IMPL_GO_4, impl, [FE_GO]
+    CommentType.go: {
+        "function_declaration",
+        "method_declaration",
+        "type_declaration",
+        "type_spec",
+    },
 }
 
-# initialize logger
-logger = logging.getLogger(__name__)
-logger.setLevel(logging.INFO)
-# log to the console
-console = logging.StreamHandler()
-console.setLevel(logging.INFO)
-logger.addHandler(console)
+logger = get_logger(__name__)
 
 GIT_HOST_URL_TEMPLATE = {
     "github": "https://github.com/{owner}/{repo}/blob/{rev}/{path}#L{lineno}",
@@ -45,6 +65,27 @@ PYTHON_QUERY = """
 CPP_QUERY = """(comment) @comment"""
 C_SHARP_QUERY = """(comment) @comment"""
 YAML_QUERY = """(comment) @comment"""
+RUST_QUERY = """
+    (line_comment) @comment
+    (block_comment) @comment
+"""
+# @Go comment query for tree-sitter, IMPL_GO_3, impl, [FE_GO]
+GO_QUERY = """
+    (comment) @comment
+"""
+JSONC_QUERY = """(comment) @comment"""
+
+# JSON value node types that can be associated with a comment.
+JSON_STRUCTURE_TYPES = {
+    "pair",
+    "object",
+    "array",
+    "string",
+    "number",
+    "true",
+    "false",
+    "null",
+}
 
 
 def is_text_file(filepath: Path, sample_size: int = 2048) -> bool:
@@ -62,6 +103,7 @@ def is_text_file(filepath: Path, sample_size: int = 2048) -> bool:
         return False
 
 
+# @Tree-sitter parser initialization for multiple languages, IMPL_LANG_1, impl, [FE_C_SUPPORT, FE_CPP, FE_PY, FE_YAML, FE_RUST, FE_GO, FE_JSONC]
 def init_tree_sitter(comment_type: CommentType) -> tuple[Parser, Query]:
     if comment_type == CommentType.cpp:
         import tree_sitter_cpp  # noqa: PLC0415
@@ -83,6 +125,21 @@ def init_tree_sitter(comment_type: CommentType) -> tuple[Parser, Query]:
 
         parsed_language = Language(tree_sitter_yaml.language())
         query = Query(parsed_language, YAML_QUERY)
+    elif comment_type == CommentType.rust:
+        import tree_sitter_rust  # noqa: PLC0415
+
+        parsed_language = Language(tree_sitter_rust.language())
+        query = Query(parsed_language, RUST_QUERY)
+    elif comment_type == CommentType.go:
+        import tree_sitter_go  # noqa: PLC0415
+
+        parsed_language = Language(tree_sitter_go.language())
+        query = Query(parsed_language, GO_QUERY)
+    elif comment_type == CommentType.jsonc:
+        import tree_sitter_json  # noqa: PLC0415
+
+        parsed_language = Language(tree_sitter_json.language())
+        query = Query(parsed_language, JSONC_QUERY)
     else:
         raise ValueError(f"Unsupported comment style: {comment_type}")
     parser = Parser(parsed_language)
@@ -98,6 +155,7 @@ def wrap_read_callable_point(
     return read_callable_byte_offset
 
 
+# @Comment extraction from source code using tree-sitter, IMPL_EXTR_1, impl, [FE_DEF]
 def extract_comments(
     src_string: ByteString, parser: Parser, query: Query
 ) -> list[TreeSitterNode] | None:
@@ -181,8 +239,11 @@ def find_yaml_next_structure(node: TreeSitterNode) -> TreeSitterNode | None:
     return None
 
 
-def find_yaml_prev_sibling_on_same_row(node: TreeSitterNode) -> TreeSitterNode | None:
-    """Find a previous named sibling that is on the same row as the comment."""
+def find_prev_sibling_on_same_row(node: TreeSitterNode) -> TreeSitterNode | None:
+    """Find a previous named sibling that is on the same row as the comment.
+
+    Grammar-agnostic: used to detect inline comments in both YAML and JSONC.
+    """
     comment_row = node.start_point.row
     current = node.prev_named_sibling
 
@@ -203,7 +264,7 @@ def find_yaml_prev_sibling_on_same_row(node: TreeSitterNode) -> TreeSitterNode |
 def find_yaml_associated_structure(node: TreeSitterNode) -> TreeSitterNode | None:
     """Find the YAML structure (key-value pair, list item, etc.) associated with a comment."""
     # First, check if this is an inline comment by looking for a previous sibling on the same row
-    prev_sibling_same_row = find_yaml_prev_sibling_on_same_row(node)
+    prev_sibling_same_row = find_prev_sibling_on_same_row(node)
     if prev_sibling_same_row:
         return prev_sibling_same_row
 
@@ -222,6 +283,36 @@ def find_yaml_associated_structure(node: TreeSitterNode) -> TreeSitterNode | Non
     return None
 
 
+# @JSONC comment-to-structure association, IMPL_JSONC_2, impl, [FE_JSONC]
+def find_jsonc_associated_structure(node: TreeSitterNode) -> TreeSitterNode | None:
+    """Find the JSON structure (key/value pair, value, list item) for a comment.
+
+    JSON is data rather than code, so association follows the same intent as YAML:
+    an inline comment belongs to the value on its row, a leading comment belongs to
+    the following structure, otherwise it belongs to the enclosing structure.
+    """
+    # Inline comment: a value/pair on the same row, before the comment
+    prev_sibling_same_row = find_prev_sibling_on_same_row(node)
+    if prev_sibling_same_row:
+        return prev_sibling_same_row
+
+    # Leading comment: the next structure following the comment
+    current = node.next_named_sibling
+    while current:
+        if current.type in JSON_STRUCTURE_TYPES:
+            return current
+        current = current.next_named_sibling
+
+    # Otherwise: the enclosing structure
+    parent = node.parent
+    while parent:
+        if parent.type in {"pair", "object", "array"}:
+            return parent
+        parent = parent.parent
+
+    return None
+
+
 def find_associated_scope(
     node: TreeSitterNode, comment_type: CommentType = CommentType.cpp
 ) -> TreeSitterNode | None:
@@ -230,6 +321,10 @@ def find_associated_scope(
         # YAML uses different structure association logic
         return find_yaml_associated_structure(node)
 
+    if comment_type == CommentType.jsonc:
+        # JSONC uses data-aware structure association logic
+        return find_jsonc_associated_structure(node)
+
     if node.type == CommentCategory.docstring:
         # Only for python's docstring
         return find_enclosing_scope(node, comment_type)
@@ -248,7 +343,11 @@ def locate_git_root(src_dir: Path) -> Path | None:
     for parent in parents:
         if (parent / ".git").exists() and (parent / ".git").is_dir():
             return parent
-    logger.warning(f"git root is not found in the parent of {src_dir}")
+    logger.warning(
+        f"git root is not found in the parent of {src_dir}",
+        subtype="git_root",
+        location=str(src_dir),
+    )
     return None
 
 
@@ -256,7 +355,11 @@ def get_remote_url(git_root: Path, remote_name: str = "origin") -> str | None:
     """Get remote url from .git/config."""
     config_path = git_root / ".git" / "config"
     if not config_path.exists():
-        logging.warning(f"{config_path} does not exist")
+        logger.warning(
+            f"{config_path} does not exist",
+            subtype="git_config",
+            location=str(config_path),
+        )
         return None
 
     config = configparser.ConfigParser(allow_no_value=True, strict=False)
@@ -265,7 +368,11 @@ def get_remote_url(git_root: Path, remote_name: str = "origin") -> str | None:
     if section in config and "url" in config[section]:
         url: str = config[section]["url"]
         return url
-    logger.warning(f"remote-url is not found in {config_path}")
+    logger.warning(
+        f"remote-url is not found in {config_path}",
+        subtype="git_remote",
+        location=str(config_path),
+    )
     return None
 
 
@@ -273,16 +380,25 @@ def get_current_rev(git_root: Path) -> str | None:
     """Get current commit rev from .git/HEAD."""
     head_path = git_root / ".git" / "HEAD"
     if not head_path.exists():
-        logging.warning(f"{head_path} does not exist")
+        logger.warning(
+            f"{head_path} does not exist",
+            subtype="git_head",
+            location=str(head_path),
+        )
         return None
     head_content = head_path.read_text().strip()
     if not head_content.startswith("ref: "):
-        logging.warning(f"Expect starting with 'ref: ' in {head_path}")
-        return None
+        # Detached HEAD (e.g. CI checkouts): .git/HEAD holds the commit SHA
+        # directly, which is exactly the rev we want.
+        return head_content
 
     ref_path = git_root / ".git" / head_content.split(":", 1)[1].strip()
     if not ref_path.exists():
-        logging.warning(f"{ref_path} does not exist")
+        logger.warning(
+            f"{ref_path} does not exist",
+            subtype="git_ref",
+            location=str(ref_path),
+        )
         return None
     return ref_path.read_text().strip()
 
@@ -293,7 +409,10 @@ def form_https_url(
     parsed_url = parse(git_url)
     template = GIT_HOST_URL_TEMPLATE.get(parsed_url.platform)
     if not template:
-        logging.warning(f"Unsupported Git host: {parsed_url.platform}")
+        logger.warning(
+            f"Unsupported Git host: {parsed_url.platform}",
+            subtype="git_host",
+        )
         return git_url
     https_url = template.format(
         owner=parsed_url.owner,
@@ -333,6 +452,7 @@ class ExtractedRstType(TypedDict):
     end_idx: int
 
 
+# @Extract reStructuredText blocks embedded in comments, IMPL_RST_1, impl, [FE_RST_EXTRACTION]
 def extract_rst(
     text: str, start_marker: str, end_marker: str
 ) -> ExtractedRstType | None: