codeanalyzer-python 1.2.0__py3-none-any.whl → 1.3.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`` -- capped
+    by ``text_max_bytes`` and emptied by ``capture_text=False`` (payload-size
+    controls, not extraction controls). 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,59 @@ 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,
+            text_max_bytes=self.options.artifact_text_max_bytes,
+        )
+        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 +756,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:

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,187 @@ 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,
+                    "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}",
+        )
+
+
 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", "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"]
@@ -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"},
+    ),
 ]
 
 

codeanalyzer/options/options.py

@@ -37,8 +37,13 @@ class AnalysisOptions:
     rebuild_analysis: bool = False
     skip_tests: bool = True
     no_venv: bool = False
+    resolve_installed: bool = False
     file_name: Optional[Path] = None
     cache_dir: Optional[Path] = None
     clear_cache: bool = False
     verbosity: int = 0
     entrypoint_rules: Tuple[Path, ...] = ()
+    # Artifact text-capture controls (#157 follow-up): whether to capture
+    # `source` at all, and the per-file byte cap before it truncates.
+    artifact_text: bool = True
+    artifact_text_max_bytes: int = 262144

codeanalyzer/schema/ids.py

@@ -21,3 +21,24 @@ def callable_sig_segment(name: str, param_names: List[str]) -> str:
 
 def ordinal_id(callable_id: str, tag: str) -> str:
     return f"{callable_id}@{tag}"
+
+
+def artifact_id(app_name: str, rel_path: str) -> str:
+    """Language-neutral artifact id: ``can://artifact/<app>/<rel-path>``.
+
+    The first segment is a namespace (a language for code nodes, the literal
+    ``artifact`` for files), so sibling analyzers over the same repo emit the
+    same id for the same file."""
+    return f"can://artifact/{app_name}/{rel_path}"
+
+
+def config_key_id(artifact_id: str, dotted_key: str) -> str:
+    """A ``PyConfigKey`` extracted from an artifact: ``<artifact-id>@key/<dotted.key>``.
+    ``dotted_key`` uses numeric segments for array indices (e.g.
+    ``services.web.ports.0``); ids are opaque, do not re-split them."""
+    return f"{artifact_id}@key/{dotted_key}"
+
+
+def purl_pypi(name: str) -> str:
+    """Package URL for a (PEP 503 normalized) PyPI distribution name."""
+    return f"pkg:pypi/{name}"

codeanalyzer/schema/py_schema.py

@@ -306,6 +306,17 @@ class PyCallArgument(BaseModel):
 
     ast_kind: str
     inferred_type: Optional[str] = None
+    # Literal capture (#162): populated only for an `ast.Constant` argument
+    # whose value is str/int/float/bool/None, JSON-encoded (`json.dumps`) --
+    # decode with `json.loads` to recover the Python constant. `None` for
+    # every non-constant argument (and for a Constant of another type, e.g.
+    # bytes/complex/Ellipsis).
+    value: Optional[str] = None
+    # Bare-identifier capture (#162): the `id` of an `ast.Name` argument
+    # (e.g. `f(KEY)` -> `"KEY"`) -- ships alongside `value` as the dataflow
+    # tier's join point back to the variable's own definitions. `None` for
+    # every other argument shape.
+    name: Optional[str] = None
 
 
 # BodyNode.arguments forward-references PyCallArgument (defined later);
@@ -470,6 +481,104 @@ class PyExternalSymbol(BaseModel):
     module: Optional[str] = None  # best-effort owning module, e.g. "requests"
 
 
