[SDTEST-3057] Track constants usage in each Ruby file as a static dependency to enrich Test Impact Analysis data

[anmarchenko]

Motivation
Bug report from a customer: tests are skipped when the code they test is using a constant defined in a separate file.

What does this PR do?
Test Impact Analysis relies on line-based code coverage. When Ruby executes the code, the coverage collector records which lines were hit. But here's the catch: constant access is not a line of code execution.

In a test like that:

it "validates the threshold" do
  expect(MyApp::Config::THRESHOLD).to eq(100)
end

When Ruby runs this test, the coverage collector sees the expect() call on that line. But MyApp::Config::THRESHOLD? That's resolved through Ruby's constant lookup mechanism - it doesn't "execute" a line in config.rb. The constant value was loaded when the file was required, and now it's retrieved from Ruby's constants table.

To solve this, we need to find constant references before the test runs. The only place that information exists? Ruby's compiled bytecode.

When Ruby parses the code, it compiles it into instructions for YARV. Among these instructions are two that handle constant access:

• getconstant - Retrieves a constant by name
• opt_getconstant_path - An optimized instruction for fully-qualified paths (e.g., Foo::Bar::Baz)

You can read more about these instructions in Kevin Newton's excellent Advent of YARV.

I expanded the native C extension with an ability to walk the Ruby object space to find all live Instruction Sequences (ISeqs) - this is done similar to how DI propose to do it: DataDog/dd-trace-rb#5111

Then, we process the resulting iseqs array in Ruby to:

• Parse each ISeq's bytecode looking for getconstant and opt_getconstant_path instructions
• Resolve constant names to source files using Object.const_source_location
• Build a dependency map: {source_file => {dependency_file => true}}

When a test finishes, we take the line-based coverage and enrich it with static dependencies. If your test file references Constants::Config::THRESHOLD, we add config.rb to the coverage even though no lines in it were executed.

The opt_getconstant_path instruction stores the constant path as an array of symbols in its cache entry:
opt_getconstant_path <ic:0 Constants::Config::THRESHOLD>

We extract [:Constants, :Config, :THRESHOLD], build the string "Constants::Config::THRESHOLD", then call Object.const_source_location("Constants::Config::THRESHOLD") to get the file path where that constant is defined.

For getconstant, we get just the symbol name (e.g., :BaseConstant), which we try to resolve the same way—though this has limitations (see below).

This feature is experimental and enabled with environment variable DD_TEST_OPTIMIZATION_TIA_STATIC_DEPS_COVERAGE_ENABLED

Limitations
This will work only when the code is eager loaded in tests, otherwise the source location for constants will not be resolved correctly.

Class-level constant Resolution - inheritance and module inclusion happen at class definition time, not inside method bodies

class MyService < BaseService  # Not tracked
  include Loggable                        # Not tracked
  
  def process
    Config::TIMEOUT                       #  Tracked
  end
end

It doesn't work for unqualified constant names (for now):

module MyApp
  class Processor
    def call
      Config.get(:key)  # getconstant :Config - will not be resolved correctly to `MyApp::Config`
    end
  end
end

Ruby version compatibility
This feature works only for Ruby versions 3.2 and newer because it relies on opt_getconstant_path YARV instruction to be present.

In Ruby 3.1:

RubyVM::InstructionSequence.compile("A::B").to_a.last
> 
[
  ["opt_getinlinecache", "label_13", 0],
  ["putobject", true],
  ["getconstant", "A"],
  ["putobject", false],
  ["getconstant", "B"],
  ["opt_setinlinecache", 0],
  "label_13",
  ["leave"]
]

In Ruby 3.2:

RubyVM::InstructionSequence.compile("A::B").to_a.last
> 
[
  ["opt_getconstant_path", ["A", "B"]],
  ["leave"]
]

How to test the change?
There is a comprehensive testing suite provided

[datadog-official]

✅ Tests

🎉 All green!

❄️ No new flaky tests detected
🧪 All tests passed

🎯 Code Coverage
• Patch Coverage: 93.43%
• Overall Coverage: 97.18% (-0.17%)

View detailed report

_{This comment will be updated automatically if new data arrives.
🔗 Commit SHA: 4edd3b7 | Docs | Datadog PR Page | Was this helpful? Give us feedback!}

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[ivoanjo]

Gave it a pass, left some notes ;)

[anmarchenko]

did another round of testing here: anmarchenko/forem#7

the tests that depend on constants now being correctly not skipped

[anmarchenko]

we can merge it now