docs(python): add high-level dependency validation comments

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: eavanvalkenburg

.github/workflows/python-dependency-range-validation.yml

@@ -33,11 +33,13 @@ jobs:
 
       - name: Run dependency range validation
         id: validate_ranges
+        # Keep workflow running so we can still publish diagnostics from this run.
         continue-on-error: true
         run: uv run poe validate-dependency-ranges
         working-directory: ./python
 
       - name: Upload dependency range report
+        # Always publish the report so failures are inspectable even when validation fails.
         if: always()
         uses: actions/upload-artifact@v4
         with:
@@ -46,6 +48,7 @@ jobs:
           if-no-files-found: warn
 
       - name: Create issues for failed dependency candidates
+        # Always process the report so failed candidates create actionable tracking issues.
         if: always()
         uses: actions/github-script@v8
         with:
@@ -160,6 +163,7 @@ jobs:
             }
 
       - name: Refresh lockfile
+        # Only refresh lockfile after a clean validation to avoid committing known-bad ranges.
         if: steps.validate_ranges.outcome == 'success'
         run: uv lock --upgrade
         working-directory: ./python
@@ -186,6 +190,7 @@ jobs:
           echo "has_changes=true" >> "$GITHUB_OUTPUT"
 
       - name: Create or update pull request with GitHub CLI
+        # Only open/update PRs for validated updates to keep automation branches trustworthy.
         if: steps.validate_ranges.outcome == 'success' && steps.commit_updates.outputs.has_changes == 'true'
         run: |
           BRANCH="automation/python-dependency-range-updates"

python/scripts/validate_dependency_lower_bounds.py

@@ -578,6 +578,7 @@ def _optimize_dependency(
     attempted_versions: list[str] = []
     attempts: list[DependencyAttempt] = []
 
+    # Establish a validated baseline before searching for lower acceptable bounds.
     baseline_version = dependency.lower_version
     attempted_versions.append(str(baseline_version))
     print(f"[cyan]{package_label} :: {dependency.name} :: baseline current_lower [{baseline_version}] [/cyan]")
@@ -637,6 +638,7 @@ def _optimize_dependency(
             skipped_reason="No lower candidate bounds found within allowed boundary.",
         )
 
+    # Probe older bounds with a binary-search-style loop: keep successful tighter lowers, revert failures.
     low = 0
     high = len(candidates) - 1
     while low <= high:
@@ -710,6 +712,7 @@ def _process_package(
             skipped=["No check/test task combination found."],
         )
 
+    # Build the per-package optimization target set from eligible bounded dependency specifications.
     targets, skipped = _collect_targets(pyproject_file, dependency_filters=dependency_filters)
     if not targets:
         return PackageOutcome(
@@ -758,6 +761,7 @@ def _process_package(
             if candidate.exists():
                 temp_internal_editables.append(candidate)
 
+        # Execute lower-bound trials per dependency and accumulate final replacement strings for persistence.
         dependency_results: list[DependencyOutcome] = []
         replacements: dict[str, str] = {}
         package_label = f"{plan.project_path} ({plan.package_name})"
@@ -893,6 +897,7 @@ def main() -> None:
     dependency_filters = {name.lower() for name in args.dependencies} if args.dependencies else None
     output_json_path = (workspace_root / args.output_json).resolve()
 
+    # Phase 1: prepare shared workspace metadata and collect package execution plans.
     package_map = _build_workspace_package_map(workspace_root)
     internal_graph = _build_internal_graph(workspace_root, package_map)
     lock_versions = _load_lock_versions(workspace_root)
@@ -927,6 +932,7 @@ def main() -> None:
         print("[yellow]No packages matched the selection.[/yellow]")
         return
 
+    # Phase 2: initialize incremental report state before running package validations in parallel.
     report: dict = {
         "started_at": _utc_now(),
         "workspace_root": str(workspace_root),
@@ -978,6 +984,7 @@ def main() -> None:
             if outcome.changed and not args.dry_run:
                 _apply_package_replacements(plan.pyproject_path, outcome.replacements)
 
+            # Phase 3: aggregate outcomes, persist incremental JSON snapshots, and emit per-package progress.
             report["packages"].append(_to_json(outcome))
             report["summary"]["packages_changed"] = sum(1 for value in package_outcomes if value.changed)
             report["summary"]["dependencies_changed"] = sum(

python/scripts/validate_dependency_ranges.py

@@ -576,6 +576,7 @@ def _optimize_dependency(
     include_dev_group: bool,
     include_dev_extra: bool,
 ) -> DependencyOutcome:
+    # Build descending candidate trial bounds from the current constraint window.
     candidates = _build_trial_bounds(
         available_versions,
         lower=dependency.lower_version,
@@ -674,6 +675,7 @@ def _optimize_dependency(
             skipped_reason="No higher candidate bounds found.",
         )
 
+    # Probe candidates from highest to lowest; keep the first passing upper-bound rewrite.
     for candidate in candidates:
         attempted_versions.append(str(candidate))
         trial_requirements = [entry.with_upper(candidate) for entry in dependency.entries]
@@ -793,6 +795,7 @@ def _process_package(
         replacements: dict[str, str] = {}
         package_label = f"{plan.project_path} ({plan.package_name})"
 
+        # Run per-dependency trial generation + validation in the isolated temp workspace.
         for target in targets:
             versions = catalog.get(target.name)
             outcome = _optimize_dependency(
@@ -918,6 +921,7 @@ def main() -> None:
     parser.add_argument("--dry-run", action="store_true", help="Do not execute uv commands or update pyprojects.")
     args = parser.parse_args()
 
+    # Preparation/target collection: resolve workspace metadata and package execution plans.
     workspace_pyproject = Path(__file__).parent.parent / "pyproject.toml"
     workspace_root = workspace_pyproject.parent
     package_filters = set(args.packages) if args.packages else None
@@ -958,6 +962,7 @@ def main() -> None:
         print("[yellow]No packages matched the selection.[/yellow]")
         return
 
+    # Aggregation + persistence/reporting: initialize the incremental JSON report.
     report: dict = {
         "started_at": _utc_now(),
         "workspace_root": str(workspace_root),
@@ -1009,6 +1014,7 @@ def main() -> None:
             if outcome.changed and not args.dry_run:
                 _apply_package_replacements(plan.pyproject_path, outcome.replacements)
 
+            # Persist each completed package outcome so long runs keep a live report.
             report["packages"].append(_to_json(outcome))
             report["summary"]["packages_changed"] = sum(1 for value in package_outcomes if value.changed)
             report["summary"]["dependencies_changed"] = sum(