codeanalyzer-python 1.2.0__py3-none-any.whl → 1.4.0__py3-none-any.whl

codeanalyzer/core.py

@@ -37,6 +37,21 @@ from codeanalyzer.utils import ProgressBar
 from codeanalyzer.options import AnalysisOptions
 from codeanalyzer.provenance import analyzer_info, repository_info
 
+def _artifact_full_text(project_dir: Path, path: str, art) -> str:
+    """Mirrors ``artifacts.dependencies._full_text`` verbatim (not imported
+    -- that name is module-private to ``dependencies.py``): config-key
+    extraction (#152) must never depend on the stored ``source`` -- emptied
+    by ``capture_text=False`` (a payload-size control, not an extraction
+    control). Read the real file fresh instead;
+    fall back to ``art.source`` only if it's gone (e.g. a synthetic artifact
+    in a unit test, or the file vanished mid-run). Keep the two in sync if
+    this logic changes."""
+    try:
+        return (project_dir / path).read_bytes().decode("utf-8")
+    except (OSError, UnicodeDecodeError):
+        return art.source
+
+
 def _ensure_ray() -> None:
     """Initialize Ray with the driver's pinned hash seed in the workers.
 
@@ -648,6 +663,58 @@ class Codeanalyzer:
 
         detect_entrypoints(app, self.project_dir, self.options.entrypoint_rules)
 
+        # Artifacts + dependencies: L1 data, every level, never varies with -a
+        # (spec 2026-08-27). Deterministic by default; venv probing is opt-in.
+        from codeanalyzer.artifacts import (
+            build_dependency_view, discover_artifacts, extract_config_keys,
+            is_config_eligible,
+        )
+
+        app.artifacts = discover_artifacts(
+            self.project_dir, app_name,
+            capture_text=self.options.artifact_text,
+        )
+        app.dependencies, app.unresolved_imports = build_dependency_view(
+            app.artifacts,
+            app.symbol_table,
+            self.project_dir,
+            self.virtualenv if self.options.resolve_installed else None,
+            self.options.resolve_installed,
+        )
+
+        # Config keys (#152): L1 data, layered onto the same artifacts, every
+        # level. Namespace-eligible artifacts only (env-family by basename,
+        # else by format). `extraction` combines with any prior
+        # dependency-manifest pass on the same artifact: a parse failure here
+        # always downgrades to "partial" (never drops the artifact); a clean
+        # parse upgrades an untouched "none" to "full", but never overwrites
+        # an existing "partial" (e.g. from a failed dependency-manifest parse
+        # on the same artifact) -- a successful pass here must not silently
+        # erase an unrelated failure already recorded on the artifact.
+        for path in sorted(app.artifacts):
+            art = app.artifacts[path]
+            if not is_config_eligible(art):
+                continue
+            full_text = _artifact_full_text(self.project_dir, path, art)
+            keys, ok = extract_config_keys(art, full_text, self.options.artifact_text)
+            art.config_keys = keys
+            if not ok:
+                art.extraction = "partial"
+            elif art.extraction == "none":
+                art.extraction = "full"
+
+        # config_use (#162) detection: needs callees resolved (backfill_
+        # callees above, gated the same >= 2) and config_keys just extracted
+        # above, so this runs after both rather than immediately following
+        # the callee backfill call itself. Resolution is deferred past the
+        # L3/L4 blocks below (the dataflow tiers need DDG and call_graph/
+        # caller-argument substrate those blocks populate) and gated by
+        # level there, literal tier included.
+        if self.analysis_level >= 2:
+            from codeanalyzer.artifacts import detect_config_reads
+
+            config_reads = detect_config_reads(app)
+
         # L3: intraprocedural dataflow (CFG/CDG/DDG) emitted onto the v2 tree.
         if self.analysis_level >= 3:
             from codeanalyzer.dataflow.builder import (
@@ -688,6 +755,29 @@ class Codeanalyzer:
             # ``infos`` are the syntactic (L3) PDGs from the >=3 block above.
             emit_ddg_pointsto_delta(app, infos, ir, sig_to_id)
 
+        # config_use (#162) resolution: literal tier always runs at >= 2;
+        # the dataflow tiers widen the set as substrate comes online -- intra
+        # needs the DDG the L3 block above just emitted, interproc needs
+        # call_graph + caller PyCallArgument values (already present since
+        # L2) plus, for its one-hop caller-side closure, the caller's own
+        # DDG -- populated for every callable by the same L3 block, which
+        # always runs before this when analysis_level >= 4. A read resolved
+        # at a lower tier is never recomputed, so `-a 2 ⊆ -a 3 ⊆ -a 4` holds
+        # by construction.
+        if self.analysis_level >= 2:
+            from codeanalyzer.artifacts import (
+                dataflow_intra_tier, dataflow_interproc_tier, resolve_uses,
+            )
+
+            tier_fns = []
+            if self.analysis_level >= 3:
+                tier_fns.append(dataflow_intra_tier)
+            if self.analysis_level >= 4:
+                tier_fns.append(dataflow_interproc_tier)
+            app.config_uses, app.config_reads_unresolved = resolve_uses(
+                config_reads, app, tier_fns=tier_fns
+            )
+
         # Build the v2 envelope, then persist it (the cache stores the full
         # ``Analysis`` envelope so a reused cache round-trips schema_version).
         # k_limit is an L3+ envelope key: below the dataflow levels it stays

codeanalyzer/dataflow/builder.py

@@ -353,6 +353,10 @@ def build_program_graphs(
     """
     class_idx = _class_index(app)
     callable_idx = _callable_index(app)
