codeanalyzer-python 1.2.0__tar.gz → 1.4.0__tar.gz

{codeanalyzer_python-1.2.0 → codeanalyzer_python-1.4.0}/.gitignore

@@ -195,3 +195,7 @@ node_modules/
 !.claude/
 .claude/*
 !.claude/SCHEMA_DECISIONS.md
+
+# Track fixture lock files past the repo-root uv.lock ignore
+!test/fixtures/**/uv.lock
+!test/fixtures/**/.env

{codeanalyzer_python-1.2.0 → codeanalyzer_python-1.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: codeanalyzer-python
-Version: 1.2.0
+Version: 1.4.0
 Summary: Static analysis for Python — canonical schema v2 (symbol table, call graph, and native CFG/PDG/SDG dataflow) as analysis.json or a Neo4j property graph.
 Author-email: Rahul Krishna <i.m.ralk@gmail.com>
 License-File: LICENSE
@@ -21,6 +21,7 @@ Requires-Dist: ray==2.0.0; python_version < '3.11'
 Requires-Dist: requests<3.0.0,>=2.20.0; python_version >= '3.11'
 Requires-Dist: rich<14.0.0,>=12.6.0; python_version < '3.11'
 Requires-Dist: rich<15.0.0,>=14.0.0; python_version >= '3.11'
+Requires-Dist: tomli>=2.0; python_version < '3.11'
 Requires-Dist: typer<1.0.0,>=0.9.0; python_version < '3.11'
 Requires-Dist: typer<2.0.0,>=0.9.0; python_version >= '3.11'
 Requires-Dist: typing-extensions<5.0.0,>=4.0.0; python_version < '3.11'
@@ -98,7 +99,9 @@ needs.
   **interprocedural SDG** (synthetic parameter vertices, `param_in`/`param_out`/`summary`,
   alias-aware DDG) at level 4 — all built in-process from the stdlib `ast`.
 - **Neo4j output** — project the analysis into a labeled property graph: a self-contained
-  `graph.cypher` snapshot, or an **incremental** push to a live database over Bolt.
+  `graph.cypher` snapshot, or an **incremental** push to a live database over Bolt. A push is
+  **additive by default** and never deletes: `--eager` is what permits it to remove declarations
+  and edges the source no longer has.
 - **Versioned schema** — a machine-readable, version-stamped Neo4j schema contract (`--emit schema`),
   checked in as `schema.neo4j.json` (`2.0.0`) and shipped with every release.
 - **Incremental cache** — per-file results are cached under `.codeanalyzer`; `--lazy` (default)
@@ -299,7 +302,19 @@ $ canpy --help
 │ --eager                --lazy                               Enable eager or  │
 │                                                             lazy analysis.   │
 │                                                             Defaults to      │
-│                                                             lazy.            │
+│                                                             lazy. Also gates │
+│                                                             every            │
+│                                                             destructive step │
+│                                                             of a '--emit     │
+│                                                             neo4j' Bolt      │
+│                                                             push: a lazy     │
+│                                                             push only adds   │
+│                                                             and updates, an  │
+│                                                             eager one also   │
+│                                                             removes          │
+│                                                             declarations and │
+│                                                             edges the source │
+│                                                             no longer has.   │
 │                                                             [default: lazy]  │
 │ --skip-tests           --include-tests                      Skip test files  │
 │                                                             in analysis.     │
@@ -315,6 +330,16 @@ $ canpy --help
 │                                                             environment      │
 │                                                             instead.         │
 │                                                             [default: venv]  │
+│ --resolve-instal…                                           Additionally     │
+│                                                             bind imports via │
+│                                                             the project      │
+│                                                             venv's installed │
+│                                                             metadata         │
+│                                                             (*.dist-info);   │
+│                                                             output becomes   │
+│                                                             machine-depende… │
+│                                                             (prov:           │
+│                                                             installed-metad… │
 │ --file-name                               <path>            Analyze only the │
 │                                                             specified file   │
 │                                                             (relative to     │
@@ -346,6 +371,22 @@ $ canpy --help
 │                                                             shipped rules. A │
 │                                                             malformed file   │
 │                                                             is an error.     │
+│ --artifact-text        --no-artifact-…                      Capture verbatim │
+│                                                             `source` text on │
+│                                                             discovered       │
+│                                                             artifacts.       │
+│                                                             `source` is the  │
+│                                                             whole file;      │
+│                                                             --no-artifact-t… │
+│                                                             empties it       │
+│                                                             everywhere       │
+│                                                             (inventory       │
+│                                                             unchanged).      │
+│                                                             sha256/size_byt… │
+│                                                             always reflect   │
+│                                                             the full file.   │
+│                                                             [default:        │
+│                                                             artifact-text]   │
 │ --help                                                      Show this        │
 │                                                             message and      │
 │                                                             exit.            │
@@ -517,14 +558,29 @@ A **callable** (function or method) carries its own CPG, keyed by node id:
 }
 ```
 
+The application envelope also contains three substrate sections:
+
+- **`artifacts`** — discovered non-code files (manifests, configs, Docker files, CI workflows,
+  packaging files, scripts, docs, and legal files) with extraction status (`none`, `partial`, or
+  `full`; default `none`), keyed by relative path; each artifact carries the
+  `can://artifact/<app>/<path>` id namespace. Config files carry extracted `config_keys`
+  (keys, values, namespaces, and references) and `DEFINES_CONFIG` Neo4j edges.
+- **`dependencies`** — declared packages with kind (`runtime`/`dev`/`optional`/`build`), spec,
+  locked version, and provenance (`prov`): where each binding came from (manifest file, lock file,
+  installed metadata).
+- **`unresolved_imports`** — modules imported but not resolvable in the declared dependency set,
+  one entry per module.
+
 Notable properties:
 
 - **Durable `can://` ids** identify every node at callable granularity and above
   (`can://python/<app>/<file>/<callable-sig>`); nodes below a callable use ordinal ids
   (`@entry`, `@exit`, `line:col`, `@formal_in:N`, `line:col/actual_in:N`).
 - **`source` lives once per module**; every node's text is the `module.source[span.bytes]` slice.
-- **Cross-function edges** — `call_graph`, `param_in`, `param_out` — live at **application** scope;
+- **Cross-function edges** — `call_graph`, `param_in`, `param_out`, `config_uses` — live at **application** scope;
   the intraprocedural `cfg`/`cdg`/`ddg` and the `summary` edges live **on the callable**.
+  `config_uses` resolve from call-site key arguments to `ConfigKey` nodes; unresolved reads
+  go to `config_reads_unresolved`.
 - **No dangling endpoints** — every `call_graph` `src`/`dst` joins the id space: declared
   callables by their tree id, imported/builtin targets by a `…/@external/<module>/<name>` id
   homed in `application.external_symbols`.
@@ -545,9 +601,13 @@ binary format).
 
 ### Neo4j graph
 
-`--emit neo4j` projects the same schema v2.0.0 analysis into a labeled property graph. Every node
-label is `Py`-prefixed and every relationship type is `PY_`-prefixed (e.g. `:PyClass`, `PY_CALLS`)
-so multiple language analyzers can share one database without label or relationship-type collisions.
+`--emit neo4j` projects the same schema v2.0.0 analysis into a labeled property graph. Every
+Python-specific node label is `Py`-prefixed and every Python-specific relationship type is
+`PY_`-prefixed (e.g. `:PyClass`, `PY_CALLS`) so multiple language analyzers can share one database
+without label or relationship-type collisions. The one deliberate exception is the language-neutral
+`Artifact`/`Package` subgraph (non-code files and third-party dependencies) — those nodes carry no
+`Py` prefix, since they are meant as cross-language merge targets: a sibling-language analyzer over
+the same repo should land on the same `Artifact`/`Package` nodes, not a per-language duplicate.
 Declarations are keyed by their **`can://` id** under a shared `:PySymbol` label; calls, imports,
 inheritance, decorators, and call sites are relationships. At `-a 3`/`-a 4` the projection gains the
 **CPG overlay** — `:PyBodyNode` nodes (statements, and at level 4 the parameter vertices) wired by
@@ -608,6 +668,56 @@ runtime (Docker or Podman) and is enabled with an environment variable:
 RUN_CONTAINER_TESTS=1 uv run pytest test/test_neo4j_bolt.py -s
 ```
 
+## Graph query cookbook
+
+Example Cypher over the projected graph (`--emit neo4j`, then load `graph.cypher` or push via Bolt).
+
+```cypher
+// who calls this function? (direct callers)
+MATCH (c:PyCallable)-[:PY_CALLS]->(t:PyCallable {name: "process_payment"})
+RETURN c.id
+
+// every callable that reaches a given library, via the external ghosts
+MATCH (c:PyCallable)-[:PY_CALLS]->(e:PyExternal)
+WHERE e.id CONTAINS "/@external/requests/"
+RETURN DISTINCT c.id
+
+// entrypoints and the frameworks that invoke them
+MATCH (m:PyCallable {is_entrypoint: true})
+RETURN m.id, m.entrypoint_frameworks
+
+// data dependences into one statement (level 3+)
+MATCH (s:PyBodyNode {id: $stmt})<-[d:PY_DDG]-(src:PyBodyNode)
+RETURN src.id, d.var, d.prov
+
+// interprocedural flow through a parameter (level 4)
+MATCH (a:PyBodyNode)-[:PY_PARAM_IN]->(f:PyBodyNode)
+WHERE f.id STARTS WITH "can://python/myapp/src/api.py"
+RETURN a.id, f.id
+```
+
+Artifact and dependency queries (1.3.0+):
+
+```cypher
+// all container/orchestration configs in the app
+MATCH (a:PyApplication)-[:HAS_ARTIFACT]->(f:Artifact)
+WHERE any(r IN f.roles WHERE r IN ["service-topology", "container-image"])
+RETURN f.id, f.format
+
+// every callable that reaches code from a declared package
+MATCH (c:PyCallable)-[:PY_CALLS]->(:PyExternal)<-[:PY_PROVIDES]-(p:Package {id: "pkg:pypi/requests"})
+RETURN c.id
+
+// undeclared imports (dependency hygiene)
+MATCH (a:PyApplication)-[u:PY_UNRESOLVED_IMPORT]->(e:PyExternal)
+WHERE NOT (e)<-[:PY_PROVIDES]-(:Package)
+RETURN e.id, u.prov
+
+// which lock file pins this package, and to what
+MATCH (f:Artifact)-[l:LOCKS]->(p:Package {id: "pkg:pypi/numpy"})
+RETURN f.id, l.version
+```
+
 ## License
 
 Apache 2.0 — see [LICENSE](./LICENSE).

{codeanalyzer_python-1.2.0 → codeanalyzer_python-1.4.0}/README.md

@@ -66,7 +66,9 @@ needs.
   **interprocedural SDG** (synthetic parameter vertices, `param_in`/`param_out`/`summary`,
   alias-aware DDG) at level 4 — all built in-process from the stdlib `ast`.
 - **Neo4j output** — project the analysis into a labeled property graph: a self-contained
-  `graph.cypher` snapshot, or an **incremental** push to a live database over Bolt.
+  `graph.cypher` snapshot, or an **incremental** push to a live database over Bolt. A push is
+  **additive by default** and never deletes: `--eager` is what permits it to remove declarations
+  and edges the source no longer has.
 - **Versioned schema** — a machine-readable, version-stamped Neo4j schema contract (`--emit schema`),
   checked in as `schema.neo4j.json` (`2.0.0`) and shipped with every release.
 - **Incremental cache** — per-file results are cached under `.codeanalyzer`; `--lazy` (default)
@@ -267,7 +269,19 @@ $ canpy --help
 │ --eager                --lazy                               Enable eager or  │
 │                                                             lazy analysis.   │
 │                                                             Defaults to      │
-│                                                             lazy.            │
+│                                                             lazy. Also gates │
+│                                                             every            │
+│                                                             destructive step │
+│                                                             of a '--emit     │
+│                                                             neo4j' Bolt      │
+│                                                             push: a lazy     │
+│                                                             push only adds   │
+│                                                             and updates, an  │
+│                                                             eager one also   │
+│                                                             removes          │
+│                                                             declarations and │
+│                                                             edges the source │
+│                                                             no longer has.   │
 │                                                             [default: lazy]  │
 │ --skip-tests           --include-tests                      Skip test files  │
 │                                                             in analysis.     │
@@ -283,6 +297,16 @@ $ canpy --help
 │                                                             environment      │
 │                                                             instead.         │
 │                                                             [default: venv]  │
+│ --resolve-instal…                                           Additionally     │
+│                                                             bind imports via │
+│                                                             the project      │
+│                                                             venv's installed │
+│                                                             metadata         │
+│                                                             (*.dist-info);   │
+│                                                             output becomes   │
+│                                                             machine-depende… │
+│                                                             (prov:           │
+│                                                             installed-metad… │
 │ --file-name                               <path>            Analyze only the │
 │                                                             specified file   │
 │                                                             (relative to     │
@@ -314,6 +338,22 @@ $ canpy --help
 │                                                             shipped rules. A │
 │                                                             malformed file   │
 │                                                             is an error.     │
+│ --artifact-text        --no-artifact-…                      Capture verbatim │
+│                                                             `source` text on │
+│                                                             discovered       │
+│                                                             artifacts.       │
+│                                                             `source` is the  │
+│                                                             whole file;      │
+│                                                             --no-artifact-t… │
+│                                                             empties it       │
+│                                                             everywhere       │
+│                                                             (inventory       │
+│                                                             unchanged).      │
+│                                                             sha256/size_byt… │
+│                                                             always reflect   │
+│                                                             the full file.   │
+│                                                             [default:        │
+│                                                             artifact-text]   │
 │ --help                                                      Show this        │
 │                                                             message and      │
 │                                                             exit.            │
@@ -485,14 +525,29 @@ A **callable** (function or method) carries its own CPG, keyed by node id:
 }
 ```
 
+The application envelope also contains three substrate sections:
+
+- **`artifacts`** — discovered non-code files (manifests, configs, Docker files, CI workflows,
+  packaging files, scripts, docs, and legal files) with extraction status (`none`, `partial`, or
+  `full`; default `none`), keyed by relative path; each artifact carries the
+  `can://artifact/<app>/<path>` id namespace. Config files carry extracted `config_keys`
+  (keys, values, namespaces, and references) and `DEFINES_CONFIG` Neo4j edges.
+- **`dependencies`** — declared packages with kind (`runtime`/`dev`/`optional`/`build`), spec,
+  locked version, and provenance (`prov`): where each binding came from (manifest file, lock file,
+  installed metadata).
+- **`unresolved_imports`** — modules imported but not resolvable in the declared dependency set,
+  one entry per module.
+
 Notable properties:
 
 - **Durable `can://` ids** identify every node at callable granularity and above
   (`can://python/<app>/<file>/<callable-sig>`); nodes below a callable use ordinal ids
   (`@entry`, `@exit`, `line:col`, `@formal_in:N`, `line:col/actual_in:N`).
 - **`source` lives once per module**; every node's text is the `module.source[span.bytes]` slice.
-- **Cross-function edges** — `call_graph`, `param_in`, `param_out` — live at **application** scope;
+- **Cross-function edges** — `call_graph`, `param_in`, `param_out`, `config_uses` — live at **application** scope;
   the intraprocedural `cfg`/`cdg`/`ddg` and the `summary` edges live **on the callable**.
+  `config_uses` resolve from call-site key arguments to `ConfigKey` nodes; unresolved reads
+  go to `config_reads_unresolved`.
 - **No dangling endpoints** — every `call_graph` `src`/`dst` joins the id space: declared
   callables by their tree id, imported/builtin targets by a `…/@external/<module>/<name>` id
   homed in `application.external_symbols`.
@@ -513,9 +568,13 @@ binary format).
 
 ### Neo4j graph
 
