🐛 Don't mutate rebuild='env' src_trace_projects config during builds (#75)

## Summary

Incremental Sphinx builds always re-read every document, logging
`[config changed ('src_trace_projects')] N added, 0 changed, 0 removed`,
even
when nothing changed — incremental builds behave like full rebuilds.

`src_trace_projects` is registered with `rebuild="env"`, so Sphinx
pickles it
into `environment.pickle` and invalidates the environment whenever the
pickled
("old") value differs from the freshly computed ("new") one.
`generate_project_configs()` stores runtime `analyse_config` /
`source_discover_config` dataclass objects in that value; on their own
they
round-trip through pickle as `==`-equal.

The bug: the `src-trace` directive mutated the stored `analyse_config`
**in
place** during the build (`src_dir`, `src_files`, `git_root` set to
build-time,
resolved values). Those build-time values were persisted into the
pickle, while
the next build's `config-inited` produced a fresh `analyse_config`
(`src_files=[]`, `src_dir=Path(".")`), so the comparison always
differed:

| Side | `src_dir` | `src_files` |
|------|-----------|-------------|
| persisted (pickle, "old") | `/abs/.../dcdc` | `['demo_3.cpp', ...]` |
| fresh config-inited ("new") | `Path('.')` | `[]` |

## Fix

Operate on a per-directive `dataclasses.replace()` copy instead of
mutating the
`analyse_config` stored in the `rebuild="env"` config value. The stored
value
then stays equal to what `generate_project_configs()` yields, so
incremental
builds report `0 added, 0 changed, 0 removed`.

## Verification

- New regression test
`test_incremental_build_keeps_src_trace_projects_unchanged`
  builds the fixture twice and asserts the 2nd (incremental) build sees
`CONFIG_OK` — fails before the fix (`CONFIG_CHANGED
('src_trace_projects')`),
  passes after.
- Full suite: **207 passed**.
- Manual triple build: builds 2 & 3 now report `0 added, 0 changed, 0
removed`.

Fixes #74

Author: ubmarco

src/sphinx_codelinks/sphinx_extension/directives/src_trace.py

@@ -1,4 +1,5 @@
 from collections.abc import Callable
+from dataclasses import replace
 import os
 from pathlib import Path
 from typing import Any, ClassVar, cast
@@ -113,16 +114,28 @@ def run(self) -> list[nodes.Node]:
         for source_file in source_files:
             self.env.note_dependency(str(source_file.resolve()))
 
-        analyse_config = src_trace_conf["analyse_config"]
-        analyse_config.src_dir = src_dir
-        analyse_config.src_files = source_files
+        # ``analyse_config`` is stored in the ``src_trace_projects`` config value,
+        # which is registered with ``rebuild="env"`` and therefore persisted into
+        # ``environment.pickle``. Mutating it in place would make Sphinx compare the
+        # build-populated object against the freshly generated (empty) config on the
+        # next build and report ``[config changed ('src_trace_projects')]`` every
+        # time, forcing a full re-read. Build a per-directive copy instead so the
+        # stored config value stays equal to what ``generate_project_configs`` yields.
+        base_analyse_config = src_trace_conf["analyse_config"]
         # git_root shall be relative to the config file's location (if provided)
-        if analyse_config.git_root:
+        git_root = base_analyse_config.git_root
+        if git_root:
             conf_dir = Path(self.env.app.confdir)
             if src_trace_sphinx_config.config_from_toml:
                 src_trace_toml_path = Path(src_trace_sphinx_config.config_from_toml)
                 conf_dir = conf_dir / src_trace_toml_path.parent
-            analyse_config.git_root = (conf_dir / analyse_config.git_root).resolve()
+            git_root = (conf_dir / git_root).resolve()
+        analyse_config = replace(
+            base_analyse_config,
+            src_dir=src_dir,
+            src_files=source_files,
+            git_root=git_root,
+        )
         src_analyse = SourceAnalyse(analyse_config, name=project)
         src_analyse.run()
 

tests/test_src_trace.py

@@ -4,6 +4,7 @@
 import shutil
 
 import pytest
+from sphinx.environment import CONFIG_OK
 from sphinx.testing.util import SphinxTestApp
 
 from sphinx_codelinks.analyse.projects import AnalyseProjects
@@ -228,3 +229,50 @@ def test_build_html(
     assert not warnings
 
     assert app.env.get_doctree("index") == snapshot_doctree
+
+
+def test_incremental_build_keeps_src_trace_projects_unchanged(
+    tmpdir: Path,
+    make_app: Callable[..., SphinxTestApp],
+) -> None:
+    """An incremental rebuild with no source changes must not invalidate the env.
+
+    Regression test for the ``src-trace`` directive mutating the ``analyse_config``
+    object stored inside the ``rebuild="env"`` ``src_trace_projects`` config value.
+    The mutated object (populated ``src_dir``/``src_files``) was persisted into
+    ``environment.pickle``, so every incremental build compared it against the
+    freshly generated (empty) config and reported
+    ``[config changed ('src_trace_projects')]``, forcing a full re-read.
+    """
+    this_file_dir = Path(__file__).parent
+    sphinx_project = Path("data") / "sphinx"
+    source_code = Path("data") / "dcdc"
+
+    sphinx_src_dir = Path(tmpdir) / sphinx_project
+    shutil.copytree(this_file_dir / sphinx_project, sphinx_src_dir, dirs_exist_ok=True)
+    shutil.copytree(
+        this_file_dir / source_code, Path(tmpdir) / source_code, dirs_exist_ok=True
+    )
+
+    # First build populates environment.pickle in the shared build dir.
+    make_app(srcdir=sphinx_src_dir, freshenv=True).build()
+
+    # Second build reuses the same build dir and loads the pickled environment.
+    app = make_app(srcdir=sphinx_src_dir, freshenv=False)
+
+    captured: dict[str, object] = {}
+
+    def capture_config_status(_app, env, _added, _changed, _removed):  # type: ignore[no-untyped-def]
+        # ``env-get-outdated`` fires during read() after the config comparison
+        # but before config_status is reset to CONFIG_OK at the end of read().
+        captured["status"] = env.config_status
+        captured["extra"] = env.config_status_extra
+        return []
+
+    app.connect("env-get-outdated", capture_config_status)
+    app.build()
+
+    assert captured["status"] == CONFIG_OK, (
+        f"incremental build wrongly invalidated the environment: "
+        f"config changed{captured.get('extra')}"
+    )