+    # Reverse of callable_idx: a callsite's already-L2-backfilled BodyNode.callee
+    # (a can:// id, folding in the defuse linker's resolution -- not just Jedi's
+    # own callee_signature side channel) resolved back to a dotted signature.
+    id_to_sig = {c.id: sig for sig, c in callable_idx.items()}
 
     infos, func_asts = build_function_pdgs(app, k, oracle_factory=oracle_factory)
 
@@ -373,7 +377,17 @@ def build_program_graphs(
                 calls_by_line.setdefault(call.lineno, (node.id, call))
 
         for site in pycallable.call_sites or []:
-            target = site.callee_signature
+            # Prefer the callsite's body-backfilled callee over Jedi's own
+            # callee_signature side channel: under cross-test parso/Jedi cache
+            # pressure that inference can silently degrade (full-suite-only
+            # loss of SDG summary/global stitching -- test_dataflow_sdg.py),
+            # while BodyNode.callee is the deterministic L2 path (Jedi filtered
+            # the same way, PLUS the defuse linker's fallback -- l2_callees.py).
+            # Only a resolved INTERNAL target counts (id_to_sig misses on an
+            # external/unresolved callee); falls through to callee_signature
+            # exactly as before whenever the body doesn't have an answer.
+            body_node = pycallable.body.get(f"{site.start_line}:{site.start_column}")
+            target = (id_to_sig.get(body_node.callee) if body_node else None) or site.callee_signature
             if not target:
                 continue
             if target in class_idx and target not in infos:
@@ -428,8 +442,13 @@ def build_program_graphs(
             for t in cs.targets:
                 call_edges.append((sig, t))
 
-    summaries = compute_summaries(infos, sorted(set(call_edges)))
-    return assemble_sdg(infos, summaries, k)
+    # The converged (facts, ddg) per function are threaded straight into the
+    # assembler rather than re-derived there (#155).
+    solutions: Dict[str, object] = {}
+    summaries = compute_summaries(
+        infos, sorted(set(call_edges)), solutions=solutions
+    )
+    return assemble_sdg(infos, summaries, k, solutions=solutions)
 
 
 def emit_l4(

codeanalyzer/dataflow/sdg.py

@@ -386,8 +386,18 @@ def assemble_sdg(
     infos: Dict[str, FunctionInfo],
     summaries: Dict[str, FunctionSummary],
     k: int,
+    *,
+    solutions: Optional[Dict[str, Tuple[Dict[int, object], List[object]]]] = None,
 ) -> ProgramGraphsIR:
-    """Stitch every function's PDG into the whole-program SDG."""
+    """Stitch every function's PDG into the whole-program SDG.
+
+    *solutions* optionally carries the converged ``(facts, ddg)`` that
+    :func:`~codeanalyzer.dataflow.summaries.compute_summaries` already
+    derived, sparing a second identical solve per function (#155). Omit it and
+    every function is re-solved, which is the historical behaviour and the
+    right posture whenever *summaries* did not come from an immediately
+    preceding run over these same *infos*.
+    """
     ir = ProgramGraphsIR(k_limit=k)
 
     # Pass 1: solve each function against the final summaries and lay out its
@@ -396,7 +406,12 @@ def assemble_sdg(
     formal_ids: Dict[str, Dict[str, int]] = {}
     for sig in sorted(infos):
         info = infos[sig]
-        summary, facts, ddg = solve_function(info, summaries)
+        cached = solutions.get(sig) if solutions is not None else None
+        if cached is None:
+            summary, facts, ddg = solve_function(info, summaries)
+        else:
+            facts, ddg = cached
+            summary = summaries[sig]
         asm = _FunctionAssembler(info, summary, facts, ddg)
         asm.build_formals()
         assemblers[sig] = asm

codeanalyzer/dataflow/summaries.py

@@ -199,19 +199,42 @@ def solve_function(
 def compute_summaries(
     infos: Dict[str, FunctionInfo],
     call_edges: List[Tuple[str, str]],
+    *,
+    solutions: Optional[Dict[str, Tuple[Dict[int, object], List[DDGEdge]]]] = None,
 ) -> Dict[str, FunctionSummary]:
     """Bottom-up composition over the SCC condensation DAG, monotone fixpoint
-    within each SCC."""
+    within each SCC.
+
+    A **singleton SCC with no self-edge** is solved exactly once: the
+    condensation is processed bottom-up, so every callee summary it reads is
+    already final and a second pass could only recompute the same answer to
+    observe that nothing changed. Genuinely recursive SCCs (several members,
+    or one member calling itself) still iterate to fixpoint.
+
+    When *solutions* is supplied it receives each signature's converged
+    ``(facts, ddg)`` — the by-products of the final solve, which
+    :func:`~codeanalyzer.dataflow.sdg.assemble_sdg` would otherwise recompute
+    from scratch. They are the same values that a fresh solve against the
+    final summaries produces, because a converged pass is by definition one
+    in which no member's summary changed (#155).
+    """
     order = strongly_connected_components(sorted(infos), call_edges)
+    self_calls = {src for src, dst in call_edges if src == dst}
     summaries: Dict[str, FunctionSummary] = {}
     for scc in order:
         members = [s for s in scc if s in infos]
-        changed = True
-        while changed:
+        if not members:
+            continue
+        recursive = len(members) > 1 or members[0] in self_calls
+        while True:
             changed = False
             for sig in members:
-                new, _, _ = solve_function(infos[sig], summaries)
+                new, facts, ddg = solve_function(infos[sig], summaries)
+                if solutions is not None:
+                    solutions[sig] = (facts, ddg)
                 if summaries.get(sig) != new:
                     summaries[sig] = new
                     changed = True
+            if not (recursive and changed):
+                break
     return summaries

codeanalyzer/neo4j/bolt.py

@@ -27,11 +27,24 @@ Algorithm (the module subgraph is the unit of idempotent replacement):
   4. upsert edges owned by changed modules (+ the shared edges).
   5. on a FULL run only, prune modules whose source file vanished.
 
+**A push never deletes by default** (#171). Steps 3 and 5 are the only destructive
+ones and both run on ``eager`` (``--eager``) only; a default ``--lazy`` push is purely
+additive — MERGE-upsert of nodes and edges, nothing removed. The cost of the default is
+staleness: a declaration or a call edge the source no longer has stays in the graph until
+an ``--eager`` push reconciles it. That is the deliberate trade — an incremental push into
+a shared database should not be able to destroy anything, and the destructive rebuild is
+opt-in under the same flag that already forces a clean analysis rebuild.
+
 Nodes are MERGE-upserted, never blindly deleted, so a declaration another
 (unchanged) module still references survives and its incoming edges stay valid.
 ``:PyExternal`` / ``:PyPackage`` / ``:PyDecorator`` are shared (no ``_module``) and are
 MERGE-only.
 
+Every ``_module`` match is anchored on the python-owned labels
+(``schema.MODULE_OWNED_PATTERN``). ``_module`` is a shared convention, not a python-private
+one -- codeanalyzer-java and codeanalyzer-typescript set it on their nodes too -- so an
+unlabelled match reaches a sibling analyzer's graph in a shared database (#171).
+
 The ``neo4j`` driver is imported lazily so it stays an optional dependency and
 off the default (json) output path entirely.
 """
@@ -41,7 +54,7 @@ from dataclasses import dataclass
 from typing import Dict, List, Optional
 
 from codeanalyzer.neo4j.rows import EdgeRow, GraphRows, NodeRow, chunk
-from codeanalyzer.neo4j.schema import CONSTRAINTS, INDEXES
+from codeanalyzer.neo4j.schema import CONSTRAINTS, INDEXES, MODULE_OWNED_PATTERN
 from codeanalyzer.utils import logger
 
 DESCENDANTS = (
@@ -59,7 +72,7 @@ class BoltConfig:
     database: Optional[str] = None
 
 
-def bolt_writer(rows: GraphRows, cfg: BoltConfig, full_run: bool) -> None:
+def bolt_writer(rows: GraphRows, cfg: BoltConfig, full_run: bool, eager: bool = False) -> None:
     try:
         import neo4j  # noqa: WPS433 (lazy, optional dependency)
     except ImportError as exc:  # pragma: no cover - exercised only without the extra
@@ -119,15 +132,26 @@ def bolt_writer(rows: GraphRows, cfg: BoltConfig, full_run: bool) -> None:
         _upsert_nodes(session, neo4j, shared)
 
         # 4. per changed module: purge owned edges + vanished decls, then upsert its nodes.
+        # The purge is the only destructive step in a push, so it runs on --eager only.
         for m in changed:
             nodes = by_module[m]
             keys = [n.value for n in nodes]
+            if not eager:
+                _upsert_nodes(session, neo4j, nodes)
+                continue
             with session() as s:
                 def _purge(tx, module=m, node_keys=keys):
-                    tx.run("MATCH (x {_module: $m})-[r]->() DELETE r", m=module)
+                    # Anchored on python-owned labels: `_module` is also set by the java
+                    # and typescript analyzers, so an unlabelled match would delete a
+                    # sibling's nodes wherever a file key collides (#171).
                     tx.run(
-                        "MATCH (x {_module: $m}) "
-                        "WHERE NOT coalesce(x.signature, x.id, x.file_key) IN $keys "
+                        f"MATCH (x:{MODULE_OWNED_PATTERN}) WHERE x._module = $m "
+                        "MATCH (x)-[r]->() DELETE r",
+                        m=module,
+                    )
+                    tx.run(
+                        f"MATCH (x:{MODULE_OWNED_PATTERN}) WHERE x._module = $m "
+                        "AND NOT coalesce(x.signature, x.id, x.file_key) IN $keys "
                         "DETACH DELETE x",
                         m=module,
                         keys=node_keys,
@@ -147,7 +171,7 @@ def bolt_writer(rows: GraphRows, cfg: BoltConfig, full_run: bool) -> None:
         # 6. orphan prune — only safe on a full run (a targeted run can't tell deleted from untargeted).
         # Scope to THIS application's anchor so a full run for application B never
         # deletes application A's modules from a shared database.
-        if full_run and app_name is not None:
+        if full_run and eager and app_name is not None:
             present = list(by_module.keys())
             with session() as s:
                 res = s.run(
@@ -161,6 +185,11 @@ def bolt_writer(rows: GraphRows, cfg: BoltConfig, full_run: bool) -> None:
                 pruned = res.single()
                 pruned_count = pruned["pruned"] if pruned else 0
                 logger.info(f"neo4j(bolt): pruned {pruned_count} vanished module(s)")
+        elif not eager:
+            logger.info(
+                "neo4j(bolt): additive push (--lazy) — nothing deleted; "
+                "re-run with --eager to reconcile removed declarations and edges"
+            )
         else:
             logger.info(
                 "neo4j(bolt): targeted run — orphan pruning skipped (deleted files not removed)"

codeanalyzer/neo4j/emit.py

@@ -67,9 +67,10 @@ def emit_neo4j(analysis: Analysis, options: AnalysisOptions) -> None:
             password=options.neo4j_password,
             database=options.neo4j_database,
         )
-        # A full run (no single-file restriction) makes orphan pruning safe.
+        # A full run (no single-file restriction) makes orphan pruning safe; --eager
+        # is what permits any deletion at all (#171).
         full_run = options.file_name is None
-        bolt_writer(rows, cfg, full_run)
+        bolt_writer(rows, cfg, full_run, eager=options.rebuild_analysis)
         return
 
     out_dir = options.output if options.output is not None else Path.cwd()

codeanalyzer/neo4j/project.py

@@ -47,6 +47,7 @@ from codeanalyzer.schema import (
     PyModule,
     PyVariableDeclaration,
 )
+from codeanalyzer.schema.ids import application_id, purl_pypi
 from codeanalyzer.schema.py_schema import PyDecorator
 
 
@@ -100,6 +101,16 @@ def project(app: PyApplication, app_name: str, sig_to_id: dict,
     # MERGE — a no-op when no callable carries L3 fields (levels 1/2).
     _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()
 
 
@@ -248,6 +259,186 @@ def _project_program_graphs(
         )
 
 
+# ----------------------------------------------------------------------------------------------
+# 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,
+                    "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}",
+        )
+
+
 def _sym(can_id: str) -> NodeRef:
     return NodeRef("PySymbol", "id", can_id)
 

codeanalyzer/neo4j/schema.py

@@ -201,6 +201,30 @@ NODE_LABELS: List[NodeLabel] = [
             "_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", "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"]
@@ -250,6 +274,39 @@ REL_TYPES: List[RelType] = [
     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"},
+    ),
 ]
 
 
@@ -275,10 +332,27 @@ def uniqueness_constraints() -> list[str]:
 
 CONSTRAINTS: List[str] = uniqueness_constraints()
 
+# The labels this analyzer owns per module -- the ones carrying the internal ``_module``
+# provenance property. Derived from NODE_LABELS so a new module-scoped label is covered
+# without a second list to maintain. `_module` is NOT python-private: codeanalyzer-java
+# and codeanalyzer-typescript set the same property on their nodes, so every statement
+# matching on it must be anchored to these labels or it matches a sibling analyzer's graph
+# in a shared database (#171).
+MODULE_OWNED_LABELS: List[str] = [n.label for n in NODE_LABELS if "_module" in n.properties]
+
+# The label disjunction to anchor such a statement with: ``MATCH (x:PyModule|PyClass|...)``.
+MODULE_OWNED_PATTERN: str = "|".join(MODULE_OWNED_LABELS)
+
 INDEXES: List[str] = [
     "CREATE INDEX py_callable_name IF NOT EXISTS FOR (c:PyCallable) ON (c.name)",
     "CREATE INDEX py_class_name IF NOT EXISTS FOR (c:PyClass) ON (c.name)",
     "CREATE FULLTEXT INDEX py_code_fts IF NOT EXISTS FOR (c:PyCallable) ON EACH [c.code, c.docstring]",
+] + [
+    # One per module-owned label: the incremental writer's per-module purge matches on
+    # `_module` once per changed module, which without these is a label scan per label per
+    # module -- quadratic on a full push (#171).
+    f"CREATE INDEX {label.lower()}_module IF NOT EXISTS FOR (x:{label}) ON (x._module)"
+    for label in MODULE_OWNED_LABELS
 ]