fix(ast): prevent TU parent from including unmatched globals

.github/workflows/ci.yml

@@ -73,9 +73,9 @@ jobs:
             apple-clang: Release
             msvc: RelWithDebInfo
           install: |
-            gcc: git build-essential pkg-config python3 curl openjdk-11-jdk pkg-config libncurses-dev libxml2-utils libxml2-dev
-            gcc Coverage: git build-essential pkg-config python3 curl openjdk-11-jdk pkg-config libncurses-dev libxml2-utils libxml2-dev lcov
-            clang: git build-essential pkg-config python3 curl openjdk-11-jdk pkg-config libncurses-dev libxml2-utils libxml2-dev g++-14=14.2.0-4ubuntu2~24.04
+            gcc: git build-essential pkg-config python3 curl unzip openjdk-11-jdk pkg-config libncurses-dev libxml2-utils libxml2-dev
+            gcc Coverage: git build-essential pkg-config python3 curl unzip openjdk-11-jdk pkg-config libncurses-dev libxml2-utils libxml2-dev lcov
+            clang: git build-essential pkg-config python3 curl unzip openjdk-11-jdk pkg-config libncurses-dev libxml2-utils libxml2-dev g++-14=14.2.0-4ubuntu2~24.04
             msvc: ''
           extra-values: |
             use-libcxx: {{#if (and (ieq compiler 'clang') (ge major 19)) }}true{{else}}false{{/if}}
@@ -332,36 +332,6 @@ jobs:
           path: ${{ steps.rmatrix.outputs.llvm-path }}
           key: ${{ matrix.llvm-archive-basename }}
 
-      - name: Download LLVM Binaries
-        id: llvm-download
-        if: steps.llvm-cache.outputs.cache-hit != 'true'
-        run: |
-          set -x
-          url=https://mrdocs.com/llvm+clang/${{ matrix.llvm-archive-filename }}
-          http_status=$(curl -s -o /dev/null -w "%{http_code}" -I "$url")
-          if [ "$http_status" -eq 200 ]; then
-              found="true"
-              echo "found=$found" >> $GITHUB_OUTPUT
-              curl -L -o ${{ matrix.llvm-archive-filename }} "$url"
-              install_prefix=${{ steps.rmatrix.outputs.llvm-path }}
-              mkdir -p $install_prefix
-              if [[ ${{ matrix.llvm-archive-extension }} == '7z' ]]; then
-                  7z x ${{ matrix.llvm-archive-filename }} -o$install_prefix
-              else
-                  tar -xjf ${{ matrix.llvm-archive-filename }} -C $install_prefix
-              fi
-              if [[ $(ls -1 $install_prefix | wc -l) -eq 1 ]]; then
-                  single_dir=$(ls -1 $install_prefix)
-                  if [[ -d $install_prefix/$single_dir ]]; then
-                      mv $install_prefix/$single_dir/* $install_prefix/
-                      rmdir $install_prefix/$single_dir
-                  fi
-              fi
-          else
-              found="false"
-              echo "found=$found" >> $GITHUB_OUTPUT
-          fi
-
       # Installs libc++ separately, using the LLVM standalone runtimes build.
       # The libc++ built here will be built using the host compiler, so this is
       # limited by what libc++ at the current LLVM revision supports.
@@ -375,16 +345,27 @@ jobs:
       # FIXME: Build this for the GCC and MacOS sanitizer jobs.
       # Currently GCC fails linking it, and for MacOS there are compiler-rt
       # requirements not satisfied.
+      - name: Fetch LLVM source archive
+        if: steps.llvm-cache.outputs.cache-hit != 'true'
+        run: |
+          set -eux
+          mkdir -p ../third-party
+          cd ../third-party
+          archive="llvm-${{ matrix.llvm-hash }}.zip"
+          if [ ! -d llvm-project ]; then
+            curl -L -o "$archive" "https://github.com/llvm/llvm-project/archive/${{ matrix.llvm-hash }}.zip"
+            unzip -q "$archive"
+            mv "llvm-project-${{ matrix.llvm-hash }}" llvm-project
+            rm "$archive"
+          fi
+
       - name: Install libc++
         id: install_libcxx
         uses: alandefreitas/cpp-actions/[email protected]
-        if: matrix.use-libcxx == 'true' && steps.llvm-cache.outputs.cache-hit != 'true' && steps.llvm-download.outputs.found != 'true'
+        if: matrix.use-libcxx == 'true' && steps.llvm-cache.outputs.cache-hit != 'true'
         with:
           cmake-version: '>=3.26'
           source-dir: ../third-party/llvm-project/runtimes
-          git-repository: https://github.com/llvm/llvm-project.git
-          git-tag: ${{ matrix.llvm-hash }}
-          download-dir: ../third-party/llvm-project
           build-dir: ${sourceDir}/build
           build-type: ${{ matrix.build-type }}
           extra-args: |
@@ -415,13 +396,10 @@ jobs:
       - name: Install LLVM
         id: install_llvm
         uses: alandefreitas/cpp-actions/[email protected]
-        if: steps.llvm-cache.outputs.cache-hit != 'true' && steps.llvm-download.outputs.found != 'true'
+        if: steps.llvm-cache.outputs.cache-hit != 'true'
         with:
           cmake-version: '>=3.26'
           source-dir: ../third-party/llvm-project/llvm
-          git-repository: https://github.com/llvm/llvm-project.git
-          git-tag: ${{ matrix.llvm-hash }}
-          download-dir: ../third-party/llvm-project
           patches: |
             ./third-party/patches/llvm/llvm/CMakePresets.json
             ./third-party/patches/llvm/llvm/CMakeUserPresets.json
@@ -1246,69 +1224,9 @@ jobs:
         with:
           apt-get: ${{ matrix.install }}
 
-      - name: Check website releases
-        id: website-releases
-        run: |
-          set -x
-          archive_url="https://mrdocs.com/llvm+clang/${{ matrix.llvm-archive-filename }}"
-          http_status=$(curl -s -o /dev/null -w "%{http_code}" -I "$archive_url")
-          if [ "$http_status" -eq 200 ]; then
-              exists="true"
-          else
-              exists="false"
-          fi
-          echo "exists=$exists" >> $GITHUB_OUTPUT
-
       - name: LLVM Binaries
         id: llvm-cache
-        if: steps.website-releases.outputs.exists != 'true'
         uses: actions/cache@v4
         with:
           path: ${{ steps.rmatrix.outputs.llvm-path }}
           key: ${{ matrix.llvm-archive-basename }}
-
-      - name: Compress LLVM
-        id: llvm-upload
-        if: steps.llvm-cache.outputs.cache-hit == 'true'
-        shell: bash
-        run: |
-          # LLVM is be installed with the default compiler
-          set -x
-
-          # Use 7z on windows
-          if [[ ${{ runner.os }} == 'Windows' ]]; then
-              7z a -t7z -m0=lzma2 -mx=9 -mfb=64 -md=32m -ms=on "${{ matrix.llvm-archive-filename }}" "${{ steps.rmatrix.outputs.llvm-path }}"
-          else
-              tar -cjf "${{ matrix.llvm-archive-filename }}" -C "${{ steps.rmatrix.outputs.llvm-path }}/.." llvm
-          fi
-
-      - name: Website LLVM Releases
-        if: steps.llvm-cache.outputs.cache-hit == 'true' && github.event_name == 'push' && (contains(fromJSON('["master", "develop"]'), github.ref_name) || startsWith(github.ref, 'refs/tags/'))
-        run: |
-          set -x
-
-          # Ensure required commands exist
-          for cmd in ssh-keyscan ssh-agent ssh-add scp; do
-            if ! command -v $cmd >/dev/null; then
-              echo "$cmd not found"
-              exit 1
-            fi
-          done
-
-          # Add SSH key
-          mkdir -p ~/.ssh
-          ssh-keyscan dev-websites.cpp.al >> ~/.ssh/known_hosts
-          chmod 600 ~/.ssh/known_hosts
-          echo "${{ secrets.DEV_WEBSITES_SSH_KEY }}" > ~/.ssh/github_actions
-          chmod 600 ~/.ssh/github_actions
-
-          # Start ssh-agent and add the key
-          SSH_AUTH_SOCK="$RUNNER_TEMP/ssh_agent.sock"
-          export SSH_AUTH_SOCK
-          ssh-agent -a $SSH_AUTH_SOCK > /dev/null
-          ssh-add ~/.ssh/github_actions
-
-          # Copy llvm archive: This step will copy the archive to www.mrdocs.com/llvm+clang
-          llvm_dir="/var/www/mrdox.com/llvm+clang"
-          chmod 755 ${{ matrix.llvm-archive-filename }}
-          scp -o StrictHostKeyChecking=no $(pwd)/${{ matrix.llvm-archive-filename }} [email protected]:$llvm_dir/

.github/workflows/pr-target-checks.yml

@@ -33,7 +33,7 @@ jobs:
       - name: Install repo-check tools
         run: npm --prefix util/danger ci
 
-      - name: Repo checks (Danger)
+      - name: Repo checks (Danger.js)
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
         run: npx --prefix util/danger danger ci --dangerfile util/danger/dangerfile.ts

bootstrap.py

@@ -3132,7 +3132,7 @@ def validate_cli_compatibility(self):
 
     def collect_user_inputs(self):
         """
-        Phase 1: ask all questions up front to mirror bootstrap-other's two-phase flow.
+        Phase 1: ask all questions up front for a two-phase flow.
         This keeps prompts grouped before any work begins.
         """
         self.ui.section("MrDocs Bootstrap", icon="🚀")

src/lib/AST/ASTVisitor.cpp

@@ -3201,6 +3201,26 @@ checkSymbolFilters(clang::Decl const* D, bool const AllowParent)
     else if (AllowParent)
     {
         clang::Decl const* P = getParent(D);
+        while (P)
+        {
+            // Only propagate inclusion from meaningful scopes. Translation units
+            // (and other non-scope wrappers like linkage specs) should not cause
+            // otherwise-unmatched globals to be extracted.
+            if (isa<clang::NamespaceDecl>(P) ||
+                isa<clang::RecordDecl>(P) ||
+                isa<clang::EnumDecl>(P))
+            {
+                break;
+            }
+
+            if (isa<clang::TranslationUnitDecl>(P))
+            {
+                P = nullptr;
+                break;
+            }
+
+            P = getParent(P);
+        }
         if (P)
         {
             // 4) Parent symbols imply this symbol should be included

test-files/golden-tests/config/include-symbols/global-symbol-excluded.adoc

@@ -0,0 +1,45 @@
+= Reference
+:mrdocs:
+
+[#index]
+== Global namespace
+
+=== Namespaces
+
+[cols="1,4"]
+|===
+| Name| Description
+| link:#mrdocs[`mrdocs`] 
+| Included namespace
+|===
+
+[#mrdocs]
+== mrdocs
+
+Included namespace
+
+=== Types
+
+[cols="1,4"]
+|===
+| Name| Description
+| link:#mrdocs-Foo[`Foo`] 
+| Included record
+|===
+
+[#mrdocs-Foo]
+== link:#mrdocs[mrdocs]::Foo
+
+Included record
+
+=== Synopsis
+
+Declared in `<global‐symbol‐excluded.cpp>`
+
+[source,cpp,subs="verbatim,replacements,macros,-callouts"]
+----
+struct Foo;
+----
+
+
+[.small]#Created with https://www.mrdocs.com[MrDocs]#

test-files/golden-tests/config/include-symbols/global-symbol-excluded.cpp

@@ -0,0 +1,9 @@
+// Regression test for #1121: limiting include-symbols to a namespace should
+// not extract global symbols that do not match the pattern.
+struct Baz {};
+
+/// Included namespace
+namespace mrdocs {
+/// Included record
+struct Foo {};
+} // namespace mrdocs

test-files/golden-tests/config/include-symbols/global-symbol-excluded.html

@@ -0,0 +1,79 @@
+<html lang="en">
+<head>
+<title>Reference</title>
+<meta charset="utf-8">
+</head>
+<body>
+<div>
+<h1>Reference</h1>
+<div>
+<div>
+<h2 id="index">
+Global Namespace<a class="mrdocs-anchor" href="#index" aria-label="Permalink">#</a>
+</h2>
+</div>
+<h2>
+Namespaces</h2>
+<table style="table-layout: fixed; width: 100%;">
+<thead>
+<tr>
+<th>Name</th><th>Description</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td><a href="#mrdocs"><code>mrdocs</code></a> </td><td>Included namespace</td></tr>
+</tbody>
+</table>
+
+</div>
+<div>
+<div>
+<h2 id="mrdocs">
+mrdocs<a class="mrdocs-anchor" href="#mrdocs" aria-label="Permalink">#</a>
+</h2>
+<div>
+<p>Included namespace</p>
+</div>
+</div>
+<h2>
+Types</h2>
+<table style="table-layout: fixed; width: 100%;">
+<thead>
+<tr>
+<th>Name</th><th>Description</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td><a href="#mrdocs-Foo"><code>Foo</code></a> </td><td>Included record</td></tr>
+</tbody>
+</table>
+
+</div>
+<div>
+<div>
+<h2 id="mrdocs-Foo">
+mrdocs::Foo<a class="mrdocs-anchor" href="#mrdocs-Foo" aria-label="Permalink">#</a>
+</h2>
+<div>
+<p>Included record</p>
+</div>
+</div>
+<div>
+<h3>
+Synopsis</h3>
+<div>
+Declared in <code>&lt;global-symbol-excluded.cpp&gt;</code></div>
+<pre><code class="source-code cpp">struct Foo;</code></pre>
+</div>
+
+
+</div>
+
+</div>
+<footer class="mrdocs-footer">
+<span>Created with <a href="https://www.mrdocs.com">MrDocs</a></span>
+</footer>
+</body>
+</html>

test-files/golden-tests/config/include-symbols/global-symbol-excluded.xml

@@ -0,0 +1,21 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<mrdocs xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+       xsi:noNamespaceSchemaLocation="https://github.com/cppalliance/mrdocs/raw/develop/mrdocs.rnc">
+<namespace id="//////////////////////////8=">
+  <namespace name="mrdocs" id="rQr6X4pFwyRradNsE4fgTcl6Jmk=">
+    <doc>
+      <brief>
+        <text>Included namespace</text>
+      </brief>
+    </doc>
+    <struct name="Foo" id="yJQinsro3N5aSu4KK6p+ChnY5FM=">
+      <file short-path="global-symbol-excluded.cpp" source-path="global-symbol-excluded.cpp" line="8" class="def"/>
+      <doc>
+        <brief>
+          <text>Included record</text>
+        </brief>
+      </doc>
+    </struct>
+  </namespace>
+</namespace>
+</mrdocs>

test-files/golden-tests/config/include-symbols/global-symbol-excluded.yml

@@ -0,0 +1,2 @@
+include-symbols:
+  - 'mrdocs::**'