Add physics constraint validation and auto-generated docs

[sbryngelson]

User description

Summary

• Adds physics warning infrastructure to the case validator (warn() alongside existing prohibit()) with warnings for EOS parameter sanity, volume fraction sums, alpha-rho consistency, patch bounds, velocity components in inactive dimensions, and more
• Validates all 134 example cases in CI via a new lint gate job
• Auto-generates physics_constraints.md from PHYSICS_DOCS metadata in case_validator.py + AST-extracted validation rules, replacing the hand-written doc
• Adds _format_message() helper that handles Fortran % accessor escaping for Doxygen, AST artifact cleanup (istr→i), and code-token backticking
• Documents the "How to add physics constraints" workflow in the contributing guide

Test plan

• ./mfc.sh validate displays physics warnings correctly
• ./mfc.sh build -t documentation generates physics_constraints.md with proper formatting
• All 134 example cases pass validation (./mfc.sh validate --examples)
• ./mfc.sh lint passes (doc references, formatting, spell check)
• Rendered Doxygen HTML shows Fortran % accessors correctly (e.g., fluid_pp(i)%gamma)

🤖 Generated with Claude Code

---

CodeAnt-AI Description

Add non-fatal physics warnings, auto-generate a Physics Constraints doc, and validate all examples in CI

What Changed

• Validator now emits non-fatal physics warnings (e.g., volume-fraction sum, alpha–rho mismatches, EOS gamma sanity, domain/patch bounds, velocity in inactive dimensions) and returns them to callers instead of treating them as errors
• The CLI validate and case-generation flows display these warnings in yellow so users see potential physics issues without aborting runs
• Physics constraints documentation is auto-generated from inline PHYSICS_DOCS metadata plus extracted validator rules; a new physics_constraints.md is produced and wired into docs generation and the readme
• CI "validate examples" step now runs validation across all example cases (and the scaling example was replaced/renamed), and small example fixes were applied so example validation passes
• Formatting helpers and docs tooling improvements ensure Fortran-style parameter names render correctly in generated docs

Impact

✅ Clearer physics warnings during validation
✅ Auto-generated physics constraints docs
✅ Fewer broken example validations in CI

💡 Usage Guide

Checking Your Pull Request

Every time you make a pull request, our system automatically looks through it. We check for security issues, mistakes in how you're setting up your infrastructure, and common code problems. We do this to make sure your changes are solid and won't cause any trouble later.

Talking to CodeAnt AI

Got a question or need a hand with something in your pull request? You can easily get in touch with CodeAnt AI right here. Just type the following in a comment on your pull request, and replace "Your question here" with whatever you want to ask:

@codeant-ai ask: Your question here

This lets you have a chat with CodeAnt AI about your pull request, making it easier to understand and improve your code.

Example

@codeant-ai ask: Can you suggest a safer alternative to storing this secret?

Preserve Org Learnings with CodeAnt

You can record team preferences so CodeAnt AI applies them in future reviews. Reply directly to the specific CodeAnt AI suggestion (in the same thread) and replace "Your feedback here" with your input:

@codeant-ai: Your feedback here

This helps CodeAnt AI learn and adapt to your team's coding style and standards.

Example

@codeant-ai: Do not flag unused imports.

Retrigger review

Ask CodeAnt AI to review the PR again, by typing:

@codeant-ai: review

Check Your Repository Health

To analyze the health of your code repository, visit our dashboard at https://app.codeant.ai. This tool helps you identify potential issues and areas for improvement in your codebase, ensuring your repository maintains high standards of code health.

Summary by CodeRabbit

• New Features

  • Added Physics Constraints documentation and an automated generator.

• Improvements

  • Validator now emits and reports non-fatal physics warnings and includes more cross-cutting checks.
  • CI/tooling now validates all examples and summarizes pass/fail counts.

• Documentation

  • New guidance for documenting physics constraints; multiple docs updated to escape percent signs and reference renamed example scripts.

• Chores

  • Removed a deprecated example script and added a documentation ignore rule.