Fail closed on nested docgen.yaml mappings and empty lint/compose

Reject list or scalar values for dirs, segments, visual_map, and related
keys. segments.all must be a YAML list. lint and compose error when there
are no segment ids to process.

Co-authored-by: jmjava <jmjava@gmail.com>

Author: cursoragent

milestones/README.md

@@ -5,11 +5,14 @@ repositories that install `docgen` and maintain their own demo bundle. The
 library no longer ships an in-repo dogfood; consumers are the integration test
 of record.
 
-**Active:** **[manim-lint-config.md](manim-lint-config.md)** — missing
-`scenes.py` must fail `validate`; invalid `docgen.yaml` must not traceback
-or be rewritten as `{}`; TTS empty-all must not succeed.
+**Active:** **[config-mapping-keys.md](config-mapping-keys.md)** — nested
+`docgen.yaml` mapping/list keys must not traceback; lint/compose empty-all
+must not succeed.
 
 **Shipped:**
+- **[manim-lint-config.md](manim-lint-config.md)** — missing `scenes.py`
+  fails validate; invalid `docgen.yaml` is `ConfigError`; TTS empty-all
+  fails (#82).
 - **[wizard-narration-paths.md](wizard-narration-paths.md)** — wizard
   generate-narration must not drop missing sources; timestamps must not wipe
   corrupt `timing.json` (#81).

milestones/config-mapping-keys.md

@@ -0,0 +1,26 @@
+# Milestone — Nested config mappings and empty lint/compose
+
+**Goal:** Nested `docgen.yaml` keys that must be mappings or lists must not
+traceback (`AttributeError` / `TypeError`). `docgen lint` and `docgen compose`
+must not exit 0 when there are no segments to process.
+
+**Branch / PR:** `cursor/config-mapping-keys-2ccd`
+
+Follows **[manim-lint-config.md](manim-lint-config.md)** (#82).
+
+## Shipped
+
+- [x] `dirs`, `segments`, `visual_map`, `tts`, `manim`, `validation`, and
+      related keys reject list/scalar values (`ConfigError`)
+- [x] `segments.all` / `segments.default` must be YAML lists (a string is not
+      iterated as characters)
+- [x] Null mapping keys still mean “use defaults”
+- [x] `docgen lint` with empty `segments.all` (no `--segment`) is an error
+- [x] `docgen compose` with no remaining segment ids is an error
+
+## Not this milestone
+
+- Missing recordings stay a pre-push **warning**
+- `timestamps` with empty `segments.all` still leaves `timing.json`
+      unchanged (#78)
+- Archived Playwright / Embabel / slides

src/docgen/cli.py

@@ -499,6 +499,11 @@ def compose(
             "[compose] No segments left after --only-visual-type filter "
             f"({', '.join(only_visual_types)})."
         )
+    if not target:
+        raise click.ClickException(
+            "[compose] no segments to compose — set segments.default or "
+            "segments.all, or pass segment ids"
+        )
     click.echo(f"=== Composing {len(target)} segments ===")
     composed = comp.compose_segments(target)
     mapped = [
@@ -541,7 +546,11 @@ def lint(ctx: click.Context, segment: str | None) -> None:
 
     cfg = _require_config(ctx)
     linter = NarrationLinter(cfg)
-    segments = [segment] if segment else cfg.segments_all
+    segments = [segment] if segment else list(cfg.segments_all)
+    if not segments:
+        raise click.ClickException(
+            "segments.all is empty — add segment ids in docgen.yaml before lint"
+        )
     issues_total = 0
 
     missing = 0

src/docgen/compose.py

@@ -29,7 +29,9 @@ def filter_segments_by_visual_types(
         return list(segment_ids)
     out: list[str] = []
     for sid in segment_ids:
-        vm = config.visual_map.get(sid, {})
+        vm = config.visual_map.get(sid)
+        if not isinstance(vm, dict):
+            continue
         vt = str(vm.get("type", "")).strip().lower()
         if vt in allowed:
             out.append(sid)