codeanalyzer-python 1.1.1__py3-none-any.whl → 1.3.0__py3-none-any.whl

codeanalyzer/neo4j/project.py

@@ -47,7 +47,8 @@ from codeanalyzer.schema import (
     PyModule,
     PyVariableDeclaration,
 )
-from codeanalyzer.schema.py_schema import PyCallsite
+from codeanalyzer.schema.ids import application_id, purl_pypi
+from codeanalyzer.schema.py_schema import PyDecorator
 
 
 def project(app: PyApplication, app_name: str, sig_to_id: dict,
@@ -98,7 +99,17 @@ def project(app: PyApplication, app_name: str, sig_to_id: dict,
 
     # 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)
+    _project_program_graphs(b, app, externals, sig_to_id)
+
+    # Neutral artifact/dependency subgraph (Task 6). L1 data — always present,
+    # full-depth-always regardless of -a.
+    _project_artifacts(b, app, app_name, app_ref)
+
+    # config_use (#162): the resolved-read bridge (PyBodyNode from
+    # _project_program_graphs above) into the config-key subgraph
+    # (ConfigKey from _project_artifacts above), plus first-class unresolved
+    # reads.
+    _project_config_uses(b, app, app_ref, externals, sig_to_id)
 
     return b.finish()
 
@@ -109,7 +120,7 @@ def project(app: PyApplication, app_name: str, sig_to_id: dict,
 
 
 def _global_ordinal(callable_id: str, local_key: str) -> str:
-    """The globally-unique PyCFGNode merge key for a callable's body node: the
+    """The globally-unique PyBodyNode 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 ``@``.
@@ -124,18 +135,20 @@ def _global_ordinal(callable_id: str, local_key: str) -> str:
     )
 
 
-def _cfg_ref(callable_id: str, local_key: str) -> NodeRef:
-    return NodeRef("PyCFGNode", "id", _global_ordinal(callable_id, local_key))
+def _body_ref(callable_id: str, local_key: str) -> NodeRef:
+    return NodeRef("PyBodyNode", "id", _global_ordinal(callable_id, local_key))
 
 
-def _project_program_graphs(b: RowBuilder, app: PyApplication) -> None:
+def _project_program_graphs(
+    b: RowBuilder, app: PyApplication, externals: dict, sig_to_id: dict
+) -> 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
+    Node label ``PyBodyNode`` (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``)
+    ``PY_HAS_BODY_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
@@ -149,7 +162,7 @@ def _project_program_graphs(b: RowBuilder, app: PyApplication) -> None:
     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."""
+    emitted ``PyBodyNode`` 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():
@@ -163,7 +176,7 @@ def _project_program_graphs(b: RowBuilder, app: PyApplication) -> None:
                 # their owning callsite (``parent``) instead of span lines; both
                 # are None on ordinary statement nodes and pruned away there.
                 ref = b.node(
-                    ["PyCFGNode"],
+                    ["PyBodyNode"],
                     "id",
                     _global_ordinal(c.id, local_key),
                     prune(
@@ -173,23 +186,43 @@ def _project_program_graphs(b: RowBuilder, app: PyApplication) -> None:
                             "end_line": span.end[0] if span else None,
                             "var": node.of,
                             "call_node": node.parent,
+                            # Call-site detail (#120). The JSON emits one node per
+                            # call site; the graph now does too, instead of a
+                            # separate :PyCallSite under a third id scheme.
+                            "method_name": node.method_name,
+                            "receiver_expr": node.receiver_expr,
+                            "receiver_type": node.receiver_type,
+                            "return_type": node.return_type,
+                            "is_constructor_call": node.is_constructor_call,
+                            "arguments_json": _stringify_if(node.arguments),
                             "_module": file_key,
                         }
                     ),
                 )
-                b.edge("PY_HAS_CFG_NODE", owner, ref)
+                b.edge("PY_HAS_BODY_NODE", owner, ref)
+                if node.kind == "call" and node.callee:
+                    # `callee` is ALREADY a resolved can:// id (a declared callable
+                    # or an @external home), so it must not go through
+                    # `_symbol_ref`, which expects a dotted signature and would
+                    # fall back to matching a `signature` property against an id --
+                    # emitting an edge that matches nothing at load time.
+                    b.edge(
+                        "PY_RESOLVES_TO",
+                        ref,
+                        _call_endpoint(b, node.callee, externals, sig_to_id),
+                    )
             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),
+                    _body_ref(c.id, e.src),
+                    _body_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))
+                b.edge("PY_CDG", _body_ref(c.id, e.src), _body_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
@@ -197,32 +230,213 @@ def _project_program_graphs(b: RowBuilder, app: PyApplication) -> None:
                 # them and silently drops dependences.
                 b.edge(
                     "PY_DDG",
-                    _cfg_ref(c.id, e.src),
-                    _cfg_ref(c.id, e.dst),
+                    _body_ref(c.id, e.src),
+                    _body_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.
+            # pass-throughs); LOCAL ids resolved to global PyBodyNode refs.
             for e in c.summary or []:
-                b.edge("PY_SUMMARY", _cfg_ref(c.id, e.src), _cfg_ref(c.id, e.dst))
+                b.edge("PY_SUMMARY", _body_ref(c.id, e.src), _body_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
+    # endpoint functions' identity maps), so they land on the very PyBodyNode 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),
+            NodeRef("PyBodyNode", "id", e.src),
+            NodeRef("PyBodyNode", "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),
+            NodeRef("PyBodyNode", "id", e.src),
+            NodeRef("PyBodyNode", "id", e.dst),
+        )
+
+
+# ----------------------------------------------------------------------------------------------
+# Artifact / dependency subgraph (spec 2026-08-27, Task 6)
+# ----------------------------------------------------------------------------------------------
+
+_LOCK_BASENAMES = ("poetry.lock", "uv.lock", "Pipfile.lock")
+
+
+def _import_ghost(b: RowBuilder, app_can_id: str, name: str) -> NodeRef:
+    """A ``:PyExternal`` ghost for a bare imported module name (``PY_PROVIDES``'s
+    ``provides_imports`` entries, ``PY_UNRESOLVED_IMPORT``'s ``module``).
+
+    ``app.external_symbols`` only homes call-graph endpoints (``_home_external_
+    symbols`` walks ``app.call_graph``), so a module that is imported but never
+    called — the overwhelmingly common case for ``provides_imports`` and the
+    *only* case for an unresolved import — has no existing ghost to MERGE onto.
+    This builds one with the same id shape ``_call_endpoint``/``_home_external_
+    symbols`` use for a dot-less (no ``.`` in the signature) call target:
+    ``<app can:// id>/@external/<name>``, ``module=None``. Same two-label
+    ``["PySymbol", "PyExternal"]`` idiom as ``_call_endpoint`` -- the schema
+    declares :PyExternal's merge label as PySymbol, and RowBuilder MERGEs by
+    ``(labels[0], value)``, so if a call to that same bare name is ever
+    projected too, both rows collapse onto this one node — correctly, since
+    they name the same real-world symbol."""
+    return b.node(
+        ["PySymbol", "PyExternal"], "id", f"{app_can_id}/@external/{name}", {"name": name}
+    )
+
+
+def _project_artifacts(b: RowBuilder, app: PyApplication, app_name: str, app_ref: NodeRef) -> None:
+    """Non-code artifacts, declared dependencies and undeclared imports (Tasks
+    1-5) -- neutral ``Artifact``/``Package`` nodes with no ``Py`` prefix
+    (deliberate: cross-language merge targets, unlike everything else this
+    module projects). Always emitted regardless of ``-a`` -- this section is
+    L1 data, identical at every analysis level (mirrors ``analysis.json``)."""
+    app_can_id = application_id(app_name)
+
+    for path in sorted(app.artifacts or {}):
+        art = app.artifacts[path]
+        art_ref = b.node(
+            ["Artifact"],
+            "id",
+            art.id,
+            prune(
+                {
+                    "path": art.path,
+                    "format": art.format,
+                    "roles": art.roles,
+                    "size_bytes": art.size_bytes,
+                    "sha256": art.sha256,
+                    "source": art.source,
+                    "text_truncated": art.text_truncated,
+                    "extraction": art.extraction,
+                }
+            ),
+        )
+        b.edge("HAS_ARTIFACT", app_ref, art_ref)
+
+        # Config keys flattened out of this artifact (#152) -- sorted by key
+        # for deterministic row order, matching the JSON side's L1 determinism.
+        for ck in sorted(art.config_keys or [], key=lambda k: k.key):
+            ck_ref = b.node(
+                ["ConfigKey"],
+                "id",
+                ck.id,
+                prune(
+                    {
+                        "key": ck.key,
+                        "namespace": ck.namespace,
+                        "value": ck.value,
+                        "references": list(ck.references or []),
+                        "start_line": ck.span.start[0] if ck.span else None,
+                        "end_line": ck.span.end[0] if ck.span else None,
+                    }
+                ),
+            )
+            b.edge("DEFINES_CONFIG", art_ref, ck_ref)
+
+    # Every lock artifact present LOCKS every dependency it pinned. The pins
+    # from all lock files are already merged into one `locked_version` per
+    # dependency upstream (Task 5 `build_dependency_view`) -- there is no
+    # per-lock-file attribution to split on, so (like the JSON projection) a
+    # dependency locked with N lock artifacts present gets N LOCKS edges.
+    lock_ids = [
+        app.artifacts[p].id
+        for p in sorted(app.artifacts or {})
+        if p.rsplit("/", 1)[-1] in _LOCK_BASENAMES
+    ]
+
+    # app.dependencies has one PyDependency per DECLARING MANIFEST, so a
+    # package declared in 2+ manifests (e.g. requirements.txt +
+    # requirements-dev.txt both listing "requests") walks this loop once per
+    # manifest. DECLARES_DEPENDENCY is correctly one row per declaration (its
+    # `from_ref` is the manifest, so those rows are already distinct) -- but
+    # LOCKS/PY_PROVIDES/PY_UNRESOLVED_IMPORT are per-PACKAGE facts, and
+    # RowBuilder.edge() is append-only (unlike node(), it does not MERGE-dedup)
+    # -- so without a guard they'd be emitted once per declaring manifest
+    # instead of once, violating GraphRows' documented deduped-bag contract.
+    seen: set = set()
+
+    for d in app.dependencies or []:
+        pkg_id = purl_pypi(d.name)
+        pkg_ref = b.node(["Package"], "id", pkg_id, {"ecosystem": "pypi", "name": d.name})
+        # kind-discriminated: the same manifest may declare one package twice
+        # under different kinds (e.g. requests in [project.dependencies] AND
+        # again under [project.optional-dependencies]) -- same endpoint pair,
+        # so a plain MERGE would collapse the two declarations into one row.
+        b.edge(
+            "DECLARES_DEPENDENCY",
+            NodeRef("Artifact", "id", d.declared_in),
+            pkg_ref,
+            prune({"spec": d.spec, "kind": d.kind, "extras": d.extras, "prov": d.prov, "direct": d.direct}),
+            key=d.kind,
+        )
+        if d.locked_version:
+            for lock_id in lock_ids:
+                key = ("LOCKS", lock_id, pkg_id)
+                if key not in seen:
+                    seen.add(key)
+                    b.edge(
+                        "LOCKS",
+                        NodeRef("Artifact", "id", lock_id),
+                        pkg_ref,
+                        {"version": d.locked_version},
+                    )
+        for top in d.provides_imports:
+            ghost_ref = _import_ghost(b, app_can_id, top)
+            key = ("PY_PROVIDES", pkg_id, ghost_ref.value)
+            if key not in seen:
+                seen.add(key)
+                b.edge("PY_PROVIDES", pkg_ref, ghost_ref)
+
+    for u in app.unresolved_imports or []:
+        ghost_ref = _import_ghost(b, app_can_id, u.module)
+        key = ("PY_UNRESOLVED_IMPORT", app_ref.value, ghost_ref.value)
+        if key not in seen:
+            seen.add(key)
+            b.edge("PY_UNRESOLVED_IMPORT", app_ref, ghost_ref, prune({"prov": u.prov}))
+
+
+def _project_config_uses(
+    b: RowBuilder, app: PyApplication, app_ref: NodeRef, externals: dict, sig_to_id: dict,
+) -> None:
+    """config_use (#162): PY_USES_CONFIG (`app.config_uses`) and
+    PY_READS_CONFIG_UNRESOLVED (`app.config_reads_unresolved`).
+
+    `PyConfigUseEdge.src`/`.dst` are already a GLOBAL ordinal id and a
+    ConfigKey id (both resolved upstream by `resolve_uses`), so — like
+    `param_in`/`param_out` — they address existing PyBodyNode/ConfigKey rows
+    directly with a plain :class:`NodeRef`; no defer-and-gate needed. Call
+    nodes enter a callable's `body` at L1 (before any config_use tier runs),
+    so the src PyBodyNode is always already projected by
+    `_project_program_graphs`, whatever level this ran at.
+
+    `PyConfigRead.callee` is already the full external `can://…/@external/…`
+    id (not a bare module name), so its ghost goes through `_call_endpoint`
+    (which looks it up in `externals` directly) rather than `_import_ghost`
+    (built for a bare imported name) — same inline node()+edge() shape
+    `PY_UNRESOLVED_IMPORT` uses. `_k` discriminates by (key, reason): the same
+    external callee (e.g. `os.getenv`) legitimately reads several distinct
+    undeclared/dynamic keys across a codebase, and without a discriminant a
+    plain endpoint-pair MERGE would collapse those onto one relationship.
+    """
+    for e in app.config_uses:
+        b.edge(
+            "PY_USES_CONFIG",
+            NodeRef("PyBodyNode", "id", e.src),
+            NodeRef("ConfigKey", "id", e.dst),
+            prune({"prov": list(e.prov) if e.prov else None}),
+        )
+    for r in app.config_reads_unresolved:
+        ghost_ref = _call_endpoint(b, r.callee, externals, sig_to_id)
+        b.edge(
+            "PY_READS_CONFIG_UNRESOLVED",
+            app_ref,
+            ghost_ref,
+            prune({"key": r.key, "reason": r.reason, "prov": list(r.prov) if r.prov else None}),
+            # _k=(key,reason) does not per-site discriminate the non-literal bucket (accepted prop-list ceiling).
+            key=f"{r.key or ''}|{r.reason}",
         )
 
 
@@ -369,6 +583,9 @@ def _project_class(
     )
     b.edge(parent_rel, parent, ref)
 
+    for d in cl.decorators or []:
+        _project_decorator(b, ref, d)
+
     for base in cl.base_classes or []:
         if base:
             b.edge_to_symbol("PY_EXTENDS", ref, _symbol_ref(base, externals, sig_to_id))
@@ -397,19 +614,6 @@ def _project_callable(
     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,
-                _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.callables or {}).values():
@@ -439,9 +643,36 @@ def _project_variable(
     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)
+def _project_decorator(b: RowBuilder, on: NodeRef, decorator: PyDecorator) -> None:
+    """Project one decorator application (#128).
+
+    The merge key is the resolved ``qualified_name`` when Jedi supplies one, so
+    ``@lru_cache`` and ``@lru_cache(maxsize=128)`` land on one node instead of two,
+    and two spellings of one decorator stop being separate nodes. Unresolved
+    decorators fall back to the written spelling. Per-application facts (the
+    arguments) ride on the relationship, not the shared node -- ``:PyDecorator``
+    has no ``_module`` and is never pruned, so anything application-specific on it
+    would accumulate across every project in the database.
+    """
+    key = decorator.qualified_name or decorator.name
+    dec = b.node(
+        ["PyDecorator"],
+        "name",
+        key,
+        {"name": key, "qualified_name": decorator.qualified_name or ""},
+    )
+    b.edge(
+        "PY_DECORATED_BY",
+        on,
+        dec,
+        {
+            "expression": decorator.expression or "",
+            "positional_arguments": list(decorator.positional_arguments or []),
+            "keyword_arguments_json": json.dumps(
+                dict(decorator.keyword_arguments or {}), sort_keys=True
+            ),
+        },
+    )
 
 
 # ----------------------------------------------------------------------------------------------
@@ -482,10 +713,13 @@ def _class_props(cl: PyClass, file_key: str, source: str) -> Props:
             "name": cl.name,
             "code": _span_code(source, cl.span),
             "base_classes": list(cl.base_classes or []),
+            "decorators": [d.qualified_name or d.name for d in (cl.decorators or [])],
             "docstring": _docstring_of(cl.comments),
             "start_line": cl.start_line,
             "end_line": cl.end_line,
             "_module": file_key,
+            "is_entrypoint": bool(cl.entrypoints),
+            "entrypoint_frameworks": sorted({e.framework for e in (cl.entrypoints or [])}),
         }
     )
 
@@ -504,10 +738,13 @@ def _callable_props(c: PyCallable, file_key: str, source: str) -> Props:
             "start_line": c.start_line,
             "end_line": c.end_line,
             "docstring": _docstring_of(c.comments),
-            "decorators": list(c.decorators or []),
+            "decorators": [d.qualified_name or d.name for d in (c.decorators or [])],
+            "modifiers": list(c.modifiers or []),
             "parameters_json": _stringify_if(c.parameters),
             "accessed_symbols_json": _stringify_if(c.accessed_symbols),
             "_module": file_key,
+            "is_entrypoint": bool(c.entrypoints),
+            "entrypoint_frameworks": sorted({e.framework for e in (c.entrypoints or [])}),
         }
     )
 
@@ -542,26 +779,6 @@ def _variable_props(v: PyVariableDeclaration, var_id: str, file_key: str) -> Pro
     )
 
 
-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 []),
-            "arguments_json": _stringify_if(s.arguments),
-            "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, prov: List[str]) -> Props:

codeanalyzer/neo4j/schema.py

@@ -101,9 +101,12 @@ NODE_LABELS: List[NodeLabel] = [
             "name": "string",
             "code": "string",
             "base_classes": "string[]",
+            "decorators": "string[]",
             "docstring": "string",
             **_SPAN,
             "_module": "string",
+            "is_entrypoint": "boolean",
+            "entrypoint_frameworks": "string[]",
         },
     ),
     NodeLabel(
@@ -122,9 +125,12 @@ NODE_LABELS: List[NodeLabel] = [
             **_SPAN,
             "docstring": "string",
             "decorators": "string[]",
+            "modifiers": "string[]",
             "parameters_json": "string",
             "accessed_symbols_json": "string",
             "_module": "string",
+            "is_entrypoint": "boolean",
+            "entrypoint_frameworks": "string[]",
         },
     ),
     NodeLabel(
@@ -138,28 +144,7 @@ NODE_LABELS: List[NodeLabel] = [
         "PyDecorator",
         "PyDecorator",
         "name",
-        {"name": "string"},
-    ),
-    NodeLabel(
-        "PyCallSite",
-        "PyCallSite",
-        "id",
-        {
-            "id": "string",
-            "method_name": "string",
-            "receiver_expr": "string",
-            "receiver_type": "string",
-            "argument_types": "string[]",
-            "arguments_json": "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",
-        },
+        {"name": "string", "qualified_name": "string"},
     ),
     NodeLabel(
         "PyAttribute",
@@ -196,18 +181,50 @@ NODE_LABELS: List[NodeLabel] = [
     # another's. `id` = "<signature>#<node_id>"; parameter-passing nodes
     # (formal/actual in/out) ride the same label with `var`/`call_node`.
     NodeLabel(
-        "PyCFGNode",
-        "PyCFGNode",
+        "PyBodyNode",
+        "PyBodyNode",
         "id",
         {
             "id": "string",
             "kind": "string",
             "var": "string",
             "call_node": "string",
+            # Call-site detail (#120): the graph emits one node per call site,
+            # matching analysis.json, instead of a separate :PyCallSite.
+            "method_name": "string",
+            "receiver_expr": "string",
+            "receiver_type": "string",
+            "return_type": "string",
+            "is_constructor_call": "boolean",
+            "arguments_json": "string",
             **_SPAN,
             "_module": "string",
         },
     ),
+    # Neutral artifact/dependency subgraph (spec 2026-08-27, Task 6). No `Py`
+    # prefix -- deliberate: `Artifact`/`Package` are cross-language merge
+    # targets, so a sibling-language analyzer over the same repo lands on the
+    # same nodes instead of a per-language duplicate. `PY_PROVIDES` /
+    # `PY_UNRESOLVED_IMPORT` stay PY_-namespaced (this analyzer's own claim
+    # about what an import resolves to) and target `:PyExternal`.
+    NodeLabel("Artifact", "Artifact", "id", {
+        "id": "string", "path": "string", "format": "string",
+        "roles": "string[]", "size_bytes": "integer", "sha256": "string",
+        "source": "string", "text_truncated": "boolean", "extraction": "string",
+    }),
+    NodeLabel("Package", "Package", "id", {
+        "id": "string", "ecosystem": "string", "name": "string",
+    }),
+    # A configuration key flattened out of a config-bearing Artifact (#152).
+    # Neutral vocabulary like Artifact/Package -- a yaml/env/ini key is not a
+    # Python concept. `value` is omitted (not null) when the source model's
+    # value is None (--no-artifact-text, or a namespace with no value at that
+    # path); `references` is always present, possibly empty.
+    NodeLabel("ConfigKey", "ConfigKey", "id", {
+        "id": "string", "key": "string", "namespace": "string",
+        "value": "string", "references": "string[]",
+        **_SPAN,
+    }),
 ]
 
 _DECL_TARGETS = ["PyClass", "PyCallable"]
@@ -219,8 +236,7 @@ REL_TYPES: List[RelType] = [
     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_RESOLVES_TO", ["PyBodyNode"], ["PyCallable", "PyExternal"]),
     RelType(
         "PY_CALLS",
         ["PyCallable", "PyExternal"],
@@ -234,21 +250,63 @@ REL_TYPES: List[RelType] = [
         ["PyModule", "PyPackage"],
         {"spellings": "string[]", "imported_names": "string[]", "aliases": "string[]"},
     ),
-    RelType("PY_DECORATED_BY", ["PyCallable"], ["PyDecorator"]),
+    RelType(
+        "PY_DECORATED_BY",
+        ["PyCallable", "PyClass"],
+        ["PyDecorator"],
+        {
+            "expression": "string",
+            "positional_arguments": "string[]",
+            "keyword_arguments_json": "string",
+        },
+    ),
     # 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"]),
+    RelType("PY_HAS_BODY_NODE", ["PyCallable"], ["PyBodyNode"]),
     # ``_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"]),
+    RelType("PY_CFG_NEXT", ["PyBodyNode"], ["PyBodyNode"], {"kind": "string", "_k": "string"}),
+    RelType("PY_CDG", ["PyBodyNode"], ["PyBodyNode"]),
+    RelType("PY_DDG", ["PyBodyNode"], ["PyBodyNode"], {"var": "string", "prov": "string[]", "_k": "string"}),
+    RelType("PY_PARAM_IN", ["PyBodyNode"], ["PyBodyNode"], {"var": "string"}),
+    RelType("PY_PARAM_OUT", ["PyBodyNode"], ["PyBodyNode"], {"var": "string"}),
+    RelType("PY_SUMMARY", ["PyBodyNode"], ["PyBodyNode"]),
+    # Neutral artifact/dependency subgraph (Task 6).
+    RelType("HAS_ARTIFACT", ["PyApplication"], ["Artifact"]),
+    # A config key nests under exactly one owning artifact (its id is
+    # `<artifact-id>@key/<dotted.key>`) -- a plain containment edge, no
+    # per-edge properties or discriminant needed (#152).
+    RelType("DEFINES_CONFIG", ["Artifact"], ["ConfigKey"]),
+    # ``_k`` (merges per ``kind``): the same manifest may declare one package
+    # twice under different kinds (e.g. a runtime dep re-listed under an
+    # optional extra) -- same endpoint pair, so without the discriminant the
+    # plain MERGE collapses the two declarations into one row.
+    RelType("DECLARES_DEPENDENCY", ["Artifact"], ["Package"], {
+        "spec": "string", "kind": "string", "extras": "string[]", "prov": "string[]",
+        "direct": "boolean", "_k": "string",
+    }),
+    RelType("LOCKS", ["Artifact"], ["Package"], {"version": "string"}),
+    RelType("PY_PROVIDES", ["Package"], ["PyExternal"]),
+    RelType("PY_UNRESOLVED_IMPORT", ["PyApplication"], ["PyExternal"], {"prov": "string[]"}),
+    # config_use (#162): the resolved-read bridge from a call site's body node
+    # to the PyConfigKey it reads. `src`/`dst` are already GLOBAL ordinal /
+    # ConfigKey ids (resolved upstream by `resolve_uses`), so no discriminant
+    # is needed -- one call site reads one key per edge.
+    RelType("PY_USES_CONFIG", ["PyBodyNode"], ["ConfigKey"], {"prov": "string[]"}),
+    # A detector-matched read that never closed on exactly one declared key --
+    # first-class per #162, PyApplication -> PyExternal ghost of the callee
+    # (mirrors PY_UNRESOLVED_IMPORT's shape). `_k` discriminates by (key,
+    # reason): the same external callee (e.g. `os.getenv`) legitimately reads
+    # several distinct undeclared/dynamic keys across a codebase -- without a
+    # discriminant a plain endpoint-pair MERGE would collapse those onto one
+    # relationship and silently drop every key but the last one SET.
+    RelType(
+        "PY_READS_CONFIG_UNRESOLVED", ["PyApplication"], ["PyExternal"],
+        {"key": "string", "reason": "string", "prov": "string[]", "_k": "string"},
+    ),
 ]