🌱 Add test-specific mock include directives

[JannisRln]

🍍

Summary

This draft PR adds support for test-specific mock include directives. Issue 1138

The goal is to allow a test file to inject additional headers into a
specific generated mock without applying those includes globally to all
generated mocks.

Example:

#include "unity.h"
#include "mock_driver.h"

TEST_MOCK_INCLUDE("mock_driver.h", "test_driver_types.h")

This should inject test_driver_types.h only into the generated mock for
mock_driver.h for the current test executable.

Motivation

CMock already supports global include configuration options such as:

:includes_h_pre_orig_header: []
:includes_h_post_orig_header: []
:includes_c_pre_header: []
:includes_c_post_header: []

These options are useful, but they apply globally. In larger embedded
projects this can lead to unwanted includes, unnecessary dependencies, or
conflicts in unrelated tests.

This PR adds test-specific build directive macros so additional mock
headers can be scoped to one test and one mock.

Added directives

TEST_MOCK_INCLUDE("mock_driver.h", "test_driver_types.h")
TEST_MOCK_INCLUDE_H_PRE_ORIG_HEADER("mock_driver.h", "test_driver_types.h")
TEST_MOCK_INCLUDE_H_POST_ORIG_HEADER("mock_driver.h", "test_driver_types.h")
TEST_MOCK_INCLUDE_C_PRE_HEADER("mock_driver.h", "test_driver_config.h")
TEST_MOCK_INCLUDE_C_POST_HEADER("mock_driver.h", "test_driver_config.h")

TEST_MOCK_INCLUDE(...) is treated as an alias for
TEST_MOCK_INCLUDE_H_PRE_ORIG_HEADER(...).

PL Open in Unity Pull 830

Current status

This is currently a draft PR.

The parser-level specs for TestContextExtractor pass locally:

17 examples, 0 failures

However, I have not yet been able to run the full test suite locally.
Some tests require gcc, which is not currently available in my local
environment. We use the project.yaml file to define the gcc location

I am also not fully certain yet that my manual end-to-end test is using
the modified local Ceedling instance rather than another installed
Ceedling version. Because of that, I am opening this as a draft for early
feedback on the approach before marking it ready for review.

Notes for reviewers

I would especially appreciate feedback on:

• whether the macro names fit the existing Ceedling style
• whether this belongs in Ceedling rather than CMock directly
• whether the configuration is being merged in the correct place during
  mock generation
• whether the test-specific scoping approach is acceptable

Testing

Completed locally:

bundle exec rspec ./spec/test_context_extractor_spec.rb

Result:

17 examples, 0 failures

Not completed locally yet:

• full spec suite
• gcc-dependent integration tests
• open end-to-end test with the modified local Ceedling instance

Documentation

This PR also adds documentation for the new test-specific mock include
directives.