Canonicalize and share Git checkout paths #1434

Summary

Use one canonical Git checkout path so bootstrap, build replay, step commands, and plugins find the same checkout when a package name has different valid spellings.

Context

Configured Git downloads and step prepare-source independently construct <work-dir>/<name>-<version>/<name>-<version>. The downloader uses req.name as spelled. Bootstrap records canonicalize_name(req.name) as dist in build-order.json, and build-sequence reconstructs the requirement from dist. For zope_event==1.0, bootstrap creates work-dir/zope_event-1.0/zope_event-1.0, while replay looks under work-dir/zope-event-1.0/zope-event-1.0. It clones again and can fail when the source repository is unavailable. step prepare-source has the same spelling-dependent lookup.

The double-nested layout is documented for plugin authors in docs/reference/hooks.rst. The parent directory stores build metadata. Archive downloads already use a canonical package name.

Review comments: checkout-name bug and shared-path request. Related: #1431 covers reuse of a matching, clean checkout.

Acceptance Criteria

• Provide a public helper that returns the double-nested checkout path from a work directory, package name, and resolved version. It canonicalizes the package name internally.
• Use the helper in configured Git downloads and step prepare-source when no explicit --source-path is provided.
• Keep the existing double-nested layout, checkout validation, cleanup behavior, and explicit --source-path support. Only the package-name spelling in the generated path changes.
• Keep archive filenames canonical and leave the original Requirement unchanged for resolver and hook calls.
• Test that a checkout downloaded for zope_event is reused during replay under zope-event in the same work directory, including when the source repository is unavailable and with cleanup both enabled and disabled.
• Test that step prepare-source finds the canonical checkout when given a noncanonical package spelling.
• Document the canonical path and helper for plugin authors and in the resolver architecture description.

Definition of Done

• Code and focused regression tests are complete.
• File-scoped formatting, linting, type checking, and affected tests pass.
• Documentation is updated.
• The change is reviewed and merged.

Implementation Notes

src/fromager/packagesettings/_resolver.py and src/fromager/commands/step.py are the two path constructors. src/fromager/gitutils.py is an existing module both can use without an import cycle. finders.find_source_dir() already considers canonical names. No build-order format change is needed.