Merge pull request #168 from codellm-devkit/feat/issue-165-deployment-env

feat: deployment-env config keys — Dockerfile ENV/ARG, compose and k8s env

Author: rahlk

CHANGELOG.md

@@ -35,6 +35,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   Unresolved reads (non-literal keys, undefined keys) emitted in
   `application.config_reads_unresolved` with reasons; `PY_READS_CONFIG_UNRESOLVED`
   Neo4j projection (#162).
+- Deployment-env config-key namespaces: Dockerfile `ENV`/`ARG` directives
+  (multi-key, legacy space form, backslash continuations, quoted values) and
+  compose/k8s `environment`/`env` shapes are now extracted too. `ENV` and
+  compose/k8s `environment`/`env` entries mint namespace `env`, so
+  `os.environ`/`os.getenv` reads resolve against deployment-declared
+  variables; Dockerfile `ARG` mints its own `dockerfile` namespace
+  (build-time only, not env-detector-bindable). Compose/k8s recognition
+  dual-mints alongside the plain `yaml` dotted-path keys, by design (#165).
 
 ## [1.2.0] - 2026-08-26
 

codeanalyzer/artifacts/config_keys.py

@@ -492,7 +492,7 @@ class PyConfigKey(BaseModel):
 
     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
+    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

codeanalyzer/schema/py_schema.py

@@ -25,10 +25,18 @@ reading a key) is the recorded follow-up.
    references are always extracted — `--no-artifact-text` drops values and
    source together, so the secret off-switch actually switches everything off.
 3. **V1 formats**: `env` (`.env`, `.env.*`, `.flaskenv`), `yaml`, `json`,
-   `toml`, `ini`, `properties`. Extraction is format-driven over existing
-   artifacts (pyproject.toml gets keys too; overlap with dependency records is
-   harmless). `references[]` v1 recognizes three syntaxes, recorded as raw
-   tokens: `${VAR}`/`$VAR`, `%(name)s`, `${{ ... }}`.
+   `toml`, `ini`, `properties`, `dockerfile`. Extraction is format-driven over
+   existing artifacts (pyproject.toml gets keys too; overlap with dependency
+   records is harmless). `references[]` v1 recognizes three syntaxes, recorded
+   as raw tokens: `${VAR}`/`$VAR`, `%(name)s`, `${{ ... }}`. Deployment-env
+   namespaces (issue #165, a later extension of this same machinery): a
+   `dockerfile`-format artifact's `ENV` directives mint namespace `env` (so
+   `os.environ`/`os.getenv` reads bind to them) while its `ARG` directives
+   mint namespace `dockerfile` (build-time only, not env-detector-bindable);
+   a `yaml`-format artifact
+   additionally dual-mints namespace `env` keys for recognized compose
+   (`services.*.environment`) and k8s (`...env[].name`/`.value`) shapes,
+   alongside the plain dotted-path `yaml` mint of the same leaves.
 4. **Placement: nested.** `PyArtifact.config_keys: List[PyConfigKey]` —
    containment mirrors `DEFINES_CONFIG`; L1 data, identical at every level.
 5. **Overlay posture.** Parse failure never drops the artifact node; it sets
@@ -43,7 +51,7 @@ reading a key) is the recorded follow-up.
 | --- | --- | --- |
 | `id` | str | `<artifact-id>@key/<dotted.key>` |
 | `key` | str | dotted path; numeric segments for arrays (`services.web.ports.0`) |
-| `namespace` | str | `env` \| `yaml` \| `json` \| `toml` \| `ini` \| `properties` |
+| `namespace` | str | `env` \| `yaml` \| `json` \| `toml` \| `ini` \| `properties` \| `dockerfile` |
 | `value` | Optional[str] | only when text capture on |
 | `span` | Span | into the artifact's source |
 | `references` | List[str] | raw recognized tokens |

docs/design/specs/2026-08-28-config-key-family-design.md

@@ -1 +1,4 @@
 FROM python:3.12-slim
+
+ARG BUILD_REV
+ENV APP_MODE=production

test/fixtures/whole_applications/manifests_app/Dockerfile

@@ -1,3 +1,5 @@
 services:
   web:
     build: .
+    environment:
+      COMPOSE_ONLY_KEY: x

test/fixtures/whole_applications/manifests_app/docker-compose.yml

@@ -1,4 +1,4 @@
-"""Config-use e2e fixture for all five detection shapes (#162 Task 5)."""
+"""Config-use e2e fixture for all six detection shapes (#162 Task 5, #165)."""
 import os
 
 
@@ -38,3 +38,9 @@ def get_config_multi_def(use_debug):
 # Should appear in config_reads_unresolved with reason: "undefined-key"
 def get_missing_config():
     return os.getenv("NOT_DEFINED_ANYWHERE")
+
+
+# Shape 6: Deployment-env, reads APP_MODE from the Dockerfile ENV directive
+# (#165). Direct literal, resolves at -a 2 like shape 1.
+def get_app_mode():
+    return os.getenv("APP_MODE")

test/fixtures/whole_applications/manifests_app/pkg/config_reader.py

@@ -205,20 +205,26 @@ def test_config_keys_extraction_level(tmp_path):
     )).analyze().application
 
     # Config keys should be identical at both levels
-    for art_name in [".env", "config/settings.yml", "app.properties"]:
+    for art_name in [
+        ".env", "config/settings.yml", "app.properties",
+        "Dockerfile", "docker-compose.yml",  # deployment-env namespaces (#165)
+    ]:
         l1_keys = sorted([k.key for k in app_l1.artifacts[art_name].config_keys])
         l4_keys = sorted([k.key for k in app_l4.artifacts[art_name].config_keys])
         assert l1_keys == l4_keys
 
 
 def test_config_keys_extraction_full(tmp_path):
