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

codeanalyzer/neo4j/project.py

@@ -50,7 +50,11 @@ from codeanalyzer.schema import (
 from codeanalyzer.schema.py_schema import PyCallsite
 
 
-def project(app: PyApplication, app_name: str) -> GraphRows:
+def project(app: PyApplication, app_name: str, sig_to_id: dict,
+            analyzer: Optional[Any] = None) -> GraphRows:
+    """``analyzer`` is the envelope-level ``PyAnalyzerInfo`` (the keystone home
+    for analyzer identity); the caller that holds the ``Analysis`` envelope
+    passes it through so the :PyApplication node carries it as props."""
     b = RowBuilder()
 
     app_ref = b.node(
@@ -60,8 +64,8 @@ def project(app: PyApplication, app_name: str) -> GraphRows:
         prune(
             {
                 "schema_version": SCHEMA_VERSION,
-                "analyzer_name": app.analyzer.name if app.analyzer else None,
-                "analyzer_version": app.analyzer.version if app.analyzer else None,
+                "analyzer_name": analyzer.name if analyzer else None,
+                "analyzer_version": analyzer.version if analyzer else None,
                 "repo_uri": app.repository.uri if app.repository else None,
                 "source_revision": app.repository.revision if app.repository else None,
                 "repo_dirty": app.repository.dirty if app.repository else None,
@@ -69,52 +73,210 @@ def project(app: PyApplication, app_name: str) -> GraphRows:
         ),
     )
 
+    # Endpoints listed in app.external_symbols become :PyExternal ghost nodes; the
+    # rest are declared :PySymbol nodes emitted here (keyed by their can:// id,
+    # resolved through ``sig_to_id``). Both the module-body projection (for
+    # PY_EXTENDS / PY_RESOLVES_TO) and the PY_CALLS twin below share this split.
+    externals = app.external_symbols or {}
+
+    # file key → module can:// id, so resolved PY_IMPORTS edges land on the v2
+    # module merge key (id) rather than the legacy file_key property.
+    module_id_by_key = {k: m.id for k, m in app.symbol_table.items()}
+
     for file_key, mod in app.symbol_table.items():
-        mod_ref = b.node(
-            ["PyModule"], "file_key", file_key, _module_props(mod, file_key)
-        )
+        mod_ref = b.node(["PyModule"], "id", mod.id, _module_props(mod, file_key))
         b.edge("PY_HAS_MODULE", app_ref, mod_ref)
-        _project_module_body(b, file_key, mod_ref, mod)
+        _project_module_body(b, file_key, mod_ref, mod, externals, sig_to_id, module_id_by_key)
 
-    # The aggregated :PY_CALLS twin. Endpoints listed in app.external_symbols become
-    # :PyExternal ghost nodes; the rest are declared :PySymbol nodes already emitted.
-    externals = app.external_symbols or {}
+    # The aggregated :PY_CALLS twin.
     for e in app.call_graph:
-        src = _call_endpoint(b, e.source, externals)
-        tgt = _call_endpoint(b, e.target, externals)
+        src = _call_endpoint(b, e.src, externals, sig_to_id)
+        tgt = _call_endpoint(b, e.dst, externals, sig_to_id)
         b.edge(
-            "PY_CALLS", src, tgt, _call_edge_props(e.weight, list(e.provenance or []))
+            "PY_CALLS", src, tgt, _call_edge_props(e.weight, list(e.prov or []))
         )
 
+    # Level-3 CPG overlay: each callable's v2 body/cfg/cdg/ddg. Idempotent under
+    # MERGE — a no-op when no callable carries L3 fields (levels 1/2).
+    _project_program_graphs(b, app)
+
     return b.finish()
 
 
-def _sym(signature: str) -> NodeRef:
-    return NodeRef("PySymbol", "signature", signature)
+# ----------------------------------------------------------------------------------------------
+# Level-3 CPG overlay
+# ----------------------------------------------------------------------------------------------
 
 
-def _call_endpoint(b: RowBuilder, signature: str, externals: dict) -> NodeRef:
-    """A call-graph endpoint: a declared callable already emitted, or an external
-    symbol (imported library / builtin member) materialized as a :PyExternal ghost.
+def _global_ordinal(callable_id: str, local_key: str) -> str:
+    """The globally-unique PyCFGNode merge key for a callable's body node: the
+    callable's ``can://`` id joined to its LOCAL body key with a single ``@``.
+    The synthetic bookends already carry the leading ``@`` (``"@entry"``/
+    ``"@exit"``); real statements are bare ``"line:col"`` and gain the ``@``.
 
-    Classification is authoritative -- it comes from ``app.external_symbols``, not a
-    "present in the graph" heuristic -- so an imported module name (which exists only
-    as a :PyPackage) can never shadow the call target. A small fallback still
-    materializes an external for any endpoint that is neither declared nor listed."""
-    ext = externals.get(signature)
-    if ext is None and b.has_key("PySymbol", signature):
-        return _sym(signature)
-    name = (
-        ext.name
-        if ext is not None
-        else (signature.rsplit(".", 1)[-1] if "." in signature else signature)
+    This MUST agree with :meth:`IdentityMap.global_id` for the same node, so the
+    JSON ``body``/``cfg`` projection and this Neo4j projection land on one node
+    identity (two-projection agreement)."""
+    return (
+        f"{callable_id}{local_key}"
+        if local_key.startswith("@")
+        else f"{callable_id}@{local_key}"
     )
-    module = ext.module if ext is not None else None
+
+
+def _cfg_ref(callable_id: str, local_key: str) -> NodeRef:
+    return NodeRef("PyCFGNode", "id", _global_ordinal(callable_id, local_key))
+
+
+def _project_program_graphs(b: RowBuilder, app: PyApplication) -> None:
+    """Level-3 CPG overlay, projected off each callable's v2 ``body``/``cfg``/
+    ``cdg``/``ddg`` (populated by ``emit_l3_body`` at ``-a 3``; empty otherwise).
+
+    Node label ``PyCFGNode`` (merge key ``id`` = the GLOBAL ordinal
+    ``<callable can:// id>@<local body key>`` — identical to the JSON body key
+    prefixed with the callable id, so the two projections agree). Edges:
+    ``PY_HAS_CFG_NODE`` from the owning callable, ``PY_CFG_NEXT`` (prop ``kind``)
+    over the CFG, ``PY_CDG`` over control dependence, and ``PY_DDG`` (props
+    ``var``/``prov``) over data dependence. The vocabulary is cross-language in
+    shape but PY_-namespaced like every other row family, so a multi-language
+    database never mingles analyzers' dependence edges.
+
+    L4 (``-a 4``) layers the interprocedural delta onto the same node label:
+    parameter-passing vertices (``formal_in``/``formal_out``/``actual_in``/
+    ``actual_out``) carry ``var`` (the variable/return they model, from
+    ``BodyNode.of``) and ``call_node`` (the owning callsite local id, from
+    ``BodyNode.parent``) instead of span-derived lines; ``PY_SUMMARY`` runs over
+    each callable's transitive pass-throughs (LOCAL ids → global refs), and the
+    app-level ``PY_PARAM_IN``/``PY_PARAM_OUT`` edges connect actual↔formal
+    vertices across callables (endpoints are already GLOBAL ordinals matching the
+    emitted ``PyCFGNode`` keys). All idempotent under MERGE — no-ops below L4."""
+    from codeanalyzer.semantic_analysis.call_graph import _walk_module_callables
+
+    for file_key, mod in app.symbol_table.items():
+        for c in _walk_module_callables(mod):
+            if not c.id:
+                continue  # unstamped callable — assign_ids must run first
+            owner = _sym(c.id)  # the :PyCallable node, keyed by its can:// id
+            for local_key, node in (c.body or {}).items():
+                span = node.span
+                # L4 param vertices carry the variable they model (``of``) and
+                # their owning callsite (``parent``) instead of span lines; both
+                # are None on ordinary statement nodes and pruned away there.
+                ref = b.node(
+                    ["PyCFGNode"],
+                    "id",
+                    _global_ordinal(c.id, local_key),
+                    prune(
+                        {
+                            "kind": node.kind,
+                            "start_line": span.start[0] if span else None,
+                            "end_line": span.end[0] if span else None,
+                            "var": node.of,
+                            "call_node": node.parent,
+                            "_module": file_key,
+                        }
+                    ),
+                )
+                b.edge("PY_HAS_CFG_NODE", owner, ref)
+            for e in c.cfg or []:
+                # kind-discriminated: a conditional's true/false pair between one
+                # endpoint pair must stay two relationships, not one MERGE.
+                b.edge(
+                    "PY_CFG_NEXT",
+                    _cfg_ref(c.id, e.src),
+                    _cfg_ref(c.id, e.dst),
+                    {"kind": e.kind},
+                    key=e.kind,
+                )
+            for e in c.cdg or []:
+                b.edge("PY_CDG", _cfg_ref(c.id, e.src), _cfg_ref(c.id, e.dst))
+            for e in c.ddg or []:
+                # (var, prov)-discriminated: the DDG legitimately carries several
+                # edges between one statement pair (one per variable, and the
+                # ssa/points-to split) — a plain endpoint-pair MERGE collapses
+                # them and silently drops dependences.
+                b.edge(
+                    "PY_DDG",
+                    _cfg_ref(c.id, e.src),
+                    _cfg_ref(c.id, e.dst),
+                    prune({"var": e.var, "prov": list(e.prov) if e.prov else None}),
+                    key=f"{e.var or ''}|{','.join(e.prov or [])}",
+                )
+            # L4 intraprocedural summaries (transitive actual_in → actual_out
+            # pass-throughs); LOCAL ids resolved to global PyCFGNode refs.
+            for e in c.summary or []:
+                b.edge("PY_SUMMARY", _cfg_ref(c.id, e.src), _cfg_ref(c.id, e.dst))
+
+    # L4 interprocedural parameter passing, emitted once at the app scope. The
+    # endpoints are ALREADY global ordinals (emit_l4 resolved them through the
+    # endpoint functions' identity maps), so they land on the very PyCFGNode ids
+    # projected above — a formal_in global id equals _global_ordinal(callee.id,
+    # "@formal_in:0"). No dangling references.
+    for e in app.param_in or []:
+        b.edge(
+            "PY_PARAM_IN",
+            NodeRef("PyCFGNode", "id", e.src),
+            NodeRef("PyCFGNode", "id", e.dst),
+        )
+    for e in app.param_out or []:
+        b.edge(
+            "PY_PARAM_OUT",
+            NodeRef("PyCFGNode", "id", e.src),
+            NodeRef("PyCFGNode", "id", e.dst),
+        )
+
+
+def _sym(can_id: str) -> NodeRef:
+    return NodeRef("PySymbol", "id", can_id)
+
+
+def _symbol_ref(signature: str, externals: dict, sig_to_id: dict) -> NodeRef:
+    """Resolve a call/inheritance target to the NodeRef under which it was (or
+    will be) emitted: a declared symbol by its can:// id, otherwise a
+    signature-keyed :PySymbol (external ghost)."""
+    can_id = sig_to_id.get(signature)
+    if can_id is not None:
+        return NodeRef("PySymbol", "id", can_id)
+    return NodeRef("PySymbol", "signature", signature)
+
+
+def _call_endpoint(
+    b: RowBuilder, signature: str, externals: dict, sig_to_id: dict
+) -> NodeRef:
+    """A call-graph endpoint: a declared callable already emitted (keyed by its
+    canonical ``can://`` id, resolved through ``sig_to_id``), or an external symbol
+    (imported library / builtin member) materialized as a :PyExternal ghost.
+
+    Classification is authoritative -- it comes from ``app.external_symbols``
+    (keyed by ``can://…/@external/…`` id), not a "present in the graph" heuristic --
+    so an imported module name (which exists only as a :PyPackage) can never shadow
+    the call target. A declared endpoint resolves to its ``can://`` id (either
+    already re-identified on the edge, or resolved through ``sig_to_id``); anything
+    neither declared nor listed falls back to an id-keyed :PyExternal ghost rather
+    than raising."""
+    ext = externals.get(signature)
+    if ext is None:
+        can_id = sig_to_id.get(signature)
+        if can_id is not None:
+            ext = externals.get(can_id)
+            if ext is None:
+                return _sym(can_id)
+        elif signature.startswith("can://") and "/@external/" not in signature:
+            # An already re-identified declared endpoint (post reidentify_call_graph).
+            return _sym(signature)
+    if ext is not None:
+        return b.node(
+            ["PySymbol", "PyExternal"],
+            "id",
+            ext.id or signature,
+            prune({"name": ext.name, "module": ext.module}),
+        )
+    name = signature.rsplit(".", 1)[-1] if "." in signature else signature
     return b.node(
         ["PySymbol", "PyExternal"],
-        "signature",
+        "id",
         signature,
-        prune({"name": name, "module": module}),
+        prune({"name": name}),
     )
 
 
@@ -124,18 +286,20 @@ def _call_endpoint(b: RowBuilder, signature: str, externals: dict) -> NodeRef:
 
 
 def _project_module_body(
-    b: RowBuilder, file_key: str, mod_ref: NodeRef, mod: PyModule
+    b: RowBuilder, file_key: str, mod_ref: NodeRef, mod: PyModule,
+    externals: dict, sig_to_id: dict, module_id_by_key: dict,
 ) -> 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)
+        _project_callable(b, file_key, mod_ref, "PY_DECLARES", fn, externals, sig_to_id)
+    for cl in (mod.types or {}).values():
+        _project_class(b, file_key, mod_ref, "PY_DECLARES", cl, externals, sig_to_id)
     for v in mod.variables or []:
         _project_variable(b, file_key, mod_ref, file_key, v)
-    _project_imports(b, mod_ref, mod)
+    _project_imports(b, mod_ref, mod, module_id_by_key)
 
 
-def _project_imports(b: RowBuilder, mod_ref: NodeRef, mod: PyModule) -> None:
+def _project_imports(b: RowBuilder, mod_ref: NodeRef, mod: PyModule,
+                     module_id_by_key: dict) -> None:
     # At most one PY_IMPORTS edge per (module, target) pair -- mirrors PY_CALLS,
     # which pre-aggregates for the same reason: both writers MERGE edges on
     # (type, from, to) and SET their props, so a second row for the same pair
@@ -166,10 +330,15 @@ def _project_imports(b: RowBuilder, mod_ref: NodeRef, mod: PyModule) -> None:
         if im.alias:
             a["aliases"].add(im.alias)
     for key, a in agg.items():
-        if a["resolved"] is not None:
-            target = NodeRef("PyModule", "file_key", a["resolved"])
-        else:
+        resolved_id = module_id_by_key.get(a["resolved"]) if a["resolved"] is not None else None
+        if resolved_id is not None:
+            target = NodeRef("PyModule", "id", resolved_id)
+        elif a["resolved"] is None:
             target = b.node(["PyPackage"], "name", key, {})
+        else:
+            # resolved to a file key that is not in this symbol table (partial
+            # run) — keep the module target via its legacy file_key property.
+            target = NodeRef("PyModule", "file_key", a["resolved"])
         b.edge(
             "PY_IMPORTS",
             mod_ref,
@@ -190,31 +359,34 @@ def _project_imports(b: RowBuilder, mod_ref: NodeRef, mod: PyModule) -> None:
 
 
 def _project_class(
-    b: RowBuilder, file_key: str, parent: NodeRef, parent_rel: str, cl: PyClass
+    b: RowBuilder, file_key: str, parent: NodeRef, parent_rel: str, cl: PyClass,
+    externals: dict, sig_to_id: dict,
 ) -> None:
     ref = b.node(
-        ["PySymbol", "PyClass"], "signature", cl.signature, _class_props(cl, file_key)
+        ["PySymbol", "PyClass"], "id", cl.id, _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)
+        if base:
+            b.edge_to_symbol("PY_EXTENDS", ref, _symbol_ref(base, externals, sig_to_id))
 
-    for m in (cl.methods or {}).values():
-        _project_callable(b, file_key, ref, "PY_HAS_METHOD", m)
+    for m in (cl.callables or {}).values():
+        _project_callable(b, file_key, ref, "PY_HAS_METHOD", m, externals, sig_to_id)
     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)
+    for ic in (cl.types or {}).values():
+        _project_class(b, file_key, ref, "PY_DECLARES", ic, externals, sig_to_id)
 
 
 def _project_callable(
-    b: RowBuilder, file_key: str, owner: NodeRef, owner_rel: str, c: PyCallable
+    b: RowBuilder, file_key: str, owner: NodeRef, owner_rel: str, c: PyCallable,
+    externals: dict, sig_to_id: dict,
 ) -> None:
     ref = b.node(
         ["PySymbol", "PyCallable"],
-        "signature",
-        c.signature,
+        "id",
+        c.id,
         _callable_props(c, file_key),
     )
     b.edge(owner_rel, owner, ref)
@@ -230,14 +402,17 @@ def _project_callable(
         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)
+            b.edge_to_symbol(
+                "PY_RESOLVES_TO", cs,
+                _symbol_ref(s.callee_signature, externals, sig_to_id),
+            )
 
     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)
