feat(constraints): add per-specifier provenance tracking

[smoparth]

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

Closes: #1186

Pull Request Description

What

Why

• PR follows CONTRIBUTING.md guidelines

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 45a0590b-be1b-4cc2-877c-fc3f68156b6e

📥 Commits

Reviewing files that changed from the base of the PR and between 424ccfb and 071002e.

📒 Files selected for processing (5)

• src/fromager/constraints.py
• src/fromager/resolver.py
• tests/test_constraints.py
• tests/test_context.py
• tests/test_resolver.py

🚧 Files skipped from review as they are similar to previous changes (4)

• tests/test_context.py
• src/fromager/constraints.py
• tests/test_resolver.py
• tests/test_constraints.py

---

📝 Walkthrough

Walkthrough

This PR implements per-constraint-file provenance tracking in the Constraints class. The core change adds a _provenance dictionary that maps package names to source-to-constraint-lines mappings. When add_constraint() merges specifiers from multiple files, provenance is accumulated. The merged output from dump_constraints() now includes inline comments showing which source files contributed each constraint line. Error messages for constraint conflicts and resolution failures are enriched with provenance information to help engineers quickly identify which input files caused issues.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

🚥 Pre-merge checks | ✅ 4

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely describes the main change: adding per-specifier provenance tracking to the constraints system.
Description check	✅ Passed	The description is directly related to the changeset, explaining the motivation (engineers need to know which constraint files contributed each specifier) and listing the key implementation changes.
Linked Issues check	✅ Passed	The PR fully addresses all acceptance criteria from issue #1186: Constraints tracks source files for each constraint, merged-constraints.txt includes inline provenance comments, conflict error messages include source file names, and tests are updated.
Out of Scope Changes check	✅ Passed	All changes are directly scoped to issue #1186 requirements: provenance tracking infrastructure, error message enrichment, and test updates. No extraneous modifications detected.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 3

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@src/fromager/constraints.py`:
- Around line 168-177: get_provenance currently returns a shallow copy of
self._provenance so callers can mutate nested lists and change internal state;
update get_provenance to return a deep copy of the provenance mapping (e.g., use
copy.deepcopy on self._provenance[canonicalize_name(name)] or construct a new
dict copying each list) so callers cannot modify internal data structures
accessed via get_provenance; ensure you still canonicalize the name with
canonicalize_name(name) and return an empty dict when missing.

In `@tests/test_constraints.py`:
- Around line 306-307: Update the test that asserts InvalidConstraintError from
c.add_constraint to ensure the exception message contains both conflicting
sources: change the pytest.raises regex (the match= argument) to require both
"base.txt" and "override.txt" (for example using a positive lookahead pattern
like (?=.*base\.txt)(?=.*override\.txt)) so the test fails if either source is
missing from the error message; target the assertion surrounding the
c.add_constraint call that raises InvalidConstraintError.
- Around line 275-281: The test test_provenance_returns_copy currently only
verifies the outer dict is copied; update it to also check for nested mutation
leakage by mutating a list value returned by Constraints.get_provenance and
asserting that the internal provenance inside the Constraints instance is not
changed. Specifically, after using Constraints.add_constraint("foo>=1.0",
source="a.txt") call c.get_provenance("foo"), append/modify the returned list
(from the dict value) and then call c.get_provenance("foo") again to assert the
original list value remains unchanged, ensuring get_provenance returns
deep-copied (or otherwise protected) list values.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 46b1bdaf-7ff4-4858-b8d0-c2bc42261980

📥 Commits

Reviewing files that changed from the base of the PR and between b6c8fc7 and 424ccfb.

📒 Files selected for processing (5)

• src/fromager/constraints.py
• src/fromager/resolver.py
• tests/test_constraints.py
• tests/test_context.py
• tests/test_resolver.py