codeanalyzer-python 0.2.1__py3-none-any.whl → 0.3.1__py3-none-any.whl

codeanalyzer/neo4j/catalog.py

@@ -1,245 +0,0 @@
-################################################################################
-# Copyright IBM Corporation 2025
-#
-# Licensed under the Apache License, Version 2.0 (the "License");
-# you may not use this file except in compliance with the License.
-# You may obtain a copy of the License at
-#
-#       http://www.apache.org/licenses/LICENSE-2.0
-#
-# Unless required by applicable law or agreed to in writing, software
-# distributed under the License is distributed on an "AS IS" BASIS,
-# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-# See the License for the specific language governing permissions and
-# limitations under the License.
-################################################################################
-
-"""The declarative Neo4j schema catalog — the single in-repo source of truth for
-the graph contract (node labels, their keys and typed properties, relationship
-types and their endpoints). ``--emit schema`` serializes this (with the DDL from
-:mod:`codeanalyzer.neo4j.schema`) to a machine-readable ``schema.json``, and the
-conformance test (``test/test_neo4j_schema.py``) asserts the real emitter never
-produces a label / relationship / property that isn't declared here — so this
-file cannot silently drift from :mod:`codeanalyzer.neo4j.project`.
-
-SCHEMA_VERSION is the contract version: bump MAJOR on a breaking change
-(renamed/removed label, relationship or key), MINOR on an additive change (new
-label/rel/property). It is stamped onto the ``:PyApplication`` node of every
-emitted graph so any consumer can detect a producer/consumer mismatch at runtime.
-"""
-from __future__ import annotations
-
-from dataclasses import dataclass, field
-from typing import Dict, List
-
-from codeanalyzer.neo4j.schema import CONSTRAINTS, INDEXES
-
-SCHEMA_VERSION = "1.1.0"
-
-# PropType ∈ {"string", "integer", "float", "boolean", "string[]", "integer[]"}.
-
-
-@dataclass
-class NodeLabel:
-    label: str  # the specific label (also the catalog key)
-    merge_label: str  # the label the uniqueness constraint / MERGE is on
-    key: str
-    properties: Dict[str, str]
-
-
-@dataclass
-class RelType:
-    type: str
-    from_labels: List[str]
-    to_labels: List[str]
-    properties: Dict[str, str] = field(default_factory=dict)
-
-
-# Labels layered onto a node in addition to its primary/specific label.
-MARKER_LABELS: List[str] = []
-
-_SPAN = {"start_line": "integer", "end_line": "integer"}
-
-
-NODE_LABELS: List[NodeLabel] = [
-    NodeLabel(
-        "PyApplication",
-        "PyApplication",
-        "name",
-        {"name": "string", "schema_version": "string"},
-    ),
-    NodeLabel(
-        "PyModule",
-        "PyModule",
-        "file_key",
-        {
-            "file_key": "string",
-            "module_name": "string",
-            "content_hash": "string",
-            "last_modified": "float",
-            "file_size": "integer",
-            "_module": "string",
-        },
-    ),
-    NodeLabel(
-        "PyClass",
-        "PySymbol",
-        "signature",
-        {
-            "signature": "string",
-            "name": "string",
-            "code": "string",
-            "base_classes": "string[]",
-            "docstring": "string",
-            **_SPAN,
-            "_module": "string",
-        },
-    ),
-    NodeLabel(
-        "PyCallable",
-        "PySymbol",
-        "signature",
-        {
-            "signature": "string",
-            "name": "string",
-            "path": "string",
-            "return_type": "string",
-            "cyclomatic_complexity": "integer",
-            "code": "string",
-            "code_start_line": "integer",
-            **_SPAN,
-            "docstring": "string",
-            "decorators": "string[]",
-            "parameters_json": "string",
-            "accessed_symbols_json": "string",
-            "_module": "string",
-        },
-    ),
-    NodeLabel(
-        "PyExternal",
-        "PySymbol",
-        "signature",
-        {"signature": "string", "name": "string", "module": "string"},
-    ),
-    NodeLabel("PyPackage", "PyPackage", "name", {"name": "string"}),
-    NodeLabel(
-        "PyDecorator",
-        "PyDecorator",
-        "name",
-        {"name": "string"},
-    ),
-    NodeLabel(
-        "PyCallSite",
-        "PyCallSite",
-        "id",
-        {
-            "id": "string",
-            "method_name": "string",
-            "receiver_expr": "string",
-            "receiver_type": "string",
-            "argument_types": "string[]",
-            "return_type": "string",
-            "callee_signature": "string",
-            "is_constructor_call": "boolean",
-            "start_line": "integer",
-            "start_column": "integer",
-            "end_line": "integer",
-            "end_column": "integer",
-            "_module": "string",
-        },
-    ),
-    NodeLabel(
-        "PyAttribute",
-        "PyAttribute",
-        "id",
-        {
-            "id": "string",
-            "name": "string",
-            "type": "string",
-            "docstring": "string",
-            **_SPAN,
-            "_module": "string",
-        },
-    ),
-    NodeLabel(
-        "PyVariable",
-        "PyVariable",
-        "id",
-        {
-            "id": "string",
-            "name": "string",
-            "type": "string",
-            "initializer": "string",
-            "scope": "string",
-            **_SPAN,
-            "_module": "string",
-        },
-    ),
-]
-
-_DECL_TARGETS = ["PyClass", "PyCallable"]
-
-
-REL_TYPES: List[RelType] = [
-    RelType("PY_HAS_MODULE", ["PyApplication"], ["PyModule"]),
-    RelType("PY_DECLARES", ["PyModule", "PyClass", "PyCallable"], _DECL_TARGETS),
-    RelType("PY_HAS_METHOD", ["PyClass"], ["PyCallable"]),
-    RelType("PY_HAS_ATTRIBUTE", ["PyClass"], ["PyAttribute"]),
-    RelType("PY_DECLARES_VAR", ["PyModule", "PyCallable"], ["PyVariable"]),
-    RelType("PY_HAS_CALLSITE", ["PyCallable"], ["PyCallSite"]),
-    RelType("PY_RESOLVES_TO", ["PyCallSite"], ["PyCallable", "PyExternal"]),
-    RelType(
-        "PY_CALLS",
-        ["PyCallable", "PyExternal"],
-        ["PyCallable", "PyExternal"],
-        {"weight": "integer", "provenance": "string[]"},
-    ),
-    RelType("PY_EXTENDS", ["PyClass"], ["PyClass"]),
-    RelType(
-        "PY_IMPORTS",
-        ["PyModule"],
-        ["PyPackage"],
-        {"imported_names": "string[]", "aliases": "string[]"},
-    ),
-    RelType("PY_DECORATED_BY", ["PyCallable"], ["PyDecorator"]),
-]
-
-
-@dataclass
-class SchemaDocument:
-    schema_version: str
-    generator: str
-    marker_labels: List[str]
-    node_labels: List[NodeLabel]
-    relationship_types: List[RelType]
-    constraints: List[str]
-    indexes: List[str]
-
-
-def build_schema_document() -> dict:
-    """Build the full machine-readable schema document emitted by ``--emit schema``."""
-    return {
-        "schema_version": SCHEMA_VERSION,
-        "generator": "codeanalyzer-python",
-        "marker_labels": list(MARKER_LABELS),
-        "node_labels": [
-            {
-                "label": n.label,
-                "merge_label": n.merge_label,
-                "key": n.key,
-                "properties": n.properties,
-            }
-            for n in NODE_LABELS
-        ],
-        "relationship_types": [
-            {
-                "type": r.type,
-                "from": r.from_labels,
-                "to": r.to_labels,
-                "properties": r.properties,
-            }
-            for r in REL_TYPES
-        ],
-        "constraints": list(CONSTRAINTS),
-        "indexes": list(INDEXES),
-    }

