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

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}")

codeanalyzer/neo4j/project.py

@@ -0,0 +1,322 @@
+################################################################################
+# 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.
+################################################################################
+
+"""``project()`` — the pure projection from the canonical :class:`PyApplication`
+IR to graph rows. It walks the same recursive symbol table the call-graph builder
+walks, but instead of collecting callables it emits nodes + edges. No I/O: the
+writers (cypher snapshot / bolt incremental) consume the returned
+:class:`GraphRows`.
+
+Modelling decisions (mirror of the TypeScript backend):
+  - signature-keyed declarations (PyClass, PyCallable) carry a shared ``:PySymbol``
+    label (the global-identity / MERGE key).
+  - call sites, decorators, class attributes and variables are first-class nodes.
+  - call-graph endpoints absent from the symbol table become ``:PyExternal`` ghost
+    nodes, so RPC / third-party / framework edges are preserved (matching the
+    analyzer's own ghost-node behaviour).
+  - every project-owned node carries an internal ``_module`` provenance prop, so
+    the incremental writer can delete exactly what a re-analyzed module emitted.
+"""
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any, List, Optional
+
+from codeanalyzer.neo4j.catalog import SCHEMA_VERSION
+from codeanalyzer.neo4j.rows import GraphRows, NodeRef, Props, RowBuilder, prune
+from codeanalyzer.schema import (
+    PyApplication,
+    PyCallable,
+    PyClass,
+    PyClassAttribute,
+    PyComment,
+    PyModule,
+    PyVariableDeclaration,
+)
+from codeanalyzer.schema.py_schema import PyCallsite
+
+
+def project(app: PyApplication, app_name: str) -> GraphRows:
+    b = RowBuilder()
+
+    app_ref = b.node(["PyApplication"], "name", app_name, {"schema_version": SCHEMA_VERSION})
+
+    for file_key, mod in app.symbol_table.items():
+        mod_ref = b.node(["PyModule"], "file_key", file_key, _module_props(mod, file_key))
+        b.edge("PY_HAS_MODULE", app_ref, mod_ref)
+        _project_module_body(b, file_key, mod_ref, mod)
+
+    # The aggregated :PY_CALLS twin. Endpoints not present in the symbol table become
+    # :PyExternal ghost nodes (the analyzer already preserves them as ghost nodes).
+    for e in app.call_graph:
+        src = _call_endpoint(b, e.source)
+        tgt = _call_endpoint(b, e.target)
+        b.edge("PY_CALLS", src, tgt, _call_edge_props(e.weight, list(e.provenance or [])))
+
+    return b.finish()
+
+
+def _sym(signature: str) -> NodeRef:
+    return NodeRef("PySymbol", "signature", signature)
+
+
+def _call_endpoint(b: RowBuilder, signature: str) -> NodeRef:
+    """A call-graph endpoint: a known callable already emitted, or a phantom
+    :PyExternal symbol materialized on demand for a ghost target."""
+    if b.has_key(signature):
+        return _sym(signature)
+    name = signature.rsplit(".", 1)[-1] if "." in signature else signature
+    return b.node(["PySymbol", "PyExternal"], "signature", signature, {"name": name})
+
+
+# ----------------------------------------------------------------------------------------------
+# Module body
+# ----------------------------------------------------------------------------------------------
+
+
+def _project_module_body(b: RowBuilder, file_key: str, mod_ref: NodeRef, mod: PyModule) -> None:
+    for fn in (mod.functions or {}).values():
+        _project_callable(b, file_key, mod_ref, "PY_DECLARES", fn)
+    for cl in (mod.classes or {}).values():
+        _project_class(b, file_key, mod_ref, "PY_DECLARES", cl)
+    for v in mod.variables or []:
+        _project_variable(b, file_key, mod_ref, file_key, v)
+    _project_imports(b, mod_ref, mod)
+
+
+def _project_imports(b: RowBuilder, mod_ref: NodeRef, mod: PyModule) -> None:
+    # Per-target-module aggregation: collapse all bindings for a given imported
+    # module into one PY_IMPORTS edge to a shared :PyPackage node.
+    agg: dict = {}
+    for im in mod.imports or []:
+        if not im.module:
+            continue  # relative `from . import x` — no resolvable package
+        a = agg.setdefault(im.module, {"names": set(), "aliases": set()})
+        if im.name:
+            a["names"].add(im.name)
+        if im.alias:
+            a["aliases"].add(im.alias)
+    for module_name, a in agg.items():
+        pkg = b.node(["PyPackage"], "name", module_name, {})
+        b.edge(
+            "PY_IMPORTS",
+            mod_ref,
+            pkg,
+            prune(
+                {
+                    "imported_names": sorted(a["names"]) or None,
+                    "aliases": sorted(a["aliases"]) or None,
+                }
+            ),
+        )
+
+
+# ----------------------------------------------------------------------------------------------
+# Declarations
+# ----------------------------------------------------------------------------------------------
+
+
+def _project_class(
+    b: RowBuilder, file_key: str, parent: NodeRef, parent_rel: str, cl: PyClass
+) -> None:
+    ref = b.node(["PySymbol", "PyClass"], "signature", cl.signature, _class_props(cl, file_key))
+    b.edge(parent_rel, parent, ref)
+
+    for base in cl.base_classes or []:
+        b.edge_to_symbol("PY_EXTENDS", ref, base)
+
+    for m in (cl.methods or {}).values():
+        _project_callable(b, file_key, ref, "PY_HAS_METHOD", m)
+    for a in (cl.attributes or {}).values():
+        _project_attribute(b, file_key, ref, cl.signature, a)
+    for ic in (cl.inner_classes or {}).values():
+        _project_class(b, file_key, ref, "PY_DECLARES", ic)
+
+
+def _project_callable(
+    b: RowBuilder, file_key: str, owner: NodeRef, owner_rel: str, c: PyCallable
+) -> None:
+    ref = b.node(["PySymbol", "PyCallable"], "signature", c.signature, _callable_props(c, file_key))
+    b.edge(owner_rel, owner, ref)
+
+    for d in c.decorators or []:
+        _project_decorator(b, ref, d)
+
+    for s in c.call_sites or []:
+        # Key off the relative file (a call site lives in its callable's file) so ids stay portable.
+        cs_id = f"{file_key}#{s.start_line}:{s.start_column}-{s.end_line}:{s.end_column}"
+        cs = b.node(["PyCallSite"], "id", cs_id, _call_site_props(s, file_key))
+        b.edge("PY_HAS_CALLSITE", ref, cs)
+        if s.callee_signature:
+            b.edge_to_symbol("PY_RESOLVES_TO", cs, s.callee_signature)
+
+    for v in c.local_variables or []:
+        _project_variable(b, file_key, ref, c.signature, v)
+    for ic in (c.inner_callables or {}).values():
+        _project_callable(b, file_key, ref, "PY_DECLARES", ic)
+    for cl in (c.inner_classes or {}).values():
+        _project_class(b, file_key, ref, "PY_DECLARES", cl)
+
+
+def _project_attribute(
+    b: RowBuilder, file_key: str, owner: NodeRef, owner_sig: str, a: PyClassAttribute
+) -> None:
+    attr_id = f"{owner_sig}.{a.name}"
+    ref = b.node(["PyAttribute"], "id", attr_id, _attribute_props(a, attr_id, file_key))
+    b.edge("PY_HAS_ATTRIBUTE", owner, ref)
+
+
+def _project_variable(
+    b: RowBuilder, file_key: str, owner: NodeRef, owner_id: str, v: PyVariableDeclaration
+) -> None:
+    var_id = f"{owner_id}#{v.name}@{v.start_line}"
+    ref = b.node(["PyVariable"], "id", var_id, _variable_props(v, var_id, file_key))
+    b.edge("PY_DECLARES_VAR", owner, ref)
+
+
+def _project_decorator(b: RowBuilder, on: NodeRef, decorator: str) -> None:
+    dec = b.node(["PyDecorator"], "name", decorator, {"name": decorator})
+    b.edge("PY_DECORATED_BY", on, dec)
+
+
+# ----------------------------------------------------------------------------------------------
+# Property flattening
+# ----------------------------------------------------------------------------------------------
+
+
+def _module_props(mod: PyModule, file_key: str) -> Props:
+    return prune(
+        {
+            "module_name": mod.module_name,
+            "content_hash": mod.content_hash,
+            "last_modified": mod.last_modified,
+            "file_size": mod.file_size,
+            "_module": file_key,
+        }
+    )
+
+
+def _class_props(cl: PyClass, file_key: str) -> Props:
+    return prune(
+        {
+            "name": cl.name,
+            "code": cl.code,
+            "base_classes": list(cl.base_classes or []),
+            "docstring": _docstring_of(cl.comments),
+            "start_line": cl.start_line,
+            "end_line": cl.end_line,
+            "_module": file_key,
+        }
+    )
+
+
+def _callable_props(c: PyCallable, file_key: str) -> Props:
+    return prune(
+        {
+            "name": c.name,
+            "path": c.path,
+            "return_type": c.return_type,
+            "cyclomatic_complexity": c.cyclomatic_complexity,
+            "code": c.code,
+            "code_start_line": c.code_start_line,
+            "start_line": c.start_line,
+            "end_line": c.end_line,
+            "docstring": _docstring_of(c.comments),
+            "decorators": list(c.decorators or []),
+            "parameters_json": _stringify_if(c.parameters),
+            "accessed_symbols_json": _stringify_if(c.accessed_symbols),
+            "_module": file_key,
+        }
+    )
+
+
+def _attribute_props(a: PyClassAttribute, attr_id: str, file_key: str) -> Props:
+    return prune(
+        {
+            "id": attr_id,
+            "name": a.name,
+            "type": a.type,
+            "docstring": _docstring_of(a.comments),
+            "start_line": a.start_line,
+            "end_line": a.end_line,
+            "_module": file_key,
+        }
+    )
+
+
+def _variable_props(v: PyVariableDeclaration, var_id: str, file_key: str) -> Props:
+    return prune(
+        {
+            "id": var_id,
+            "name": v.name,
+            "type": v.type,
+            "initializer": v.initializer,
+            "scope": v.scope,
+            "start_line": v.start_line,
+            "end_line": v.end_line,
+            "_module": file_key,
+        }
+    )
+
+
+def _call_site_props(s: PyCallsite, file_key: str) -> Props:
+    cs_id = f"{file_key}#{s.start_line}:{s.start_column}-{s.end_line}:{s.end_column}"
+    return prune(
+        {
+            "id": cs_id,
+            "method_name": s.method_name,
+            "receiver_expr": s.receiver_expr,
+            "receiver_type": s.receiver_type,
+            "argument_types": list(s.argument_types or []),
+            "return_type": s.return_type,
+            "callee_signature": s.callee_signature,
+            "is_constructor_call": s.is_constructor_call,
+            "start_line": s.start_line,
+            "start_column": s.start_column,
+            "end_line": s.end_line,
+            "end_column": s.end_column,
+            "_module": file_key,
+        }
+    )
+
+
+def _call_edge_props(weight: int, provenance: List[str]) -> Props:
+    return prune({"weight": weight, "provenance": list(provenance)})
+
+
+def _docstring_of(comments: Optional[List[PyComment]]) -> Optional[str]:
+    docs = [c.content for c in (comments or []) if c.is_docstring]
+    return "\n".join(docs) if docs else None
+
+
+def _stringify_if(value: Any) -> Optional[str]:
+    """JSON-encode a list/dict of pydantic models, or None when empty."""
+    if value is None:
+        return None
+    if isinstance(value, (list, dict)) and len(value) == 0:
+        return None
+    return json.dumps(value, default=_jsonable, sort_keys=True)
+
+
+def _jsonable(o: Any) -> Any:
+    if hasattr(o, "model_dump"):
+        return o.model_dump()
+    if hasattr(o, "dict"):
+        return o.dict()
+    if isinstance(o, Path):
+        return str(o)
+    return str(o)