Quality of life improvements for MFC toolchain

[sbryngelson]

User description

PR Type

Enhancement, Tests, Documentation

Description

Major Quality of Life Improvements for MFC Toolchain

• Centralized Parameter System: Consolidated ~3,300 MFC case parameters into unified registry with descriptions, constraints, and dependencies (params/definitions.py, params/descriptions.py)

• Enhanced CLI Architecture: Refactored argument parsing with declarative schema-based command definitions, auto-generated argparse parsers, and shell completion support (cli/schema.py, cli/argparse_gen.py, cli/completion_gen.py)

• Improved User Experience: Added interactive user guide with topic-based help system, contextual tips, and first-time user onboarding (user_guide.py, completion.py)

• Case Template System: New case template generator with built-in minimal templates and example-based case creation (init.py)

• Parameter Discovery: New CLI command for searching and exploring parameters with filtering and statistics (params_cmd.py)

• Enhanced Validation: Comprehensive physics constraint validation for bubbles, patches, time stepping, and acoustic sources with improved error reporting (case_validator.py)

• Build System Improvements: Added progress bars, streaming output, and detailed error reporting with contextual hints (build.py)

• Test Infrastructure: Comprehensive parameter validation test suite including negative tests, mutation testing, snapshot regression testing, and coverage analysis (params_tests/ module)

• Documentation Generation: Auto-generated CLI reference and parameter documentation from schema definitions (cli/docs_gen.py, params/generators/docs_gen.py)

• Code Quality: Fixed formatting issues across example cases and benchmarks (PEP 8 compliance for imports and comments)

Diagram Walkthrough

flowchart LR
  A["Parameter Registry<br/>definitions.py<br/>descriptions.py"] -->|"loads"| B["Case Validator<br/>Enhanced Constraints"]
  A -->|"powers"| C["Parameter Search<br/>params_cmd.py"]
  D["CLI Schema<br/>schema.py"] -->|"generates"| E["Argparse Parser<br/>argparse_gen.py"]
  D -->|"generates"| F["Shell Completions<br/>completion_gen.py"]
  D -->|"generates"| G["CLI Docs<br/>docs_gen.py"]
  E -->|"used by"| H["Enhanced Args<br/>args.py"]
  H -->|"provides"| I["User Guide<br/>user_guide.py"]
  J["Build System<br/>build.py"] -->|"reports"| I
  B -->|"tested by"| K["Test Suite<br/>negative/mutation/<br/>snapshot/coverage"]
  L["Case Templates<br/>init.py"] -->|"creates"| M["New Cases"]

Loading

File Walkthrough

	Relevant files