+@builder
+class PyConfigKey(BaseModel):
+    """A configuration key flattened out of a config-bearing ``PyArtifact``
+    (#152). Graph vocabulary stays neutral (label ``ConfigKey``, edge
+    ``DEFINES_CONFIG``) -- the ``Py`` prefix here is only the ``PyArtifact``
+    naming precedent, not a Python-specific claim. L1 data, identical at
+    every analysis level; nested under the owning artifact, containment
+    mirrors ``DEFINES_CONFIG``."""
+
+    id: str = ""  # <artifact-id>@key/<dotted.key>
+    key: str  # dotted path; numeric segments for arrays, e.g. "services.web.ports.0"
+    namespace: str  # env|yaml|json|toml|ini|properties|dockerfile
+    value: Optional[str] = None  # populated only when options.artifact_text is on
+    span: Optional[Span] = None  # into the artifact's source; best-effort for yaml/json/toml
+    references: List[str] = []  # raw recognized tokens, order of appearance, deduplicated
+
+
+@builder
+class PyArtifact(BaseModel):
+    """Any non-`.py` project file (config, manifest, CI, container spec, or
+    plain data/binary) -- never dropped from the walk. Captured broadly (node
+    + verbatim ``source``); *meaning* is extracted narrowly -- only
+    ``dependency-manifest`` roles feed ``dependencies`` today. ``id`` is
+    language-neutral (``can://artifact/<app>/<path>``)."""
+
+    id: str = ""
+    kind: str = "artifact"
+    path: str  # repo-relative POSIX path (also the map key)
+    format: str  # toml|yaml|json|ini|properties|requirements|dockerfile|text|binary
+    roles: List[str] = []
+    size_bytes: int = 0
+    sha256: str = ""  # always the full file's hash, even when source is truncated/empty
+    source: str = ""  # verbatim by default; "" for binary or when capture is disabled
+    text_truncated: bool = False  # True when `source` is a prefix, not the full file
+    extraction: str = "none"  # none|partial|full
+    config_keys: List[PyConfigKey] = []  # flattened config keys (#152); [] when not namespace-eligible
+
+
+@builder
+class PyConfigUseEdge(BaseModel):
+    """One resolved config read (#162): a detector-matched call's key
+    argument closed on exactly one string literal that matches a declared
+    ``PyConfigKey``. ``src`` is the call's GLOBAL ordinal id
+    (``<callable-id>@<local-id>``); ``dst`` is the matched ``PyConfigKey.id``
+    -- application scope, mirroring ``param_in`` (endpoints span callables/
+    artifacts). Superset-monotonic across levels, same additive contract as
+    the DDG's ``prov`` widening: literal (``-a 2``+) subset of +dataflow
+    (``-a 3``/``-a 4``)."""
+
+    src: str
+    dst: str
+    prov: List[Literal["literal", "dataflow"]] = []
+
+
+@builder
+class PyConfigRead(BaseModel):
+    """A detector-matched call whose key did not close on exactly one string
+    literal -- first-class so a config read nobody can trace is as visible
+    as one that resolves (#162). ``key`` is the decoded literal text only
+    when it IS a literal but matches no declared ``PyConfigKey``
+    (``reason="undefined-key"``); ``None`` for a key that never closed on a
+    literal at all (``reason="non-literal"``). ``prov`` lists every tier
+    that was attempted before giving up."""
+
+    site: str  # GLOBAL ordinal id
+    callee: str  # external id (can://.../@external/<module>/<name>)
+    key: Optional[str] = None
+    reason: Literal["non-literal", "undefined-key"]
+    prov: List[Literal["literal", "dataflow"]] = []
+
+
+@builder
+class PyDependency(BaseModel):
+    """One declared third-party dependency, evidence-tagged via ``prov``."""
+
+    name: str  # PEP 503 normalized
+    ecosystem: str = "pypi"  # SDK symmetry with purl (#152 rider); the only ecosystem this analyzer emits
+    spec: str = ""
+    kind: str = "runtime"  # runtime|dev|optional|build
+    extras: List[str] = []
+    declared_in: str = ""  # PyArtifact id
+    # False for lockfile-only (transitive) dependencies -- pinned in a lock
+    # with no manifest declaration (#152 reconciliation).
+    direct: bool = True
+    locked_version: Optional[str] = None
+    provides_imports: List[str] = []
+    prov: List[str] = []  # declared|lockfile|installed-metadata|heuristic
+
+
+@builder
+class PyImportBinding(BaseModel):
+    """A top-level import no declared dependency accounts for."""
+
+    module: str
+    bound_to: Optional[str] = None  # best-effort distribution name
+    prov: List[str] = []
+
+
 @builder
 class PyRepositoryInfo(BaseModel):
     """Where the analyzed source came from: git provenance captured at analysis time."""
@@ -502,6 +611,11 @@ class PyApplication(BaseModel):
     # builtin members), keyed by signature. Populated by the analyzer so every
     # backend (JSON and Neo4j) shares one authoritative external-symbol set.
     external_symbols: Dict[str, PyExternalSymbol] = {}
+    # Non-code artifacts, declared dependencies, and undeclared imports
+    # (spec 2026-08-27). L1 data: identical at every analysis level.
+    artifacts: Dict[str, PyArtifact] = {}
+    dependencies: List[PyDependency] = []
+    unresolved_imports: List[PyImportBinding] = []
     # Coverage/failure record for the entrypoint pass; see PyEntrypointReport (#27).
     entrypoint_report: PyEntrypointReport = PyEntrypointReport()
     # Git provenance of the analyzed checkout, captured at analysis time.
@@ -509,6 +623,10 @@ class PyApplication(BaseModel):
     # Interprocedural parameter-passing edges (formal↔actual); populated at L4.
     param_in: List[ParamEdge] = []
     param_out: List[ParamEdge] = []
+    # config_use (#162): PY_USES_CONFIG edges + first-class unresolved reads.
+    # Literal tier from L2; dataflow tiers widen the set at L3/L4 (additive).
+    config_uses: List[PyConfigUseEdge] = []
+    config_reads_unresolved: List[PyConfigRead] = []
 
 
 @builder

codeanalyzer/syntactic_analysis/symbol_table_builder.py

@@ -1,5 +1,6 @@
 import ast
 import hashlib
+import json
 import os
 import tokenize
 from ast import AST, ClassDef
@@ -786,6 +787,16 @@ class SymbolTableBuilder:
                 PyCallArgument(
                     ast_kind=type(arg).__name__,
                     inferred_type=self._infer_type(script, arg.lineno, arg.col_offset),
+                    # Literal/name capture (#162): value JSON-encoded for a
+                    # Constant of a JSON-safe type; name for a bare Name --
+                    # never both, per the AST shapes involved.
+                    value=(
+                        json.dumps(arg.value)
+                        if isinstance(arg, ast.Constant)
+                        and isinstance(arg.value, (str, int, float, bool, type(None)))
+                        else None
+                    ),
+                    name=arg.id if isinstance(arg, ast.Name) else None,
                 )
                 for arg in node.args
             ]