-`--emit neo4j` projects the same schema v2.0.0 analysis into a labeled property graph. Every node
-label is `Py`-prefixed and every relationship type is `PY_`-prefixed (e.g. `:PyClass`, `PY_CALLS`)
-so multiple language analyzers can share one database without label or relationship-type collisions.
+`--emit neo4j` projects the same schema v2.0.0 analysis into a labeled property graph. Every
+Python-specific node label is `Py`-prefixed and every Python-specific relationship type is
+`PY_`-prefixed (e.g. `:PyClass`, `PY_CALLS`) so multiple language analyzers can share one database
+without label or relationship-type collisions. The one deliberate exception is the language-neutral
+`Artifact`/`Package` subgraph (non-code files and third-party dependencies) — those nodes carry no
+`Py` prefix, since they are meant as cross-language merge targets: a sibling-language analyzer over
+the same repo should land on the same `Artifact`/`Package` nodes, not a per-language duplicate.
 Declarations are keyed by their **`can://` id** under a shared `:PySymbol` label; calls, imports,
 inheritance, decorators, and call sites are relationships. At `-a 3`/`-a 4` the projection gains the
 **CPG overlay** — `:PyBodyNode` nodes (statements, and at level 4 the parameter vertices) wired by
@@ -576,6 +635,56 @@ runtime (Docker or Podman) and is enabled with an environment variable:
 RUN_CONTAINER_TESTS=1 uv run pytest test/test_neo4j_bolt.py -s
 ```
 
+## Graph query cookbook
+
+Example Cypher over the projected graph (`--emit neo4j`, then load `graph.cypher` or push via Bolt).
+
+```cypher
+// who calls this function? (direct callers)
+MATCH (c:PyCallable)-[:PY_CALLS]->(t:PyCallable {name: "process_payment"})
+RETURN c.id
+
+// every callable that reaches a given library, via the external ghosts
+MATCH (c:PyCallable)-[:PY_CALLS]->(e:PyExternal)
+WHERE e.id CONTAINS "/@external/requests/"
+RETURN DISTINCT c.id
+
+// entrypoints and the frameworks that invoke them
+MATCH (m:PyCallable {is_entrypoint: true})
+RETURN m.id, m.entrypoint_frameworks
+
+// data dependences into one statement (level 3+)
+MATCH (s:PyBodyNode {id: $stmt})<-[d:PY_DDG]-(src:PyBodyNode)
+RETURN src.id, d.var, d.prov
+
+// interprocedural flow through a parameter (level 4)
+MATCH (a:PyBodyNode)-[:PY_PARAM_IN]->(f:PyBodyNode)
+WHERE f.id STARTS WITH "can://python/myapp/src/api.py"
+RETURN a.id, f.id
+```
+
+Artifact and dependency queries (1.3.0+):
+
+```cypher
+// all container/orchestration configs in the app
+MATCH (a:PyApplication)-[:HAS_ARTIFACT]->(f:Artifact)
+WHERE any(r IN f.roles WHERE r IN ["service-topology", "container-image"])
+RETURN f.id, f.format
+
+// every callable that reaches code from a declared package
+MATCH (c:PyCallable)-[:PY_CALLS]->(:PyExternal)<-[:PY_PROVIDES]-(p:Package {id: "pkg:pypi/requests"})
+RETURN c.id
+
+// undeclared imports (dependency hygiene)
+MATCH (a:PyApplication)-[u:PY_UNRESOLVED_IMPORT]->(e:PyExternal)
+WHERE NOT (e)<-[:PY_PROVIDES]-(:Package)
+RETURN e.id, u.prov
+
+// which lock file pins this package, and to what
+MATCH (f:Artifact)-[l:LOCKS]->(p:Package {id: "pkg:pypi/numpy"})
+RETURN f.id, l.version
+```
+
 ## License
 
 Apache 2.0 — see [LICENSE](./LICENSE).

{codeanalyzer_python-1.2.0 → codeanalyzer_python-1.4.0}/codeanalyzer/__main__.py

@@ -175,7 +175,10 @@ def main(
         bool,
         typer.Option(
             "--eager/--lazy",
-            help="Enable eager or lazy analysis. Defaults to lazy.",
+            help="Enable eager or lazy analysis. Defaults to lazy. Also gates every "
+            "destructive step of a '--emit neo4j' Bolt push: a lazy push only adds and "
+            "updates, an eager one also removes declarations and edges the source no "
+            "longer has.",
         ),
     ] = False,
     skip_tests: Annotated[
@@ -193,6 +196,14 @@ def main(
             "imports against the ambient Python environment instead.",
         ),
     ] = False,
+    resolve_installed: Annotated[
+        bool,
+        typer.Option(
+            "--resolve-installed",
+            help="Additionally bind imports via the project venv's installed metadata "
+            "(*.dist-info); output becomes machine-dependent (prov: installed-metadata).",
+        ),
+    ] = False,
     file_name: Annotated[
         Optional[Path],
         typer.Option(
@@ -226,6 +237,16 @@ def main(
             "the shipped rules. A malformed file is an error.",
         ),
     ] = None,
+    artifact_text: Annotated[
+        bool,
+        typer.Option(
+            "--artifact-text/--no-artifact-text",
+            help="Capture verbatim `source` text on discovered artifacts. "
+            "`source` is the whole file; --no-artifact-text empties it "
+            "everywhere (inventory unchanged). sha256/size_bytes always "
+            "reflect the full file.",
+        ),
+    ] = True,
 ):
     # Determinism: pin the interpreter hash seed before any analysis (no-op
     # when PYTHONHASHSEED is already set; --version exits before this).
@@ -303,11 +324,13 @@ def main(
         rebuild_analysis=rebuild_analysis,
         skip_tests=skip_tests,
         no_venv=no_venv,
+        resolve_installed=resolve_installed,
         file_name=file_name,
         cache_dir=cache_dir,
         clear_cache=clear_cache,
         verbosity=verbosity,
         entrypoint_rules=tuple(entrypoint_rules or ()),
+        artifact_text=artifact_text,
     )
 
     _set_log_level(options.verbosity)

codeanalyzer_python-1.4.0/codeanalyzer/artifacts/__init__.py

@@ -0,0 +1,20 @@
+"""Non-code artifact capture and dependency extraction (spec 2026-08-27).
+
+Capture never drops a file (every non-`.py` file becomes a
+:class:`~codeanalyzer.schema.py_schema.PyArtifact`, rule-matched or not,
+text or binary -- issue #157 follow-up); extraction is narrow (only
+dependency manifests are parsed for meaning in this unit)."""
+
+from codeanalyzer.artifacts.config_keys import extract_config_keys, is_config_eligible
+from codeanalyzer.artifacts.config_use import (
+    dataflow_intra_tier, dataflow_interproc_tier, detect_config_reads, resolve_uses,
+)
+from codeanalyzer.artifacts.dependencies import build_dependency_view
+from codeanalyzer.artifacts.discovery import discover_artifacts
+
+__all__ = [
+    "discover_artifacts", "build_dependency_view",
+    "extract_config_keys", "is_config_eligible",
+    "detect_config_reads", "resolve_uses",
+    "dataflow_intra_tier", "dataflow_interproc_tier",
+]