[gennaroprota]

This fixes a bug for which an include file reached from an input directory through e.g. #include "../vendor/x.hpp" was taken to lie inside that directory. Its symbols were documented as the project's own, exclude could not reach it, and its path read api/../vendor/x.hpp.

The compiler records the includer's directory joined with what the include spells out, ".." and all. Such an unnormalized path was normalized when the compiler recorded it as relative, on its way to being made absolute, but not when it recorded it as absolute, as it does for a header found through an absolute include directory and for every file of a compilation database, including the one synthesized from the configuration. This normalizes it there, too. The normalization is lexical, like the one already applied to relative paths, so it resolves no symlinks. It is skipped when the normalized path names another file than the one the compiler opened, which happens on POSIX when a symlinked directory comes before the "..", and such a path is kept as written, as before. The include directories and the source root a path is shortened against are normalized the same way, so they still match it as text.

This narrows the "as written" rule that exclude followed so far to "not symlink-resolved": exclude now matches the file path once "." and ".." are removed, and still does not resolve symlinks.

Changes

• Source: ASTVisitor::buildFileInfo normalizes a source file path the compiler recorded as absolute when the result names the same file, as it already did for one recorded as relative, and normalizes the directories it shortens paths against.
• Tests: A golden fixture, filters/file/unnormalized-path, reaches a header through an include directory and "..", once unfiltered, once with exclude and once with a narrower input. Unit tests build a real corpus over a temporary tree, one for an include file outside the inputs and one for an include file inside an exclusion.
• Breaking changes: The reference of a project with include files reached through ".." can change. Symbols from files outside input that were documented by mistake disappear, exclude now applies to such files, their paths are shown normalized, and macros defined in them get new IDs and links. This holds for every absolute source path the compiler records, including main files listed in a compilation database. An absolute exclude entry that contains ".." no longer matches the files under it, because file paths are now normalized and such an entry is not (a relative entry is); normalizing absolute path options is left for a follow-up.

Testing

The golden fixture tests/golden/fixtures/filters/file/unnormalized-path shows the vendored header at vendor/vendored.hpp when nothing filters it, and drops it under exclude and under a narrower input; all three outputs differ without the fix. tests/unit/AST/FileFilters.cpp adds testUnnormalizedPathOutsideTheInputs and testUnnormalizedPathInsideAnExclusion, which go through the database synthesized from the configuration, and both fail without the fix. No existing golden output changes.

The symlink case has no test: it needs a symlinked directory, which a Windows checkout without symlink support cannot create. FileFilters.cpp carries a third copy of the writeFile helper of the script and data-driven generator tests; consolidating them is left for a follow-up.

Documentation

The exclude option now says that it matches the file path once "." and ".." are removed, and that an absolute entry is used as written, so it should not contain "." or "..". input needs no change: it selects "files in these directories", which is what it now does for an include file reached through "..".

[github-actions]

✨ Highlights

• 🧪 New golden tests added

🧾 Changes by Scope

Scope	Lines Δ%	Lines Δ	Lines +	Lines -	Files Δ	Files +	Files ~	Files ↔	Files -
🥇 Golden Tests	53%	234	234	-	11	11	-	-	-
🧪 Unit Tests	31%	135	135	-	1	1	-	-	-
🛠️ Source	15%	67	57	10	3	-	3	-	-
📄 Docs	<1%	2	1	1	1	-	1	-	-
Total	100%	438	427	11	16	12	4	-	-

Legend: Files + (added), Files ~ (modified), Files ↔ (renamed), Files - (removed)

🔝 Top Files

• tests/unit/AST/FileFilters.cpp (Unit Tests): 135 lines Δ (+135 / -0)
• tests/golden/fixtures/filters/file/unnormalized-path/unfiltered.xml (Golden Tests): 98 lines Δ (+98 / -0)
• tests/golden/fixtures/filters/file/unnormalized-path/exclude.xml (Golden Tests): 55 lines Δ (+55 / -0)

Generated by 🚫 dangerJS against 62e398c

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 83.21%. Comparing base (1a0bbac) to head (62e398c).
⚠️ Report is 33 commits behind head on develop.

Additional details and impacted files

@@             Coverage Diff             @@
##           develop    #1318      +/-   ##
===========================================
+ Coverage    83.12%   83.21%   +0.09%     
===========================================
  Files           35       35              
  Lines         3662     3670       +8     
  Branches       844      845       +1     
===========================================
+ Hits          3044     3054      +10     
  Misses         410      410              
+ Partials       208      206       -2     

Flag	Coverage Δ
bootstrap	83.21% <ø> (+0.09%)	⬆️

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

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[cppalliance-bot]

An automated preview of the documentation is available at https://1318.mrdocs.prtest2.cppalliance.org/index.html

If more commits are pushed to the pull request, the docs will rebuild at the same URL.

2026-10-14 14:28:28 UTC