Merge pull request #536 from ChBrain/governance/subnational-aware-bump-logic

ChBrain · web-flow · commit 67083c82bbc2 · 2026-05-26T09:39:14.000+02:00
fix(release): bump logic + alignment cross-check are sub-national-aware
diff --git a/.github/workflows/auto-release.yml b/.github/workflows/auto-release.yml
@@ -89,16 +89,33 @@ jobs:
           git worktree add --detach "$WT_AFTER"  "$AFTER"  >/dev/null
           trap 'git worktree remove --force "$WT_BEFORE" 2>/dev/null || true; git worktree remove --force "$WT_AFTER" 2>/dev/null || true' EXIT
 
+          # Use complete_cultures() so sub-national cultures (ADR-0001)
+          # join the bump diff -- pre-#536 this ran complete_countries()
+          # (depth-3 only), so a new sub-national appeared as the parent
+          # country being UPDATED instead of being ADDED itself (the SH
+          # promotion patch-bumped to v0.14.2 instead of minor-bumping
+          # to v0.15.0). The output emits the FULL relative path from
+          # regions/ so depth-aware UPDATED detection below can tell a
+          # sub-national change from a sovereign-state change.
+          #
+          # Fallback to complete_countries() when the AFTER ref doesn't
+          # yet have complete_cultures (this PR's predecessor refs);
+          # produces depth-3 paths so the comparison still works on
+          # both sides.
           PY='
           import sys
           sys.path.insert(0, "scripts")
           try:
-              from culture_completeness import complete_countries
+              from culture_completeness import complete_cultures, _REGIONS
+              rows = complete_cultures()
           except Exception:
-              # Script missing at this ref -- treat as empty set.
-              sys.exit(0)
-          for region, path in complete_countries():
-              print(f"{region}/{path.name}")
+              try:
+                  from culture_completeness import complete_countries, _REGIONS
+                  rows = complete_countries()
+              except Exception:
+                  sys.exit(0)
+          for _region, path in rows:
+              print(path.relative_to(_REGIONS).as_posix())
           '
           PREV=$(cd "$WT_BEFORE" && python3 -c "$PY" | sort)
           NEXT=$(cd "$WT_AFTER"  && python3 -c "$PY" | sort)
@@ -108,18 +125,33 @@ jobs:
           KEPT=$(comm  -12 <(printf '%s\n' "$PREV") <(printf '%s\n' "$NEXT") | sed '/^$/d')
 
           # Which KEPT cultures had a content change in this push?
-          # A change to a region's culture content under regions/<slug>/
-          # is the signal; touching the README of a region without
-          # changing the culture folder doesn't count.
+          # A culture is UPDATED only when a file changes AT ITS OWN
+          # depth -- NOT when a deeper sub-national folder under it
+          # changes. For sovereign europe/germany (depth 3 under
+          # regions/), files at regions/europe/germany/<file> count;
+          # files at regions/europe/germany/schleswig_holstein/<file>
+          # do NOT (the sub-national has its own entry and triggers its
+          # own UPDATED / ADDED row). Pre-#536 the grep was prefix-only
+          # and Germany was flagged as updated for any SH content
+          # change, double-counting the SH promotion.
           CHANGED=$(git diff --name-only "$BEFORE" "$AFTER" -- 'regions/' || true)
 