Enhancement	15 files descriptions.py Centralized parameter descriptions and documentation system toolchain/mfc/params/descriptions.py New file providing centralized parameter descriptions for ~3,300 MFC case parameters Includes manual descriptions dictionary extracted from documentation Implements pattern-based auto-generation for indexed parameters (e.g., patch_icpp(N)%geometry) Provides fallback naming convention inference for undocumented parameters +552/-0  case_dicts.py Migrate parameter definitions to central registry                toolchain/mfc/run/case_dicts.py Refactored to load parameter definitions from central registry instead of hardcoded dictionaries Replaced ~500 lines of manual parameter type definitions with dynamic loading via _load_from_registry() Updated CASE_OPTIMIZATION to derive from registry metadata instead of hardcoded list Added comprehensive docstrings to ParamType enum and utility functions +61/-523 commands.py Unified CLI command definitions and schema                              toolchain/mfc/cli/commands.py New file defining all MFC CLI commands as a single source of truth Includes 20+ commands (build, run, test, clean, validate, new, params, etc.) with full argument specifications Defines common argument sets, command aliases, and help topics Provides structured schema for generating argparse parsers, completions, and documentation +1003/-0 case_validator.py Enhanced case validation with physics constraints                toolchain/mfc/case_validator.py Added check_parameter_types() to validate logical parameters are 'T' or 'F' Enhanced check_bubbles_euler() with validation for bubble physics parameters (R0ref, p0ref, viscosities, surface tension) Added check_patch_physics() to validate initial condition constraints (positive pressure, valid volume fractions, positive dimensions) Improved check_time_stepping() to handle multiple time stepping modes (CFL-based, adaptive, fixed) Enhanced check_acoustic_source() with physics validation (positive frequency, wavelength, gaussian parameters) Added _is_numeric() helper and _format_errors() for better error reporting with hints +257/-20 definitions.py Consolidated parameter definitions module with constraint and dependency support toolchain/mfc/params/definitions.py New file consolidating ~3,300 parameter definitions into a single compact module using loops instead of a definitions/ directory Defines parameter constraints (choices, min/max values) and dependencies (requires/recommends relationships) Implements _load() function that registers all parameters across COMMON, PRE_PROCESS, SIMULATION, and POST_PROCESS stages Supports indexed parameters for patches, fluids, boundary conditions, acoustic sources, probes, and other multi-instance configurations +394/-0  user_guide.py New user guide with enhanced help and interactive onboarding system toolchain/mfc/user_guide.py New comprehensive user guide module providing enhanced help system with Rich formatting Implements topic-based help system covering GPU configuration, cluster setup, batch jobs, and debugging Provides contextual tips after build failures, case errors, test failures, and run failures Includes onboarding for first-time users with welcome message and interactive menu-driven interface +594/-0  init.py New case template generator with built-in and example-based templates toolchain/mfc/init.py New case template generator module for creating new case files from built-in or example templates Provides three built-in minimal templates: 1D_minimal, 2D_minimal, and 3D_minimal with documented parameters Implements create_case() function to generate new cases from templates or copy from examples directory Includes list_templates() to display available templates and get_available_templates() for programmatic access +500/-0  args.py Refactored argument parsing with centralized CLI schema and enhanced help toolchain/mfc/args.py Refactored argument parsing to use auto-generated parsers from centralized CLI schema instead of manual argparse setup Added enhanced help output with print_help(), print_command_help(), and topic-based help system integration Implemented _handle_enhanced_help() to provide rich formatting before argparse help Deferred test case loading to avoid slow startup for non-test commands Added support for command aliases and improved help for first-time users +106/-151 build.py Enhanced build system with progress bars and improved error reporting toolchain/mfc/build.py Added progress bar visualization for build process with ninja/make output parsing using regex patterns Implemented _run_build_with_progress() function supporting streaming mode (-v) and interactive progress bars Added _show_build_error() to display detailed error information from captured subprocess output Enhanced configure, build, and install steps with status indicators (✓/✗), timing information, and contextual error tips Improved verbosity levels: default (progress bar), -v (streaming), -vv+ (full compiler output) +339/-7  completion_gen.py New shell completion generator for bash and zsh from CLI schema toolchain/mfc/cli/completion_gen.py New module generating bash and zsh shell completion scripts from CLI schema Implements generate_bash_completion() and generate_zsh_completion() functions for auto-generated completions Supports completion for commands, options, positional arguments, and file types (Python, YAML, pack files) Handles command aliases, mutually exclusive groups, and common argument sets in completion generation +353/-0  argparse_gen.py New argparse generator from declarative CLI schema              toolchain/mfc/cli/argparse_gen.py New module generating argparse parsers from declarative CLI schema definitions Implements generate_parser() to convert schema into complete ArgumentParser with subcommands and argument groups Handles MFCConfig boolean pair arguments (--flag/--no-flag) dynamically from dataclass fields Supports positional arguments, common argument sets, mutually exclusive groups, and nested subcommands +226/-0  params_cmd.py Parameter search and discovery CLI command                              toolchain/mfc/params_cmd.py New module providing CLI command for searching and exploring ~3,300 MFC case parameters Implements parameter search with filtering by type and collapsing of indexed parameters Displays parameter statistics, families, and descriptions with configurable output formats Includes helper functions for pattern matching, result formatting, and alternative suggestions +330/-0  test.py Enhanced test reporting and failure feedback                          toolchain/mfc/test/test.py Enhanced test output formatting with improved progress display showing test names prominently Added test duration tracking and comprehensive summary report with visual panel formatting Implemented real-time failure feedback with error type detection and helpful hints Added failed_tests tracking and _print_test_summary() function for detailed failure reporting +136/-18 completion.py Shell completion installation and management                          toolchain/mfc/completion.py New module for shell completion installation and management Implements auto-detection and installation for bash and zsh shells Manages completion script installation to ~/.local/share/mfc/completions/ Provides status checking, uninstall, and RC file configuration +220/-0  schema.py CLI schema dataclass definitions                                                  toolchain/mfc/cli/schema.py New module defining dataclasses for CLI schema (single source of truth) Implements Argument, Positional, Command, CommonArgumentSet, and CLISchema dataclasses Defines enums for ArgAction and CompletionType with completion configuration Provides helper methods for command lookup and argument flag generation +204/-0
Formatting	7 files case.py Fix comment formatting in example case                                      examples/2D_shearlayer/case.py Fixed comment formatting from #' to # ' for consistency with Python style guidelines +4/-4      case.py Fix import statement formatting                                                    examples/1D_bubblescreen/case.py Split multi-import statement into separate lines for PEP 8 compliance +2/-1      case.py Code formatting improvement for import statements                examples/nD_perfect_reactor/case.py Minor formatting change: split import json, argparse into separate lines for PEP 8 compliance +2/-1      case.py Code formatting and style improvements                                      benchmarks/5eq_rk3_weno3_hllc/case.py Reformatted import statements to follow PEP 8 (one import per line) Converted multi-line comments from ## to single # for consistency +9/-7      case.py Comment style normalization                                                            examples/2D_axisym_shockwatercavity/case.py Converted multi-line comments from ## to single # for consistency +6/-6      case.py Comment style normalization                                                            examples/2D_ibm_steady_shock/case.py Converted multi-line comment from ## to single # for consistency +1/-1      export.py Import statement formatting                                                            examples/scaling/export.py Reformatted import statements to follow PEP 8 (one import per line) +5/-1
Tests	6 files negative_tests.py Negative test case generator for validator constraints      toolchain/mfc/params_tests/negative_tests.py New test module generating negative test cases that intentionally violate validator constraints Defines BASE_CASE with valid parameters and ConstraintTest dataclass for test specification Implements generate_constraint_tests() covering simulation domain, model equations, time stepping, WENO, boundary conditions, and acoustic source constraints Provides run_constraint_tests() and print_test_report() for validation and reporting +358/-0  mutation_tests.py Mutation testing for validator coverage analysis                  toolchain/mfc/params_tests/mutation_tests.py New module for mutation testing that systematically mutates valid parameters to verify validator coverage Defines MUTATIONS dictionary with invalid values for ~40 parameters across numeric, boolean, physics, and numerics categories Implements mutation application and validation checking with result tracking Provides comprehensive reporting on catch rates and missed mutations by parameter +279/-0  snapshot.py Validation snapshot tool for regression testing                    toolchain/mfc/params_tests/snapshot.py New module for capturing and comparing validation snapshots of example cases for regression testing Implements CaseSnapshot and ValidationResult dataclasses for storing validation state Provides functions to load case parameters, validate across stages, and save/load snapshots to JSON Includes comparison logic to detect changes in validation behavior across refactoring +301/-0  coverage.py Constraint coverage analysis tool                                                toolchain/mfc/params_tests/coverage.py New module analyzing constraint coverage by parsing case_validator.py AST Extracts all self.prohibit() calls and maps them to validation stages Generates coverage reports showing constraints per method and stage Provides JSON export and console reporting of coverage metrics +278/-0  runner.py Test safety net runner and orchestrator                                    toolchain/mfc/params_tests/runner.py New main entry point for building and verifying parameter validation test suite Implements build_safety_net() to capture parameter inventory, validation snapshots, and constraint coverage Provides verify_safety_net() to detect unintended validation behavior changes Includes CLI interface supporting build, verify, summary, and report generation commands +258/-0  inventory.py Parameter inventory export and analysis                                    toolchain/mfc/params_tests/inventory.py New module exporting parameter inventory with types and validation stages Implements export_parameter_inventory() categorizing parameters by stage and type Extracts dynamic parameter patterns with normalization and example tracking Provides JSON export and console summary reporting of parameter metadata +176/-0
Documentation	2 files docs_gen.py CLI documentation generator from schema                                    toolchain/mfc/cli/docs_gen.py New module generating markdown CLI reference documentation from schema definitions Formats command sections with usage, arguments, options tables, examples, and subcommands Organizes commands by category (core, utility, development, CI, other) Generates quick reference tables and common options documentation +322/-0  docs_gen.py Parameter documentation generator                                                toolchain/mfc/params/generators/docs_gen.py New module generating markdown documentation for all MFC case parameters Organizes parameters by family with descriptions, types, and constraints Generates table of contents and detailed family sections with pattern grouping for large families Includes command-line reference examples and footer with CLI search instructions +234/-0
Additional files	74 files docs.yml +1/-1      lint-toolchain.yml +3/-0      settings.json +21/-9    CMakeLists.txt +1/-1      README.md +46/-0    case.py +3/-1      case.py +3/-1      case.py +3/-1      case.py +3/-1      authors.md +2/-0      case.md +5/-1      cli-reference.md +667/-0  docker.md +2/-0      expectedPerformance.md +2/-0      getting-started.md +40/-0    gpuParallelization.md +2/-0      papers.md +2/-0      parameters.md +1000/-0 readme.md +29/-18  references.md +2/-0      running.md +2/-0      testing.md +2/-0      troubleshooting.md +151/-0  visualization.md +2/-0      examples.sh +1/-1      index.html +1/-1      plot.py +3/-3      case.py +1/-1      case.py +3/-1      case.py +2/-1      case.py +2/-1      case.py +2/-1      case.py +2/-1      case.py +2/-1      case.py +6/-4      casefile.py +8/-5      case.py +2/-2      case.py +9/-7      case.py +2/-1      case.py +2/-1      case.py +6/-4      case.py +2/-2      case.py +6/-6      case.py +6/-6      analyze.py +2/-1      case.py +7/-3      mfc.sh +22/-5    format.sh +53/-19  format_python.sh +6/-1      lint.sh +1/-1      python.sh +235/-4  _mfc +449/-0  mfc.bash +191/-0  main.py +60/-11  mfc-case-schema.json +24427/-0 case.py +37/-7    clean.py +22/-0    __init__.py +37/-0    common.py +26/-1    gen_case_constraints_docs.py +1/-0      generate.py +116/-0  ide.py +136/-0  __init__.py +10/-0    __init__.py +5/-0      case_dicts_gen.py +46/-0    json_schema_gen.py +128/-0  registry.py +52/-0    schema.py +88/-0    validate.py +148/-0  __init__.py +8/-0      input.py +20/-5    run.py +29/-1    validate.py +58/-0    pyproject.toml +1/-1

