envshield 4.6.2__tar.gz → 4.7.0__tar.gz

{envshield-4.6.2 → envshield-4.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: envshield
-Version: 4.6.2
+Version: 4.7.0
 Summary: EnvShield: environment variables as a version-controlled configuration contract.
 Author-email: Rabbil Yasar Sajal <rabbilyasar@gmail.com>
 License: MIT License
@@ -100,9 +100,11 @@ env.schema.toml
 ## Quick Start
 
 ```bash
-pip install envshield
+pipx install envshield
 ```
 
+Prefer an existing Python/pip workflow instead? `pip install envshield` works the same way, as an alternative.
+
 In an existing project:
 
 ```bash
@@ -299,7 +301,7 @@ jobs:
     steps:
       - uses: actions/checkout@v4
         with: { fetch-depth: 0 }
-      - run: pip install envshield
+      - run: pipx install envshield
       - run: |
           BASE=$(git merge-base "origin/${{ github.base_ref }}" HEAD)
           envshield schema diff "$BASE" HEAD
@@ -353,12 +355,67 @@ envshield check --service api
 
 Every command is service-aware. `--service` is optional with exactly one service configured, inferred automatically when you're standing inside a registered service's own directory, and only prompted for interactively when there's more than one and neither applies.
 
+### Discovering reads in a shared library (`additional_source_roots`)
+
+`undeclared` and `explain` only walk a service's own directory by default. If part of a service's real configuration is read from a shared internal library that lives outside that directory — a common-utilities package imported by several services, say — those reads are invisible to both commands, for every service that imports the library.
+
+`additional_source_roots` widens a service's discovery scope to cover extra directories:
+
+```yaml
+services:
+  api:
+    schema: services/api/env.schema.toml
+    additional_source_roots:
+      - libs/shared
+```
+
+`undeclared --service api` and `explain --service api` now also look inside `libs/shared` — a variable read there counts toward `api`'s own discovery results exactly as if it lived in `services/api/` itself. The same directory can be listed by more than one service; each one independently sees the reads it contains. A path that doesn't exist yet contributes nothing (no error); a path resolving outside the project is refused, the same protection every other path in `envshield.yml` already has. `scan` is unaffected — it's already repository-wide.
+
+---
+
+## Multiple sources per service (`completeness: union`)
+
+By default, every registered source for a service — its `local_file`, each registered deployment manifest — is validated independently against the *whole* schema: `check`/`doctor` expect any one of them to be self-sufficient on its own. Some services genuinely don't work that way: part of the configuration lives in a local config file, the rest is supplied by a deployment manifest. Under the default model, a variable that only ever lives in one of them shows up as "missing" everywhere else, even though nothing is actually wrong.
+
+Set `completeness: union` on a service to validate against the *combined* presence of all its registered sources instead — a variable satisfied by any one of them satisfies the service as a whole:
+
+```yaml
+services:
+  api:
+    schema: services/api/env.schema.toml
+    local_file: services/api/config/settings.py
+    completeness: union
+manifests:
+  - file: docker-compose.yml
+    containers:
+      api: api
+```
+
+```toml
+[DB_HOST]
+description = "set in config/settings.py"
+
+[FEATURE_MODE]
+description = "set via docker-compose.yml"
+```
+
+With `completeness: union`, `check`/`doctor` stop expecting `config/settings.py` to declare `FEATURE_MODE`, or `docker-compose.yml` to set `DB_HOST` — the schema is satisfied as long as every variable is present *somewhere* among the registered sources. `envshield schema sync` respects this too: it only ever appends a variable to a Python `local_file` that's genuinely missing from every registered source, never one that another source already covers.
+
+A few things worth knowing:
+
+- **Opt-in, per service.** Unset (the default) means every source must be independently self-sufficient, exactly as before this existed — nothing changes unless you set the key.
+- **Union means presence, not values.** Whether an ordinary variable is satisfied depends only on whether it's present (and valid) somewhere — never on merging, comparing, or picking between its values across sources. A blank or invalid value is still reported, wherever it occurs. **The one deliberate exception** is a `requiredIf` trigger's own value (see next) — deciding whether a condition currently holds has always meant reading one specific value, even before `completeness: union` existed; union only extends *where* that one value may come from, it doesn't turn this into general value merging.
+- **A `requiredIf` condition (see [Conditional requirements](#conditional-requirements-requiredif) above) is resolved against the union too** — if the variable a condition depends on lives in a different source than the one being checked, `completeness: union` still finds it. Sources that agree on the trigger's value resolve normally; if two sources genuinely disagree, EnvShield reports it as an explicit conflict rather than guessing which one wins — registration order is never used as a tiebreaker.
+- **A source that fails to load is always a failure**, even if the sources that did load happen to satisfy the schema between them. `doctor` reports this as two separate signals for a union-mode service — source health (does this file exist and parse) and registered-source completeness (does the union satisfy the schema) — so one can never quietly hide behind the other. `check --json` reflects the same split: each source's own result is still reported individually, plus one `combined` entry per union-mode service carrying the aggregate verdict.
+
 ---
 
 ## Supported languages / discovery
 
 Source-code discovery (what powers `undeclared` and `explain`'s "used in source" section) is AST-based for **Python** (`os.environ.get`, `os.getenv`, `os.environ[...]`) and pattern-based for **JavaScript/TypeScript** (`process.env.X`, `process.env["X"]`, `import.meta.env.X`, including single-level destructuring). No other language is discovered yet — the schema and validation commands work with any stack, but `undeclared`/`explain` can only see what's read from these two.
 
+`explain` additionally recognizes Flask's `current_app.config[...]`/`.get(...)` in Python — including the common `from flask import current_app as <alias>` import form — and reports it at **medium confidence**, shown inline as `(medium confidence)`: it's one level of indirection through a config object whose contents could come from anywhere, not a direct environment read. This recognition is deliberately `explain`-only — it never affects `undeclared`'s or `scan`'s pass/fail signal, so a Flask-config read can never quietly satisfy (or break) a completeness check the way a direct `os.environ`/`os.getenv` read does.
+
 ---
 
 ## Secret safety
@@ -374,8 +431,8 @@ A supporting check alongside the contract, not the product itself. `secret = tru
 
 EnvShield is built around the patterns real projects actually use. A few narrower cases aren't handled yet — none of them let a secret leak or let a genuinely missing required variable pass as clean:
 
-- **Docker Compose:** `${VAR}` and `${VAR:-default}` are supported. The no-colon `${VAR-default}` form, the `${VAR:?}`/`${VAR:+}` forms, and embedded/multiple interpolation references in one value aren't evaluated yet.
-- **Kubernetes:** `secretKeyRef`/`configMapKeyRef` are matched by the container's environment-variable name (`env[].name`), not the referenced Secret/ConfigMap's internal key — name your schema variable after the env var, not the key. `envFrom.prefix` isn't applied yet.
+- **Docker Compose:** `${VAR}`, `${VAR:-default}`, and the no-colon `${VAR-default}` form are all supported. The `${VAR:?}`/`${VAR:+}` forms and embedded/multiple interpolation references in one value aren't evaluated yet.
+- **Kubernetes:** `env[].valueFrom.secretKeyRef`/`configMapKeyRef` are matched by the container's environment-variable name (`env[].name`) — name your schema variable after the env var, not the key — and, when the referenced Secret/ConfigMap is defined in the same manifest, the referenced key is validated to actually exist there. `envFrom.prefix` is applied. `initContainers` are selectable via `--container` but never auto-selected by default.
 - **Source discovery:** Python is AST-based; JavaScript/TypeScript is pattern-based. No other language is discovered yet.
 - **.env:** multiline quoted values aren't supported.
 

{envshield-4.6.2 → envshield-4.7.0}/README.md

@@ -41,9 +41,11 @@ env.schema.toml
 ## Quick Start
 
 ```bash
-pip install envshield
+pipx install envshield
 ```
 
+Prefer an existing Python/pip workflow instead? `pip install envshield` works the same way, as an alternative.
+
 In an existing project:
 
 ```bash
@@ -240,7 +242,7 @@ jobs:
     steps:
       - uses: actions/checkout@v4
         with: { fetch-depth: 0 }
-      - run: pip install envshield
+      - run: pipx install envshield
       - run: |
           BASE=$(git merge-base "origin/${{ github.base_ref }}" HEAD)
           envshield schema diff "$BASE" HEAD
@@ -294,12 +296,67 @@ envshield check --service api
 
 Every command is service-aware. `--service` is optional with exactly one service configured, inferred automatically when you're standing inside a registered service's own directory, and only prompted for interactively when there's more than one and neither applies.
 
+### Discovering reads in a shared library (`additional_source_roots`)
+
+`undeclared` and `explain` only walk a service's own directory by default. If part of a service's real configuration is read from a shared internal library that lives outside that directory — a common-utilities package imported by several services, say — those reads are invisible to both commands, for every service that imports the library.
+
+`additional_source_roots` widens a service's discovery scope to cover extra directories:
+
+```yaml
+services:
+  api:
+    schema: services/api/env.schema.toml
+    additional_source_roots:
+      - libs/shared
+```
+
+`undeclared --service api` and `explain --service api` now also look inside `libs/shared` — a variable read there counts toward `api`'s own discovery results exactly as if it lived in `services/api/` itself. The same directory can be listed by more than one service; each one independently sees the reads it contains. A path that doesn't exist yet contributes nothing (no error); a path resolving outside the project is refused, the same protection every other path in `envshield.yml` already has. `scan` is unaffected — it's already repository-wide.
+
+---
+
+## Multiple sources per service (`completeness: union`)
+
+By default, every registered source for a service — its `local_file`, each registered deployment manifest — is validated independently against the *whole* schema: `check`/`doctor` expect any one of them to be self-sufficient on its own. Some services genuinely don't work that way: part of the configuration lives in a local config file, the rest is supplied by a deployment manifest. Under the default model, a variable that only ever lives in one of them shows up as "missing" everywhere else, even though nothing is actually wrong.
+
+Set `completeness: union` on a service to validate against the *combined* presence of all its registered sources instead — a variable satisfied by any one of them satisfies the service as a whole:
+
+```yaml
+services:
+  api:
+    schema: services/api/env.schema.toml
+    local_file: services/api/config/settings.py
+    completeness: union
+manifests:
+  - file: docker-compose.yml
+    containers:
+      api: api
+```
+
+```toml
+[DB_HOST]
+description = "set in config/settings.py"
+
+[FEATURE_MODE]
+description = "set via docker-compose.yml"
+```
+
+With `completeness: union`, `check`/`doctor` stop expecting `config/settings.py` to declare `FEATURE_MODE`, or `docker-compose.yml` to set `DB_HOST` — the schema is satisfied as long as every variable is present *somewhere* among the registered sources. `envshield schema sync` respects this too: it only ever appends a variable to a Python `local_file` that's genuinely missing from every registered source, never one that another source already covers.
+
+A few things worth knowing:
+
+- **Opt-in, per service.** Unset (the default) means every source must be independently self-sufficient, exactly as before this existed — nothing changes unless you set the key.
+- **Union means presence, not values.** Whether an ordinary variable is satisfied depends only on whether it's present (and valid) somewhere — never on merging, comparing, or picking between its values across sources. A blank or invalid value is still reported, wherever it occurs. **The one deliberate exception** is a `requiredIf` trigger's own value (see next) — deciding whether a condition currently holds has always meant reading one specific value, even before `completeness: union` existed; union only extends *where* that one value may come from, it doesn't turn this into general value merging.
+- **A `requiredIf` condition (see [Conditional requirements](#conditional-requirements-requiredif) above) is resolved against the union too** — if the variable a condition depends on lives in a different source than the one being checked, `completeness: union` still finds it. Sources that agree on the trigger's value resolve normally; if two sources genuinely disagree, EnvShield reports it as an explicit conflict rather than guessing which one wins — registration order is never used as a tiebreaker.
+- **A source that fails to load is always a failure**, even if the sources that did load happen to satisfy the schema between them. `doctor` reports this as two separate signals for a union-mode service — source health (does this file exist and parse) and registered-source completeness (does the union satisfy the schema) — so one can never quietly hide behind the other. `check --json` reflects the same split: each source's own result is still reported individually, plus one `combined` entry per union-mode service carrying the aggregate verdict.
+
 ---
 
 ## Supported languages / discovery
 
 Source-code discovery (what powers `undeclared` and `explain`'s "used in source" section) is AST-based for **Python** (`os.environ.get`, `os.getenv`, `os.environ[...]`) and pattern-based for **JavaScript/TypeScript** (`process.env.X`, `process.env["X"]`, `import.meta.env.X`, including single-level destructuring). No other language is discovered yet — the schema and validation commands work with any stack, but `undeclared`/`explain` can only see what's read from these two.
 
+`explain` additionally recognizes Flask's `current_app.config[...]`/`.get(...)` in Python — including the common `from flask import current_app as <alias>` import form — and reports it at **medium confidence**, shown inline as `(medium confidence)`: it's one level of indirection through a config object whose contents could come from anywhere, not a direct environment read. This recognition is deliberately `explain`-only — it never affects `undeclared`'s or `scan`'s pass/fail signal, so a Flask-config read can never quietly satisfy (or break) a completeness check the way a direct `os.environ`/`os.getenv` read does.
+
 ---
 
 ## Secret safety
@@ -315,8 +372,8 @@ A supporting check alongside the contract, not the product itself. `secret = tru
 
 EnvShield is built around the patterns real projects actually use. A few narrower cases aren't handled yet — none of them let a secret leak or let a genuinely missing required variable pass as clean:
 
-- **Docker Compose:** `${VAR}` and `${VAR:-default}` are supported. The no-colon `${VAR-default}` form, the `${VAR:?}`/`${VAR:+}` forms, and embedded/multiple interpolation references in one value aren't evaluated yet.
-- **Kubernetes:** `secretKeyRef`/`configMapKeyRef` are matched by the container's environment-variable name (`env[].name`), not the referenced Secret/ConfigMap's internal key — name your schema variable after the env var, not the key. `envFrom.prefix` isn't applied yet.
+- **Docker Compose:** `${VAR}`, `${VAR:-default}`, and the no-colon `${VAR-default}` form are all supported. The `${VAR:?}`/`${VAR:+}` forms and embedded/multiple interpolation references in one value aren't evaluated yet.
+- **Kubernetes:** `env[].valueFrom.secretKeyRef`/`configMapKeyRef` are matched by the container's environment-variable name (`env[].name`) — name your schema variable after the env var, not the key — and, when the referenced Secret/ConfigMap is defined in the same manifest, the referenced key is validated to actually exist there. `envFrom.prefix` is applied. `initContainers` are selectable via `--container` but never auto-selected by default.
 - **Source discovery:** Python is AST-based; JavaScript/TypeScript is pattern-based. No other language is discovered yet.
 - **.env:** multiline quoted values aren't supported.
 

envshield-4.7.0/envshield/__init__.py

@@ -0,0 +1 @@
+__version__ = "4.7.0"

{envshield-4.6.2 → envshield-4.7.0}/envshield/cli.py

@@ -30,7 +30,11 @@ from .core import (
     service_manager,
     setup_manager,
 )
-from .core.exceptions import EnvShieldException, SchemaNotFoundError
+from .core.exceptions import (
+    EnvShieldException,
+    SchemaNotFoundError,
+    VariableNotFoundError,
+)
 from .utils import git_utils
 
 
@@ -134,6 +138,52 @@ def _print_service_header(targets: List[str], target: str) -> None:
         console.print(f"\n[bold underline]── {target} ──[/bold underline]")
 
 
+def _print_union_completeness_summary(
+    service_name: str,
+    union_result: "schema_manager.UnionCompletenessResult",
+    source_errors: List[str],
+) -> None:
+    """
+    `check`'s Rich-output counterpart to each source's own individual diff
+    table above it -- explains *why* a target with one or more
+    individually-incomplete-looking source tables can still exit 0 (or
+    still fail, for a reason none of those tables show on their own, like
+    a cross-source requiredIf ambiguity or a source that failed to load).
+    """
+    console.print(
+        f"\n[bold]Registered-source completeness ({service_name}, completeness: union)[/bold]"
+    )
+    for error in source_errors:
+        console.print(f"  [bold red]✗[/bold red] Source error: {error}")
+    if union_result.is_clean and not source_errors:
+        console.print(
+            "  [bold green]✓ Satisfied by the union of registered sources.[/bold green]"
+        )
+        return
+    if union_result.missing:
+        console.print(
+            "  [red]Missing from every registered source:[/red] "
+            f"{', '.join(sorted(union_result.missing))}"
+        )
+    if union_result.blank:
+        console.print(
+            "  [red]Blank everywhere it's declared:[/red] "
+            f"{', '.join(sorted(union_result.blank))}"
+        )
+    if union_result.invalid:
+        details = "; ".join(
+            f"{k} ({v})" for k, v in sorted(union_result.invalid.items())
+        )
+        console.print(f"  [red]Invalid:[/red] {details}")
+    if union_result.unresolved:
+        console.print(
+            "  [yellow]Cannot confirm (a registered source has an unresolved "
+            f"external reference):[/yellow] {', '.join(sorted(union_result.unresolved))}"
+        )
+    for key, reason in sorted(union_result.ambiguous_requiredif.items()):
+        console.print(f"  [red]Ambiguous ({key}):[/red] {reason}")
+
+
 # --- Commands ---
 @app.command()
 def init(
@@ -438,9 +488,18 @@ def check(
 
     had_error = False
     results = []
+    combined: Dict[str, Any] = {}
     for target in targets:
         if not json_output:
             _print_service_header(targets, target)
+        # completeness: union (BL-030) is opt-in per service and only
+        # applies to the service's own default source set -- an explicit
+        # `file` argument means the user asked for exactly that one file,
+        # which is unaffected by (and skips) union evaluation entirely,
+        # same as it already skips registered manifests below.
+        is_union = (
+            not file and config_manager.get_service_completeness_mode(target) == "union"
+        )
         try:
             resolved_file = (
                 file or config_manager.get_env_paths(service_name=target)["local_file"]
@@ -450,12 +509,13 @@ def check(
                     resolved_file, service_name=target, container=container
                 )
                 results.append(result)
-                if not result["clean"]:
+                if not is_union and not result["clean"]:
                     had_error = True
             elif not schema_manager.check_schema(
                 resolved_file, service_name=target, container=container
             ):
-                had_error = True
+                if not is_union:
+                    had_error = True
 
             # An explicit file argument means the user asked for exactly
             # that file, and nothing else -- only pile on registered
@@ -473,14 +533,42 @@ def check(
                             container=manifest_container,
                         )
                         results.append(result)
-                        if not result["clean"]:
+                        if not is_union and not result["clean"]:
                             had_error = True
                     elif not schema_manager.check_schema(
                         manifest["path"],
                         service_name=target,
                         container=manifest_container,
                     ):
-                        had_error = True
+                        if not is_union:
+                            had_error = True
+
+            # completeness: union's own aggregate verdict, computed
+            # separately from (and never replacing) the per-source diffs
+            # above -- those keep reporting each source's own individual
+            # gaps for visibility; this decides whether the TARGET as a
+            # whole passes. A source that failed to load here is always a
+            # failure, independent of whether the sources that DID load
+            # happen to satisfy the schema between them (BL-030's explicit
+            # source-health requirement).
+            if is_union:
+                schema = config_manager.load_schema(service_name=target)
+                sources, source_errors = schema_manager.load_union_sources(
+                    target, container=container
+                )
+                union_result = schema_manager.evaluate_union_completeness(
+                    schema, sources
+                )
+                if source_errors or not union_result.is_clean:
+                    had_error = True
+                if json_output:
+                    combined[target] = schema_manager.union_completeness_result_to_dict(
+                        union_result, source_errors=source_errors
+                    )
+                else:
+                    _print_union_completeness_summary(
+                        target, union_result, source_errors
+                    )
         except EnvShieldException as e:
             if json_output:
                 results.append({"service": target, "clean": False, "error": str(e)})
@@ -489,7 +577,10 @@ def check(
             had_error = True
 
     if json_output:
-        print(json.dumps({"success": not had_error, "results": results}, indent=2))
+        payload: Dict[str, Any] = {"success": not had_error, "results": results}
+        if combined:
+            payload["combined"] = combined
+        print(json.dumps(payload, indent=2))
 
     if had_error:
         raise typer.Exit(code=1)
@@ -572,6 +663,100 @@ _EXPLAIN_REQUIREDNESS_LABEL = {
 }
 
 
+def _render_source_usages(
+    source_usages: List["explain.discovery.DiscoveredVariableUsage"],
+) -> None:
+    """Shared between the declared-variable report and the undeclared one -- the exact same section, so the two commands' output stays visually consistent."""
+    console.print("\n[bold]Used in source[/bold]")
+    if source_usages:
+        for usage in source_usages:
+            line = f"  {usage.file_path}:{usage.line}"
+            if usage.confidence != "high":
+                # BL-113: a Flask current_app.config[...] read is one level
+                # of indirection through an object whose contents came from
+                # somewhere unspecified -- never as certain as a direct
+                # os.environ/os.getenv read, and this must stay visible at
+                # the point of reading, not just in --json's confidence field.
+                line += f" [dim]({usage.confidence} confidence)[/dim]"
+            console.print(line)
+    else:
+        console.print("  None discovered")
+        console.print(
+            "  [dim]EnvShield only recognizes os.environ/os.getenv/process.env-style "
+            "reads in Python and JS/TS -- this doesn't prove the variable is unused.[/dim]"
+        )
+
+
+def _render_manifest_references(
+    manifest_references: List["explain.ManifestReference"], variable: str
+) -> None:
+    """Shared between the declared-variable report and the undeclared one."""
+    console.print("\n[bold]Deployment[/bold]")
+    if not manifest_references:
+        console.print("  No deployment manifest registered for this service.")
+        return
+
+    declared = [r for r in manifest_references if r.status == "declared"]
+    not_declared = [r for r in manifest_references if r.status == "not_declared"]
+    unresolved = [r for r in manifest_references if r.status == "unresolved"]
+    errored = [r for r in manifest_references if r.status == "error"]
+    if declared:
+        for ref in declared:
+            console.print(f"  {ref.path}")
+            if ref.container:
+                console.print(f"    container: {ref.container}")
+    elif not_declared:
+        # Only claim "not found" when at least one manifest positively
+        # doesn't declare it -- printing this alongside "Cannot confirm"
+        # below (when every non-declared reference is actually unresolved)
+        # would read as EnvShield confidently asserting absence in the
+        # same breath it admits it can't tell.
+        checked = ", ".join(r.path for r in manifest_references)
+        console.print(
+            "  Not found in any registered deployment manifest "
+            f"(checked: {checked}) -- this doesn't prove it isn't deployed elsewhere."
+        )
+    if unresolved:
+        console.print(
+            f"  [yellow]Cannot confirm for {len(unresolved)} manifest(s): "
+            f"{', '.join(r.path for r in unresolved)} -- references an external "
+            f"ConfigMap/Secret not included in the manifest; '{variable}' "
+            "may be supplied from there.[/yellow]"
+        )
+    if errored:
+        console.print(
+            f"  [dim]Could not check {len(errored)} manifest(s): "
+            f"{', '.join(r.path for r in errored)}[/dim]"
+        )
+
+
+def _render_undeclared_explain_report(
+    report: "explain.UndeclaredVariableReport",
+) -> None:
+    """
+    'explain' on a variable that isn't in the schema yet -- degrades
+    gracefully instead of only erroring, reusing the exact same
+    source-usage/manifest-reference rendering a declared variable's report
+    uses, so a developer investigating something 'undeclared'/'scan' just
+    found gets the same evidence, framed as "not declared yet" rather than
+    a bare error.
+    """
+    console.print(f"\n[bold cyan]{report.variable}[/bold cyan]")
+    console.print("─" * max(len(report.variable), 8))
+    console.print(
+        f"\n[yellow]Not declared in the schema for service '{report.service}'.[/yellow]"
+    )
+
+    _render_source_usages(report.source_usages)
+    _render_manifest_references(report.manifest_references, report.variable)
+
+    if report.source_usages:
+        console.print(
+            "\n[dim]Add it to the schema once you know what it should require -- "
+            "see the file/line above for where it's read.[/dim]"
+        )
+
+
 def _render_explain_report(report: "explain.ExplainReport") -> None:
     console.print(f"\n[bold cyan]{report.variable}[/bold cyan]")
     console.print("─" * max(len(report.variable), 8))
@@ -607,16 +792,7 @@ def _render_explain_report(report: "explain.ExplainReport") -> None:
             "  [dim](could not determine whether this is inherited via extends)[/dim]"
         )
 
-    console.print("\n[bold]Used in source[/bold]")
-    if report.source_usages:
-        for usage in report.source_usages:
-            console.print(f"  {usage.file_path}:{usage.line}")
-    else:
-        console.print("  None discovered")
-        console.print(
-            "  [dim]EnvShield only recognizes os.environ/os.getenv/process.env-style "
-            "reads in Python and JS/TS -- this doesn't prove the variable is unused.[/dim]"
-        )
+    _render_source_usages(report.source_usages)
 
     if report.required_by:
         console.print("\n[bold]Required by[/bold]")
@@ -627,45 +803,7 @@ def _render_explain_report(report: "explain.ExplainReport") -> None:
                 f'    when {report.variable} == "{condition.get("equals", "true")}"'
             )
 
-    console.print("\n[bold]Deployment[/bold]")
-    if not report.manifest_references:
-        console.print("  No deployment manifest registered for this service.")
-    else:
-        declared = [r for r in report.manifest_references if r.status == "declared"]
-        not_declared = [
-            r for r in report.manifest_references if r.status == "not_declared"
-        ]
-        unresolved = [r for r in report.manifest_references if r.status == "unresolved"]
-        errored = [r for r in report.manifest_references if r.status == "error"]
-        if declared:
-            for ref in declared:
-                console.print(f"  {ref.path}")
-                if ref.container:
-                    console.print(f"    container: {ref.container}")
-        elif not_declared:
-            # Only claim "not found" when at least one manifest positively
-            # doesn't declare it -- printing this alongside "Cannot
-            # confirm" below (when every non-declared reference is
-            # actually unresolved) would read as EnvShield confidently
-            # asserting absence in the same breath it admits it can't
-            # tell.
-            checked = ", ".join(r.path for r in report.manifest_references)
-            console.print(
-                "  Not found in any registered deployment manifest "
-                f"(checked: {checked}) -- this doesn't prove it isn't deployed elsewhere."
-            )
-        if unresolved:
-            console.print(
-                f"  [yellow]Cannot confirm for {len(unresolved)} manifest(s): "
-                f"{', '.join(r.path for r in unresolved)} -- references an external "
-                f"ConfigMap/Secret not included in the manifest; '{report.variable}' "
-                "may be supplied from there.[/yellow]"
-            )
-        if errored:
-            console.print(
-                f"  [dim]Could not check {len(errored)} manifest(s): "
-                f"{', '.join(r.path for r in errored)}[/dim]"
-            )
+    _render_manifest_references(report.manifest_references, report.variable)
 
 
 @app.command(name="explain")
@@ -703,6 +841,16 @@ def explain_command(
 
     try:
         report = explain.build_report(variable, resolved_service)
+    except VariableNotFoundError:
+        # Degrade gracefully instead of only erroring -- exactly the
+        # workflow moment a developer reaches for 'explain' most: a
+        # variable 'undeclared'/'scan' just found, not yet in the schema.
+        undeclared_report = explain.build_undeclared_report(variable, resolved_service)
+        if json_output:
+            print(json.dumps(undeclared_report.to_dict(), indent=2))
+        else:
+            _render_undeclared_explain_report(undeclared_report)
+        raise typer.Exit(code=1)
     except EnvShieldException as e:
         if json_output:
             print(