Merge pull request #167 from codellm-devkit/design/skill-config-use

docs(skills): config_use vocabulary and bridge analyses

Author: rahlk

docs/skills/analyzing-canpy-graphs/SKILL.md

@@ -19,7 +19,7 @@ minimum `-a` level.
 | `-a` | tree | edges |
 | --- | --- | --- |
 | 1 | callables + `call` body nodes + entrypoints + artifacts/dependencies | `HAS_ARTIFACT`, `DECLARES_DEPENDENCY`, `LOCKS`, `PY_PROVIDES`, `PY_UNRESOLVED_IMPORT` |
-| 2 | `callee` resolved | `PY_CALLS` (prov `jedi`/`defuse`), `PY_RESOLVES_TO` |
+| 2 | `callee` resolved | `PY_CALLS` (prov `jedi`/`defuse`), `PY_RESOLVES_TO`, `PY_USES_CONFIG` (literal tier) + `PY_READS_CONFIG_UNRESOLVED` |
 | 3 | full statement `body`, `@entry`/`@exit` | `PY_CFG_NEXT`, `PY_CDG`, `PY_DDG` (prov `ssa`, `reaching-defs`) |
 | 4 | `formal_in/out`, `actual_in/out` vertices | `PY_PARAM_IN`, `PY_PARAM_OUT`, `PY_SUMMARY`, ddg widened `points-to` |
 
@@ -54,7 +54,9 @@ Neo4j is always projected full-depth for the level analyzed.
    `entrypoint_frameworks`) of `PyCallable` AND `PyClass` — there is no
    `:Entrypoint` label.
 
-Taint is composed, not stored: reachability over
+`PY_USES_CONFIG` widens with the analysis level (literal at `-a 2`, def-use
+closure at `-a 3`, cross-call closure at `-a 4`) and never guesses — unresolved
+reads carry a reason instead. Taint is composed, not stored: reachability over
 `PY_DDG ∪ PY_PARAM_IN ∪ PY_PARAM_OUT ∪ PY_SUMMARY` (provider/client boundary —
 source/sink packs are the SDK's job). Exit points = returns + external calls +
 caller-visible writes; both have full recipes in analyses.md.

docs/skills/analyzing-canpy-graphs/references/analyses.md

@@ -224,7 +224,45 @@ MATCH (f:Artifact) WHERE f.source CONTAINS "POSTGRES_PASSWORD" RETURN f.path
 MATCH (p:Package) WHERE p.id STARTS WITH "pkg:" RETURN p.ecosystem, count(*)
 ```
 
-## 12. Health metrics (any level)
+## 12. Config-use bridge (L2 literal; L3/L4 widen)
+
+```cypher
+// which statements read which config keys, with tier evidence
+MATCH (s:PyBodyNode)-[u:PY_USES_CONFIG]->(k:ConfigKey)
+RETURN s.id, k.key, k.namespace, u.prov
+
+// blast radius of renaming a key: every reading statement + its callable
+MATCH (k:ConfigKey {key: "DB_HOST"})<-[:PY_USES_CONFIG]-(s:PyBodyNode)
+MATCH (c:PyCallable)-[:PY_HAS_BODY_NODE]->(s)
+RETURN c.id, s.start_line
+
+// the service's ambient-environment contract: reads nobody defines
+MATCH (:PyApplication)-[r:PY_READS_CONFIG_UNRESOLVED]->(callee:PyExternal)
+WHERE r.reason = "undefined-key"
+RETURN r.key, callee.module + "." + callee.name AS via, count(*) AS sites
+ORDER BY sites DESC
+
+// dynamic config reads needing human eyes (key statically unknown)
+MATCH (:PyApplication)-[r:PY_READS_CONFIG_UNRESOLVED]->(callee:PyExternal)
+WHERE r.reason = "non-literal"
+RETURN callee.module, count(*)
+
+// config-to-exit-point join: keys whose values look like backend URLs,
+// beside the external libraries the code exits through
+MATCH (a:Artifact)-[:DEFINES_CONFIG]->(k:ConfigKey)
+WHERE k.value =~ ".*(postgres|redis|amqp|https?)://.*"
+WITH collect({file: a.path, key: k.key}) AS declared_backends
+MATCH (c:PyCallable)-[:PY_CALLS]->(x:PyExternal)
+WHERE x.module IN ["psycopg2", "redis", "requests"]
+RETURN declared_backends, x.module, count(DISTINCT c)
+```
+
+Edges never guess: literal tier (`-a 2`) needs a string-literal key at a
+detector-listed call; dataflow tier (`-a 3` intra, `-a 4` interprocedural)
+resolves only chains closing over exactly one literal. Everything else lands
+in the unresolved rel with a reason.
+
+## 13. Health metrics (any level)
 
 ```cypher
 // external surface per module

docs/skills/analyzing-canpy-graphs/references/vocabulary.md

@@ -51,7 +51,13 @@
 | `LOCKS` | lock artifact → package | version | locks never create packages alone |
 | `PY_PROVIDES` | package → external (module-level ghost) | — | joins dependencies into the call graph |
 | `PY_UNRESOLVED_IMPORT` | application → external (module-level ghost) | prov[] | undeclared-import hygiene |
+| `PY_USES_CONFIG` | body node → ConfigKey | prov[] | which statement reads which key; prov ⊆ {literal, dataflow}; superset-monotonic `-a 2 ⊆ 3 ⊆ 4` |
+| `PY_READS_CONFIG_UNRESOLVED` | application → external (callee ghost) | key, reason, prov[], `_k` | config reads that never resolved; reason ∈ {non-literal, undefined-key}; the unresolved list is the edge set's sanctioned complement (shrinks as levels rise) |
 
 All dataflow relationships are stored src→dst in the forward direction.
+
+Call arguments carry literal evidence: `PyCallArgument.value` (JSON-encoded
+constant — `json.loads` it) and `.name` (bare identifier) back the config_use
+tiers and are queryable via `PyBodyNode.arguments_json`.
 Dependency `prov` vocabulary: `declared`, `lockfile`, `installed-metadata`
 (only with `--resolve-installed`), `heuristic`.