feat(constraints): add per-specifier provenance tracking

When multiple constraint files are merged, engineers had no way to
determine which input file contributed each specifier. This adds
provenance tracking so every constraint records its source file.

- Add `_provenance` dict to `Constraints` class, grouped by source file
- Make `source` a required keyword-only parameter on `add_constraint()`
- Add `get_provenance()` public method returning `{source: [lines]}`
- Include inline provenance comments in `merged-constraints.txt` output
- Enrich `InvalidConstraintError` messages with source file info
- Add provenance to resolver rejection logs and exception messages
- Add `_format_provenance()` helper for human-readable formatting

Co-Authored-By: Claude <claude@anthropic.com>
Closes: #1186
Signed-off-by: Shanmukh Pawan <smoparth@redhat.com>

Author: smoparth

src/fromager/constraints.py

@@ -27,6 +27,23 @@ def _is_blocked_specifier(specifier: SpecifierSet) -> bool:
     )
 
 
+def _format_provenance(provenance: dict[str, list[str]]) -> str:
+    """Format a per-package provenance dict as a human-readable string.
+
+    Args:
+        provenance: Mapping of source file to original constraint lines.
+
+    Returns:
+        Formatted string, e.g.
+        ``"/path/to/base.txt (>=2.0), /path/to/override.txt (!=2.1.1)"``.
+    """
+    parts: list[str] = []
+    for source, lines in provenance.items():
+        specifiers = ", ".join(str(Requirement(line).specifier) for line in lines)
+        parts.append(f"{source} ({specifiers})")
+    return ", ".join(parts)
+
+
 class InvalidConstraintError(ValueError):
     pass
 
@@ -36,6 +53,8 @@ def __init__(self) -> None:
         # mapping of canonical names to requirements
         # NOTE: Requirement.name is not normalized
         self._data: dict[NormalizedName, Requirement] = {}
+        # per-package provenance: {canonical_name: {source_file: [original_lines]}}
+        self._provenance: dict[NormalizedName, dict[str, list[str]]] = {}
 
     def __iter__(self) -> Generator[NormalizedName, None, None]:
         yield from self._data
@@ -46,13 +65,21 @@ def __bool__(self) -> bool:
     def __len__(self) -> int:
         return len(self._data)
 
-    def add_constraint(self, unparsed: str) -> None:
-        """Add new constraint, must not conflict with any existing constraints
+    def add_constraint(self, unparsed: str, *, source: str) -> None:
+        """Add new constraint, must not conflict with any existing constraints.
+
+        Args:
+            unparsed: Raw constraint string, e.g. ``"foo>=2.0"``.
+            source: Path or URL of the file that contains this constraint.
+                Required for provenance tracking.
 
-        .. versionchanged: 0.83.0
+        .. versionchanged:: 0.83.0
            Non-conflicting constraints are now combined. Constraints with
            conflicts now raise :exc:`InvalidConstraintError`. Inputs without a
            version specifier or with extras or url are also refused.