---

CodeAnt-AI Description

Centralize parameters, add human-readable parameter descriptions, and unify CLI commands

What Changed

• Added a complete parameter descriptions registry and pattern-based generators so every case parameter (including indexed ones) now has a clear, human-readable description available.
• Replaced the ad-hoc per-stage parameter dictionaries with registry-driven stage views and a single source of truth for parameter types, schema, validator, and GPU case-optimization lists — get valid parameter lists and JSON schema from the central registry.
• Introduced a declarative CLI schema that defines all user-facing commands and options (build, run, test, validate, clean, params, completion, generate, new, packer, etc.), enabling consistent help text, shell completion, examples, and standardized arguments across commands.
• Added a searchable "params" command and feature groups for exploring parameters by feature/family and for showing descriptions or counts.
• Added explicit validate and clean commands and surfaced a --case-optimization option in build/run/test flows for producing GPU-optimized builds.

Impact

✅ Clearer parameter descriptions for case authors
✅ Easier pre-flight case validation (validate command + registry schema)
✅ Consistent CLI experience and reliable shell tab-completion

💡 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

  • Expanded CLI: init/templates, validate (case-only), params search/describe, generate (completions/docs/schema), completion install/uninstall, clean, interactive mode.

• Documentation

  • Doxygen-style restructure and many new pages (CLI reference, parameters, troubleshooting, GPU, performance, getting-started) plus README quick-starts and CLI/parameter docs generation.

• Improvements

  • Centralized parameter registry, richer validation with suggestions, VS Code schema integration, improved build/run progress and verbosity, shell completions and IDE helpers.

• Tests & CI

  • Extensive new tests and added CI smoke checks, lint/test, and toolchain validation steps.

[codeant-ai]

✅ Suggestion: The feature-parameter matching logic only normalizes parameter names (stripping numeric indices in parentheses) for patterns containing '%', so feature entries that use plain base names like "chem_wrt_Y" or "alpha_wrt" will not match indexed parameters such as "chem_wrt_Y(1)" or "alpha_wrt(1)", causing those parameters to be omitted from the corresponding feature groups. Normalizing every parameter name once per iteration and comparing against both the raw and normalized name for exact-match patterns fixes this and makes the matching consistent. [logic error]

Severity Level: Major ⚠️

- ❌ params_cmd.py feature discovery omits indexed parameters
- ⚠️ CLI parameter search returns incomplete results
- ⚠️ Auto-completion may miss indexed parameters

Suggested change

	for pattern in patterns:
	if pattern.endswith("%"):
	# Prefix pattern: match anything starting with this
	# Strip index from param name for comparison
	base_name = re.sub(r"\(\d+\)", "", param_name)
	if base_name.startswith(pattern[:-1]):
	matches.append(param_name)
	break
	elif "%" in pattern:
	# Partial pattern like "patch_icpp%Bx"
	# Match patch_icpp(N)%Bx
	base_name = re.sub(r"\(\d+\)", "", param_name)
	if base_name == pattern or base_name.startswith(pattern):
	matches.append(param_name)
	break
	else:
	# Exact match
	if param_name == pattern:
	# Strip numeric indices in parentheses for consistent matching
	base_name = re.sub(r"\(\d+\)", "", param_name)
	for pattern in patterns:
	if pattern.endswith("%"):
	# Prefix pattern: match anything starting with this
	if base_name.startswith(pattern[:-1]):
	matches.append(param_name)
	break
	elif "%" in pattern:
	# Partial pattern like "patch_icpp%Bx"
	# Match patch_icpp(N)%Bx
	if base_name == pattern or base_name.startswith(pattern):
	matches.append(param_name)
	break
	else:
	# Exact match (also allow match against base name without indices)
	if param_name == pattern or base_name == pattern:

Steps of Reproduction ✅

1. Open the repository Python REPL or run a small script that imports the function defined
at toolchain/mfc/params/descriptions.py:766 (function get_feature_params).

2. Call get_feature_params("chemistry", ["chem_wrt_Y(1)"]) from the REPL (this simulates a
registry containing an indexed parameter chem_wrt_Y(1)). Expectation: the feature group
"chemistry" (FEATURE_GROUPS entry) lists "chem_wrt_Y" but the function returns [] (missing
the indexed parameter).

3. Trace execution inside toolchain/mfc/params/descriptions.py between lines 766–805: the
loop over all_param_names runs, and for the pattern "chem_wrt_Y" the code reaches the
exact-match branch (the final else) which compares param_name == pattern (existing code)
and does not compare the normalized base name without "(1)". As a result, "chem_wrt_Y(1)"
is not considered a match and is omitted.

4. Verify corrected behavior by applying the improved code: re-run
get_feature_params("chemistry", ["chem_wrt_Y(1)"]) and observe the result contains
["chem_wrt_Y(1)"] because the improved code normalizes base_name once per loop and
compares base_name == pattern, causing the indexed parameter to be included.

Prompt for AI Agent 🤖

This is a comment left during a code review.

**Path:** toolchain/mfc/params/descriptions.py
**Line:** 784:801
**Comment:**
	*Logic Error: The feature-parameter matching logic only normalizes parameter names (stripping numeric indices in parentheses) for patterns containing '%', so feature entries that use plain base names like "chem_wrt_Y" or "alpha_wrt" will not match indexed parameters such as "chem_wrt_Y(1)" or "alpha_wrt(1)", causing those parameters to be omitted from the corresponding feature groups. Normalizing every parameter name once per iteration and comparing against both the raw and normalized name for exact-match patterns fixes this and makes the matching consistent.

Validate the correctness of the flagged issue. If correct, How can I resolve this? If you propose a fix, implement it and please make it concise.

[codeant-ai]

Suggestion: The new optional CLI flags ("features", "feature", and "names_only") are read via ARG without defaults, so if the argument registry does not define these keys (e.g., in older tests or non-CLI callers), calling params() will raise a KeyError instead of simply treating the options as disabled; they should default to False/None to avoid spurious crashes. [possible bug]

Severity Level: Major ⚠️

- ❌ params CLI command crashes with KeyError when flags missing.
- ⚠️ Direct Python callers importing params_cmd may raise KeyError.
- ⚠️ Batch scripts/tests invoking params() programmatically affected.

Suggested change

	show_features = ARG("features")
	feature_name = ARG("feature")
	names_only = ARG("names_only")
	show_features = ARG("features", False)
	feature_name = ARG("feature", None)
	names_only = ARG("names_only", False)

Steps of Reproduction ✅

1. Import and call the params() function directly: run Python and execute:

   from toolchain.mfc.params_cmd import params; params()

   This executes the ARG lookups inside params() at toolchain/mfc/params_cmd.py lines
   ~18-30 (the ARG calls at lines 21-23).

2. Inside params(), the code calls ARG("features"), ARG("feature"), ARG("names_only")
(toolchain/mfc/params_cmd.py:21-23). ARG delegates to the global argument registry.

3. If gARG does not contain those keys, state.ARG raises KeyError per its implementation
at toolchain/mfc/state.py:85-93 ("raise KeyError(f\"{arg} is not an argument.\")").

4. Observe a KeyError traceback originating from state.ARG (toolchain/mfc/state.py:85-93)
when params() is invoked without those keys set. This reproduces the crash
deterministically — calling params() without the three keys present triggers the error.
(This is not hypothetical: ARG explicitly raises KeyError when the key is absent.)

Prompt for AI Agent 🤖

This is a comment left during a code review.

**Path:** toolchain/mfc/params_cmd.py
**Line:** 21:23
**Comment:**
	*Possible Bug: The new optional CLI flags ("features", "feature", and "names_only") are read via ARG without defaults, so if the argument registry does not define these keys (e.g., in older tests or non-CLI callers), calling params() will raise a KeyError instead of simply treating the options as disabled; they should default to False/None to avoid spurious crashes.

Validate the correctness of the flagged issue. If correct, How can I resolve this? If you propose a fix, implement it and please make it concise.

[codeant-ai]

CodeAnt AI Incremental review completed.

[coderabbitai]

Actionable comments posted: 1

🤖 Fix all issues with AI agents

In `@toolchain/mfc/params/descriptions.py`:
- Around line 766-804: The partial-pattern branch in get_feature_params is too
permissive: when a pattern contains "%" but doesn't end with it (patterns
variable), the code currently allows base_name.startswith(pattern) which can
wrongly match longer names; change the elif "%" in pattern branch to only
compare the stripped base_name for exact equality to the pattern (using the same
re.sub(r"\(\d+\)", "", param_name) logic already used) and remove the startswith
check so that non-wildcard patterns only match exact names.

🧹 Nitpick comments (2)

toolchain/mfc/params_cmd.py (2)

15-16: Remove unused noqa directive.

The static analysis tool flagged that the noqa: F401 directive on line 16 is unnecessary since F401 is not enabled. The import of definitions appears intentional (likely for side effects), but the noqa comment serves no purpose.

🔧 Suggested fix

     from .params import REGISTRY
-    from .params import definitions  # noqa: F401  pylint: disable=unused-import
+    from .params import definitions  # pylint: disable=unused-import

---

167-179: Redundant conditional branches produce identical output.

Lines 168-171 and 173-176 have identical branches - both produce the same range string format regardless of whether the indices are contiguous:

if idx1_vals == list(range(min(idx1_vals), max(idx1_vals) + 1)):
    range_parts.append(f"N={min(idx1_vals)}..{max(idx1_vals)}")
else:
    range_parts.append(f"N={min(idx1_vals)}..{max(idx1_vals)}")  # Same!

Either remove the contiguity check or differentiate the output (e.g., show individual values for non-contiguous ranges).

🔧 Suggested fix (simplify)

             if idx1_vals:
-                if idx1_vals == list(range(min(idx1_vals), max(idx1_vals) + 1)):
-                    range_parts.append(f"N={min(idx1_vals)}..{max(idx1_vals)}")
-                else:
-                    range_parts.append(f"N={min(idx1_vals)}..{max(idx1_vals)}")
+                range_parts.append(f"N={min(idx1_vals)}..{max(idx1_vals)}")
             if idx2_vals:
-                if idx2_vals == list(range(min(idx2_vals), max(idx2_vals) + 1)):
-                    range_parts.append(f"M={min(idx2_vals)}..{max(idx2_vals)}")
-                else:
-                    range_parts.append(f"M={min(idx2_vals)}..{max(idx2_vals)}")
+                range_parts.append(f"M={min(idx2_vals)}..{max(idx2_vals)}")
             if idx3_vals:
                 range_parts.append(f"K={min(idx3_vals)}..{max(idx3_vals)}")

[coderabbitai]

Actionable comments posted: 3

🤖 Fix all issues with AI agents

In `@toolchain/mfc/params_cmd.py`:
- Around line 15-16: Remove the redundant noqa directive from the side-effect
import of definitions in params_cmd.py: keep the import statement "from .params
import definitions" (so the module is still imported for side effects) but
delete the trailing "# noqa: F401" while retaining the "pylint:
disable=unused-import" if you want to silence pylint; ensure REGISTRY import and
the definitions import remain otherwise unchanged.

In `@toolchain/mfc/params/definitions.py`:
- Around line 205-206: The _load function triggers Pylint R0912 (too many
branches); to unblock CI either explicitly silence that specific check on the
function or refactor into smaller helpers: add a function-level disable for
R0912 to the _load definition (e.g., keep def _load(): but add the pylint
disable for R0912) or extract independent logical blocks from _load into named
helper functions (e.g., _load_section_x, _load_validations, _load_defaults) and
call them from _load so the original function's branch count drops below the
limit; update any imports/locals used by those helpers accordingly.

In `@toolchain/mfc/params/schema.py`:
- Around line 50-72: ParamDef currently triggers Pylint R0902 for too many
instance attributes; to unblock CI add a class-level pylint disable for R0902
immediately above the dataclass definition of ParamDef (i.e., annotate the
ParamDef declaration to suppress R0902) so the linter ignores this class, or
alternatively refactor by grouping metadata into a nested dataclass used by
ParamDef (e.g., move constraints, dependencies, tags into a ParamMetadata
dataclass and replace those fields with a single metadata: ParamMetadata field)
and update references to ParamDef accordingly.

[coderabbitai]

⚠️ Potential issue | 🟡 Minor

Remove unused noqa directive.

Ruff flags # noqa: F401 on Line 16 as unused (RUF100). Keep the side-effect import, but drop the redundant noqa.

🔧 Suggested fix

-from .params import definitions  # noqa: F401  pylint: disable=unused-import
+from .params import definitions  # pylint: disable=unused-import

📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change

	from .params import REGISTRY
	from .params import definitions # noqa: F401 pylint: disable=unused-import
	from .params import REGISTRY
	from .params import definitions # pylint: disable=unused-import

🧰 Tools

🪛 Ruff (0.14.14)

[warning] 16-16: Unused noqa directive (non-enabled: F401)

Remove unused noqa directive

(RUF100)

🤖 Prompt for AI Agents

In `@toolchain/mfc/params_cmd.py` around lines 15 - 16, Remove the redundant noqa
directive from the side-effect import of definitions in params_cmd.py: keep the
import statement "from .params import definitions" (so the module is still
imported for side effects) but delete the trailing "# noqa: F401" while
retaining the "pylint: disable=unused-import" if you want to silence pylint;
ensure REGISTRY import and the definitions import remain otherwise unchanged.

[coderabbitai]

Actionable comments posted: 2

🤖 Fix all issues with AI agents

In `@toolchain/mfc/params_cmd.py`:
- Around line 164-173: The current logic in params_cmd.py building range_parts
uses min..max for both contiguous and non-contiguous idx1_vals/idx2_vals, hiding
gaps; modify the branches that handle idx1_vals and idx2_vals so that when the
set is contiguous (idx1_vals == list(range(min(...), max(...)+1))) you keep the
"N=min..max" / "M=min..max" format, but when non-contiguous you emit an explicit
list (e.g., "N={v1,v2,...}" or comma-separated values) instead of min..max;
update the code around the idx1_vals/idx2_vals checks and the range_parts append
logic to generate the explicit list for non-contiguous cases so users see gaps.

In `@toolchain/mfc/run/case_dicts.py`:
- Around line 68-71: ARG may raise KeyError when "case_optimization" is missing;
change the check in the block using ARG, target_name, ALL and CASE_OPTIMIZATION
so it defaults to False when the argument is absent (e.g., call ARG with a
default or catch KeyError) and then return list(ALL.keys()) when case
optimization is not enabled or target_name != "simulation"; otherwise filter
ALL.keys() by excluding CASE_OPTIMIZATION as before.

[cubic-dev-ai]

1 issue found across 2 files (changes from recent commits).

Prompt for AI agents (all issues)

Check if these issues are valid — if so, understand the root cause of each and fix them.


<file name="toolchain/mfc/params/definitions.py">

<violation number="1" location="toolchain/mfc/params/definitions.py:239">
P3: The attribute regex in `_auto_describe` only matches lowercase letters, so uppercase attributes like `Re(1)` never use the `_ATTR_DESCS` mapping and produce degraded descriptions. Expand the regex to include uppercase letters so parameter docs resolve to the intended descriptions.</violation>
</file>

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}

[coderabbitai]

Actionable comments posted: 3

🤖 Fix all issues with AI agents

In `@toolchain/mfc/cli/completion_gen.py`:
- Around line 300-345: The zsh generator (_generate_zsh_command_args) omits
several mfc_config_flags present in the bash completions; update the
mfc_config_flags branch (the block guarded by if common_set.mfc_config_flags) to
include the missing paired flags --gcov/--no-gcov, --unified/--no-unified,
--single/--no-single, --mixed/--no-mixed, and --fastmath/--no-fastmath (use the
same pattern as existing --mpi/--no-mpi and --gpu/--no-gpu entries), or better
yet refactor to centralize the common flag definitions so both bash and zsh use
the same source (e.g., move the literal flag list into a shared
constant/function and reference it from _generate_zsh_command_args and the bash
generator) so completions remain in sync.
- Around line 159-177: The current _generate_bash_command_case builds only
top-level subcommand name completion and returns early, so option/positional
completions for the chosen subcommand never run; replace the early return when
cmd.subcommands is truthy with a nested case on ${COMP_WORDS[2]} that dispatches
to the selected subcommand's completion block. Concretely, keep the subcmd_names
pattern but instead of returning, append a line like '            case
"${COMP_WORDS[2]}" in' and for each subcommand in cmd.subcommands call the same
generator logic (e.g., reuse _generate_bash_command_case or inline its logic for
that subcommand) to produce its options/positionals, then close the nested case
and only after that append the ';;' for the parent pattern so option/positional
completion of the selected subcommand runs. Ensure variables referenced
(patterns, options, cmd.subcommands, subcmd_names) match existing names and
remove the early return.

In `@toolchain/mfc/params/definitions.py`:
- Around line 282-338: The function _auto_describe has too many return
statements causing Pylint R0911; to quickly fix CI either extract chunks into
small helpers (e.g., _describe_indexed_prefix, _describe_percent_attr,
_describe_suffix_indexed) and call them from _auto_describe to reduce returns,
or add an explicit Pylint disable for this function by placing a disable comment
for R0911 on the _auto_describe definition; update references to helper names
(_describe_indexed_prefix, _describe_percent_attr, _describe_suffix_indexed) if
you choose refactoring so logic and tests remain unchanged.

🧹 Nitpick comments (2)

toolchain/mfc/cli/completion_gen.py (1)

66-70: Make the Optional type explicit in the signature.
This avoids implicit Optional per PEP 484 and aligns with typing best practices.

💡 Proposed typing fix

