[3/n] [dropshot-api-manager] handle unparseable git ref files gracefully

[sunshowers]

Git ref files can become unparseable due to merge conflicts (conflict
markers), non-canonical formatting (backslashes on Windows, missing
trailing newlines), or corruption. Previously, these would cause errors
that blocked the tool from running.

This commit makes the tool resilient to such issues:

• Define a canonical git ref format: forward slashes in paths, single
  trailing newline. The GitRef::needs_rewrite() method detects files
  that need normalization.
• Normalize backslashes to forward slashes during parsing and display,
  ensuring cross-platform compatibility.
• Add load_unparseable() to track malformed local files so they can
  be regenerated during generate instead of blocking with errors.
• Unparseable git ref files are now detected, warned about, and
  automatically regenerated from blessed content.

Also refactor git ref/JSON filename handling into ApiSpecFileName:

• git_ref_basename() / json_basename() for basename conversion
• to_git_ref_filename() as the inverse of to_json_filename()

This simplifies the Fix execution code in resolved.rs and consolidates
the conversion logic in one place.

[Copilot]

Pull request overview

This PR enhances the dropshot-api-manager to gracefully handle unparseable or malformed git ref files, which can occur due to merge conflicts, cross-platform formatting differences, or file corruption. Previously, such issues would block the tool from running.

Key changes:

• Adds load_unparseable() method to track malformed files for regeneration instead of hard errors
• Defines canonical git ref format (forward slashes, single trailing newline) with automatic detection and rewriting via GitRef::needs_rewrite()
• Refactors git ref/JSON filename conversions into dedicated ApiSpecFileName methods

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
crates/integration-tests/tests/integration/git_ref.rs	Adds comprehensive integration tests for unparseable git refs (conflict markers, non-canonical format, empty files, invalid commit hashes)
crates/dropshot-api-manager/src/spec_files_local.rs	Updates git ref loading to detect unparseable/non-canonical files and mark them for regeneration
crates/dropshot-api-manager/src/spec_files_generic.rs	Implements load_unparseable() method to track unparseable files as warnings rather than errors
crates/dropshot-api-manager/src/resolved.rs	Refactors to use new ApiSpecFileName methods for git ref/JSON filename conversions and canonical format writing
crates/dropshot-api-manager/src/git.rs	Adds to_file_contents() for canonical format output, needs_rewrite() for format validation, normalizes backslashes in parsing/display, and adds new error variants
crates/dropshot-api-manager-types/src/validation.rs	Adds filename conversion methods: to_git_ref_filename(), to_json_filename(), git_ref_basename(), json_basename()

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.