+
+        .. versionchanged:: 0.84.0
+           Added *source* parameter for provenance tracking.
         """
         req = Requirement(unparsed)
         canon_name = canonicalize_name(req.name)
@@ -81,43 +108,77 @@ def add_constraint(self, unparsed: str) -> None:
         if previous is not None:
             prev_blocked = _is_blocked_specifier(previous.specifier)
             if blocked != prev_blocked:
+                prev_prov = _format_provenance(self._provenance.get(canon_name, {}))
                 raise InvalidConstraintError(
                     f"Cannot combine blocked and non-blocked constraints "
-                    f"(existing: {previous}, new: {req})"
+                    f"(existing: {previous} from {prev_prov}, "
+                    f"new: {req} from {source})"
                 )
             if not blocked:
                 logger.debug("combining constraints %s and %s", previous, req)
                 new_specifier = req.specifier & previous.specifier
                 if new_specifier.is_unsatisfiable():
+                    prev_prov = _format_provenance(self._provenance.get(canon_name, {}))
                     raise InvalidConstraintError(
                         f"Combined specifier '{new_specifier}' is not satisfiable "
-                        f"(existing: {previous}, new: {req})"
+                        f"(existing: {previous} from {prev_prov}, "
+                        f"new: {req} from {source})"
                     )
                 req.specifier = new_specifier
         else:
             logger.debug(f"adding constraint {req}")
 
         self._data[canon_name] = req
+        pkg_prov = self._provenance.setdefault(canon_name, {})
+        pkg_prov.setdefault(source, []).append(unparsed)
 
     def load_constraints_file(self, constraints_file: str | pathlib.Path) -> None:
-        """Load constraints from a constraints file or URL"""
+        """Load constraints from a constraints file or URL."""
         logger.info("loading constraints from %s", constraints_file)
+        source = str(constraints_file)
         content = requirements_file.parse_requirements_file(constraints_file)
         for line in content:
-            self.add_constraint(line)
+            self.add_constraint(line, source=source)
 
     def dump_constraints(self, output: typing.TextIO) -> None:
-        """Dump combined constraints to a text stream"""
-        # sort by normalized name
-        for _, req in sorted(self._data.items()):
-            # write requirement without markers. They have been evaluated
-            # in add_constraint()
-            output.write(f"{req.name}{req.specifier}\n")
+        """Dump combined constraints to a text stream.
+
+        Each line includes an inline comment showing which source file(s)
+        contributed each specifier.
+
+        Args:
+            output: Writable text stream.
+
+        .. versionchanged:: 0.84.0
+           Output now includes per-line provenance comments.
+        """
+        # sort by normalized name, write requirement without markers.
+        # They have been evaluated in add_constraint()
+        for name, req in sorted(self._data.items()):
+            line = f"{req.name}{req.specifier}"
+            prov = self._provenance.get(name, {})
+            if prov:
+                line = f"{line}  # {_format_provenance(prov)}"
+            output.write(f"{line}\n")
 
     def get_constraint(self, name: str) -> Requirement | None:
+        """Return the merged constraint for *name*, or ``None``."""
         return self._data.get(canonicalize_name(name))
 
+    def get_provenance(self, name: str) -> dict[str, list[str]]:
+        """Return provenance info for *name*.
+
+        Returns:
+            Mapping of ``{source_file: [original_constraint_lines]}``,
+            or an empty dict if the package has no constraints.
+
+        .. versionadded:: 0.84.0
+        """
+        prov = self._provenance.get(canonicalize_name(name), {})
+        return {source: list(lines) for source, lines in prov.items()}
+
     def allow_prerelease(self, pkg_name: str) -> bool:
+        """Return ``True`` if the constraint for *pkg_name* allows prereleases."""
         constraint = self.get_constraint(pkg_name)
         if constraint:
             return bool(constraint.specifier.prereleases)
@@ -131,6 +192,7 @@ def is_blocked(self, pkg_name: str) -> bool:
         return False
 
     def is_satisfied_by(self, pkg_name: str, version: Version) -> bool:
+        """Return ``True`` if *version* satisfies the constraint for *pkg_name*."""
         constraint = self.get_constraint(pkg_name)
         if constraint:
             return constraint.specifier.contains(version, prereleases=True)

src/fromager/resolver.py

@@ -32,7 +32,7 @@
 
 from . import overrides
 from .candidate import Candidate, Cooldown
-from .constraints import Constraints
+from .constraints import Constraints, _format_provenance
 from .extras_provider import ExtrasProvider
 from .http_retry import RETRYABLE_EXCEPTIONS, retry_on_exception
 from .request_session import session
@@ -287,10 +287,15 @@ def find_all_matching_from_provider(
         )
     except resolvelib.resolvers.ResolverException as err:
         constraint = provider.constraints.get_constraint(req.name)
+        provenance = provider.constraints.get_provenance(req.name)
         provider_desc = provider.get_provider_description()
         original_msg = str(err)
+        prov_msg = ""
+        if provenance:
+            prov_msg = f" (from {_format_provenance(provenance)})"
         raise resolvelib.resolvers.ResolverException(
-            f"Unable to resolve requirement specifier {req} with constraint {constraint} using {provider_desc}: {original_msg}"
+            f"Unable to resolve requirement specifier {req} with constraint "
+            f"{constraint}{prov_msg} using {provider_desc}: {original_msg}"
         ) from err
 
     # Materialize candidates so we can iterate more than once if filtering
@@ -689,8 +694,13 @@ def is_satisfied_by(self, requirement: Requirement, candidate: Candidate) -> boo
         if not self.constraints.is_satisfied_by(requirement.name, candidate.version):
             if DEBUG_RESOLVER:
                 c = self.constraints.get_constraint(requirement.name)
+                provenance = self.constraints.get_provenance(requirement.name)
+                prov_msg = ""
+                if provenance:
+                    prov_msg = f" from {_format_provenance(provenance)}"
                 logger.debug(
-                    f"{requirement.name}: skipping {candidate.version} due to constraint {c}"
+                    f"{requirement.name}: skipping {candidate.version} "
+                    f"due to constraint {c}{prov_msg}"
                 )
             return False