sphinx-codelinks 1.2.0__tar.gz → 1.4.0__tar.gz

{sphinx_codelinks-1.2.0 → sphinx_codelinks-1.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sphinx-codelinks
-Version: 1.2.0
+Version: 1.4.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: typer>=0.16.0
+Requires-Dist: ignore-python>=0.3.3
+Requires-Dist: typer>=0.16.0,<0.26.8
 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
@@ -24,6 +24,11 @@ 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
+Requires-Dist: tree-sitter-bash>=0.25.1
+Requires-Dist: libclang>=16 ; extra == "libclang"
+Provides-Extra: libclang
 
 # Sphinx CodeLinks
 

{sphinx_codelinks-1.2.0 → sphinx_codelinks-1.4.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "sphinx-codelinks"
-version = "1.2.0"
+version = "1.4.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",
-  "typer>=0.16.0",
+  "ignore-python>=0.3.3",
+  "typer>=0.16.0,<0.26.8",      # 0.26.8 removed rich_utils.STYLE_METAVAR, still imported by sphinxcontrib-typer (docs)
   "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
@@ -30,8 +30,21 @@ dependencies = [
   "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",
+  "tree-sitter-bash>=0.25.1",
 ]
 
+[project.optional-dependencies]
+# libclang enables the preprocessor-aware C/C++ engine (skips comments inside
+# inactive #if/#ifdef regions). Plain tree-sitter C/C++ extraction needs none of
+# this, so libclang stays optional. Named after the backend, not "cpp": the
+# engine handles C and Objective-C too, and tree-sitter already covers C++.
+# Floor 16 (not 18): the extraction snapshots are byte-identical on libclang 16,
+# 17 and 18 (the engine only uses get_all_skipped_ranges + comment tokenization,
+# stable since long before 16), so support older toolchains too. No upper bound.
+libclang = ["libclang>=16"]
+
 [build-system]
 requires = ["flit_core >=3.4,<4"]
 build-backend = "flit_core.buildapi"
@@ -46,13 +59,14 @@ testing = [
   "moto ~= 5.0",
   "toml>=0.10.2",
   "furo>=2024.5.6",
+  "libclang>=18",
 ]
 docs = [
   "furo>=2024.5.6",
   "myst-parser>=4.0.0",
   "sphinx-design>=0.6.1",
   "sphinx-code-tabs>=0.5.5",
-  "sphinxcontrib-typer>=0.5.1",
+  "sphinxcontrib-typer>=0.5.1,<0.9.1", # 0.9.1 imports typer.rich_utils.STYLE_TYPES, absent in the capped typer <0.26.8, breaking the docs build
   "sphinxcontrib-video>=0.4.1",
 ]
 mypy = [
@@ -66,64 +80,9 @@ mypy = [
 ruff = ["ruff>=0.8.0"]
 build = ["simple-build>=0.0.2", "shiv>=1.0.8"]
 
-[tool.rye]
-managed = true
-dev-dependencies = [
-  "types-docutils",
-  "types-Pygments",
-  "syrupy>=4.9.1",
-  "furo>=2024.5.6",
-  "moto ~= 5.0",
-  "mypy>=1.12.1",
-  "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",
-]
-
 [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",
@@ -159,17 +118,11 @@ force-sort-within-sections = true
 "**/tests/*" = [
   "ARG001",  # unused-function-argument - fixtures
   "ARG005",  # unused-lambda-argument - monkeypatches
+  "E402",    # module-import-not-at-top - pytest.importorskip guard pattern
+  "PLC0415", # import-outside-top-level - inline imports in test bodies
   "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
+  "SIM300",  # yoda-conditions - assert order in tests is intentional
 ]
 "src/sphinx_codelinks/sphinx_extension/debug.py" = [
   "T201",  # print - used for output
@@ -202,7 +155,8 @@ plugins = ["pydantic.mypy"]
 mypy_path = "typings"
 
 [[tool.mypy.overrides]]
-module = ["licensing.*", "tomlkit.*"]
+# clang.cindex ships no type stubs / py.typed; the libclang engine wraps it.
+module = ["licensing.*", "tomlkit.*", "clang.*"]
 ignore_missing_imports = true
 
 [[tool.mypy.overrides]]

{sphinx_codelinks-1.2.0 → sphinx_codelinks-1.4.0}/src/sphinx_codelinks/analyse/analyse.py

@@ -1,9 +1,8 @@
 from collections.abc import Generator
 from dataclasses import dataclass
 import json
-import logging
 from pathlib import Path
-from typing import Any, TypedDict
+from typing import Any, TypedDict, cast
 
 from tree_sitter import Node as TreeSitterNode
 
@@ -26,14 +25,15 @@ from sphinx_codelinks.config import (
     OneLineCommentStyle,
     SourceAnalyseConfig,
 )
+from sphinx_codelinks.logger import get_logger
+from sphinx_codelinks.source_discover.config import CommentType
 
-# 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 +57,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] = []
@@ -76,10 +79,11 @@ class SourceAnalyse:
         self.git_commit_rev: str | None = (
             utils.get_current_rev(self.git_root) if self.git_root else None
         )
-        self.project_path: Path = (
-            self.git_root if self.git_root else self.analyse_config.src_dir
-        )
+        self.project_path: Path = self.git_root or self.analyse_config.src_dir
         self.oneline_warnings: list[AnalyseWarning] = []
+        # Per-run memo of parsed compile_commands.json, keyed by DB path, so the
+        # database is read once per run instead of once per source file.
+        self._flags_map_cache: dict[Path, dict[Path, list[str]] | None] = {}
 
     def get_src_strings(self) -> Generator[tuple[Path, bytes], Any, None]:  # type: ignore[explicit-any]
         """Load source files and extract their content."""
@@ -110,8 +114,126 @@ 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 _flags_map_for(self, db_path: Path) -> dict[Path, list[str]] | None:
+        """Return the parsed compile_commands.json for ``db_path``, memoized.
+
+        The database is read and parsed once per run instead of once per source
+        file (O(files x entries) -> O(entries)). A present-but-malformed or
+        unreadable database is warned once and cached as ``None`` so callers fall
+        back to the configured defines without re-reading or re-warning per file.
+        """
+        from sphinx_codelinks.analyse.preproc import compile_db  # noqa: PLC0415
+
+        if db_path in self._flags_map_cache:
+            return self._flags_map_cache[db_path]
+        try:
+            flags = compile_db.load_flags_map(db_path)
+        except (OSError, ValueError, TypeError) as exc:
+            logger.warning(
+                f"codelinks: failed to read {db_path} ({exc}); "
+                f"falling back to the configured defines"
+            )
+            self._flags_map_cache[db_path] = None
+            return None
+        self._flags_map_cache[db_path] = flags
+        return flags
+
+    def _resolve_preproc_args(self, src_path: Path) -> list[str] | None:
+        from sphinx_codelinks.analyse.preproc import compile_db  # noqa: PLC0415
+
+        # `run()` calls this (via create_src_objects_libclang) only when
+        # `preprocessor is not None`, but keep the guard: it narrows the type for
+        # the checker and is a cheap defense (an `assert` would trip bandit S101).
+        preproc = self.analyse_config.preprocessor
+        if preproc is None:
+            return []
+        db_path = preproc.compile_commands
+        if db_path is None:
+            db_path = compile_db.find_compile_db(src_path, self.project_path)
+        if db_path is not None and db_path.is_file():
+            flags = self._flags_map_for(db_path)
+            if flags is None:
+                # Present-but-malformed/unreadable DB (warned once in the helper):
+                # fall back to the configured defines so extraction still runs.
+                return compile_db.defines_to_args(
+                    preproc.defines, preproc.includes, preproc.std
+                )
+            args = flags.get(src_path.absolute().resolve())
+            if args is not None:
+                return args
+            # Absent from the DB. compile_commands.json lists only compiled
+            # translation units, never headers — so a header here is parsed
+            # standalone with the global defines (one run = one variant). A
+            # compiled source absent from the build is skipped (spec §3.3).
+            if compile_db.is_translation_unit_source(src_path):
+                return None
+            return compile_db.defines_to_args(
+                preproc.defines, preproc.includes, preproc.std
+            )
+        # No readable DB. `find_compile_db` only ever returns a real file, so a
+        # non-None `db_path` that reaches here is an explicit `compile_commands`
+        # path that is not a readable file (typo/missing): warn and fall back
+        # rather than skip silently. A genuinely absent DB (db_path is None) just
+        # falls back to the manual defines applied globally.
+        if db_path is not None:
+            logger.warning(
+                f"codelinks: compile_commands path {db_path} is not a readable "
+                f"file; falling back to the configured defines"
+            )
+        return compile_db.defines_to_args(
+            preproc.defines, preproc.includes, preproc.std
+        )
+
+    # @Extract traceability objects with the preprocessor-aware libclang engine, IMPL_PREPROC_1, impl, [FE_PREPROC]
+    def create_src_objects_libclang(self) -> None:
+        from sphinx_codelinks.analyse.preproc import (  # noqa: PLC0415
+            libclang_parser,
+            loader,
+        )
+
+        # Resolve the exception via the loader (never a direct ``import
+        # clang.cindex``) so a missing ``libclang`` extra still surfaces the
+        # loader's friendly install hint rather than a bare ImportError.
+        translation_unit_load_error = (
+            loader.load_clang_cindex().TranslationUnitLoadError
+        )
+
+        for src_path in self.analyse_config.src_files:
+            if not utils.is_text_file(src_path):
+                continue
+            args = self._resolve_preproc_args(src_path)
+            if args is None:
+                logger.debug(
+                    f"codelinks: skipping {src_path} — not found in compile_commands.json"
+                )
+                continue
+            try:
+                comments = libclang_parser.extract_active_comments(src_path, args)
+            except translation_unit_load_error:
+                # Last-resort guard. Standalone parses pin ``-x`` to match the
+                # ``-std`` (see defines_to_args), so the common case — a ``.h``/
+                # ``.c`` header handed a C++ ``-std`` — now parses as C++ and its
+                # markers extract. This only fires if libclang still cannot load
+                # the file as a translation unit at all; skip it rather than
+                # aborting the whole run. Surfaced as a ``warning`` so the silent
+                # data-loss (a file's markers dropped) is visible — accepting that
+                # this fails ``sphinx-build -W``.
+                logger.warning(
+                    f"codelinks: skipping {src_path} — libclang could not load it "
+                    f"as a translation unit"
+                )
+                continue
+            if not comments:
+                continue
+            # ``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.
+            src_comments = [SourceComment(cast("TreeSitterNode", c)) for c in comments]
+            src_file = SourceFile(src_path.absolute())
+            src_file.add_comments(src_comments)
+            self.src_files.append(src_file)
+            self.src_comments.extend(src_comments)
 
     def extract_marker(
         self,
@@ -328,9 +450,12 @@ class SourceAnalyse:
             )
             if not filepath:
                 continue
-            tagged_scope: TreeSitterNode | None = utils.find_associated_scope(
-                src_comment.node, self.analyse_config.comment_type
-            )
+            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
+                )
             if self.analyse_config.get_need_id_refs:
                 anchors = self.extract_anchors(
                     text, filepath, tagged_scope, src_comment
@@ -353,13 +478,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"])
@@ -378,9 +496,29 @@ 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()
+        if (
+            self.analyse_config.preprocessor is not None
+            and self.analyse_config.comment_type == CommentType.cpp
+        ):
+            self.create_src_objects_libclang()
+        else:
+            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.2.0 → sphinx_codelinks-1.4.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."""
@@ -52,6 +43,19 @@ def oneline_parser(  # noqa: PLR0912, PLR0911 # handel warnings
         # start or end sequences do not exist
         return None
 
+    # A marker whose end sequence is the newline extends to the end of the
+    # line, so an unanchored start sequence would swallow trailing prose. Anchor
+    # such a marker to the start of the comment content: everything preceding
+    # the start sequence must be comment decoration (`//`, `#`, `*`, ...) and
+    # whitespace. A word character before it means the start sequence is part of
+    # free-form prose (e.g. `// see @author, ...`) and the line is ignored
+    # (issue #88). Explicitly-bounded markers (e.g. `[[ ... ]]`) are
+    # self-delimiting and may appear anywhere, so they are exempt.
+    if oneline_config.end_sequence == UNIX_NEWLINE and any(
+        char.isalnum() for char in oneline[:start_idx]
+    ):
+        return None
+
     # extract the string wrapped by start and end
     start_idx = start_idx + len(oneline_config.start_sequence)
     string = oneline[start_idx:end_idx].strip()

sphinx_codelinks-1.4.0/src/sphinx_codelinks/analyse/preproc/__init__.py

@@ -0,0 +1,5 @@
+"""libclang-based, preprocessor-aware extraction engine (opt-in)."""
+
+from sphinx_codelinks.analyse.preproc import compile_db, libclang_parser, loader
+
+__all__ = ["compile_db", "libclang_parser", "loader"]

sphinx_codelinks-1.4.0/src/sphinx_codelinks/analyse/preproc/compile_db.py

@@ -0,0 +1,156 @@
+"""Discover, read, and filter compile_commands.json for libclang."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+import shlex
+
+from sphinx_codelinks.config import DEFAULT_CPP_STD
+
+_DB_NAME = "compile_commands.json"
+_BOUNDARY_MARKERS = (".git", "ubproject.toml", "pyproject.toml")
+
+# Flags that take a following value we must also drop.
+_DROP_WITH_VALUE = {"-o", "-MF", "-MT", "-MQ"}
+# Exact flags to drop.
+_DROP_EXACT = {"-c", "-MMD", "-MD", "-MG", "-MP"}
+# Separate-form flags whose following VALUE token must be kept verbatim (never
+# treated as the input source and stripped by basename).
+_KEEP_WITH_VALUE = {
+    "-include",
+    "-isystem",
+    "-iquote",
+    "-idirafter",
+    "-isysroot",
+    "-x",
+    "-I",
+}
+# Minimum length for joined-form flags like -MFdep.d (prefix length = 3)
+_MIN_JOINED_FLAG_LEN = 3
+
+# Suffixes a compiler builds as a translation unit. A discovered C/C++ file
+# absent from compile_commands.json is skipped only when it is a TU source
+# (build-excluded); all other discovered files (headers) are parsed standalone.
+TU_SOURCE_SUFFIXES = {".c", ".cpp", ".cc", ".cxx"}
+
+
+# @Discover compile_commands.json by walking up from the source file, IMPL_PREPROC_3, impl, [FE_PREPROC]
+def find_compile_db(start: Path, project_root: Path | None = None) -> Path | None:
+    """Walk up from ``start`` looking for compile_commands.json.
+
+    Stops at (inclusive) the directory that contains the db, or at
+    ``project_root`` / a directory containing a boundary marker / fs root.
+    """
+    current = start if start.is_dir() else start.parent
+    current = current.resolve()
+    root = project_root.resolve() if project_root else None
+    while True:
+        candidate = current / _DB_NAME
+        if candidate.is_file():
+            return candidate
+        if root is not None and current == root:
+            return None
+        if any((current / m).exists() for m in _BOUNDARY_MARKERS):
+            return None
+        if current.parent == current:  # filesystem root
+            return None
+        current = current.parent
+
+
+def filter_args(argv: list[str], input_file: str) -> list[str]:
+    """Keep only flags libclang needs; drop the compiler, -c/-o, depfiles, input."""
+    out: list[str] = []
+    skip_next = False
+    keep_next_value = False
+    input_base = Path(input_file).name
+    # Skip leading non-flag tokens. argv[0] is the compiler, but a build may prefix
+    # it with a launcher (ccache/sccache/distcc), so drop every leading non-flag
+    # token up to the first flag — otherwise the real compiler leaks in as a
+    # positional and libclang treats it as a second input (a NULL TU that silently
+    # drops the file). The input source (also a non-flag positional) is stripped by
+    # name below.
+    in_leading = True
+    for arg in argv:
+        if in_leading:
+            if not arg.startswith("-"):
+                continue
+            in_leading = False
+        if skip_next:
+            skip_next = False
+            continue
+        if keep_next_value:
+            # Value of a separate-form -include/-isystem/-I/... — keep verbatim.
+            keep_next_value = False
+            out.append(arg)
+            continue
+        if arg in _DROP_WITH_VALUE:
+            skip_next = True
+            continue
+        if arg in _DROP_EXACT:
+            continue
+        if arg.startswith(("-MF", "-MT", "-MQ")) and len(arg) > _MIN_JOINED_FLAG_LEN:
+            continue  # joined form, e.g. -MFdep.d
+        if arg in _KEEP_WITH_VALUE:
+            out.append(arg)
+            keep_next_value = True
+            continue
+        # Strip the TU source positional (exact match, or same basename).
+        if not arg.startswith("-") and (
+            arg in (input_file, input_base) or Path(arg).name == input_base
+        ):
+            continue
+        out.append(arg)
+    return out
+
+
+# @Resolve per-file compiler flags from the compilation database, IMPL_PREPROC_4, impl, [FE_PREPROC]
+def load_flags_map(db_path: Path) -> dict[Path, list[str]]:
+    """Parse compile_commands.json -> {absolute file path: filtered args}."""
+    entries = json.loads(db_path.read_text())
+    flags: dict[Path, list[str]] = {}
+    for entry in entries:
+        if "file" not in entry or "directory" not in entry:
+            continue  # malformed entry: skip, keep going
+        if "arguments" in entry:
+            argv = list(entry["arguments"])
+        elif "command" in entry:
+            argv = shlex.split(entry["command"])
+        else:
+            continue
+        directory = Path(entry["directory"])
+        file_field = entry["file"]
+        abs_file = (directory / file_field).resolve()
+        flags[abs_file] = filter_args(argv, file_field)
+    return flags
+
+
+# @Parse headers standalone from configured defines and includes, IMPL_PREPROC_5, impl, [FE_PREPROC]
+def defines_to_args(
+    defines: list[str], includes: list[Path], std: str = DEFAULT_CPP_STD
+) -> list[str]:
+    """Build a global flag list for parsing a file standalone.
+
+    Used for headers and files absent from a compile DB. libclang infers the
+    language from the file extension, so a C-inferred file (``.h`` / ``.c`` /
+    ``.inc``) handed a C++ ``-std`` makes clang reject the combination and return
+    a NULL translation unit (surfacing as ``TranslationUnitLoadError``). Pin the
+    language to match ``std`` with ``-x`` so such files — e.g. a ``.h`` header
+    carrying oneline need markers — parse and extract instead of failing. (C
+    sources parse as C++ well enough for comment/marker extraction.)
+    """
+    lang = "c++" if std.startswith(("c++", "gnu++")) else "c"
+    args = ["-x", lang, f"-std={std}"]
+    args += [f"-D{d}" for d in defines]
+    args += [f"-I{inc}" for inc in includes]
+    return args
+
+
+def is_translation_unit_source(path: Path) -> bool:
+    """True if ``path`` is a compiled translation-unit source (not a header).
+
+    compile_commands.json lists one entry per compiled TU; headers are never
+    entries. So a discovered file absent from the DB is skipped only when it is
+    a TU source; header-like files are parsed standalone (see _resolve_preproc_args).
+    """
+    return path.suffix.lower() in TU_SOURCE_SUFFIXES