-          UPDATED=""
-          while IFS= read -r slug; do
-            [ -z "$slug" ] && continue
-            if printf '%s\n' "$CHANGED" | grep -q "^regions/$slug/"; then
-              UPDATED="${UPDATED}${slug}"$'\n'
-            fi
-          done <<< "$KEPT"
+          export KEPT CHANGED
+          UPDATED=$(python3 -c '
+          import os
+          kept = [s for s in os.environ.get("KEPT", "").split("\n") if s.strip()]
+          changed = [s for s in os.environ.get("CHANGED", "").split("\n") if s.strip()]
+          # A file counts for slug iff its prefix is regions/<slug>/
+          # AND its slash count equals prefix slash count (file lives
+          # at the slug own depth, not inside a sub-folder).
+          for slug in kept:
+              prefix = f"regions/{slug}/"
+              own_depth = prefix.count("/")
+              for c in changed:
+                  if c.startswith(prefix) and c.count("/") == own_depth:
+                      print(slug)
+                      break
+          ')
           UPDATED=$(printf '%s' "$UPDATED" | sed '/^$/d')
 
           {
diff --git a/.github/workflows/validate.yml b/.github/workflows/validate.yml
@@ -609,6 +609,25 @@ jobs:
       - name: Run completeness-alignment tests
         run: python -m pytest tests/test_culture_completeness_alignment.py -v
 
+  cultures-completeness-module-tests:
+    name: cultures - Completeness module tests
+    # Unit tests for scripts/culture_completeness.py itself --
+    # complete_countries (sovereign-only) and complete_cultures (both
+    # depths). Locks the depth contracts the auto-release bump diff
+    # and the alignment cross-check rely on; pre-#536 a sub-national
+    # could silently slip past both.
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+      - name: Install pytest
+        run: pip install pytest
+      - name: Run culture-completeness module tests
+        run: python -m pytest tests/test_culture_completeness.py -v
+
   cultures-hofstede-score-home:
     name: cultures - Hofstede score home
     # Single-home gate for Hofstede scores: data/hofstede_scores.json is
@@ -1117,6 +1136,7 @@ jobs:
       - cultures-zip-build
       - cultures-pdf-build
       - cultures-completeness-alignment
+      - cultures-completeness-module-tests
       - cultures-hofstede-score-home
       - cultures-validator-wiring
       - cultures-metadata-format
diff --git a/scripts/culture_completeness.py b/scripts/culture_completeness.py
@@ -8,15 +8,31 @@
   tests/test_culture_completeness_alignment.py -- cross-check that
       data/countries.json (the website map's registry) and the
       complete-cultures set stay in lockstep
+  .github/workflows/auto-release.yml -- bump-kind decision
+      (new culture -> minor, updated -> patch)
 
-The rule itself: a country folder is *complete* when it carries a
+The rule itself: a culture folder is *complete* when it carries a
 position file, at least two personas (accepting all naming forms across
 the persona-rename rollout), a place file, a piece file, and a README.
 That is exactly what the deployment artifacts need to resolve.
 
 Untested skeleton countries -- a region folder with a stub README but no
 content -- fall out. As each one finishes its v0.2.0 fix pass, it
 crosses the bar and joins the shipped set automatically.
+
+Two depths, two functions
+-------------------------
+- ``complete_countries()`` walks ``regions/<region>/<country>/``
+  (sovereign-state cultures only). The historical signature; build_zips
+  and build_pdfs depend on its sovereign-only semantics for their
+  per-country zip loop.
+- ``complete_cultures()`` walks both depths -- sovereign at
+  ``regions/<region>/<country>/`` AND sub-national (ADR-0001) at
+  ``regions/<region>/<parent>/<sub>/``. The signature consumers reach
+  for when "every shippable culture" matters: the release bump count,
+  the registry alignment cross-check. Build pipelines use the two
+  depth-specific helpers separately so the zip / PDF loops stay
+  disjoint (a sub-culture ships as a sibling artifact, not nested).
 """
 from __future__ import annotations
 
@@ -51,7 +67,11 @@ def is_complete_culture(country: Path) -> bool:
 
 
 def complete_countries() -> list[tuple[str, Path]]:
-    """(region_name, country_dir) for every complete culture, sorted.
+    """(region_name, country_dir) for every complete *sovereign-state* culture, sorted.
+
+    Sovereign-only -- depth 3 (``regions/<region>/<country>/``). For
+    the "every shippable culture including sub-nationals" set, use
+    ``complete_cultures()``.
 
     Ordered: regions alphabetically, countries within each region
     alphabetically. Hidden folders (``.xyz``) skipped.
@@ -64,3 +84,53 @@ def complete_countries() -> list[tuple[str, Path]]:
             if is_complete_culture(country):
                 out.append((region.name, country))
     return out
+
+
+def complete_cultures() -> list[tuple[str, Path]]:
+    """(region_name, culture_dir) for every complete culture at any depth, sorted.
+
+    Walks both depths:
+    - sovereign: ``regions/<region>/<slug>/``
+    - sub-national (ADR-0001): ``regions/<region>/<parent>/<sub>/``
+
+    A folder that's complete at the sovereign depth is NEVER also
+    counted at the sub-national depth -- ``is_complete_culture`` runs
+    once per candidate path, and the per-depth loops don't re-enter.
+
+    Ordering: sovereign cultures sorted by (region, slug), then sub-
+    national cultures sorted by (region, parent, sub). Stable across
+    runs so the auto-release bump diff (BEFORE vs AFTER set arithmetic)
+    is deterministic.
+
+    Consumers:
+    - auto-release bump-kind decision (new culture -> minor)
+    - test_culture_completeness_alignment (registry <-> complete set
+      cross-check, fires on culture/release-base PRs and the
+      culture/release -> main promotion)
+
+    Build pipelines DON'T use this -- they iterate sovereigns and
+    sub-nationals through separate per-depth functions because their
+    artifact layout differs (sub-cultures ship as sibling zips, not
+    nested inside the parent's zip).
+    """
+    out: list[tuple[str, Path]] = []
+    if not _REGIONS.is_dir():
+        return out
+    # First pass: sovereigns. Same signature as complete_countries.
+    sovereigns_seen: set[Path] = set()
+    for region in sorted(p for p in _REGIONS.iterdir() if p.is_dir() and not p.name.startswith(".")):
+        for country in sorted(p for p in region.iterdir() if p.is_dir() and not p.name.startswith(".")):
+            if is_complete_culture(country):
+                out.append((region.name, country))
+                sovereigns_seen.add(country)
+    # Second pass: sub-nationals. Only descend into country folders that
+    # exist on disk (sovereign or skeleton). A sub-national folder under
+    # a sovereign that itself isn't complete still ships if the
+    # sub-national meets the bar -- a Schleswig-Holstein folder can be
+    # complete while Germany itself is mid-migration.
+    for region in sorted(p for p in _REGIONS.iterdir() if p.is_dir() and not p.name.startswith(".")):
+        for country in sorted(p for p in region.iterdir() if p.is_dir() and not p.name.startswith(".")):
+            for sub in sorted(p for p in country.iterdir() if p.is_dir() and not p.name.startswith(".")):
+                if is_complete_culture(sub):
+                    out.append((region.name, sub))
+    return out
diff --git a/tests/test_culture_completeness.py b/tests/test_culture_completeness.py
@@ -0,0 +1,178 @@
+"""Tests for scripts/culture_completeness.py.
+
+Locks two contracts:
+
+1. ``complete_countries()`` returns ONLY sovereign-state cultures
+   (depth 3). build_zips and build_pdfs rely on this signature for
+   their per-country zip / PDF loop; widening it would double-build
+   sub-national content.
+2. ``complete_cultures()`` returns BOTH depths (sovereign + sub-
+   national) so the auto-release bump diff and the registry-alignment
+   cross-check see the full set. Pre-#536 these two consumers were
+   running on ``complete_countries()``, which meant a sub-national
+   like Schleswig-Holstein got patch-bumped instead of minor-bumped
+   and primed a latent alignment-test block on the next promotion.
+"""
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+import pytest
+
+REPO_ROOT = Path(__file__).resolve().parent.parent
+sys.path.insert(0, str(REPO_ROOT / "scripts"))
+
+import culture_completeness as cc  # noqa: E402
+from culture_completeness import (  # noqa: E402
+    complete_countries,
+    complete_cultures,
+    is_complete_culture,
+)
+
+
+def _make_complete(d: Path) -> None:
+    """Drop the five files is_complete_culture requires into ``d``."""
+    d.mkdir(parents=True, exist_ok=True)
+    (d / "culture_x_position.md").write_text("pos", encoding="utf-8")
+    (d / "culture_x_persona_one.md").write_text("p1", encoding="utf-8")
+    (d / "culture_x_persona_two.md").write_text("p2", encoding="utf-8")
+    (d / "culture_x_place_a.md").write_text("place", encoding="utf-8")
+    (d / "culture_x_piece_b.md").write_text("piece", encoding="utf-8")
+    (d / "README.md").write_text("readme", encoding="utf-8")
+
+
+@pytest.fixture
+def fake_regions(tmp_path, monkeypatch):
+    regions = tmp_path / "regions"
+    regions.mkdir()
+    monkeypatch.setattr(cc, "_REGIONS", regions)
+    return regions
+
+
+class TestIsCompleteCulture:
+    def test_complete_folder(self, tmp_path):
+        _make_complete(tmp_path / "x")
+        assert is_complete_culture(tmp_path / "x")
+
+    def test_missing_position(self, tmp_path):
+        _make_complete(tmp_path / "x")
+        (tmp_path / "x" / "culture_x_position.md").unlink()
+        assert not is_complete_culture(tmp_path / "x")
+
+    def test_only_one_persona(self, tmp_path):
+        _make_complete(tmp_path / "x")
+        (tmp_path / "x" / "culture_x_persona_two.md").unlink()
+        assert not is_complete_culture(tmp_path / "x")
+
+    def test_legacy_persona_name(self, tmp_path):
+        """``persona_<name>.md`` (the pre-rename form) counts."""
+        d = tmp_path / "x"
+        _make_complete(d)
+        (d / "culture_x_persona_one.md").unlink()
+        (d / "culture_x_persona_two.md").unlink()
+        (d / "persona_alice.md").write_text("a", encoding="utf-8")
+        (d / "persona_bob.md").write_text("b", encoding="utf-8")
+        assert is_complete_culture(d)
+
+    def test_non_dir(self, tmp_path):
+        f = tmp_path / "file.md"
+        f.write_text("x", encoding="utf-8")
+        assert not is_complete_culture(f)
+
+
+class TestCompleteCountriesIsSovereignOnly:
+    """``complete_countries`` MUST stay sovereign-only -- build_zips
+    and build_pdfs rely on this depth contract for their per-country
+    loop. A sub-national must NOT appear here."""
+
+    def test_returns_sovereigns_only(self, fake_regions):
+        _make_complete(fake_regions / "europe" / "germany")
+        _make_complete(fake_regions / "europe" / "germany" / "schleswig_holstein")
+        names = [path.name for _r, path in complete_countries()]
+        assert "germany" in names
+        assert "schleswig_holstein" not in names
+
+    def test_skeleton_country_not_included(self, fake_regions):
+        """A region folder without the full chapter set is filtered out."""
+        (fake_regions / "europe" / "atlantis").mkdir(parents=True)
+        (fake_regions / "europe" / "atlantis" / "README.md").write_text("stub")
+        names = [path.name for _r, path in complete_countries()]
+        assert "atlantis" not in names
+
+    def test_skips_hidden_folders(self, fake_regions):
+        _make_complete(fake_regions / ".hidden_region" / "x")
+        _make_complete(fake_regions / "europe" / ".hidden")
+        names = [path.name for _r, path in complete_countries()]
+        assert ".hidden" not in names
+        assert "x" not in names
+
+
+class TestCompleteCulturesWalksBothDepths:
+    """``complete_cultures`` returns sovereign AND sub-national folders
+    at every depth. This is what auto-release and the alignment
+    cross-check consume after #536."""
+
+    def test_includes_sub_national(self, fake_regions):
+        _make_complete(fake_regions / "europe" / "germany")
+        _make_complete(fake_regions / "europe" / "germany" / "schleswig_holstein")
+        names = [path.name for _r, path in complete_cultures()]
+        assert "germany" in names
+        assert "schleswig_holstein" in names
+
+    def test_subnational_without_complete_parent(self, fake_regions):
+        """A complete sub-national surfaces even when its parent is
+        only a skeleton -- the parent's incompleteness shouldn't hide
+        a shippable sub-culture (it has its own zip)."""
+        (fake_regions / "europe" / "germany").mkdir(parents=True)
+        (fake_regions / "europe" / "germany" / "README.md").write_text("stub")
+        _make_complete(fake_regions / "europe" / "germany" / "schleswig_holstein")
+        names = [path.name for _r, path in complete_cultures()]
+        assert "schleswig_holstein" in names
+        assert "germany" not in names
+
+    def test_skeleton_subnational_not_included(self, fake_regions):
+        _make_complete(fake_regions / "europe" / "germany")
+        (fake_regions / "europe" / "germany" / "bavaria").mkdir()
+        (fake_regions / "europe" / "germany" / "bavaria" / "README.md").write_text("stub")
+        names = [path.name for _r, path in complete_cultures()]
+        assert "germany" in names
+        assert "bavaria" not in names
+
+    def test_no_double_count_of_sovereign(self, fake_regions):
+        """A sovereign is returned once, not duplicated as its own
+        sub-self -- the per-depth loops never re-enter."""
+        _make_complete(fake_regions / "europe" / "germany")
+        rows = complete_cultures()
+        germany_rows = [r for r in rows if r[1].name == "germany"]
+        assert len(germany_rows) == 1
+
+    def test_ordering_sovereigns_then_subnationals(self, fake_regions):
+        """Sovereigns come first (sorted by region, slug), then sub-
+        nationals (sorted by region, parent, sub). Stable across runs
+        so the auto-release BEFORE/AFTER comparison is deterministic."""
+        _make_complete(fake_regions / "europe" / "germany")
+        _make_complete(fake_regions / "europe" / "denmark")
+        _make_complete(fake_regions / "europe" / "germany" / "schleswig_holstein")
+        names = [path.name for _r, path in complete_cultures()]
+        assert names.index("denmark") < names.index("germany")
+        assert names.index("germany") < names.index("schleswig_holstein")
+
+
+class TestCompleteCulturesAgainstRealRepo:
+    """The live regions/ tree must produce a sane complete-cultures
+    set: every sovereign is present, schleswig_holstein is there as
+    the only sub-national so far."""
+
+    def test_germany_present(self):
+        names = [path.name for _r, path in complete_cultures()]
+        assert "germany" in names
+
+    def test_schleswig_holstein_present(self):
+        names = [path.name for _r, path in complete_cultures()]
+        assert "schleswig_holstein" in names
+
+    def test_superset_of_complete_countries(self):
+        countries = {path.name for _r, path in complete_countries()}
+        cultures = {path.name for _r, path in complete_cultures()}
+        assert countries.issubset(cultures)
diff --git a/tests/test_culture_completeness_alignment.py b/tests/test_culture_completeness_alignment.py