+    for ic in (c.callables or {}).values():
+        _project_callable(b, file_key, ref, "PY_DECLARES", ic, externals, sig_to_id)
+    for cl in (c.types or {}).values():
+        _project_class(b, file_key, ref, "PY_DECLARES", cl, externals, sig_to_id)
 
 
 def _project_attribute(
@@ -273,6 +448,8 @@ def _project_decorator(b: RowBuilder, on: NodeRef, decorator: str) -> None:
 def _module_props(mod: PyModule, file_key: str) -> Props:
     return prune(
         {
+            "id": mod.id,
+            "file_key": file_key,
             "module_name": mod.module_name,
             "content_hash": mod.content_hash,
             "last_modified": mod.last_modified,
@@ -285,8 +462,10 @@ def _module_props(mod: PyModule, file_key: str) -> Props:
 def _class_props(cl: PyClass, file_key: str) -> Props:
     return prune(
         {
+            "id": cl.id,
+            "signature": cl.signature,
             "name": cl.name,
-            "code": cl.code,
+            "code": getattr(cl, "code", None),
             "base_classes": list(cl.base_classes or []),
             "docstring": _docstring_of(cl.comments),
             "start_line": cl.start_line,
@@ -299,11 +478,13 @@ def _class_props(cl: PyClass, file_key: str) -> Props:
 def _callable_props(c: PyCallable, file_key: str) -> Props:
     return prune(
         {
+            "id": c.id,
+            "signature": c.signature,
             "name": c.name,
             "path": c.path,
             "return_type": c.return_type,
             "cyclomatic_complexity": c.cyclomatic_complexity,
-            "code": c.code,
+            "code": getattr(c, "code", None),
             "code_start_line": c.code_start_line,
             "start_line": c.start_line,
             "end_line": c.end_line,
@@ -368,8 +549,8 @@ def _call_site_props(s: PyCallsite, file_key: str) -> Props:
     )
 
 
-def _call_edge_props(weight: int, provenance: List[str]) -> Props:
-    return prune({"weight": weight, "provenance": list(provenance)})
+def _call_edge_props(weight: int, prov: List[str]) -> Props:
+    return prune({"weight": weight, "prov": list(prov)})
 
 
 def _docstring_of(comments: Optional[List[PyComment]]) -> Optional[str]:

codeanalyzer/neo4j/rows.py

@@ -58,6 +58,12 @@ class EdgeRow:
     from_ref: NodeRef
     to_ref: NodeRef
     props: Props
+    # Optional relationship discriminant: when set, the MERGE is on
+    # ``{_k: key}`` so several legitimately-distinct edges of one type may
+    # coexist between the same endpoint pair (e.g. per-variable PY_DDG edges,
+    # or the true/false PY_CFG_NEXT pair of a conditional). ``None`` keeps the
+    # plain endpoint-pair MERGE.
+    key: Optional[str] = None
 
 
 @dataclass
@@ -105,25 +111,22 @@ class RowBuilder:
         self._keys.add((labels[0], value))
         return NodeRef(labels[0], key_prop, value)
 
-    def edge(self, type_: str, from_ref: NodeRef, to_ref: NodeRef, props: Optional[Props] = None) -> None:
-        """An edge whose endpoints are known to exist (both ends emitted this run)."""
-        self._edges.append(EdgeRow(type_, from_ref, to_ref, dict(props or {})))
+    def edge(self, type_: str, from_ref: NodeRef, to_ref: NodeRef, props: Optional[Props] = None,
+             key: Optional[str] = None) -> None:
+        """An edge whose endpoints are known to exist (both ends emitted this run).
+        ``key`` sets the relationship discriminant (see :class:`EdgeRow`)."""
+        self._edges.append(EdgeRow(type_, from_ref, to_ref, dict(props or {}), key))
 
     def edge_to_symbol(
-        self, type_: str, from_ref: NodeRef, target_signature: str, props: Optional[Props] = None
+        self, type_: str, from_ref: NodeRef, target_ref: NodeRef, props: Optional[Props] = None
     ) -> None:
         """An edge to a ``:PySymbol`` target that may be external/library code not
-        present in the graph. Deferred and kept only if the target signature was
-        actually emitted as a node — so PY_EXTENDS / PY_RESOLVES_TO never dangle (the
-        string fallback lives on the source node's props)."""
-        self._deferred.append(
-            EdgeRow(
-                type_,
-                from_ref,
-                NodeRef("PySymbol", "signature", target_signature),
-                dict(props or {}),
-            )
-        )
+        present in the graph. The target is an already-resolved :class:`NodeRef`
+        (a declared symbol by its can:// id, or a signature-keyed external ghost).
+        Deferred and kept only if that ``(label, value)`` was actually emitted as a
+        node — so PY_EXTENDS / PY_RESOLVES_TO never dangle (the string fallback lives
+        on the source node's props)."""
+        self._deferred.append(EdgeRow(type_, from_ref, target_ref, dict(props or {})))
 
     def has_key(self, label: str, value: str) -> bool:
         """Whether a node with this ``(merge_label, value)`` identity was emitted."""

codeanalyzer/neo4j/schema.py

@@ -35,7 +35,7 @@ from __future__ import annotations
 from dataclasses import dataclass, field
 from typing import Dict, List
 
-SCHEMA_VERSION = "1.2.0"
+SCHEMA_VERSION = "2.0.0"
 
 # PropType ∈ {"string", "integer", "float", "boolean", "string[]", "integer[]"}.
 
@@ -80,8 +80,9 @@ NODE_LABELS: List[NodeLabel] = [
     NodeLabel(
         "PyModule",
         "PyModule",
-        "file_key",
+        "id",
         {
+            "id": "string",
             "file_key": "string",
             "module_name": "string",
             "content_hash": "string",
@@ -93,8 +94,9 @@ NODE_LABELS: List[NodeLabel] = [
     NodeLabel(
         "PyClass",
         "PySymbol",
-        "signature",
+        "id",
         {
+            "id": "string",
             "signature": "string",
             "name": "string",
             "code": "string",
@@ -107,8 +109,9 @@ NODE_LABELS: List[NodeLabel] = [
     NodeLabel(
         "PyCallable",
         "PySymbol",
-        "signature",
+        "id",
         {
+            "id": "string",
             "signature": "string",
             "name": "string",
             "path": "string",
@@ -127,8 +130,8 @@ NODE_LABELS: List[NodeLabel] = [
     NodeLabel(
         "PyExternal",
         "PySymbol",
-        "signature",
-        {"signature": "string", "name": "string", "module": "string"},
+        "id",
+        {"id": "string", "name": "string", "module": "string"},
     ),
     NodeLabel("PyPackage", "PyPackage", "name", {"name": "string"}),
     NodeLabel(
@@ -186,6 +189,25 @@ NODE_LABELS: List[NodeLabel] = [
             "_module": "string",
         },
     ),
+    # Level-3 CPG overlay (present only at -a 3). The dataflow vocabulary is
+    # shared cross-language in *shape* (same suffixes, props, semantics) but
+    # namespaced per language like every other row family — a multi-language
+    # Neo4j database must never mingle one analyzer's dependence edges with
+    # another's. `id` = "<signature>#<node_id>"; parameter-passing nodes
+    # (formal/actual in/out) ride the same label with `var`/`call_node`.
+    NodeLabel(
+        "PyCFGNode",
+        "PyCFGNode",
+        "id",
+        {
+            "id": "string",
+            "kind": "string",
+            "var": "string",
+            "call_node": "string",
+            **_SPAN,
+            "_module": "string",
+        },
+    ),
 ]
 
 _DECL_TARGETS = ["PyClass", "PyCallable"]
@@ -203,7 +225,7 @@ REL_TYPES: List[RelType] = [
         "PY_CALLS",
         ["PyCallable", "PyExternal"],
         ["PyCallable", "PyExternal"],
-        {"weight": "integer", "provenance": "string[]"},
+        {"weight": "integer", "prov": "string[]"},
     ),
     RelType("PY_EXTENDS", ["PyClass"], ["PyClass"]),
     RelType(
@@ -213,6 +235,20 @@ REL_TYPES: List[RelType] = [
         {"spellings": "string[]", "imported_names": "string[]", "aliases": "string[]"},
     ),
     RelType("PY_DECORATED_BY", ["PyCallable"], ["PyDecorator"]),
+    # Level-3 CPG overlay (-a 3 only): the cross-language dataflow vocabulary,
+    # PY_-namespaced so per-language SDK backends can scope their queries.
+    RelType("PY_HAS_CFG_NODE", ["PyCallable"], ["PyCFGNode"]),
+    # ``_k`` is the relationship-identity discriminant (internal, underscore-
+    # prefixed like ``_module``): PY_CFG_NEXT merges per ``kind`` (a conditional's
+    # true/false pair), PY_DDG per ``(var, prov)`` (one dependence per variable,
+    # and the ssa/points-to split) — a plain endpoint-pair MERGE would collapse
+    # legitimately-distinct edges.
+    RelType("PY_CFG_NEXT", ["PyCFGNode"], ["PyCFGNode"], {"kind": "string", "_k": "string"}),
+    RelType("PY_CDG", ["PyCFGNode"], ["PyCFGNode"]),
+    RelType("PY_DDG", ["PyCFGNode"], ["PyCFGNode"], {"var": "string", "prov": "string[]", "_k": "string"}),
+    RelType("PY_PARAM_IN", ["PyCFGNode"], ["PyCFGNode"], {"var": "string"}),
+    RelType("PY_PARAM_OUT", ["PyCFGNode"], ["PyCFGNode"], {"var": "string"}),
+    RelType("PY_SUMMARY", ["PyCFGNode"], ["PyCFGNode"]),
 ]
 
 

codeanalyzer/options/options.py

@@ -49,6 +49,10 @@ class AnalysisOptions:
     neo4j_password: str = "neo4j"
     neo4j_database: Optional[str] = None
     analysis_level: int = 1
+    # Level-3 dataflow knobs: which program graphs to emit (csv of
+    # cfg|dfg|pdg|sdg) and the access-path k-limit.
+    graphs: str = "cfg,dfg,pdg,sdg"
+    graph_field_depth: int = 3
     using_ray: bool = False
     rebuild_analysis: bool = False
     skip_tests: bool = True

codeanalyzer/schema/__init__.py

@@ -2,6 +2,12 @@ from importlib.metadata import version, PackageNotFoundError
 from packaging.version import parse as parse_version
 
 from .py_schema import (
+    Analysis,
+    BodyNode,
+    CdgEdge,
+    CfgEdge,
+    DdgEdge,
+    ParamEdge,
     PyApplication,
     PyCallable,
     PyCallableParameter,
@@ -12,9 +18,12 @@ from .py_schema import (
     PyImport,
     PyModule,
     PyVariableDeclaration,
+    Span,
+    SummaryEdge,
 )
 
 __all__ = [
+    "Analysis",
     "PyApplication",
     "PyExternalSymbol",
     "PyImport",
@@ -25,6 +34,13 @@ __all__ = [
     "PyCallable",
     "PyClassAttribute",
     "PyCallableParameter",
+    "Span",
+    "BodyNode",
+    "CfgEdge",
+    "CdgEdge",
+    "DdgEdge",
+    "SummaryEdge",
+    "ParamEdge",
 ]
 
 try:
@@ -44,6 +60,7 @@ if not PYDANTIC_V2:
         PyClass=PyClass,
         PyModule=PyModule
     )
+    Analysis.update_forward_refs(PyApplication=PyApplication)
     
 # Compatibility helpers for Pydantic v1/v2
 def model_dump_json(model, **kwargs):
@@ -55,6 +72,8 @@ def model_dump_json(model, **kwargs):
         v1_kwargs = {}
         if 'indent' in kwargs:
             v1_kwargs['indent'] = kwargs['indent']
+        if 'exclude_none' in kwargs:
+            v1_kwargs['exclude_none'] = kwargs['exclude_none']
         if 'separators' in kwargs:
             # In v1, separators is passed to dumps_kwargs
             v1_kwargs['separators'] = kwargs['separators']