Merge pull request #94 from jmjava/cursor/wizard-exclude-lists-2ccd

Fail closed when wizard exclude_patterns is not a list

Author: cursor[bot]

milestones/README.md

@@ -5,11 +5,12 @@ 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:** **[timestamps-merge-stems.md](timestamps-merge-stems.md)** — CLI
-`timestamps` must merge stems into existing `timing.json`, not wipe extra keys
-or overwrite garbage JSON.
+**Active:** **[wizard-exclude-lists.md](wizard-exclude-lists.md)** —
+`wizard.exclude_patterns` / `scan_extensions` must be string lists, not scalars.
 
 **Shipped:**
+- **[timestamps-merge-stems.md](timestamps-merge-stems.md)** — CLI `timestamps`
+  merges stems into existing `timing.json` instead of wiping extra keys (#93).
 - **[asset-graph-timing.md](asset-graph-timing.md)** — wizard freshness must
   not treat corrupt `timing.json` as a missing timestamps entry (#92).
 - **[yaml-generate-mappings.md](yaml-generate-mappings.md)** — `yaml-generate`

milestones/timestamps-merge-stems.md

@@ -1,7 +1,7 @@
 # Milestone: CLI timestamps must merge stems, not wipe `timing.json`
 
-**Status:** Active  
-**PR:** pending  
+**Status:** Shipped  
+**PR:** #93  
 **Depends on:** `milestones/timestamps-fail-closed.md` (PR #78),
 `milestones/timing-json-parse.md` (PR #89)
 

milestones/wizard-exclude-lists.md

@@ -0,0 +1,37 @@
+# Milestone: wizard exclude/scan lists must not be scalars
+
+**Status:** Active  
+**PR:** pending  
+**Depends on:** `milestones/yaml-generate-mappings.md` (PR #91),
+`milestones/config-mapping-keys.md` (PR #83)
+
+## Problem
+
+`wizard.exclude_patterns` is a list of glob strings. A YAML string was:
+
+1. **Wiped** by `yaml-generate` `merge_defaults` (`ex = []`).
+2. **Iterated as characters** by wizard `/api/scan` (`fnmatch` over `"a"`, `"r"`, …).
+
+`wizard.scan_extensions` as a string similarly overwrote the default extension
+tuple in `wizard_config` and scanned the wrong files.
+
+## Goal
+
+Fail closed at `Config.from_yaml` (`string_list_block`) and in `merge_defaults`
+(present non-list raises `ValueError`). Missing keys still default.
+
+## Done when
+
+- [x] `wizard.exclude_patterns` / `wizard.scan_extensions` if present must be
+      YAML lists of strings.
+- [x] `merge_defaults` does not replace a string `exclude_patterns` with `[]`.
+- [x] Tests for string exclude_patterns and scan_extensions.
+- [x] `ruff check src/ tests/`
+- [x] `pytest tests/`
+- [x] `docgen benchmark` (no clock change)
+
+## Out of scope
+
+- Empty `exclude_patterns: []` remains allowed (archive dirs are still skipped
+  via `is_under_archive_dir`).
+- Wizard `.docgen-state.json` corrupt still resets to empty.

src/docgen/config.py

@@ -248,6 +248,21 @@ def __post_init__(self) -> None:
                     f"{src}: visual_map.{sid_s} must be a YAML mapping, "
                     f"not {type(spec).__name__}"
                 )
+        wiz = self._block("wizard")
+        if wiz.get("exclude_patterns") is not None:
+            string_list_block(
+                wiz,
+                "exclude_patterns",
+                label="wizard.exclude_patterns",
+                source=src,
+            )
+        if wiz.get("scan_extensions") is not None:
+            string_list_block(
+                wiz,
+                "scan_extensions",
+                label="wizard.scan_extensions",
+                source=src,
+            )
 
     def _source_label(self) -> str:
         return self.yaml_path.name if self.yaml_path else "docgen.yaml"

src/docgen/yaml_generate.py

@@ -109,10 +109,14 @@ def merge_defaults(
         raw["wizard"] = wiz
     else:
         wiz = _require_yaml_mapping(wiz, label="wizard")
-    ex = wiz.setdefault("exclude_patterns", [])
-    if not isinstance(ex, list):
+    ex = wiz.get("exclude_patterns")
+    if ex is None:
         ex = []
         wiz["exclude_patterns"] = ex
+    elif not isinstance(ex, list):
+        raise ValueError(
+            f"wizard.exclude_patterns must be a YAML list, not {type(ex).__name__}"
+        )
     if ARCHIVE_EXCLUDE not in ex:
         ex.append(ARCHIVE_EXCLUDE)
         changes.append(f"wizard.exclude_patterns: added {ARCHIVE_EXCLUDE!r}")

tests/test_config.py

@@ -319,3 +319,17 @@ def test_from_yaml_list_manim_scene_generation_raises(tmp_path: Path) -> None:
     p.write_text("manim_scene_generation: []\n", encoding="utf-8")
     with pytest.raises(ConfigError, match="manim_scene_generation must be a YAML mapping"):
         Config.from_yaml(p)
+
+
+def test_from_yaml_string_wizard_exclude_patterns_raises(tmp_path: Path) -> None:
+    p = tmp_path / "docgen.yaml"
+    p.write_text("wizard:\n  exclude_patterns: archive\n", encoding="utf-8")
+    with pytest.raises(ConfigError, match="wizard.exclude_patterns must be a YAML list"):
+        Config.from_yaml(p)
+
+
+def test_from_yaml_string_wizard_scan_extensions_raises(tmp_path: Path) -> None:
+    p = tmp_path / "docgen.yaml"
+    p.write_text("wizard:\n  scan_extensions: .md\n", encoding="utf-8")
+    with pytest.raises(ConfigError, match="wizard.scan_extensions must be a YAML list"):
+        Config.from_yaml(p)

tests/test_yaml_generate.py

@@ -94,6 +94,13 @@ def test_merge_defaults_idempotent_archive(tmp_path: Path) -> None:
     assert not any("archive" in x and "added" in x for x in ch)
 
 
+def test_merge_defaults_rejects_string_wizard_exclude_patterns(tmp_path: Path) -> None:
+    cfg = _minimal_cfg(tmp_path)
+    raw = {"wizard": {"exclude_patterns": "**/archive/**"}, "discovery": {"auto_visual_map": False}}
+    with pytest.raises(ValueError, match="wizard.exclude_patterns must be a YAML list"):
+        merge_defaults(raw, cfg)
+
+
 def test_merge_defaults_syncs_manim_segments_from_visual_map(tmp_path: Path) -> None:
     raw = {
         "repo_root": ".",