[Primitive Update]: `codeql_query_compile` tool must use `--dump-dil` by default

[data-douser]

Primitive Type

Tool (Interactive function)

Primitive Name

codeql_query_compile

Update Type

Feature Enhancement

Current Behavior

The codeql_query_compile MCP tool does not currently have specific support for using the --dump-dil argument when invoking the backend codeql query compile CLI command.

Desired Behavior

The codeql_query_compile MCP tool will always --dump-dil unless the calling LLM explicitly passes --no-dump-dil argument, where always "dumping" the compiled CodeQL query's DIL is what the GitHub.vscode-codeql already supports for any given CodeQL query run. So will the ql-mcp server.

Example Inputs

No response

Expected Outputs

Consistent use of the --dump-dil option when compiling CodeQL queries will consistently produce a *.dil log file for the CodeQL query's Datalog Intermediate Language (DIL) representation of the query evaluation order.

Test Scenarios

This feature must be validated via:

• new server unit tests;
• client integration test improvements for the codeql_query_compile tool;
• extension integration test improvements to ensure that a standard DIL file is created at expected path with expected contents for some test run of an example CodeQL query;

Documentation or Reference Materials

From codeql query compile -h -vv CLI output:

      --[no-]dump-dil        [Advanced] Print the optimized DIL intermediate
                               representation to standard output while
                               compiling.
                             When JSON output is selected, the DIL will be
                               represented as an array of single-line strings,
                               with some wrapping to identify which query is
                               being compiled.

Use Case Improvement

Always dumping the DIL for a compiled CodeQL query will ensure that the ql-mcp server always provides agentic LLMs with the option of reviewing the pre-query-run execution order (i.e. the DIL) versus the actual query evaluation order, timing, and tuple counts (i.e. result counts per query evaluation stage). Thus, calling LLMs will be able to review the expected query evaluation behavior before running a given query (e.g. with codeql_query_run, codeql_test_run, or codeql_database_analyze MCP tools).

Future work will ensure that the ql-mcp server has tools for parsing DIL to a common data structure that is compatible with the existing profile_codeql_query_from_logs MCP tool, where the query evaluation log data should parse to a superset of the DIL log.

Bug Reproduction Steps (If applicable)

No response

Error Messages or Logs (If applicable)

No response

References

https://docs.github.com/en/code-security/how-tos/find-and-fix-code-vulnerabilities/scan-from-vs-code/running-codeql-queries#understanding-your-query-results

Priority Level

Medium (Notable improvement)

Breaking Changes Acceptable

Minor - Small API changes acceptable with deprecation

Update Checklist (Auto-populated for LLM guidance)

• Backward Compatibility: Maintain existing API contracts where possible
• Test Coverage: All existing tests continue to pass
• New Functionality Testing: Comprehensive tests for new features
• Error Handling: Improved error handling and edge case coverage
• Performance: No performance regressions, ideally improvements
• Documentation: Updated JSDoc and usage examples
• Type Safety: Maintained or improved TypeScript type safety
• Integration: Verify integration with dependent components

Code of Conduct

• I agree to follow this project's Code of Conduct