Add emissions configuration schema (inventories, species maps, sources) to mechanism v1

[smeechncar]

Summary

Closes #272.

Adds a new emissions::v1 namespace to MechanismConfiguration that
parses YAML-based emissions configs for consumption by MUSICA/MIEM.

What's new

• include/mechanism_configuration/emissions/v1/types.hpp — public types
  (EmissionsConfig, SourceDescriptor, Inventory, SpeciesMap, etc.)
• include/mechanism_configuration/emissions/v1/parse.hpp — public API:
  ParseEmissions(path) and ParseEmissions(string)
• src/emissions/v1/parser.cpp — full implementation (yaml-cpp private,
  not exposed in headers); supports ${VAR} / ${VAR:-default} env var
  expansion in data root
• 12 new ErrorCode values in errors.hpp / errors.cpp
• 14 unit tests covering valid configs, all error paths, and optional-section
  handling

Design notes

Follows the existing v1 chemistry parser pattern: std::expected<T, Errors>
return type, ErrorCode enum errors, yaml-cpp kept private to the library.
Three intentional differences from the MICM parser shape are noted for
reviewers:

1. No Parse(YAML::Node) overload — emissions configs are always file/string
   entry points
2. No separate CheckSchema()/Build() split — validation and construction
   are a single pass
3. Types live in emissions::v1::types (deeper namespace) to avoid collision
   with mechanism_configuration::types

Aside for MC maintainers

While reviewing this I noticed that yaml-cpp headers currently leak into
MC's public headers in a few places (direct YAML::Node parameters on
public APIs). This isn't blocking for MIEM (MIEM only links against MUSICA,
not MC directly), but it could cause issues for downstream consumers. Flagging
here in case the maintainers want to address it in a follow-up.

Test plan

• All 14 new emissions tests pass
• All 19 existing chemistry tests still pass (no regressions)
• Build tested on Derecho with -DMECH_CONFIG_USE_FMT=ON (Intel LLVM,
  no <format> header)

[codecov-commenter]

Codecov Report

❌ Patch coverage is 89.81481% with 33 lines in your changes missing coverage. Please review.
✅ Project coverage is 88.96%. Comparing base (6633a50) to head (42f29c2).
⚠️ Report is 1 commits behind head on main.

Files with missing lines	Patch %	Lines
src/v1/emissions_parser.cpp	89.26%	19 Missing ⚠️
src/errors.cpp	0.00%	10 Missing ⚠️
src/validate.cpp	95.12%	4 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #281      +/-   ##
==========================================
+ Coverage   88.93%   88.96%   +0.03%     
==========================================
  Files          38       39       +1     
  Lines        1627     1949     +322     
==========================================
+ Hits         1447     1734     +287     
- Misses        180      215      +35     

Files with missing lines	Coverage Δ
include/mechanism_configuration/errors.hpp	57.14% <ø> (ø)
include/mechanism_configuration/mechanism.hpp	100.00% <ø> (ø)
src/detail/v1/parser.hpp	100.00% <ø> (ø)
src/v1/parser.cpp	87.04% <100.00%> (+3.20%)	⬆️
src/v1/utils.cpp	100.00% <100.00%> (ø)
src/validate.cpp	89.34% <95.12%> (+4.12%)	⬆️
src/errors.cpp	35.13% <0.00%> (-13.02%)	⬇️
src/v1/emissions_parser.cpp	89.26% <89.26%> (ø)

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[smeechncar]

Next steps (for context)...

This PR is the first of three pieces. Once merged, the plan is:

1. MUSICA — add a translator (musica::emissions::Translate) that calls ParseEmissions, walks the resulting EmissionsConfig, and constructs MIEM's EmissionsBuilder / Source objects. MUSICA is the only layer that sees both MC and MIEM types.
2. MIEM integration test — an end-to-end test using a real CAMS-GLOB NetCDF file to verify the full config → translate → runtime pipeline.

Flagging so reviewers know the public types in emissions::v1::types and the two ParseEmissions overloads are the stable interface MUSICA will depend on.

[K20shores]

We want the description of emissions to be agnostic of the miem tool. I think it would be better to include a new section in the mechanism object called Emissions and put all created structs into that.

This would mean our v1.x format would have a new keyword, emissions, which essentially takes lines 5-end of examples/emissions/v1/emissions.yaml and indents it under the emissions key.

I guess I'll think about this a bit longer before adding more specific comments.

[boulderdaze]

Would you mind updating the PR title? We include PR titles in the release notes, so we prefer them to be more descriptive and easier to read

[K20shores]

Getting there, a couple of more changes. We also need to be able to call Validate and have the emissions be checked. It would be nice. After adding the validation code (which probably involves expanding the semantic refernces to work with emissions) please also update test/unit/test_validate.cpp so that it does an in-code check of emissions

[smeechncar]

Re: needing Validate to check emissions — done in 51c4647. Emissions are now checked by Validate() for in-code Mechanisms too, not just YAML parses: extended semantics::Input with EmissionsRef/SpeciesMapRef/SourceRef and moved the duplicate/unknown-reference/scaling-sum checks into ValidateSemantics. Added 9 new cases to test/unit/test_validate.cpp covering this.

One deliberate tightening worth flagging: a source referencing an unknown inventory/species-map is now always rejected, even if that section is entirely absent from the config. Previously that combination silently passed. Let me know if you'd rather it stay permissive there.

[boulderdaze]

Looks good to me. I don't have any additional comments beyond the ones already mentioned

[K20shores]

This seems good to me. I think in the future we may add some validation to check that species are mapped to valid species defined in the mechanism, but we probably don't need to require that check yet. This looks good to me

[smeechncar]

Merged main into this branch to resolve the conflict that popped up after approval — it was trivial: both branches had added a new #include at the same spot in src/v1/parser.cpp (this branch's detail/v1/emissions_parser.hpp vs. main's detail/error_format.hpp). Kept both, alphabetized.

That merge also pulled in main's refactor moving the ErrorLocation fmt formatter out of the public errors.hpp into src/detail/error_format.hpp. src/v1/emissions_parser.cpp was added on this branch before that refactor landed, so it needed the same include added to keep building. Rebuilt and ran the full ctest suite locally (33/33 passing) before pushing. PR is mergeable now.

[smeechncar]

Thank you both @boulderdaze @K20shores for reviewing this one!