feat/python: upgrade to codeanalyzer-python 0.3.0, remove CodeQL (1.4.0) (#186)

* feat(python)!: upgrade to codeanalyzer-python 0.3.0 and remove CodeQL

codeanalyzer-python 0.3.0 drops CodeQL in favor of PyCG for call-graph
construction and removed the `using_codeql` option from AnalysisOptions, which
broke CLDK's in-process Python backend (TypeError on every analysis).

Upgrade the pin 0.2.0 -> 0.3.0 and remove CodeQL from CLDK entirely:

- Drop the `use_codeql` knob from the public surface: PyCodeAnalyzerConfig,
  the deprecated CLDK(language).analysis(...) shim, the PyCodeanalyzer
  constructor, and the facade forwarding. Stop passing using_codeql to
  AnalysisOptions.
- Remove the CodeQLDatabaseBuildException / CodeQLQueryExecutionException
  exception classes and their re-exports.
- Scrub CodeQL from docstrings, the README, and the _jdk.py loader comments;
  describe the Python backend as Jedi + PyCG.
- Drop the now-obsolete use_codeql forwarding test; fix the Neo4j parity
  fixture to not pass using_codeql.

BREAKING CHANGE: removes the public `use_codeql` option and the CodeQL
exception classes. Call-graph results may differ (PyCG vs CodeQL-augmented Jedi).

Closes #185

* chore(release): 1.4.0

codeanalyzer-python 0.3.0 upgrade and CodeQL removal (#185).

Author: rahlk

CHANGELOG.md

@@ -7,6 +7,20 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [v1.4.0] - 2026-06-27
+
+### Changed
+- **Upgraded `codeanalyzer-python` 0.2.0 → 0.3.0**, which drops CodeQL and uses **PyCG** for
+  call-graph construction.
+
+### Removed
+- **`use_codeql` (BREAKING).** Because codeanalyzer-python 0.3.0 removed CodeQL, the `use_codeql`
+  knob no longer maps to anything and is removed from CLDK's public surface: the
+  `PyCodeAnalyzerConfig.use_codeql` field, the deprecated `CLDK(language).analysis(use_codeql=...)`
+  parameter, and the `PyCodeanalyzer(use_codeql=...)` argument. The `CodeQLDatabaseBuildException`
+  and `CodeQLQueryExecutionException` exception classes are removed as well. Call-graph results may
+  differ (PyCG vs CodeQL-augmented Jedi). See #185.
+
 ## [v1.3.0] - 2026-06-27
 
 ### Added

README.md

@@ -25,7 +25,7 @@
 
 **A unified, multilingual program-analysis SDK for Code LLMs.** CLDK turns raw source code into structured, LLM-ready program facts — symbol tables, call graphs, type hierarchies, and more — behind a single Python API, so you can build analysis-augmented LLM pipelines without wrangling a different static-analysis tool for every language.
 
-Under the hood, CLDK orchestrates mature analysis engines (WALA, Tree-sitter, Jedi, CodeQL, ts-morph) and normalizes their output into consistent, typed [Pydantic](https://docs.pydantic.dev/) models. You get the same ergonomic interface whether you are analyzing Java, Python, or TypeScript.
+Under the hood, CLDK orchestrates mature analysis engines (WALA, Tree-sitter, Jedi, PyCG, ts-morph) and normalizes their output into consistent, typed [Pydantic](https://docs.pydantic.dev/) models. You get the same ergonomic interface whether you are analyzing Java, Python, or TypeScript.
 
 CLDK is:
 
@@ -125,12 +125,12 @@ Each language is analyzed by a dedicated `codeanalyzer-*` engine; CLDK normalize
 | Language | Analysis engine | What it provides |
 | --- | --- | --- |
 | **Java** | [`codeanalyzer-java`](https://github.com/codellm-devkit/codeanalyzer-java) | WALA + JavaParser. Bytecode-level call graphs, type hierarchies, symbol resolution, CRUD-operation and entry-point detection. Optional read-only **Neo4j** graph backend. |
-| **Python** | [`codeanalyzer-python`](https://github.com/codellm-devkit/codeanalyzer-python) | Jedi with optional CodeQL augmentation. Symbol tables, call graphs, and class/method resolution. Optional read-only **Neo4j** graph backend. |
+| **Python** | [`codeanalyzer-python`](https://github.com/codellm-devkit/codeanalyzer-python) | Jedi with PyCG-based call graphs. Symbol tables, call graphs, and class/method resolution. Optional read-only **Neo4j** graph backend. |
 | **TypeScript / JavaScript** | [`codeanalyzer-typescript`](https://github.com/codellm-devkit/codeanalyzer-typescript) | ts-morph with Jelly-based call graphs. Symbols, call graph, types, decorators, and call sites. Optional read-only **Neo4j** graph backend. |
 
 The backend is selected by the **type** of the `backend=` config you pass to a factory: the in-process analyzer (default) or a `Neo4jConnectionConfig` for the read-only graph backend.
 
-> **Analysis cache (Python):** caching is owned by `codeanalyzer-python` — the backend virtualenv, CodeQL database, and analysis cache live under `cache_dir` (default `<project>/.codeanalyzer`). CodeQL is on by default, so the first run is slow (it provisions a CodeQL DB) and later runs reuse a checksum-validated cache. Add the cache directory to your `.gitignore`.
+> **Analysis cache (Python):** caching is owned by `codeanalyzer-python` — the backend virtualenv and analysis cache live under `cache_dir` (default `<project>/.codeanalyzer`). The first run is slower (it provisions the backend virtualenv) and later runs reuse a checksum-validated cache. Add the cache directory to your `.gitignore`.
 
 ## Architecture
 
@@ -147,7 +147,7 @@ graph TD
     A --> T[cldk.analysis.typescript]
 
     J --> EJ[codeanalyzer-java<br/>WALA · JavaParser]
-    P --> EP[codeanalyzer-python<br/>Jedi · CodeQL]
+    P --> EP[codeanalyzer-python<br/>Jedi · PyCG]
     T --> ET[codeanalyzer-typescript<br/>ts-morph · Jelly]
 
     J -. read-only .-> N[(Neo4j)]

cldk/analysis/commons/backend_config.py

@@ -67,11 +67,9 @@ class PyCodeAnalyzerConfig(CodeAnalyzerConfig):
     Adds the Python-only call-graph knobs on top of :class:`CodeAnalyzerConfig`.
 
     Attributes:
-        use_codeql: If ``True`` (default), augment Jedi-based call-graph resolution with CodeQL.
         use_ray: If ``True``, enable Ray-based parallel processing for large projects.
     """
 
-    use_codeql: bool = True
     use_ray: bool = False
 
 

cldk/analysis/java/codeanalyzer/_jdk.py

@@ -16,9 +16,8 @@
 
 """Fetch + cache a self-contained Temurin JDK to run codeanalyzer.jar.
 
-Mirrors the codeanalyzer-python ``CodeQLLoader`` pattern (download a platform
-archive from a release, extract restoring exec bits, locate the binary), adapted
-for a JDK:
+Follows a platform-binary loader pattern (download a platform archive from a
+release, extract restoring exec bits, locate the binary), adapted for a JDK:
 
   * pinned to an exact Temurin release (reproducible) instead of "latest",
   * SHA256-verified,
@@ -55,7 +54,7 @@
 
 
 class JdkLoader:
-    """Resolve a Temurin JDK from the Adoptium API, mirroring CodeQLLoader."""
+    """Resolve a Temurin JDK from the Adoptium API."""
 
     _API = "https://api.adoptium.net/v3"
 
@@ -131,8 +130,7 @@ def download_and_extract(cls, dest: Path) -> Path:
 
         logger.info(f"Extracting JDK to {dest}")
         if archive.name.endswith(".zip"):
-            # zipfile.extractall drops the executable bit; copy each stored mode
-            # back (same fix the CodeQL loader applies).
+            # zipfile.extractall drops the executable bit; copy each stored mode back.
             with zipfile.ZipFile(archive) as zf:
                 for info in zf.infolist():
                     out = zf.extract(info, dest)
@@ -160,7 +158,7 @@ def ensure_jdk(java_cache_dir: Path) -> Path:
             cached at ``<java_cache_dir>/jdk/<release>/`` -- the existing per-language
             cache root, not a new location.
 
-    Resolution order (mirrors codeanalyzer-python's ``_ensure_codeql_bin``):
+    Resolution order:
       1. the cached JDK under ``<java_cache_dir>/jdk/<release>/`` -- reused across runs;
       2. a system ``$JAVA_HOME`` that actually has ``jmods`` -- honored verbatim;
       3. otherwise download + extract the pinned Temurin JDK into the cache.

cldk/analysis/python/codeanalyzer/codeanalyzer.py

@@ -29,7 +29,7 @@
 
 The analysis leverages:
     - **Jedi**: For semantic code understanding and symbol resolution.
-    - **CodeQL** (optional): For enhanced call graph resolution.
+    - **PyCG**: For call-graph construction.
     - **Tree-sitter**: For fast syntactic parsing.
 
 Key features:
@@ -111,7 +111,6 @@ class PyCodeanalyzer(PythonAnalysisBackend):
         analysis_level (str): The depth of analysis performed.
         eager_analysis (bool): Whether to force regeneration of caches.
         target_files (List[str] | None): Specific files to analyze.
-        use_codeql (bool): Whether CodeQL is used for call graph enhancement.
         cache_dir (Path | None): Cache directory for the backend.
         analysis_json_path (Path | None): Path for persisting analysis results.
         application (PyApplication): The analyzed application model.
@@ -129,7 +128,6 @@ def __init__(
         eager_analysis: bool,
         cache_dir: Union[str, Path, None] = None,
         target_files: List[str] | None = None,
-        use_codeql: bool = True,
         use_ray: bool = False,
     ) -> None:
         """Initialize the Python code analyzer and run analysis.
@@ -154,27 +152,23 @@ def __init__(
                 its analysis from scratch, ignoring any cached results.
                 If ``False``, cached results are reused when available.
             cache_dir: Directory for codeanalyzer-python's caches, including
-                its virtualenv, CodeQL database, and analysis cache files.
-                If ``None``, defaults to ``<project_dir>/.codeanalyzer``.
+                its virtualenv and analysis cache files. If ``None``, defaults
+                to ``<project_dir>/.codeanalyzer``.
             target_files: Optional list of specific files to analyze. Note
                 that codeanalyzer-python currently supports only a single
                 target file; if multiple are provided, only the first is
                 used and a warning is logged.
-            use_codeql: If ``True`` (default), uses CodeQL to enhance call
-                graph resolution beyond what Jedi provides. Set to ``False``
-                for faster analysis without CodeQL.
             use_ray: If ``True``, enables Ray-based parallel processing for
-                analysis. Recommended for very large projects where Jedi/CodeQL
-                analysis would otherwise be slow. Requires Ray to be installed.
+                analysis. Recommended for very large projects where analysis
+                would otherwise be slow. Requires Ray to be installed.
                 Defaults to ``False``.
 
         Raises:
             ValueError: If ``project_dir`` is ``None``.
 
         Note:
             Analysis is performed synchronously during initialization.
-            For large projects, this may take significant time, especially
-            with ``use_codeql=True``.
+            For large projects, this may take significant time.
         """
         if project_dir is None:
             raise ValueError("project_dir is required for Python analysis.")
@@ -185,7 +179,6 @@ def __init__(
         self.analysis_level = analysis_level
         self.eager_analysis = eager_analysis
         self.target_files = target_files
-        self.use_codeql = use_codeql
         self.use_ray = use_ray
 
         # codeanalyzer-python owns all caching. CLDK forwards these paths
@@ -234,7 +227,6 @@ def _run_analyzer(self) -> PyApplication:
             input=self.project_dir,
             output=self.analysis_json_path,
             format=OutputFormat.JSON,
-            using_codeql=self.use_codeql,
             using_ray=self.use_ray,
             rebuild_analysis=self.eager_analysis,
             skip_tests=True,

cldk/analysis/python/python_analysis.py

@@ -25,8 +25,7 @@
 combination of:
     - **Jedi**: For semantic code understanding, symbol resolution, and basic
       call graph construction.
-    - **CodeQL** (optional): For enhanced call graph resolution and more
-      accurate inter-procedural analysis.
+    - **PyCG**: For call-graph construction.
     - **Tree-sitter**: For fast syntactic parsing and AST operations.
 
 Key capabilities include:
@@ -183,7 +182,6 @@ def __init__(
                 eager_analysis=eager_analysis,
                 cache_dir=cache_path,
                 target_files=target_files,
-                use_codeql=getattr(cfg, "use_codeql", True),
                 use_ray=getattr(cfg, "use_ray", False),
             )
 
@@ -370,7 +368,7 @@ def get_call_graph(self) -> nx.DiGraph:
 
         The call graph is built using:
             - Jedi for semantic call resolution
-            - CodeQL (if enabled) for enhanced inter-procedural analysis
+            - PyCG for inter-procedural call-graph construction
 
         Returns:
             A ``networkx.DiGraph`` where:
@@ -380,9 +378,8 @@ def get_call_graph(self) -> nx.DiGraph:
                 - Edge attributes may include call site information
 
         Note:
-            The completeness of the call graph depends on the analysis
-            configuration. With ``use_codeql=True``, more call relationships
-            are typically discovered at the cost of longer analysis time.
+            The completeness of the call graph depends on the analysis backend
+            (Jedi plus PyCG in codeanalyzer-python 0.3.0).
 
         See Also:
             :meth:`get_callers`: For finding callers of a specific method.

cldk/core.py

@@ -25,8 +25,8 @@
 The CLDK supports the following languages:
     - **Java**: Full static analysis via CodeAnalyzer backend, including symbol
       tables, call graphs, and code metrics.
-    - **Python**: Static analysis via codeanalyzer-python backend with optional
-      CodeQL-augmented call graph resolution.
+    - **Python**: Static analysis via codeanalyzer-python backend (Jedi plus
+      PyCG call-graph construction).
     - **C**: Basic analysis via libclang for parsing and extracting code structure.
 
 Typical usage involves instantiating :class:`CLDK` with a target language, then
@@ -252,7 +252,6 @@ def analysis(
         analysis_backend_path: str | None = None,
         analysis_json_path: str | Path | None = None,
         cache_dir: str | Path | None = None,
-        use_codeql: bool = True,
         use_ray: bool = False,
         neo4j_config: "Neo4jConnectionConfig | None" = None,
     ) -> JavaAnalysis | PythonAnalysis | CAnalysis | TypeScriptAnalysis:
@@ -300,7 +299,7 @@ def analysis(
         elif self.language == "python":
             if source_code is not None:
                 raise CldkInitializationException("source_code mode is not supported for Python; please pass project_path.")
-            backend = neo4j_config if neo4j_config is not None else PyCodeAnalyzerConfig(cache_dir=cache_root, use_codeql=use_codeql, use_ray=use_ray)
+            backend = neo4j_config if neo4j_config is not None else PyCodeAnalyzerConfig(cache_dir=cache_root, use_ray=use_ray)
             return CLDK.python(
                 project_path=project_path,
                 analysis_level=analysis_level,

cldk/utils/exceptions/__init__.py

@@ -21,13 +21,9 @@
 from .exceptions import (
     CldkInitializationException,
     CodeanalyzerExecutionException,
-    CodeQLDatabaseBuildException,
-    CodeQLQueryExecutionException,
 )
 
 __all__ = [
-    "CodeQLDatabaseBuildException",
-    "CodeQLQueryExecutionException",
     "CodeanalyzerExecutionException",
     "CldkInitializationException",
 ]

cldk/utils/exceptions/exceptions.py

@@ -23,8 +23,6 @@
     - **Initialization Errors**: :class:`CldkInitializationException`
     - **Analysis Backend Errors**: :class:`CodeanalyzerExecutionException`,
       :class:`CodeanalyzerUsageException`
-    - **CodeQL Errors**: :class:`CodeQLDatabaseBuildException`,
-      :class:`CodeQLQueryExecutionException`
 
 All exceptions inherit from Python's built-in :class:`Exception` class and
 include a descriptive message attribute.
@@ -89,75 +87,6 @@ def __init__(self, message: str) -> None:
         super().__init__(self.message)
 
 
-class CodeQLDatabaseBuildException(Exception):
-    """Exception raised for errors during CodeQL database building.
-
-    This exception is raised when the CodeQL database creation fails.
-    CodeQL databases are used for enhanced call graph analysis in Python.
-    Common causes include:
-        - CodeQL CLI not installed or not on PATH
-        - Invalid project structure for CodeQL
-        - Insufficient disk space
-        - Build errors in the target project
-
-    Attributes:
-        message (str): A descriptive error message explaining the
-            database build failure.
-
-    Note:
-        This exception is primarily relevant for Python analysis when
-        ``use_codeql=True`` is specified.
-
-    See Also:
-        :class:`~cldk.analysis.python.PythonAnalysis`: Python analysis
-            that may use CodeQL.
-    """
-
-    def __init__(self, message: str) -> None:
-        """Initialize the exception with a descriptive message.
-
-        Args:
-            message: A descriptive error message explaining what went wrong
-                during CodeQL database creation.
-        """
-        self.message = message
-        super().__init__(self.message)
-
-
-class CodeQLQueryExecutionException(Exception):
-    """Exception raised for errors during CodeQL query execution.
-
-    This exception is raised when a CodeQL query fails to execute against
-    a CodeQL database. Common causes include:
-        - Invalid query syntax
-        - Query timeout
-        - Database corruption
-        - Incompatible CodeQL version
-
-    Attributes:
-        message (str): A descriptive error message explaining the
-            query execution failure.
-
-    Note:
-        This exception is primarily relevant for Python analysis when
-        ``use_codeql=True`` is specified.
-
-    See Also:
-        :class:`CodeQLDatabaseBuildException`: Related exception for
-            database creation failures.
-    """
-
-    def __init__(self, message: str) -> None:
-        """Initialize the exception with a descriptive message.
-
-        Args:
-            message: A descriptive error message explaining what went wrong
-                during CodeQL query execution.
-        """
-        self.message = message
-        super().__init__(self.message)
-
-
 class CodeanalyzerUsageException(Exception):
     """Exception raised for incorrect CodeAnalyzer usage.
 

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "cldk"
-version = "1.3.0"
+version = "1.4.0"
 description = "The official Python SDK for Codellm-Devkit."
 readme = "README.md"
 license = { text = "Apache-2.0" }
@@ -40,7 +40,7 @@ dependencies = [
     "tree-sitter-javascript==0.23.1",
     "clang==17.0.6",
     "libclang==17.0.6",
-    "codeanalyzer-python==0.2.0",
+    "codeanalyzer-python==0.3.0",
     "codeanalyzer-typescript==0.4.3",
 ]
 
@@ -88,7 +88,7 @@ include = [
 
 [tool.backend-versions]
 codeanalyzer-java = "2.4.1"
-codeanalyzer-python = "0.2.0"
+codeanalyzer-python = "0.3.0"
 codeanalyzer-typescript = "0.4.3"
 
 ########################################