Set flags.INVOCATION_COMMAND for programmatic invocations on a best-effort basis

[dbeatty10]

Resolves #10313

Problem

For programmatic invocations, the flags.INVOCATION_COMMAND within the invocation has whatever args were passed to the python script rather than the equivalent CLI command for dbt.

There is currently no testing in CI related to flags.INVOCATION_COMMAND, and we consider this an informal feature rather than a fully-supported one.

Solution

Set a global variable named DBT_EQUIVALENT_COMMAND within dbtRunner.invoke and read from it within Flags.__init__.

Testing

Since this is still merely best-effort, no new functional tests are included in this PR.

All the dbt functional tests will hit these code paths though, so we can see that they don't generate any exceptions.

Behavior for boolean flags

This code results in the following behavior:

        if type(value) is bool:
            # Add just the flag (without the value) for booleans (and only if True)
            if value:
                cli_args.append(cli_key)

Actual behavior in the comments:

    dbt_runner.invoke(["compile", "--use-colors"])  # INVOCATION_COMMAND = dbt compile --use-colors
    dbt_runner.invoke(["compile", "--no-use-colors"])  # INVOCATION_COMMAND = dbt compile --no-use-colors
    dbt_runner.invoke(["compile"], use_colors=True)  # INVOCATION_COMMAND = dbt compile --use-colors
    dbt_runner.invoke(["compile"], use_colors=False)  # INVOCATION_COMMAND = dbt compile
    dbt_runner.invoke(["compile"], no_use_colors=True)  # INVOCATION_COMMAND = dbt compile --no-use-colors
    dbt_runner.invoke(["compile"], no_use_colors=False)  # INVOCATION_COMMAND = dbt compile

In an ideal world, the code above would provide convert into the opposite CLI flag whenever the boolean value is false. But I don't think it is necessary to do here since users can do it on their end.

Assumptions

Implementation decisions

Went with a environment variable rather than a global variable with thread-safety in mind:

Method	Thread-safe?	Best when...
Environment variable	✅ Yes	Config shared across subprocesses or between programs
Global variable	❌ No	Quick access across functions or modules in one process

Caveats

If flags.INVOCATION_COMMAND is accessed without actually running a click-based CLI command or without using invoke, this solution still won't have the equivalent CLI command. For example, some unit testing in the dbt-core repo will access flags without invoke or running a CLI command.

Checklist

• I have read the contributing guide and understand what's expected of me.
• I have run this code in development, and it appears to resolve the stated issue.
• This PR includes tests, or tests are not required or relevant for this PR.
• This PR has no interface changes (e.g., macros, CLI, logs, JSON artifacts, config files, adapter interface, etc.) or this PR has already received feedback and approval from Product or DX.
• This PR includes type annotations for new and modified functions.

[github-actions]

Thank you for your pull request! We could not find a changelog entry for this change. For details on how to document a change, see the contributing guide.

[codecov]

Codecov Report

Attention: Patch coverage is 83.33333% with 4 lines in your changes missing coverage. Please review.

Project coverage is 91.84%. Comparing base (303c63c) to head (1e53c7d).

Additional details and impacted files

@@            Coverage Diff             @@
##             main   #11779      +/-   ##
==========================================
- Coverage   91.86%   91.84%   -0.03%     
==========================================
  Files         198      198              
  Lines       24204    24227      +23     
==========================================
+ Hits        22235    22251      +16     
- Misses       1969     1976       +7     

Flag	Coverage Δ
integration	88.75% <83.33%> (-0.02%)	⬇️
unit	65.17% <50.00%> (-0.02%)	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

Components	Coverage Δ
Unit Tests	65.17% <50.00%> (-0.02%)	⬇️
Integration Tests	88.75% <83.33%> (-0.02%)	⬇️

🚀 New features to boost your workflow:

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