refactor: drop CLDK-side analysis cache, rely on codeanalyzer-python

Remove the content-addressed two-tier cache (cache.py) and CLDK's own
analysis.json read/write. codeanalyzer-python already caches the
virtualenv, CodeQL database, and analysis result under its cache_dir
with checksum-based invalidation, so the CLDK layer was a redundant
second cache that also caused unbounded ~/.cldk growth and coupled the
CodeQL DB to a dependency-hash key. cache_dir/analysis_json_path are now
forwarded verbatim to the backend (None -> backend defaults to
<project>/.codeanalyzer); eager maps to rebuild_analysis.

Author: rahlk

README.md

@@ -207,19 +207,17 @@ Each language has a dedicated analysis backend implemented under `cldk.analysis.
 - **Tools:** `codeanalyzer-python` (Jedi + CodeQL, default on), Tree-sitter for source-level parsing  
 - **Capabilities:** Symbol table, call graph, class/method resolution, comments/docstrings
 
-> **Note — analysis cache:** Analysis artifacts are cached under `~/.cldk`
-> (override with `$CLDK_CACHE_DIR`): the backend virtualenv and CodeQL
-> database under `~/.cldk/venvs/<dep_hash>/`, and `analysis.json` under
-> `~/.cldk/cache/<key>/`. **CodeQL is enabled by default**
-> (`use_codeql=True`), so the first analysis of a project builds a CodeQL
-> database and provisions the CodeQL CLI — expect a slow cold run; subsequent
-> runs on the same source tree are cache hits. Pass `use_codeql=False` for
-> Jedi-only analysis. The CodeQL flag is part of the analysis cache key, so
-> toggling it — or upgrading from a version that defaulted it off — triggers
-> a **one-time** rebuild under a new key (no stale data is served). If you
-> instead point `cache_dir` (the backend virtualenv / CodeQL database) or
-> `analysis_json_path` inside a project, add those directories to your
-> `.gitignore` — they are large and environment-specific.
+> **Note — analysis cache:** Caching is owned entirely by
+> `codeanalyzer-python`; CLDK keeps no cache of its own. Artifacts (the
+> backend virtualenv, CodeQL database, and `analysis_cache.json`) live under
+> the backend's `cache_dir`, which defaults to `<project>/.codeanalyzer` and
+> can be redirected with the `cache_dir` argument. **CodeQL is enabled by
+> default** (`use_codeql=True`), so the first analysis of a project builds a
+> CodeQL database and provisions the CodeQL CLI — expect a slow cold run;
+> subsequent runs reuse the backend's checksum-validated cache. Pass
+> `use_codeql=False` for Jedi-only analysis. Add the `cache_dir` location
+> (e.g. `.codeanalyzer/`) to your `.gitignore` — it is large and
+> environment-specific.
 
 #### C
 - **Backend:** `cldk.analysis.c`  

cldk/analysis/python/codeanalyzer/cache.py

@@ -33,13 +33,9 @@
 from codeanalyzer.config import OutputFormat
 from codeanalyzer.core import Codeanalyzer
 from codeanalyzer.options import AnalysisOptions
-from codeanalyzer.schema import model_dump_json, model_validate_json
+from codeanalyzer.schema import model_dump_json
 
 from cldk.analysis import AnalysisLevel
-from cldk.analysis.python.codeanalyzer.cache import (
-    default_analysis_dir,
-    default_backend_cache_dir,
-)
 from cldk.models.python import (
     PyApplication,
     PyCallEdge,
@@ -59,17 +55,15 @@ class PyCodeanalyzer:
     Args:
         project_dir: Path to the Python project root.
         analysis_level: Analysis level (symbol_table or call_graph).
-        analysis_json_path: Directory to persist analysis.json. If the file
-            exists and ``eager_analysis`` is False, it is loaded instead of
-            re-running the analyzer. When omitted, a content-addressed
-            location under the CLDK cache root is used (see
-            :mod:`cldk.analysis.python.codeanalyzer.cache`).
-        eager_analysis: If True, always re-runs the analyzer even when a
-            cached analysis.json is available.
-        cache_dir: Cache directory for the analyzer's virtualenv and CodeQL
-            artifacts. Forwarded verbatim to ``AnalysisOptions.cache_dir``.
-            When omitted, a dependency-hash-keyed location under the CLDK
-            cache root is used so the virtualenv survives source edits.
+        analysis_json_path: Forwarded verbatim to ``AnalysisOptions.output``.
+            ``codeanalyzer-python`` owns all caching; CLDK neither reads nor
+            writes its own analysis.json.
+        eager_analysis: If True, forces the backend to rebuild its analysis
+            (``AnalysisOptions.rebuild_analysis``) rather than reuse its cache.
+        cache_dir: Cache home for ``codeanalyzer-python`` (its virtualenv,
+            CodeQL database, and ``analysis_cache.json``). Forwarded verbatim
+            to ``AnalysisOptions.cache_dir``. When None, the backend defaults
+            it to ``<project_dir>/.codeanalyzer``.
         target_files: Optional single target file (relative to project_dir).
             When provided, only that file is analyzed.
     """
@@ -92,25 +86,13 @@ def __init__(
         self.target_files = target_files
         self.use_codeql = use_codeql
 
-        # Cache locations. Explicit args win; otherwise fall back to the
-        # content-addressed CLDK cache (two independently-keyed tiers).
-        if cache_dir:
-            self.cache_dir = Path(cache_dir)
-        else:
-            self.cache_dir = default_backend_cache_dir(self.project_dir)
-        if analysis_json_path:
-            self.analysis_json_path = Path(analysis_json_path)
-        else:
-            self.analysis_json_path = default_analysis_dir(
-                self.project_dir, analysis_level, use_codeql, target_files
-            )
-        logger.info(
-            "CLDK cache — backend: %s | analysis: %s",
-            self.cache_dir,
-            self.analysis_json_path,
-        )
+        # codeanalyzer-python owns all caching. CLDK forwards these paths
+        # verbatim; when cache_dir is None the backend defaults it to
+        # <project_dir>/.codeanalyzer.
+        self.cache_dir = Path(cache_dir) if cache_dir else None
+        self.analysis_json_path = Path(analysis_json_path) if analysis_json_path else None
 
-        self.application: PyApplication = self._load_or_run_analyzer()
+        self.application: PyApplication = self._run_analyzer()
         # Class-signature → file path lookup, built once.
         self._class_to_file: Dict[str, str] = {}
         for file_path, module in self.application.symbol_table.items():
@@ -123,13 +105,8 @@ def __init__(
             self.call_graph = None
 
     # ----------------------------------------------------------------- core
-    def _load_or_run_analyzer(self) -> PyApplication:
-        """Load a cached analysis.json when available, else run the analyzer."""
-        cached_file = self.analysis_json_path / "analysis.json" if self.analysis_json_path else None
-        if cached_file and cached_file.exists() and not self.eager_analysis:
-            logger.info(f"Loading cached PyApplication from {cached_file}")
-            return model_validate_json(PyApplication, cached_file.read_text())
-
+    def _run_analyzer(self) -> PyApplication:
+        """Run codeanalyzer-python; the backend handles its own caching."""
         target_file = None
         if self.target_files:
             if len(self.target_files) > 1:
@@ -151,12 +128,7 @@ def _load_or_run_analyzer(self) -> PyApplication:
         )
 
         with Codeanalyzer(options) as analyzer:
-            app = analyzer.analyze()
-
-        if self.analysis_json_path is not None:
-            self.analysis_json_path.mkdir(parents=True, exist_ok=True)
-            (self.analysis_json_path / "analysis.json").write_text(model_dump_json(app, indent=None))
-        return app
+            return analyzer.analyze()
 
     @staticmethod
     def _build_call_graph(edges: List[PyCallEdge]) -> nx.DiGraph:

cldk/analysis/python/codeanalyzer/codeanalyzer.py

@@ -47,12 +47,12 @@ class PythonAnalysis:
 
     Args:
         project_dir: Directory path of the project (required).
-        cache_dir: Writable directory where the ``codeanalyzer-python``
-            backend provisions its virtualenv and CodeQL database (forwarded
-            as the backend's ``cache_dir``). If None, a dependency-hash-keyed
-            location under the CLDK cache root is used.
-        analysis_json_path: Directory to persist analysis.json. If None, the
-            analysis is not persisted across runs.
+        cache_dir: Cache home for ``codeanalyzer-python`` — its virtualenv,
+            CodeQL database, and ``analysis_cache.json`` (forwarded as the
+            backend's ``cache_dir``). The backend owns all caching. If None,
+            it defaults to ``<project_dir>/.codeanalyzer``.
+        analysis_json_path: Forwarded to the backend's ``output``. CLDK keeps
+            no cache of its own.
         analysis_level: Analysis level (symbol-table or call-graph).
         target_files: Optional list of target files to constrain analysis.
         eager_analysis: If True, regenerate analysis.json on each run.

cldk/analysis/python/python_analysis.py

@@ -77,11 +77,12 @@ def analysis(
                 ``cache_dir`` instead.
             analysis_json_path (str | Path | None): Path to persist the analysis
                 database / ``analysis.json``.
-            cache_dir (str | Path | None): Python only. Writable directory where
-                the ``codeanalyzer-python`` backend provisions its virtualenv and
-                CodeQL database (forwarded as the backend's ``cache_dir``). When
-                omitted, a dependency-hash-keyed location under the CLDK cache
-                root is used. Ignored for other languages.
+            cache_dir (str | Path | None): Python only. Cache home for the
+                ``codeanalyzer-python`` backend — its virtualenv, CodeQL
+                database, and ``analysis_cache.json`` (forwarded as the
+                backend's ``cache_dir``). The backend owns all caching; when
+                omitted it defaults to ``<project_path>/.codeanalyzer``.
+                Ignored for other languages.
             use_codeql (bool): Python only, default True. Augments Jedi-resolved
                 call edges with CodeQL-resolved edges; set False for a faster,
                 Jedi-only analysis. Ignored for other languages.