-    """Verify extraction='full' on the three config files."""
+    """Verify extraction='full' on the config files, including Dockerfile
+    (newly namespace-eligible as of #165 -- it was "none" before, since
+    `is_config_eligible` used to skip it outright)."""
     app = _app(tmp_path, "extraction_test")
 
-    # All three new config files should have extraction='full'
     assert app.artifacts[".env"].extraction == "full"
     assert app.artifacts["config/settings.yml"].extraction == "full"
     assert app.artifacts["app.properties"].extraction == "full"
+    assert app.artifacts["Dockerfile"].extraction == "full"
+    assert app.artifacts["docker-compose.yml"].extraction == "full"
 
 
 def _id_suffix(id_: str) -> str:
@@ -229,7 +235,8 @@ def _id_suffix(id_: str) -> str:
 
 
 def test_config_uses_full(tmp_path):
-    """Verify config-use edges at -a 4: all five fixture shapes (#162 Task 5).
+    """Verify config-use edges at -a 4: all six fixture shapes (#162 Task 5,
+    #165 shape 6).
 
     Exact-set assertions (the plan's "exact", not a `>=` lower bound): every
     `config_uses` edge as `(src-suffix, dst-key, prov)` and every
@@ -238,7 +245,8 @@ def test_config_uses_full(tmp_path):
     against the dataflow-tier fixes landed alongside this test -- none of
     those fixes' shapes (aliasing, conditional shadowing, module-scope
     callers) occur in this fixture, so the counts are unchanged from the
-    pre-fix reviewer probe: 3 resolved, 2 unresolved at -a 4).
+    pre-fix reviewer probe except for #165's own addition: 4 resolved, 2
+    unresolved at -a 4).
     """
     app = Codeanalyzer(AnalysisOptions(
         input=FIXTURE, analysis_level=4, no_venv=True, cache_dir=tmp_path / "config_uses",
@@ -250,11 +258,14 @@ def test_config_uses_full(tmp_path):
     #    (site is the read INSIDE _read_config, not get_secret_token's call)
     # 4. Multi-def unresolved: get_config_multi_def() -> unresolved (two defs)
     # 5. Undefined-key: get_missing_config() -> unresolved (key not in .env)
+    # 6. Deployment-env literal: get_app_mode() -> os.getenv("APP_MODE"),
+    #    binding to the Dockerfile `ENV APP_MODE=production` key (#165).
     uses = {(_id_suffix(e.src), _id_suffix(e.dst), tuple(e.prov)) for e in app.config_uses}
     assert uses == {
         ("get_database_url()@7:11", "DATABASE_URL", ("literal",)),
         ("get_api_key()@14:11", "API_KEY", ("dataflow",)),
         ("_read_config(name)@20:11", "SECRET_API_TOKEN", ("dataflow",)),
+        ("get_app_mode()@46:11", "APP_MODE", ("literal",)),
     }
 
     unresolved = {(_id_suffix(r.site), r.reason, r.key) for r in app.config_reads_unresolved}
@@ -264,6 +275,40 @@ def test_config_uses_full(tmp_path):
     }
 
 
+def test_config_uses_app_mode_resolves_at_l2(tmp_path):
+    """The deployment-env DoD, verified directly (#165): `get_app_mode()`'s
+    `os.getenv("APP_MODE")` binds to the Dockerfile `ENV APP_MODE=production`
+    key at `-a 2` already -- a direct literal, same tier as `DATABASE_URL`,
+    with no dataflow tier needed."""
+    app = Codeanalyzer(AnalysisOptions(
+        input=FIXTURE, analysis_level=2, no_venv=True, cache_dir=tmp_path / "app_mode_l2",
+    )).analyze().application
+    uses = {(_id_suffix(e.src), _id_suffix(e.dst), tuple(e.prov)) for e in app.config_uses}
+    assert ("get_app_mode()@46:11", "APP_MODE", ("literal",)) in uses
+
+
+def test_config_keys_deployment_env(tmp_path):
+    """Verify Dockerfile ENV/ARG and compose environment-map config keys,
+    and their dual-mint into namespace "env" alongside the plain namespace
+    "yaml" dotted path (#165)."""
+    app = _app(tmp_path, "deployment_env_test")
+
+    df_keys = {(k.key, k.namespace, k.value) for k in app.artifacts["Dockerfile"].config_keys}
+    assert df_keys == {
+        ("APP_MODE", "env", "production"),
+        ("BUILD_REV", "dockerfile", None),
+    }
+
+    compose_keys = {(k.key, k.namespace, k.value) for k in app.artifacts["docker-compose.yml"].config_keys}
+    assert compose_keys == {
+        ("services.web.build", "yaml", "."),
+        ("services.web.environment.COMPOSE_ONLY_KEY", "yaml", "x"),
+        ("COMPOSE_ONLY_KEY", "env", "x"),  # dual-mint alongside the dotted yaml key
+    }
+    by = {k.key: k for k in app.artifacts["docker-compose.yml"].config_keys}
+    assert by["COMPOSE_ONLY_KEY"].id != by["services.web.environment.COMPOSE_ONLY_KEY"].id
+
+
 def test_config_uses_tier_visibility(tmp_path):
     """Verify config-use edges only appear at their appropriate tier (#162):
     monotonic growth AND that each tier's own shape is genuinely gated, not