Skip to content

Enhance CLI error handling: process exit code + new flag to write even if errors - #1813

Open
dehall wants to merge 6 commits into
cqframework:mainfrom
dehall:feat/cli_error_handling
Open

dehall wants to merge 6 commits into
cqframework:mainfrom
dehall:feat/cli_error_handling

Conversation

@dehall

@dehall dehall commented Jul 16, 2026

Copy link
Copy Markdown

This PR introduces a couple changes to error handling in the cql-to-elm-cli, as requested (by me) in #1810 .

  1. Uses the process exit code to indicate failure or success: if every CQL file provided as input successfully converts to ELM, the process exit code will be 0 (as it is today), but if there are any errors, the process exit code will now be 1.
  2. Adds a new optional command-line flag --write-on-error which will cause output files to be written even if there was a translator error.

The basics of the PR are straightforward but there are a few things to note and we may want to discuss further:

  • If the new command-line flag is used and an input file has a translation error, the exit code will be 1 even though the output file was written. The alternative would be, if the file is written then that's always a 0 exit code, which I'm also ok with and is only a slight tweak in the code. We could also make that another config option but I think that's overkill.
  • I didn't want to change the defaults too much, but we could consider an alternate implementation where the default behavior is to always write output files even if there is a translator error, and add the inverse command-line flag --no-write-on-error to enable the current behavior
  • There may be other code paths that exit in a "failure" state but don't necessarily indicate that with an error code. (Note that uncaught Exceptions already result in a nonzero exit code, so that's consistent with, eg, the require used in a couple places.) As of now the CLI really only has a single primary use case, and I don't see anything that looks like it would slip through, but it's worth double checking and something to keep in mind if new features are ever added.
  • If we want to get fancy, we could return a different non-zero code for fatal errors (the kind that might even prevent the file from being written). I didn't do this here to keep the diff small, but would be happy to implement this if there's interest.
  • The cli project has no tests so I didn't add any, but again I'm happy to if the maintainers would like me to.
  • Note for code review: the changes at the end of the file might be more readable with "hide whitespace" enabled in the GitHub diff UI

Sample runs:

  • A successful run, single file, default settings:
clinical_quality_language % ./cql-to-elm-cli/build/install/cql-to-elm-cli/bin/cql-to-elm-cli --input ./elm-fhir/src/test/resources/org/cqframework/cql/elm/requirements/fhir/TestCases/TestCase1.cql
================================================================================
TRANSLATE ./elm-fhir/src/test/resources/org/cqframework/cql/elm/requirements/fhir/TestCases/TestCase1.cql
kotlin-logging: initializing... active logger factory: Slf4jLoggerFactory
Translation completed successfully.
ELM output written to: ./elm-fhir/src/test/resources/org/cqframework/cql/elm/requirements/fhir/TestCases/TestCase1.xml

clinical_quality_language % echo $?
0
clinical_quality_language %
  • A successful run, single file, with write-on-error: (no difference expected)
clinical_quality_language % ./cql-to-elm-cli/build/install/cql-to-elm-cli/bin/cql-to-elm-cli --input ./elm-fhir/src/test/resources/org/cqframework/cql/elm/requirements/fhir/TestCases/TestCase1.cql --write-on-error
================================================================================
TRANSLATE ./elm-fhir/src/test/resources/org/cqframework/cql/elm/requirements/fhir/TestCases/TestCase1.cql
kotlin-logging: initializing... active logger factory: Slf4jLoggerFactory
Translation completed successfully.
ELM output written to: ./elm-fhir/src/test/resources/org/cqframework/cql/elm/requirements/fhir/TestCases/TestCase1.xml

clinical_quality_language % echo $?
0
clinical_quality_language %
  • A failed run, default settings:
clinical_quality_language % ./cql-to-elm-cli/build/install/cql-to-elm-cli/bin/cql-to-elm-cli --input ./engine/src/jvmTest/resources/org/opencds/cqf/cql/engine/execution/Invalid.cql
================================================================================
TRANSLATE ./engine/src/jvmTest/resources/org/opencds/cqf/cql/engine/execution/Invalid.cql
Translation failed due to errors:
Error:[6:0, 6:0] Syntax error at define
clinical_quality_language % echo $?
1
clinical_quality_language %
  • A failed run, with write-on-error:
clinical_quality_language % ./cql-to-elm-cli/build/install/cql-to-elm-cli/bin/cql-to-elm-cli --input ./engine/src/jvmTest/resources/org/opencds/cqf/cql/engine/execution/Invalid.cql --write-on-error
================================================================================
TRANSLATE ./engine/src/jvmTest/resources/org/opencds/cqf/cql/engine/execution/Invalid.cql
Translation completed with messages:
Error:[6:0, 6:0] Syntax error at define
ELM output written to: ./engine/src/jvmTest/resources/org/opencds/cqf/cql/engine/execution/Invalid.xml

clinical_quality_language % echo $?
1
clinical_quality_language %
  • A mixed run, folder with some success and some failed files, default settings:
clinical_quality_language % mkdir mixed_test
clinical_quality_language % cp ./elm-fhir/src/test/resources/org/cqframework/cql/elm/requirements/fhir/TestCases/TestCase1.cql mixed_test/good1.cql
clinical_quality_language % cp ./elm-fhir/src/test/resources/org/cqframework/cql/elm/requirements/fhir/TestCases/TestCase2a.cql mixed_test/good2.cql
clinical_quality_language % cp ./engine/src/jvmTest/resources/org/opencds/cqf/cql/engine/execution/Invalid.cql mixed_test/fail.cql
clinical_quality_language % ./cql-to-elm-cli/build/install/cql-to-elm-cli/bin/cql-to-elm-cli --input ./mixed_test
================================================================================
TRANSLATE ./mixed_test/fail.cql
Translation failed due to errors:
Error:[6:0, 6:0] Syntax error at define
================================================================================
TRANSLATE ./mixed_test/good1.cql
kotlin-logging: initializing... active logger factory: Slf4jLoggerFactory
Translation completed successfully.
ELM output written to: ./mixed_test/good1.xml

================================================================================
TRANSLATE ./mixed_test/good2.cql
Translation completed successfully.
ELM output written to: ./mixed_test/good2.xml

dehall@MM304610-PC clinical_quality_language % echo $?
1
dehall@MM304610-PC clinical_quality_language %
  • A mixed run, folder with some success and some failed files, with write-on-error:
clinical_quality_language % ./cql-to-elm-cli/build/install/cql-to-elm-cli/bin/cql-to-elm-cli --input ./mixed_test --write-on-error
================================================================================
TRANSLATE ./mixed_test/fail.cql
Translation completed with messages:
Error:[6:0, 6:0] Syntax error at define
ELM output written to: ./mixed_test/fail.xml

================================================================================
TRANSLATE ./mixed_test/good1.cql
kotlin-logging: initializing... active logger factory: Slf4jLoggerFactory
Translation completed successfully.
ELM output written to: ./mixed_test/good1.xml

================================================================================
TRANSLATE ./mixed_test/good2.cql
Translation completed successfully.
ELM output written to: ./mixed_test/good2.xml

clinical_quality_language % echo $?
1
clinical_quality_language %

@cmoesel

cmoesel commented Sep 20, 2026

Copy link
Copy Markdown
Member

@brynrhodes @JPercival @antvaset - There are some failing CI, but they seem related to permissions/env issues, likely because the PR is coming from a branch. Can I force merge this or is there something real that we should be concerned about in the CI?

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants