Project is built with include directories for two different versions of the same library

What kind of issue is this?

• PlatformIO Core.
  If you’ve found a bug, please provide an information below.

You can erase any parts of this template not applicable to your Issue.

---

Configuration

Operating system: Ubuntu 20.04.6 LTS

PlatformIO Version (platformio --version): 6.1.14

Description of problem

Projects that use a newer version of a library (^3.1.0) but a dependency uses an older version of the same library (^2.3.0) are built with the include directories of both versions (and the older one has precedence).

Steps to Reproduce

1. platformio run

Actual Results

Build fails because the project uses a function that is only present in the newer version of the library but the included header is from the older version.

Expected Results

Build is successful with only one version of the library's header files present.

If problems with PlatformIO Build System:

The content of platformio.ini:

[env:test]
lib_deps =
	nomis/uuid-log@^3.1.0
	nomis/uuid-modbus@^0.2.0 # depends on nomis/uuid-log@^2.3.0
lib_ldf_mode = chain

framework = arduino
platform = espressif8266@^3.0.0
board = d1_mini

Source file to reproduce issue:

#include <uuid/log.h>

static const char __pstr__logger_name[] __attribute__((__aligned__(PSTR_ALIGN))) PROGMEM = "test";

static uuid::log::Logger logger{FPSTR(__pstr__logger_name), uuid::log::Facility::KERN};

void setup() {
	logger.logp(uuid::log::Level::NOTICE, "test");
}

void loop() {
}

Additional info

This was introduced after 6.1.13, in 6.1.14:

$ git bisect ...
e1ff9a469d339b0fc4689a5e1520a89f14556a77 is the first bad commit
commit e1ff9a469d339b0fc4689a5e1520a89f14556a77
Date:   Tue Feb 13 19:32:57 2024 +0200

    Resolved an issue where the LDF selected an incorrect library version // Resolve #4860

 HISTORY.rst                            |  3 ++-
 platformio/builder/tools/piolib.py     | 17 ++++++++++---
 platformio/package/manager/_install.py |  6 ++++-
 platformio/package/meta.py             | 45 +++++++++++++++++++++++++++++-----
 4 files changed, 60 insertions(+), 11 deletions(-)

Start with the regression commit e1ff9a469d339b0fc4689a5e1520a89f14556a77 and inspect platformio/builder/tools/piolib.py, platformio/package/manager/_install.py, and platformio/package/meta.py. Reproduce with the provided platformio.ini and source using PlatformIO 6.1.14, then compare against 6.1.13. Done means the dependency graph selects compatible headers so only the intended uuid-log version is included and the example builds successfully.