-from typing import List, Set
+from typing import List, Set, Optional
...
-def _bash_completion_for_type(comp_type: CompletionType, choices: List[str] = None) -> str:
+def _bash_completion_for_type(comp_type: CompletionType, choices: Optional[List[str]] = None) -> str:

Please confirm the project’s minimum Python version and typing policy to ensure this aligns with your standards.

toolchain/mfc/case.py (1)

87-117: Use PEP 604 union syntax and preserve exception context with chaining.

The codebase already uses str | None syntax in gen_case_constraints_docs.py, confirming Python 3.10+ support. Additionally, exception chaining with from e is a pattern used throughout the codebase (run/input.py, common.py), yet it's missing in the current error handling. Apply both changes for consistency:

🔧 Proposed changes

-    def validate_params(self, origin_txt: str = None):
+    def validate_params(self, origin_txt: str | None = None):
@@
-        except fastjsonschema.JsonSchemaException as e:
-            if origin_txt:
-                raise common.MFCException(f"{origin_txt}: {e}")
-            raise common.MFCException(f"{e}")
+        except fastjsonschema.JsonSchemaException as e:
+            if origin_txt:
+                raise common.MFCException(f"{origin_txt}: {e}") from e
+            raise common.MFCException(f"{e}") from e

[cubic-dev-ai]

1 issue found across 1 file (changes from recent commits).

Prompt for AI agents (all issues)

Check if these issues are valid — if so, understand the root cause of each and fix them.


<file name="toolchain/mfc/case.py">

<violation number="1">
P1: Boolean parameters are no longer converted to Fortran logical literals. Emitting `T`/`F` directly makes the generated .inp invalid for Fortran logicals. Restore the `.true.`/`.false.` conversion for string booleans before falling back to the generic handling.</violation>
</file>

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}

[coderabbitai]

Actionable comments posted: 2

🤖 Fix all issues with AI agents

In `@toolchain/mfc/cli/completion_gen.py`:
- Around line 275-292: The _zsh_completion_for_arg function omits
CompletionType.FILES_YAML handling; add a branch for CompletionType.FILES_YAML
(similar to the FILES_PY/FILES_PACK cases) that returns f'{label}:_files -g
"*.yaml"' (and possibly "*.yml" if desired) so argument completions support YAML
file globs; update the condition checks in _zsh_completion_for_arg to include
CompletionType.FILES_YAML.
- Around line 256-272: The _zsh_completion_for_positional function is missing
handling for CompletionType.FILES_YAML, so positional args that expect YAML
files get no zsh completion; update _zsh_completion_for_positional to include an
elif branch for CompletionType.FILES_YAML (similar to FILES_PY/FILES_PACK) that
sets completion to a file glob for YAML (e.g. ':_files -g "*.yml" -g "*.yaml"'),
ensure help_text processing remains the same and reference
CompletionType.FILES_YAML and the _zsh_completion_for_positional function when
making the change.

🧹 Nitpick comments (3)

toolchain/mfc/cli/completion_gen.py (2)

66-70: Use explicit Optional or union syntax for nullable parameter.

The choices parameter defaults to None but the type hint doesn't reflect this. PEP 484 prohibits implicit Optional.

♻️ Suggested fix

-def _bash_completion_for_type(comp_type: CompletionType, choices: List[str] = None) -> str:
+def _bash_completion_for_type(comp_type: CompletionType, choices: List[str] | None = None) -> str:

---

395-404: Minor style improvement for list construction.

Similar to line 164, line 397 can use unpacking syntax per Ruff's suggestion.

♻️ Suggested fix

-        all_names = [cmd.name] + cmd.aliases
+        all_names = [cmd.name, *cmd.aliases]

toolchain/mfc/case.py (1)

89-95: Preserve schema error context with exception chaining.
Use raise ... from e to keep the original traceback for debugging.

🔧 Proposed change

-        except fastjsonschema.JsonSchemaException as e:
-            if origin_txt:
-                raise common.MFCException(f"{origin_txt}: {e}")
-            raise common.MFCException(f"{e}")
+        except fastjsonschema.JsonSchemaException as e:
+            if origin_txt:
+                raise common.MFCException(f"{origin_txt}: {e}") from e
+            raise common.MFCException(f"{e}") from e

[cubic-dev-ai]

1 issue found across 1 file (changes from recent commits).

Prompt for AI agents (all issues)

Check if these issues are valid — if so, understand the root cause of each and fix them.


<file name="toolchain/main.py">

<violation number="1" location="toolchain/main.py:48">
P2: The regeneration check ignores the zsh completion file (_mfc), so missing or outdated zsh completions will not trigger regeneration. Include _mfc in the generated list so zsh completions stay in sync.</violation>
</file>

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}