docs(proposals): add global build-system dependencies hook proposal

Document the motivation, design, hook signature, chaining behavior,
execution order, and interaction with existing mechanisms for the new
get_build_system_dependencies global hook point.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Signed-off-by: Vikash Shaw <vshaw@redhat.com>

Author: vshawrh

docs/proposals/global-build-system-dependencies-hook.md

@@ -0,0 +1,360 @@
+# Global hook for build-system dependency post-processing
+
+- Author: Vikash Shaw
+- Created: 2026-07-24
+- Status: Proposed
+- GitHub issue: [#1263](https://github.com/python-wheel-build/fromager/issues/1263)
+- GitHub PR: [#1271](https://github.com/python-wheel-build/fromager/pull/1271)
+
+## What
+
+Add `get_build_system_dependencies` as a new global hook point under
+`fromager.hooks`. This allows downstream projects to register hooks that
+post-process the build-system dependencies list for **all** packages,
+without writing per-package plugins.
+
+## Why
+
+Fromager provides two extension mechanisms for customizing build behavior:
+
+1. **Per-package plugins** (`fromager.project_overrides`): Override a
+   specific hook for a single package. Registered via entry points keyed
+   by the canonicalized package name. When present, the plugin **replaces**
+   the default implementation entirely (`overrides.find_and_invoke` uses
+   one or the other, never both).
+
+2. **Global hooks** (`fromager.hooks`): Run for every package. Currently
+   support `post_build`, `post_bootstrap`, and `prebuilt_wheel`. These
+   are event callbacks that fire after an action has completed.
+
+There is a gap: no global hook runs **during** dependency resolution.
+When a cross-cutting concern affects build dependencies for many
+packages, the only option today is to write identical per-package plugins
+for each affected package.
+
+### The setuptools problem
+
+A concrete example motivating this proposal: setuptools 81 removed
+`distutils.spawn(dry_run=...)` and `remove_tree(dry_run=...)`.
+setuptools 82 removed `pkg_resources` entirely. Many PyPI packages
+still reference these removed APIs in their `setup.py`, causing build
+failures when Fromager resolves an uncapped setuptools.
+
+In one downstream builder, this required **22 identical per-package
+plugins** that each do the same thing: scan `setup.py` with `ast.parse`,
+detect usage of removed APIs, and append a setuptools version cap to the
+build dependencies. Each plugin is 24 lines of boilerplate that calls
+a shared utility function.
+
+```
+package_plugins/albucore.py      # identical
+package_plugins/antlr4_python3_runtime.py  # identical
+package_plugins/blessed.py       # identical
+... (19 more)
+```
+
+Every time a new package triggers the same setuptools incompatibility, a
+new identical plugin must be added. This does not scale.
+
+### Why not `update_build_requires`?
+
+Fromager's YAML settings support `update_build_requires` for statically
+adding build dependencies. However, the setuptools cap is conditional:
+it depends on what APIs the package's `setup.py` actually uses. A static
+YAML entry would either over-constrain (cap all packages) or require
+per-package entries (same maintenance burden as plugins).
+
+### Why not put this in Fromager core?
+
+The initial approach (PR [#1264](https://github.com/python-wheel-build/fromager/pull/1264))
+proposed adding setuptools-capping logic directly into
+`default_get_build_system_dependencies`. Feedback from the maintainer
+(Doug Hellmann) identified that this is too opinionated for core:
+
+> *"This feels like something that a user might want, or not, based on
+> what packages they are building or some other context about their
+> build. What if, instead of putting this in core at all, we introduced
+> the idea of 'global' plugins for 'fixing' requirements?"*
+
+The global hook approach keeps Fromager generic and lets downstream
+projects opt into whatever dependency-fixing logic they need.
+
+## Goals
+
+- Extend the existing `fromager.hooks` system with a
+  `get_build_system_dependencies` hook point
+- Allow multiple hooks to chain (output of one feeds into the next)
+- Preserve backward compatibility: per-package plugins still take
+  full precedence
+- Follow the existing stevedore-based hook pattern used by `post_build`,
+  `post_bootstrap`, and `prebuilt_wheel`
+
+## Non-goals
+
+- Adding setuptools-capping logic to Fromager core. That belongs in
+  downstream hook implementations.
+- Replacing per-package plugins. Packages with truly custom build
+  dependency logic should still use `fromager.project_overrides`.
+- Adding global hooks for `get_build_backend_dependencies` or
+  `get_build_sdist_dependencies`. These can be added later if needed,
+  following the same pattern.
+
+## How
+
+### Execution order
+
+The hook runs inside `dependencies.get_build_system_dependencies()`,
+after the per-package override (or default) returns and before marker
+filtering:
+
+```
+1. Check for cached requirements file (early return if exists)
+2. overrides.find_and_invoke()          <-- per-package plugin or default
+3. hooks.run_get_build_system_dependencies_hooks()   <-- NEW: global hooks
+4. _filter_requirements()               <-- marker evaluation
+5. Write requirements cache file
+```
+
+This ordering means:
+
+- Per-package plugins produce the initial dependency list. If a package
+  has a custom `get_build_system_dependencies` override, the global hook
+  receives that override's output.
+- If no per-package plugin exists, the default implementation reads
+  `[build-system] requires` from `pyproject.toml`, and the global hook
+  receives that.
+- Global hooks can add, remove, or modify entries in the list.
+- Marker filtering happens last, so hooks do not need to evaluate
+  environment markers themselves.
+- The result is cached to `build-system-requirements.txt`, so hooks run
+  only once per package per build.
+
+### Hook signature
+
+```python
+def get_build_system_dependencies(
+    *,
+    ctx: context.WorkContext,
+    req: Requirement,
+    sdist_root_dir: pathlib.Path,
+    build_dir: pathlib.Path,
+    requirements: list[str],
+) -> list[str]:
+    """Post-process build-system dependencies for a package.
+
+    Args:
+        ctx: The current work context (variant, settings, paths).
+        req: The requirement being built.
+        sdist_root_dir: Root directory of the unpacked sdist.
+        build_dir: The build directory within the sdist.
+        requirements: Current list of build-system requirement strings.
+
+    Returns:
+        A (possibly modified) list of requirement strings.
+    """
+    ...
+```
+
+Parameters:
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `ctx` | `context.WorkContext` | Build context with variant, settings, and paths |
+| `req` | `Requirement` | The package requirement being processed |
+| `sdist_root_dir` | `pathlib.Path` | Root of the unpacked source distribution |
+| `build_dir` | `pathlib.Path` | Build directory (may differ from sdist root) |
+| `requirements` | `list[str]` | Current build-system requirements as strings |
+
+The hook **must** return a `list[str]`. It receives the output of the
+previous hook (or the initial requirements if it is the first hook).
+
+### Chaining
+
+When multiple hooks are registered, they are chained. The output of one
+becomes the `requirements` input of the next:
+
+```
+initial requirements
+    |
+    v
+  hook_a(requirements=[...]) -> [... + extra_a]
+    |
+    v
+  hook_b(requirements=[... + extra_a]) -> [... + extra_a + extra_b]
+    |
+    v
+final requirements
+```
+
+Hook execution order follows stevedore's `HookManager` iteration order
+(alphabetical by entry point name).
+
+### Registration
+
+Hooks are registered as entry points under the `fromager.hooks`
+namespace, with the name `get_build_system_dependencies`:
+
+```toml
+# In the downstream project's pyproject.toml
+[project.entry-points."fromager.hooks"]
+get_build_system_dependencies = "my_package.hooks:get_build_system_dependencies"
+```
+
+This uses the same stevedore `HookManager` infrastructure as the
+existing `post_build`, `post_bootstrap`, and `prebuilt_wheel` hooks.
+
+### Implementation details
+
+Two files are modified in Fromager:
+
+**`src/fromager/hooks.py`:**
+
+- Add `"get_build_system_dependencies"` to `GLOBAL_HOOK_NAMES`
+- Add `run_get_build_system_dependencies_hooks()` function that iterates
+  over registered hooks, chaining the requirements list through each
+
+```python
+def run_get_build_system_dependencies_hooks(
+    ctx: context.WorkContext,
+    req: Requirement,
+    sdist_root_dir: pathlib.Path,
+    build_dir: pathlib.Path,
+    requirements: list[str],
+) -> list[str]:
+    hook_mgr = _get_hooks("get_build_system_dependencies")
+    for ext in hook_mgr:
+        requirements = ext.plugin(
+            ctx=ctx,
+            req=req,
+            sdist_root_dir=sdist_root_dir,
+            build_dir=build_dir,
+            requirements=requirements,
+        )
+    return requirements
+```
+
+**`src/fromager/dependencies.py`:**
+
+- Import `hooks` module
+- Call `hooks.run_get_build_system_dependencies_hooks()` after
+  `overrides.find_and_invoke()` returns, before `_filter_requirements()`
+
+### Example: setuptools constraint hook
+
+This is the downstream hook that would replace the 22 identical plugins
+in the downstream builder:
+
+```python
+import ast
+import logging
+import pathlib
+
+from fromager import context
+from packaging.requirements import Requirement
+
+logger = logging.getLogger(__name__)
+
+
+def get_build_system_dependencies(
+    *,
+    ctx: context.WorkContext,
+    req: Requirement,
+    sdist_root_dir: pathlib.Path,
+    build_dir: pathlib.Path,
+    requirements: list[str],
+) -> list[str]:
+    """Auto-cap setuptools for packages using removed APIs."""
+    constraint = _get_setuptools_constraint(build_dir)
+    if constraint:
+        logger.info("%s: adding %s", req.name, constraint)
+        requirements = requirements + [constraint]
+    return requirements
+
+
+def _get_setuptools_constraint(sdist_root_dir: pathlib.Path) -> str | None:
+    setup_py = sdist_root_dir / "setup.py"
+    if not setup_py.is_file():
+        return None
+
+    try:
+        tree = ast.parse(setup_py.read_text())
+    except SyntaxError:
+        return None
+
+    has_pkg_resources = False
+    has_dry_run = False
+
+    for node in ast.walk(tree):
+        # Detect: import pkg_resources / from pkg_resources import ...
+        if isinstance(node, ast.Import):
+            for alias in node.names:
+                if alias.name == "pkg_resources" or alias.name.startswith(
+                    "pkg_resources."
+                ):
+                    has_pkg_resources = True
+        elif isinstance(node, ast.ImportFrom):
+            if node.module and (
+                node.module == "pkg_resources"
+                or node.module.startswith("pkg_resources.")
+            ):
+                has_pkg_resources = True
+        # Detect: dry_run keyword argument
+        elif isinstance(node, ast.keyword):
+            if node.arg == "dry_run":
+                has_dry_run = True
+
+    if has_dry_run:
+        return "setuptools<81"
+    if has_pkg_resources:
+        return "setuptools<82"
+    return None
+```
+
+## Interaction with existing mechanisms
+
+| Mechanism | Scope | Relationship to global hooks |
+| --- | --- | --- |
+| `update_build_requires` (YAML) | Per-package, static | Runs during `prepare_source` (before `get_build_system_dependencies`). Global hooks see the result. |
+| `remove_build_requires` (YAML) | Per-package, static | Same as above. |
+| Per-package plugin (`fromager.project_overrides`) | Per-package, dynamic | Runs first via `overrides.find_and_invoke()`. Global hooks receive its output. |
+| Cached `build-system-requirements.txt` | Per-package | If the cache file exists, the function returns early. Global hooks do not run. |
+| **Global hooks (this proposal)** | All packages, dynamic | Runs after per-package plugin, before marker filtering. |
+
+## Testing
+
+The PR includes 8 new tests:
+
+**In `tests/test_hooks.py`:**
+- `test_run_get_build_system_dependencies_hooks_calls_plugin`: Verifies correct arguments are passed to the hook
+- `test_run_get_build_system_dependencies_hooks_chains`: Verifies multiple hooks chain correctly (each receives the previous hook's output)
+- `test_run_get_build_system_dependencies_hooks_no_hooks`: Verifies no-op when no hooks are registered
+- `test_run_get_build_system_dependencies_hooks_exception_propagates`: Verifies exceptions from hooks are not swallowed
+
+**In `tests/test_dependencies.py`:**
+- `test_get_build_system_dependencies_runs_global_hooks`: Integration test verifying the hook is called from `get_build_system_dependencies()` with the correct initial requirements list
+
+## Future extensions
+
+The same pattern can be applied to other dependency resolution hooks if
+needed:
+
+- `get_build_backend_dependencies`: Post-process backend dependencies
+  (from `get_requires_for_build_wheel`)
+- `get_build_sdist_dependencies`: Post-process sdist build dependencies
+- `get_install_dependencies_of_sdist`: Post-process install dependencies
+
+Each would follow the same chaining pattern and execution order (after
+per-package override, before marker filtering).
+
+## Limitations
+
+- Hook execution order depends on stevedore's `HookManager` iteration,
+  which is alphabetical by entry point name. If ordering between hooks
+  matters, users must choose entry point names carefully.
+- Global hooks cannot prevent a per-package plugin from running. If a
+  package has a `get_build_system_dependencies` override, the global
+  hook receives that override's output, not the default pyproject.toml
+  requires.
+- The cached requirements file (`build-system-requirements.txt`) is
+  written after global hooks run. If a hook's behavior changes between
+  runs, the cache must be cleared manually.