codeanalyzer/semantic_analysis/codeql/codeql_analysis.py

@@ -1,382 +0,0 @@
-################################################################################
-# Copyright IBM Corporation 2025
-#
-# Licensed under the Apache License, Version 2.0 (the "License");
-# you may not use this file except in compliance with the License.
-# You may obtain a copy of the License at
-#
-#       http://www.apache.org/licenses/LICENSE-2.0
-#
-# Unless required by applicable law or agreed to in writing, software
-# distributed under the License is distributed on an "AS IS" BASIS,
-# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-# See the License for the specific language governing permissions and
-# limitations under the License.
-################################################################################
-
-"""CodeQL module for analyzing Python code using CodeQL.
-
-This module provides functionality to create and manage CodeQL databases
-for Python projects and execute queries against them.
-"""
-
-from collections import Counter
-from pathlib import Path
-from typing import Any, Dict, Iterator, List, Tuple, Union
-
-from pandas import DataFrame
-
-from codeanalyzer.schema.py_schema import PyCallEdge, PyModule
-from codeanalyzer.semantic_analysis.call_graph import iter_callables_in_symbol_table
-from codeanalyzer.semantic_analysis.codeql.codeql_query_runner import CodeQLQueryRunner
-from codeanalyzer.utils import logger
-
-
-class _CallableResolver:
-    """Maps a CodeQL endpoint ``(file, start_line, name, arity)`` to a Jedi
-    ``PyCallable``.
-
-    Resolution ladder:
-      1. exact ``(abs_path, start_line)`` — the precise join;
-      2. on miss, candidates sharing ``(abs_path, short_name)``: a single
-         candidate is taken directly; otherwise prefer those whose
-         parameter count equals the CodeQL positional arity, then the
-         nearest ``start_line``;
-      3. no name match -> ``None`` (caller row skipped / callee becomes
-         a ghost node).
-
-    Step 2 recovers edges the ``(file, line)`` join silently drops when
-    CodeQL and Jedi disagree on a definition's start line (e.g. decorator
-    handling). Jedi's ``parameters`` counts every declared slot (incl.
-    ``*args``/``**kwargs``/keyword-only) whereas CodeQL's arity is
-    positional only, so the arity filter is exact for plain signatures
-    and otherwise yields to the nearest-line tiebreak.
-    """
-
-    def __init__(self) -> None:
-        self._by_loc: Dict[Tuple[str, int], Any] = {}
-        self._by_name: Dict[Tuple[str, str], List[Any]] = {}
-
-    @staticmethod
-    def _abs(path: str) -> str:
-        try:
-            return str(Path(path).resolve())
-        except (OSError, RuntimeError):
-            return path
-
-    @classmethod
-    def from_symbol_table(
-        cls, symbol_table: Dict[str, PyModule]
-    ) -> "_CallableResolver":
-        resolver = cls()
-        for c in iter_callables_in_symbol_table(symbol_table):
-            abs_path = cls._abs(c.path)
-            resolver._by_loc[(abs_path, c.start_line)] = c
-            resolver._by_name.setdefault((abs_path, c.name), []).append(c)
-        return resolver
-
-    def resolve(
-        self, file: str, start_line: int, name: str, arity: int
-    ) -> Any:
-        exact = self._by_loc.get((file, start_line))
-        if exact is not None:
-            return exact
-        if not name:
-            return None
-        candidates = self._by_name.get((file, name))
-        if not candidates:
-            return None
-        if len(candidates) == 1:
-            return candidates[0]
-        arity_matched = [c for c in candidates if len(c.parameters) == arity]
-        pool = arity_matched or candidates
-        return min(pool, key=lambda c: abs(c.start_line - start_line))
-
-
-class CodeQL:
-    """A class for building the application view of a Python application using CodeQL.
-
-    Args:
-        project_dir (str or Path): The path to the root of the Python project.
-
-    Attributes:
-        db_path (Path): The path to the CodeQL database.
-        temp_db (TemporaryDirectory or None): The temporary directory object if a temporary database was created.
-    """
-
-    def __init__(
-        self,
-        project_dir: Union[str, Path],
-        db_path: Path,
-        codeql_bin: Union[str, Path, None] = None,
-        codeql_packs_dir: Union[str, Path, None] = None,
-    ) -> None:
-        self.project_dir = project_dir
-        self.db_path = db_path
-        self.codeql_bin = codeql_bin
-        self.codeql_packs_dir = codeql_packs_dir
-        self._cached_df: "DataFrame | None" = None
-
-    def _query_call_edges(self) -> DataFrame:
-        """Runs the CodeQL query that emits one row per resolved call site.
-
-        The query is written against CodeQL's Python library (``import python``).
-        It returns physical location handles for both endpoints so the
-        downstream post-processor can join into Jedi's existing
-        ``PyCallable.signature`` space via ``(file_path, start_line)`` —
-        no signature normalization required.
-
-        Filters:
-          * Caller must be a ``Function`` (skip module-level / class-body
-            calls — they have no ``PyCallable`` to anchor to).
-          * Callee may resolve to anything (in-source or library stub);
-            non-application callees become **ghost** nodes downstream so
-            RPC / third-party / framework edges are preserved.
-
-        Returns:
-            DataFrame: one row per resolved (caller, callee, call-site)
-            triple. Duplicate ``(caller_file, caller_start_line,
-            callee_file, callee_start_line)`` tuples represent multiple
-            call sites in the same caller targeting the same callee and
-            are coalesced into a single ``PyCallEdge`` (weight = count)
-            by the post-processor.
-        """
-        query = [
-            "/**",
-            " * @name Python call-graph edges",
-            " * @description One row per resolved call site: caller, callee,",
-            " *              and the call-expression location.",
-            " * @kind table",
-            " * @id py/codeanalyzer/call-graph-edges",
-            " */",
-            "import python",
-            # ``FunctionValue`` / ``ClassValue`` / the ``pointsTo`` predicate
-            # live in ObjectAPI, which ``import python`` only brings in as a
-            # private import — they aren't re-exported. Pull them in
-            # explicitly.
-            "import semmle.python.objects.ObjectAPI",
-            "",
-            # ``Value.getACall()`` is the modern call-resolution API in
-            # codeql/python-all 7.x — it returns the ``CallNode`` (CFG)
-            # whose target was resolved to that ``Value``. Cleaner than
-            # poking at ``pointsTo`` directly.
-            # ``callee`` is bound to the FunctionValue's scope so the
-            # endpoint emits the same Function-level facts (name, arity,
-            # location) the post-processor needs for the name+arity
-            # fallback when the (file, start_line) join misses.
-            "from CallNode call, Function caller, FunctionValue calleeVal, Function callee",
-            "where",
-            "  call.getScope() = caller and",
-            "  callee = calleeVal.getScope() and",
-            "  (",
-            # Direct function / bound-method call:  foo()  or  obj.foo()
-            "    call = calleeVal.getACall()",
-            "    or",
-            # Constructor call:  A(...)  resolves to a ClassValue; the actual
-            # callee is the class's __init__ (via MRO lookup so subclasses
-            # without an explicit __init__ still resolve to the inherited one).
-            "    exists(ClassValue clsVal |",
-            "      call = clsVal.getACall() and",
-            '      clsVal.lookup("__init__") = calleeVal',
-            "    )",
-            "  )",
-            "select",
-            # --- Caller endpoint --- (joins to PyCallable: exact by
-            #     (file, start_line), else by (file, name) + arity)
-            "  caller.getLocation().getFile().getAbsolutePath(),",
-            "  caller.getLocation().getStartLine(),",
-            "  caller.getQualifiedName(),",
-            "  caller.getName(),",
-            "  count(caller.getArg(_)),",
-            # --- Callee endpoint --- (file/line may live in a library stub;
-            #     post-processor classifies as in-source or ghost)
-            "  callee.getLocation().getFile().getAbsolutePath(),",
-            "  callee.getLocation().getStartLine(),",
-            "  calleeVal.getQualifiedName(),",
-            "  callee.getName(),",
-            "  count(callee.getArg(_)),",
-            # --- Call-site location --- (for PyCallsite augmentation)
-            "  call.getLocation().getStartLine(),",
-            "  call.getLocation().getStartColumn(),",
-            "  call.getLocation().getEndLine(),",
-            "  call.getLocation().getEndColumn()",
-            # ``is_constructor`` is derived in the post-processor by
-            # checking whether ``callee_qname`` ends in ``.__init__``;
-            # avoids QL's restrictive ``if-then-else`` typing here.
-        ]
-        if self._cached_df is not None:
-            return self._cached_df
-
-        query_string = "\n".join(query)
-
-        with CodeQLQueryRunner(
-            self.db_path,
-            codeql_bin=self.codeql_bin,
-            codeql_packs_dir=self.codeql_packs_dir,
-        ) as runner:
-            df: DataFrame = runner.execute(
-                query_string,
-                column_names=[
-                    "caller_file",
-                    "caller_start_line",
-                    "caller_qname",
-                    "caller_name",
-                    "caller_arity",
-                    "callee_file",
-                    "callee_start_line",
-                    "callee_qname",
-                    "callee_name",
-                    "callee_arity",
-                    "call_start_line",
-                    "call_start_column",
-                    "call_end_line",
-                    "call_end_column",
-                ],
-            )
-        self._cached_df = df
-        return df
-
-    @staticmethod
-    def _build_callable_resolver(
-        symbol_table: Dict[str, PyModule],
-    ) -> _CallableResolver:
-        """Build the endpoint -> ``PyCallable`` resolver from Jedi.
-
-        Paths are resolved so they match CodeQL's ``getAbsolutePath()``
-        regardless of symlinks or the current working directory.
-        """
-        return _CallableResolver.from_symbol_table(symbol_table)
-
-    def _iter_resolved_rows(
-        self, symbol_table: Dict[str, PyModule]
-    ) -> "Iterator[Tuple[str, str, Any]]":
-        """Yield ``(source_sig, target_sig, row)`` for every CodeQL row.
-
-        Rows whose caller can't be matched to a ``PyCallable`` in the
-        symbol table are skipped. Callee misses fall back to
-        ``row.callee_qname`` (ghost). Used by both edge construction and
-        call-site augmentation so a single CodeQL query feeds both.
-        """
-        df = self._query_call_edges()
-        if df.empty:
-            return
-        resolver = self._build_callable_resolver(symbol_table)
-
-        skipped_unknown_caller = 0
-        ghost_callees = 0
-        for row in df.itertuples(index=False):
-            caller = resolver.resolve(
-                row.caller_file,
-                int(row.caller_start_line),
-                row.caller_name,
-                int(row.caller_arity),
-            )
-            if caller is None:
-                skipped_unknown_caller += 1
-                continue
-
-            callee = resolver.resolve(
-                row.callee_file,
-                int(row.callee_start_line),
-                row.callee_name,
-                int(row.callee_arity),
-            )
-            if callee is not None:
-                target_sig = callee.signature
-            else:
-                target_sig = row.callee_qname
-                ghost_callees += 1
-
-            yield caller.signature, target_sig, row
-
-        if skipped_unknown_caller:
-            logger.debug(
-                f"CodeQL: skipped {skipped_unknown_caller} rows whose caller "
-                f"was not in Jedi's symbol table."
-            )
-        if ghost_callees:
-            logger.debug(
-                f"CodeQL: {ghost_callees} rows resolved to ghost (external) callees."
-            )
-
-    def build_call_graph_edges(
-        self, symbol_table: Dict[str, PyModule]
-    ) -> List[PyCallEdge]:
-        """Run the CodeQL query and turn each row into a ``PyCallEdge``.
-
-        Edges are coalesced on ``(source, target)`` — ``weight`` is the
-        number of distinct call sites in the caller targeting the callee.
-        Provenance is always ``["codeql"]``; combine with Jedi-derived
-        edges via ``call_graph.merge_edges``.
-        """
-        edge_counts: Counter = Counter()
-        for source_sig, target_sig, _row in self._iter_resolved_rows(symbol_table):
-            edge_counts[(source_sig, target_sig)] += 1
-
-        return [
-            PyCallEdge(
-                source=src,
-                target=dst,
-                weight=count,
-                provenance=["codeql"],
-            )
-            for (src, dst), count in edge_counts.items()
-        ]
-
-    def augment_call_sites(self, symbol_table: Dict[str, PyModule]) -> int:
-        """Backfill ``PyCallsite.callee_signature`` using CodeQL resolution.
-
-        Walks every CodeQL row, locates the matching ``PyCallsite`` inside
-        the caller's ``PyCallable.call_sites`` by call-expression line range
-        (``start_line``, ``end_line``), and fills in ``callee_signature``
-        **only when Jedi left it empty**. Existing Jedi-resolved signatures
-        are kept (Jedi sees lexical context CodeQL can't, e.g. closures).
-
-        Match is by line range — column matching is brittle across the two
-        tools' 0- vs 1-based conventions. Ambiguity on a single line
-        (e.g. ``a.b().c()``) resolves to the first matching site, which is
-        an acceptable approximation given how rarely Jedi misses callees
-        on chained call lines.
-
-        Returns:
-            Number of ``PyCallsite`` entries augmented.
-        """
-        resolver = self._build_callable_resolver(symbol_table)
-        df = self._query_call_edges()
-        if df.empty:
-            return 0
-
-        augmented = 0
-        for row in df.itertuples(index=False):
-            caller = resolver.resolve(
-                row.caller_file,
-                int(row.caller_start_line),
-                row.caller_name,
-                int(row.caller_arity),
-            )
-            if caller is None:
-                continue
-
-            callee = resolver.resolve(
-                row.callee_file,
-                int(row.callee_start_line),
-                row.callee_name,
-                int(row.callee_arity),
-            )
-            resolved_sig = callee.signature if callee is not None else row.callee_qname
-
-            call_start = int(row.call_start_line)
-            call_end = int(row.call_end_line)
-            for site in caller.call_sites:
-                if site.start_line != call_start or site.end_line != call_end:
-                    continue
-                if not site.callee_signature:
-                    site.callee_signature = resolved_sig
-                    augmented += 1
-                break
-
-        if augmented:
-            logger.debug(
-                f"CodeQL: augmented {augmented} PyCallsite.callee_signature entries."
-            )
-        return augmented

codeanalyzer/semantic_analysis/codeql/codeql_exceptions.py

@@ -1,12 +0,0 @@
-class CodeQLExceptions:
-    class CodeQLDatabaseBuildException(Exception):
-        """Exception raised when there is an error building the CodeQL database."""
-
-        def __init__(self, message: str) -> None:
-            super().__init__(message)
-
-    class CodeQLQueryExecutionException(Exception):
-        """Exception raised when there is an error building the CodeQL database."""
-
-        def __init__(self, message: str) -> None:
-            super().__init__(message)