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

Extends config-key extraction (#152) with the deployment-env class: Dockerfile
`ENV K=v` (multi-key, legacy space form, backslash continuations, quoted
values) mints namespace "env" so os.environ/os.getenv reads bind to it;
`ARG K[=default]` mints its own "dockerfile" namespace (build-time only, not
env-detector-bindable; no default -> value None). yaml artifacts get a
supplementary recognition pass over compose services.*.environment
(map/list) and k8s env[].name/.value shapes (matched at any nesting depth),
dual-minting namespace "env" keys alongside the plain dotted-path yaml ones.

No Neo4j catalog change needed (namespace/ConfigKey are data, not schema);
conformance tests re-verified green.

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

@@ -1,18 +1,51 @@
-"""Config-key flatteners (#152). Pure text-in/records-out, mirroring
+"""Config-key flatteners (#152, #165). Pure text-in/records-out, mirroring
 `artifacts/parsers.py`'s idiom: one dispatcher over per-format internals,
 never raising.
 
 Namespace dispatch: an env-family basename (`.env`, `.env.*`, `.flaskenv`)
 always wins, regardless of the artifact's declared `format`; otherwise the
-`format` field selects yaml/json/toml/ini/properties. Any other format
-extracts nothing (not a failure -- there's just nothing to flatten).
-
-Span precision differs by shape: env/properties/ini are line-oriented, so
-the parse itself knows the exact defining line. yaml/json/toml are
-tree-shaped -- span recovery falls back to a best-effort search for the
-final dotted-key segment on its own line (see `_find_key_span`), which can
-bind the wrong line when the same leaf name recurs at another nesting level,
-or find nothing at all (`span=None`) for a minified/single-line file.
+`format` field selects yaml/json/toml/ini/properties/dockerfile. Any other
+format extracts nothing (not a failure -- there's just nothing to flatten).
+
+Deployment-env namespaces (#165): a `dockerfile`-format artifact mints TWO
+namespaces from one file -- `ENV K=v` directives mint namespace `env` (the
+whole point is that `os.environ`/`os.getenv` reads, whose detector rule
+prefers namespace `env`, bind to them), `ARG K[=default]` directives mint
+namespace `dockerfile` (build-time only, deliberately not bindable by the
+env detectors). Both share the bare var name as `key`, so an `ARG X` later
+promoted via `ENV X=$X` -- a common idiom -- would collide on `id` (`key`
+alone determines it) if both used the plain id shape; the `dockerfile`
+mint's id is disambiguated with an internal `arg.` prefix (the `key` FIELD
+stays the bare name either way, since nothing about resolution or the
+issue's contract cares how the id looks).
+
+A `yaml`-format artifact ALSO gets a supplementary recognition pass after
+the normal dotted-path flattening: well-known compose (`services.<name>.
+environment` map/list) and k8s (`...env.<idx>.name`/`.value`, matched as a
+dotted-path shape at any nesting depth, not schema-anchored) shapes mint
+ADDITIONAL namespace-`env` keys keyed on the bare var name, alongside the
+normal namespace-`yaml` dotted-path ones -- dual-minting is intentional
+(so `os.environ`/`os.getenv` reads bind to compose/k8s-declared vars too),
+never deduped away. Ids never collide with the plain yaml mint: the env
+mint's key is always the bare var name while the yaml mint's key always
+carries the full dotted path, so the two differ by construction for every
+shape this pass recognizes. This pass is shape-based, not filename/role
+gated -- any yaml artifact whose content happens to match mints the extra
+keys, matching this module's general overlay posture (permissive, never a
+schema validator).
+
+Span precision differs by shape: env/properties/ini/dockerfile are
+line-oriented, so the parse itself knows the exact defining line. yaml/
+json/toml are tree-shaped -- span recovery falls back to a best-effort
+search for the final dotted-key segment on its own line (see
+`_find_key_span`), which can bind the wrong line when the same leaf name
+recurs at another nesting level, or find nothing at all (`span=None`) for
+a minified/single-line file. The compose/k8s env-recognition mint reuses
+this same best-effort search keyed on the bare var name: it finds the
+defining line for compose's map/list forms (`KEY:`/`KEY=` is the var's own
+line) but not k8s's name/value list shape (the var name is a VALUE on a
+`name:` line, not a key label there) -- k8s env-mint spans are `None`,
+an accepted extension of the existing best-effort gap.
 """
 from __future__ import annotations
 
@@ -94,9 +127,46 @@ def _parse_toml(text: str, lines: List[str]) -> List[_Entry]:
     return _flatten_structured(tomllib.loads(text), text, lines)
 
 
+# --- compose/k8s env recognition (#165): supplemental namespace="env" mint
+# over the SAME flattened (dotted_key, value) pairs the "yaml" namespace
+# uses -- see the module docstring for why dual-minting is safe and
+# intentional. Shape-matched on the dotted path string, not the yaml tree,
+# so both recognizers stay simple regex-over-strings, symmetric with the
+# rest of this module's line/path-oriented parsing. -------------------------
+
+_K8S_ENV_NAME = re.compile(r'(?:^|\.)env\.\d+\.name$')
+_COMPOSE_ENV = re.compile(r'^services\.[^.]+\.environment\.(.+)$')
+
+
+def _recognize_env_shapes(flat: List[Tuple[str, object]]) -> List[Tuple[str, object]]:
+    """`(key, value)` pairs for every compose/k8s env shape found in `flat`
+    (the same `_flatten(data)` pairs the "yaml" namespace flattens) --
+    NOT dotted paths, the bare var name, matching `env` namespace semantics
+    (`config_use.py` resolves that namespace by exact `key ==` match)."""
+    by_path = dict(flat)
+    out: List[Tuple[str, object]] = []
+    for dotted_key, value in flat:
+        if _K8S_ENV_NAME.search(dotted_key):
+            sibling = dotted_key[: -len("name")] + "value"  # ...env.<idx>.value
+            out.append((_stringify(value), by_path.get(sibling)))
+            continue
+        m = _COMPOSE_ENV.match(dotted_key)
+        if not m:
+            continue
+        tail = m.group(1)
+        if _ENV_KEY_NAME.match(tail):  # map form: tail IS the var name
+            out.append((tail, value))
+        elif tail.isdigit():  # list form: leaf is "KEY=val" or bare "KEY"
+            key, sep, val = _stringify(value).partition("=")
+            if _ENV_KEY_NAME.match(key):
+                out.append((key, val if sep else None))
+    return out
+
+
 # --- env: KEY=value, `#` comments, `export ` prefix, quote stripping -------
 
 _ENV_LINE = re.compile(r'^(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*)$')
+_ENV_KEY_NAME = re.compile(r'^[A-Za-z_][A-Za-z0-9_]*$')  # shared: dockerfile + compose/k8s recognition
 
 
 def _env_value(raw: str) -> str:
@@ -133,6 +203,116 @@ def _parse_env(text: str, lines: List[str]) -> List[_Entry]:
     return out
 
 
+# --- dockerfile: `ENV`/`ARG` directives (#165). Line-based, case-insensitive
+# instruction keywords (Dockerfile convention is uppercase, the spec itself
+# is not case-sensitive); no BuildKit heredoc awareness in v1 -- a heredoc
+# body line is just another line that doesn't match `_DOCKER_ENV`/`_DOCKER_ARG`
+# and is silently skipped, same as any other unparseable line (overlay
+# posture). Multi-stage `FROM ... AS x` scoping is not modeled -- every
+# ENV/ARG in the file is scanned regardless of which stage it's in. --------
+
+_DOCKER_ENV = re.compile(r'^ENV\s+(.*)$', re.IGNORECASE)
+_DOCKER_ARG = re.compile(r'^ARG\s+(.*)$', re.IGNORECASE)
+
+
+def _join_continuations(lines: List[str], start_i: int) -> Tuple[str, int]:
+    """From `lines[start_i]`, join any backslash-continued following lines
+    into one logical instruction line -- same trailing-backslash-drop +
+    leading/trailing-whitespace-strip join `_parse_properties` already uses
+    for its own continuations. Returns `(joined_text, index of the LAST
+    line consumed)`."""
+    i, n = start_i, len(lines)
+    parts = [lines[i].strip()]
+    while parts[-1].endswith("\\") and i + 1 < n:
+        parts[-1] = parts[-1][:-1]  # drop just the continuation backslash
+        i += 1
+        parts.append(lines[i].strip())
+    return "".join(parts), i
+
+
+def _split_ws_respecting_quotes(s: str) -> List[str]:
+    """Whitespace-split `s`, except inside a matching `'`/`"` span (a quoted
+    value may contain spaces) -- quote characters stay IN the returned
+    tokens, stripped afterward by `_env_value` so there is one quote-
+    stripping implementation, not two."""
+    tokens: List[str] = []
+    buf: List[str] = []
+    quote: Optional[str] = None
+    for ch in s:
+        if quote:
+            buf.append(ch)
+            if ch == quote:
+                quote = None
+        elif ch in "'\"":
+            quote = ch
+            buf.append(ch)
+        elif ch.isspace():
+            if buf:
+                tokens.append("".join(buf))
+                buf = []
+        else:
+            buf.append(ch)
+    if buf:
+        tokens.append("".join(buf))
+    return tokens
+
+
+def _dockerfile_env_entries(text: str, lines: List[str]) -> List[_Entry]:
+    """`ENV` directives -> `(KEY, value, span)`. Handles `ENV K=v`, multi-key
+    `ENV a=1 b=2`, and the legacy single-key `ENV K v` space form (Docker's
+    own disambiguation rule: the token right after `ENV` decides the form --
+    a `=` in it means one-or-more `key=value` pairs; no `=` means the
+    legacy form, where the key is the first word and the REST of the line,
+    verbatim, is the value)."""
+    out: List[_Entry] = []
+    i, n = 0, len(lines)
+    while i < n:
+        stripped = lines[i].strip()
+        if not stripped or stripped.startswith("#") or not _DOCKER_ENV.match(stripped):
+            i += 1
+            continue
+        start_lineno = i + 1
+        joined, i = _join_continuations(lines, i)
+        rest = _DOCKER_ENV.match(joined).group(1).strip()
+        span = _line_span(text, lines, start_lineno)
+        first_token = rest.split(None, 1)[0] if rest else ""
+        if "=" in first_token:
+            for tok in _split_ws_respecting_quotes(rest):
+                key, sep, raw_val = tok.partition("=")
+                if sep and _ENV_KEY_NAME.match(key):
+                    out.append((key, _env_value(raw_val), span))
+        else:
+            key, sep, raw_val = rest.partition(" ")
+            if sep and _ENV_KEY_NAME.match(key):
+                out.append((key, _env_value(raw_val.strip()), span))
+        i += 1
+    return out
+
+
+def _dockerfile_arg_entries(text: str, lines: List[str]) -> List[_Entry]:
+    """`ARG KEY[=default]` -> `(KEY, value, span)`; no `=default` means
+    `value=None` (#165's ARG semantics -- distinct from `_stringify`'s "" for
+    a modeled null elsewhere in this module: an ARG default that is simply
+    ABSENT is not the same fact as a key explicitly set to an empty value)."""
+    out: List[_Entry] = []
+    i, n = 0, len(lines)
+    while i < n:
+        stripped = lines[i].strip()
+        if not stripped or stripped.startswith("#") or not _DOCKER_ARG.match(stripped):
+            i += 1
+            continue
+        start_lineno = i + 1
+        joined, i = _join_continuations(lines, i)
+        rest = _DOCKER_ARG.match(joined).group(1).strip()
+        span = _line_span(text, lines, start_lineno)
+        key, sep, raw_default = rest.partition("=")
+        key = key.strip()
+        if _ENV_KEY_NAME.match(key):
+            out.append((key, _env_value(raw_default) if sep else None, span))
+        i += 1
+    return out
+
+
 # --- properties: key=value / key: value, `\` continuations, `!`/`#` comments
 
 _PROPS_KV = re.compile(r'^(?P<key>[^=:\s]+)\s*[:=]\s*(?P<value>.*)$')
@@ -259,16 +439,50 @@ def _stringify(value: object) -> str:
     return str(value)
 
 
+def _build_keys(
+    artifact_id: str, namespace: str, entries: List[_Entry], capture_value: bool,
+    *, raw_value: bool = False, id_key: Optional[Callable[[str], str]] = None,
+) -> List[PyConfigKey]:
+    """Coalesce `entries` (last dotted-key occurrence in file order wins --
+    the existing L1 duplicate-key precedent, e.g. a redefined env var) into
+    `PyConfigKey` records for one namespace.
+
+    `raw_value=True` (dockerfile) passes the parsed value straight through
+    instead of `_stringify`-ing it, so an ARG's absent default surfaces as
+    `value=None` rather than `_stringify`'s "" for a modeled null -- dockerfile
+    values are already plain parsed text/`None`, never a yaml/json/toml
+    bool/None that needs that coercion.
+
+    `id_key` remaps `dotted_key` for ID CONSTRUCTION only -- the `.key` FIELD
+    always stays the bare `dotted_key`. Used solely so a Dockerfile ARG's id
+    can't collide with an ENV of the same name minting the same bare-name id
+    in the "env" namespace (`ARG X` then `ENV X=$X` is a common promotion
+    idiom); every other namespace omits it, preserving today's id shape."""
+    coalesced: Dict[str, Tuple[object, Optional[Span]]] = {}
+    for dotted_key, value, span in entries:
+        coalesced[dotted_key] = (value, span)
+    keys = []
+    for dotted_key, (value, span) in coalesced.items():
+        text_value = value if raw_value else _stringify(value)
+        keys.append(PyConfigKey(
+            id=config_key_id(artifact_id, id_key(dotted_key) if id_key else dotted_key),
+            key=dotted_key, namespace=namespace,
+            value=text_value if capture_value else None,
+            span=span, references=_find_references(text_value or ""),
+        ))
+    return keys
+
+
 # --- public API -----------------------------------------------------------
 
 def is_config_eligible(artifact: PyArtifact) -> bool:
     """Whether `artifact` is worth extracting config keys from: an env-family
-    basename (`.env`/`.env.*`/`.flaskenv`, regardless of declared format), or
-    a namespace-bearing format (yaml/json/toml/ini/properties). A binary
-    artifact is never eligible -- there is no decodable text to flatten, and
-    a rule-matched-but-undecodable file downgrades to `format="binary"`
-    regardless of its basename (see discovery.py), so the binary check wins
-    even over an env-family name.
+    basename (`.env`/`.env.*`/`.flaskenv`, regardless of declared format), a
+    `dockerfile`-format artifact (#165), or a namespace-bearing format
+    (yaml/json/toml/ini/properties). A binary artifact is never eligible --
+    there is no decodable text to flatten, and a rule-matched-but-undecodable
+    file downgrades to `format="binary"` regardless of its basename (see
+    discovery.py), so the binary check wins even over an env-family name.
 
     Callers (core.py's wiring) use this to skip the on-disk read + parse
     attempt entirely on artifacts that can never yield config keys, rather
@@ -277,7 +491,11 @@ def is_config_eligible(artifact: PyArtifact) -> bool:
     if artifact.format == "binary":
         return False
     basename = artifact.path.rsplit("/", 1)[-1]
-    return _is_env_family(basename) or artifact.format in _NAMESPACE_PARSERS
+    return (
+        _is_env_family(basename)
+        or artifact.format == "dockerfile"
+        or artifact.format in _NAMESPACE_PARSERS
+    )
 
 
 def extract_config_keys(
@@ -294,39 +512,46 @@ def extract_config_keys(
     `False` only when parsing raised. Never raises: every code path below is
     covered by one `try`/`except`, so a malformed file degrades to `([],
     False)` instead of an exception escaping to the caller. `keys` is always
-    sorted by `key` (L1 determinism).
+    sorted by `key` (L1 determinism) -- a dockerfile or dual-minted yaml
+    artifact concatenates its namespace groups before this one sort, and
+    Python's sort is stable, so a same-`key` tie across namespaces still
+    resolves deterministically (env before dockerfile; yaml before env).
 
     `value` is populated only when `capture_value` is True; `key`,
     `namespace`, `span`, and `references` are extracted unconditionally
     either way (references are recognized in the raw leaf value regardless
     of whether that value is exposed)."""
     basename = artifact.path.rsplit("/", 1)[-1]
-    if _is_env_family(basename):
-        namespace, parser = "env", _parse_env
-    else:
-        parser = _NAMESPACE_PARSERS.get(artifact.format)
-        if parser is None:
-            return [], True
-        namespace = artifact.format
-
     try:
         lines = full_text.splitlines()
-        entries = parser(full_text, lines)
-        # Last occurrence wins on a duplicate dotted key (env/properties can
-        # legally redefine a key later in the file; a repeat would otherwise
-        # collide on `id`, which is derived from `key` alone).
-        coalesced: Dict[str, Tuple[object, Optional[Span]]] = {}
-        for dotted_key, value, span in entries:
-            coalesced[dotted_key] = (value, span)
-        keys = [
-            PyConfigKey(
-                id=config_key_id(artifact.id, dotted_key), key=dotted_key,
-                namespace=namespace,
-                value=_stringify(value) if capture_value else None,
-                span=span, references=_find_references(_stringify(value)),
+        if _is_env_family(basename):
+            keys = _build_keys(artifact.id, "env", _parse_env(full_text, lines), capture_value)
+        elif artifact.format == "dockerfile":
+            keys = _build_keys(
+                artifact.id, "env", _dockerfile_env_entries(full_text, lines), capture_value,
+                raw_value=True,
+            ) + _build_keys(
+                artifact.id, "dockerfile", _dockerfile_arg_entries(full_text, lines), capture_value,
+                raw_value=True, id_key=lambda k: f"arg.{k}",
+            )
+        elif artifact.format == "yaml":
+            # Two independent parses (like every other format here -- each
+            # piece parses what IT needs, no shared-state shortcut): `_parse_
+            # yaml` for the plain dotted-path entries, a second `safe_load`
+            # for the raw tree the env-shape recognizer walks.
+            flat = list(_flatten(yaml.safe_load(full_text) or {}))
+            env_entries = [
+                (k, v, _find_key_span(full_text, lines, k)) for k, v in _recognize_env_shapes(flat)
+            ]
+            keys = (
+                _build_keys(artifact.id, "yaml", _parse_yaml(full_text, lines), capture_value)
+                + _build_keys(artifact.id, "env", env_entries, capture_value)
             )
-            for dotted_key, (value, span) in coalesced.items()
-        ]
+        else:
+            parser = _NAMESPACE_PARSERS.get(artifact.format)
+            if parser is None:
+                return [], True
+            keys = _build_keys(artifact.id, artifact.format, parser(full_text, lines), capture_value)
         keys.sort(key=lambda k: k.key)
         return keys, True
     except Exception:

codeanalyzer/schema/py_schema.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