codeanalyzer-python 0.1.13__py3-none-any.whl → 0.2.0__py3-none-any.whl

codeanalyzer/neo4j/catalog.py

@@ -0,0 +1,245 @@
+################################################################################
+# 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.0.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"},
+    ),
+    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/neo4j/cypher.py

@@ -0,0 +1,138 @@
+################################################################################
+# 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 snapshot writer: render :class:`GraphRows` to a self-contained ``.cypher``
+script. Running it (e.g. ``cypher-shell < graph.cypher``) rebuilds this project's
+subgraph from scratch — constraints, a scoped wipe of the prior version, then
+batched ``UNWIND … MERGE`` for nodes and edges.
+
+This artifact is intentionally NOT incremental: a static script has no view of
+the live DB, so it expresses the full truth. Incremental updates are the bolt
+writer's job.
+"""
+from __future__ import annotations
+
+from typing import Dict, List
+
+from codeanalyzer.neo4j.rows import (
+    EdgeRow,
+    GraphRows,
+    NodeRow,
+    chunk,
+    cypher_map,
+    cypher_value,
+)
+from codeanalyzer.neo4j.schema import CONSTRAINTS, INDEXES
+
+BATCH = 500
+
+
+def render_cypher(rows: GraphRows, app_name: str) -> str:
+    out: List[str] = []
+
+    out.append("// ── constraints & indexes ──")
+    for stmt in CONSTRAINTS:
+        out.append(f"{stmt};")
+    for stmt in INDEXES:
+        out.append(f"{stmt};")
+
+    out.append("")
+    out.append("// ── wipe this project's prior subgraph (externals/packages/decorators are shared) ──")
+    out.append(_wipe(app_name))
+
+    out.append("")
+    out.append("// ── nodes ──")
+    out.extend(_node_statements(rows.nodes))
+
+    out.append("")
+    out.append("// ── relationships ──")
+    out.extend(_edge_statements(rows.edges))
+
+    out.append("")
+    return "\n".join(out)
+
+
+def _wipe(app_name: str) -> str:
+    name = cypher_value(app_name)
+    return "\n".join(
+        [
+            f"MATCH (a:PyApplication {{name: {name}}})",
+            "OPTIONAL MATCH (a)-[:PY_HAS_MODULE]->(m:PyModule)",
+            "OPTIONAL MATCH (m)-[:PY_DECLARES|PY_HAS_METHOD|PY_HAS_ATTRIBUTE|PY_DECLARES_VAR|PY_HAS_CALLSITE*1..]->(x)",
+            "DETACH DELETE x, m, a;",
+        ]
+    )
+
+
+# ----------------------------------------------------------------------------------------------
+# Nodes — grouped by their full label set + key property, batched into UNWIND lists.
+# ----------------------------------------------------------------------------------------------
+
+
+def _node_statements(nodes: List[NodeRow]) -> List[str]:
+    groups: Dict[str, List[NodeRow]] = {}
+    for n in nodes:
+        key = f"{':'.join(n.labels)}|{n.key_prop}"
+        groups.setdefault(key, []).append(n)
+
+    blocks: List[str] = []
+    for group in groups.values():
+        labels = group[0].labels
+        key_prop = group[0].key_prop
+        merge_label = labels[0]
+        extra = labels[1:]
+        set_labels = f", n:{':'.join(extra)}" if extra else ""
+        for batch in chunk(group, BATCH):
+            rows_lit = ",\n".join(
+                f"  {{k: {cypher_value(n.value)}, p: {cypher_map(n.props)}}}" for n in batch
+            )
+            blocks.append(
+                f"UNWIND [\n{rows_lit}\n] AS row\n"
+                f"MERGE (n:{merge_label} {{{key_prop}: row.k}})\n"
+                f"SET n += row.p{set_labels};"
+            )
+    return blocks
+
+
+# ----------------------------------------------------------------------------------------------
+# Edges — grouped by (type, endpoint labels + key props), batched.
+# ----------------------------------------------------------------------------------------------
+
+
+def _edge_statements(edges: List[EdgeRow]) -> List[str]:
+    groups: Dict[str, List[EdgeRow]] = {}
+    for e in edges:
+        key = f"{e.type}|{e.from_ref.label}.{e.from_ref.key_prop}|{e.to_ref.label}.{e.to_ref.key_prop}"
+        groups.setdefault(key, []).append(e)
+
+    blocks: List[str] = []
+    for group in groups.values():
+        first = group[0]
+        from_ref, to_ref = first.from_ref, first.to_ref
+        for batch in chunk(group, BATCH):
+            rows_lit = ",\n".join(
+                f"  {{f: {cypher_value(e.from_ref.value)}, t: {cypher_value(e.to_ref.value)}, "
+                f"p: {cypher_map(e.props)}}}"
+                for e in batch
+            )
+            blocks.append(
+                f"UNWIND [\n{rows_lit}\n] AS row\n"
+                f"MATCH (a:{from_ref.label} {{{from_ref.key_prop}: row.f}})\n"
+                f"MATCH (b:{to_ref.label} {{{to_ref.key_prop}: row.t}})\n"
+                f"MERGE (a)-[r:{first.type}]->(b)\n"
+                f"SET r += row.p;"
+            )
+    return blocks

codeanalyzer/neo4j/emit.py

@@ -0,0 +1,74 @@
+################################################################################
+# 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 facade between the CLI and the Neo4j backend. Two entry points:
+
+- :func:`emit_schema` — serialize the static, version-stamped schema contract
+  (``schema.json``). Needs no analyzed project.
+- :func:`emit_neo4j` — project a :class:`PyApplication` to a graph and either
+  write a ``graph.cypher`` snapshot or push it to a live Neo4j over Bolt.
+"""
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Optional
+
+from codeanalyzer.neo4j.bolt import BoltConfig, bolt_writer
+from codeanalyzer.neo4j.catalog import build_schema_document
+from codeanalyzer.neo4j.cypher import render_cypher
+from codeanalyzer.neo4j.project import project
+from codeanalyzer.options import AnalysisOptions
+from codeanalyzer.schema import PyApplication
+from codeanalyzer.utils import logger
+
+
+def emit_schema(output: Optional[Path]) -> None:
+    """Emit the Neo4j schema contract (``schema.json``) — a static artifact derived
+    from the in-repo catalog, independent of any analyzed project. With no
+    ``output`` it prints to stdout."""
+    doc = json.dumps(build_schema_document(), indent=2) + "\n"
+    if output is None:
+        print(doc, end="")
+        return
+    output.mkdir(parents=True, exist_ok=True)
+    (output / "schema.json").write_text(doc)
+    logger.info(f"Neo4j schema written to {output / 'schema.json'}")
+
+
+def emit_neo4j(app: PyApplication, options: AnalysisOptions) -> None:
+    """Project the analysis to a graph and write it: a live Bolt push when
+    ``--neo4j-uri`` is set, otherwise a self-contained ``graph.cypher`` snapshot."""
+    app_name = options.app_name or Path(options.input).resolve().name
+    rows = project(app, app_name)
+
+    if options.neo4j_uri:
+        cfg = BoltConfig(
+            uri=options.neo4j_uri,
+            user=options.neo4j_user,
+            password=options.neo4j_password,
+            database=options.neo4j_database,
+        )
+        # A full run (no single-file restriction) makes orphan pruning safe.
+        full_run = options.file_name is None
+        bolt_writer(rows, cfg, full_run)
+        return
+
+    out_dir = options.output if options.output is not None else Path.cwd()
+    out_dir.mkdir(parents=True, exist_ok=True)
+    target = out_dir / "graph.cypher"
+    target.write_text(render_cypher(rows, app_name))
+    logger.info(f"Neo4j graph written to {target}")