Fix unhelpful message when a metadata file (fixes #1145)

[spoorcc]

Fix #1145

Summary by CodeRabbit

• Bug Fixes
  • Fixed handling and messaging for corrupted/invalid metadata files: such projects are reported as having no prior fetch and operations continue instead of erroring.
  • Update/check commands now report invalid metadata explicitly and proceed with fetch or surface tag mismatches appropriately.
• Tests
  • Added scenarios covering invalid metadata cases to ensure consistent user-facing behavior.

[coderabbitai]

Warning

Rate limit exceeded

@spoorcc has exceeded the limit for the number of commits that can be reviewed per hour. Please wait 6 minutes and 11 seconds before requesting another review.

Your organization is not enrolled in usage-based pricing. Contact your admin to enable usage-based pricing to continue reviews beyond the rate limit, or try again in 6 minutes and 11 seconds.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout.

Please see our FAQ for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

Run ID: 6e965551-a898-48bc-9730-5d30b2e372fd

📥 Commits

Reviewing files that changed from the base of the PR and between 36f6325 and da7ffc2.

📒 Files selected for processing (2)

• dfetch/project/metadata.py
• tests/test_metadata.py

Walkthrough

Introduce a new InvalidMetadataError and update metadata parsing and callers to treat YAML parse/structure failures as this error; adjust reporting and subproject logic to handle invalid metadata uniformly; add BDD tests and a changelog entry for the fix.

Changes

Cohort / File(s)	Summary
Metadata parsing dfetch/project/metadata.py	Add class InvalidMetadataError(Exception) and re-raise YAML parse/structure errors as InvalidMetadataError from Metadata.from_file() instead of letting yaml.YAMLError/KeyError/TypeError propagate.
Subproject handling dfetch/project/subproject.py	Catch InvalidMetadataError (replacing previous TypeError handling) in on_disk_version() and _on_disk_hash(); behavior unchanged (log warning and return None).
Reporting logic dfetch/commands/report.py, dfetch/reporting/stdout_reporter.py	Extend exception handling to treat InvalidMetadataError the same as missing metadata when determining/printing a project’s version/last-fetch info; import InvalidMetadataError where needed.
Behavioral tests features/handle-invalid-metadata.feature	Add scenarios covering invalid .dfetch_data.yaml (invalid YAML syntax) for dfetch update and dfetch check; remove global @update feature tag.
Test step impl features/steps/generic_steps.py	Add a @given step that creates an invalid YAML payload (key: [unclosed bracket) in the project metadata file.
Changelog CHANGELOG.rst	Add entry under “Release 0.14.0 (unreleased)” noting the fix for unclear/error message when metadata file is malformed (#1145).

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

🚥 Pre-merge checks | ✅ 4 | ❌ 2

❌ Failed checks (2 warnings)

Check name	Status	Explanation	Resolution
Title check	⚠️ Warning	The title is incomplete and truncated: 'Fix unhelpful message when a metadata file' is missing the main clause describing what should happen.	Complete the title to clearly describe the fix, e.g., 'Fix unhelpful error message for invalid metadata files' or similar.
Description check	⚠️ Warning	The PR description is minimal and provides no detail beyond the reference to #1145; it lacks explanation of the solution or changes made.	Add a clear description of how the fix improves error handling, e.g., explaining the new InvalidMetadataError exception and its benefits to users.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Linked Issues check	✅ Passed	The PR successfully addresses issue #1145 by introducing InvalidMetadataError exception and improving error handling for invalid metadata files throughout the codebase.
Out of Scope Changes check	✅ Passed	All changes are directly related to handling invalid metadata files as specified in issue #1145; no out-of-scope modifications were introduced.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.

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

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feature/improve-metadata-error

---

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 the current code and only fix it if needed.

Inline comments:
In `@CHANGELOG.rst`:
- Line 16: The changelog line "* Fix unhelpful message when a metadata file
(`#1145`)" is incomplete; update that entry (the line containing that exact text)
to a complete sentence such as "Fix unhelpful error message when a metadata file
is missing or malformed (`#1145`)" so the release note clearly describes the bug
and resolution.

In `@dfetch/project/metadata.py`:
- Around line 91-94: Introduce a new InvalidMetadataError exception and modify
Metadata.from_file (the try block that does
yaml.safe_load(metadata_file)["dfetch"]) to raise InvalidMetadataError for YAML
errors, for non-dict YAML results, and when the top-level "dfetch" key is
missing (wrap KeyError/TypeError into InvalidMetadataError and preserve the
original exception via "from"). Then update every caller that currently only
catches FileNotFoundError or (TypeError, ValueError) to catch
InvalidMetadataError instead—i.e., the places that call Metadata.from_file (the
stdout reporter, the report command handler, and the subproject metadata-loading
methods) so they handle invalid metadata consistently.

In `@features/handle-invalid-metadata.feature`:
- Around line 9-31: Duplicate or extend the existing "Metadata with invalid YAML
syntax is treated as invalid" scenario so it also exercises the `dfetch check`
command (in addition to `dfetch update`); either add a second Scenario that
mirrors the current steps but runs When I run "dfetch check" and asserts the
same diagnostic lines about ".dfetch_data.yaml is an invalid metadata file..."
in the Then block, or convert the scenario into a Scenario Outline with an
Examples table for the two commands ("dfetch update", "dfetch check") to ensure
both paths trigger the same error messages.

🪄 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: ASSERTIVE

Plan: Pro

Run ID: ec46388b-5ce2-46a1-a4cb-2a1a15e066bb

📥 Commits

Reviewing files that changed from the base of the PR and between ac7dd04 and cbffeeb.

📒 Files selected for processing (5)

• CHANGELOG.rst
• dfetch/project/metadata.py
• dfetch/project/subproject.py
• features/handle-invalid-metadata.feature
• features/steps/generic_steps.py

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@dfetch/project/metadata.py`:
- Around line 95-102: The loaded YAML value for "dfetch" may be non-mapping
(list, scalar, None), which later causes an AttributeError in Metadata.__init__;
before calling cls(data) (the class constructor invoked by return cls(data)),
validate that data is a mapping/dict (e.g., isinstance(data, dict) or
collections.abc.Mapping) and raise InvalidMetadataError with a clear message if
not; place this check immediately after data: Options =
yaml.safe_load(metadata_file)["dfetch"] and before return cls(data) so malformed
YAML produces InvalidMetadataError instead of leaking AttributeError from
__init__.

🪄 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: ASSERTIVE

Plan: Pro

Run ID: 47fbc723-9d59-421f-8888-a1f12c31b052

📥 Commits

Reviewing files that changed from the base of the PR and between cbffeeb and 36f6325.

📒 Files selected for processing (6)

• CHANGELOG.rst
• dfetch/commands/report.py
• dfetch/project/metadata.py
• dfetch/project/subproject.py
• dfetch/reporting/stdout_reporter.py
• features/handle-invalid-metadata.feature