Merge branch 'develop' into ci/path-filters

Keep ci_test_documentation in repository_checks.yml and apply the
harden-runner 2.22.2 bump from #5962 there.

Signed-off-by: Niels Lohmann <mail@nlohmann.me>

.github/CONTRIBUTING.md

@@ -154,6 +154,11 @@ and each page's title (H1) and declaration by
 [`docs/docset/generate_docset.py`](https://github.com/nlohmann/json/blob/develop/docs/docset/generate_docset.py);
 `make build` reports API pages that cannot be classified.
 
+A pull request that changes only the documentation, Markdown files, GitHub metadata, or license files skips the
+compiler workflows (Ubuntu, macOS, Windows); the documentation and license checks still run. See
+[`tools/check_path_filters`](https://github.com/nlohmann/json/tree/develop/tools/check_path_filters) for the list of
+skipped files and what to do when a compiler job starts reading one of them.
+
 ### Amalgamate the source code
 
 The single-header files

.github/workflows/macos.yml

@@ -7,6 +7,25 @@ on:
       - master
       - release/*
   pull_request:
+    # Skip pull requests that change only files no job here reads. The list is checked by
+    # tools/check_path_filters/check_path_filters.py (repository_checks.yml); change both together.
+    paths:
+      - '**'
+      - '!docs/**'
+      - '!**.md'
+      - '!.github/*'
+      - '!.github/ISSUE_TEMPLATE/**'
+      - '!.github/external_ci/**'
+      - '!.github/workflows/**'
+      - '!.reuse/**'
+      - '!LICENSES/**'
+      - '!CITATION.cff'
+      - '!REUSE.toml'
+      # read by tools/check_build_options in the ci_meson_install job (ubuntu.yml)
+      - 'docs/mkdocs/docs/integration/package_managers.md'
+      # built by the swiftpm job (macos.yml)
+      - 'docs/mkdocs/docs/integration/swift/**'
+      - '.github/workflows/macos.yml'
   workflow_dispatch:
 
 concurrency:

.github/workflows/repository_checks.yml

@@ -0,0 +1,78 @@
+name: Repository checks
+
+# Checks that concern files the compiler workflows (ubuntu.yml, macos.yml,
+# windows.yml) skip with their path filter: the documentation, the license
+# information, and the path filter itself. This workflow has no path filter.
+on:
+  push:
+    branches:
+      - develop
+      - master
+      - release/*
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref || github.run_id }}
+  cancel-in-progress: true
+
+jobs:
+  check_path_filters:
+    runs-on: ubuntu-26.04
+    steps:
+      - name: Harden Runner
+        uses: step-security/harden-runner@dc2769abcc0fcfbadfc1df54081c1608579ef6b2 # v2.22.2
+        with:
+          egress-policy: audit
+
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - name: Check the path filters of the compiler workflows
+        run: python3 tools/check_path_filters/check_path_filters.py
+
+  ci_reuse_compliance:
+    runs-on: ubuntu-26.04
+    steps:
+      - name: Harden Runner
+        uses: step-security/harden-runner@dc2769abcc0fcfbadfc1df54081c1608579ef6b2 # v2.22.2
+        with:
+          egress-policy: audit
+
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - name: Get latest CMake and ninja
+        uses: lukka/get-cmake@a89e43e22a96abafcd7a62db652a65ecd33052c9 # v4.4.4
+      - name: Run CMake
+        run: cmake -S . -B build -DJSON_CI=On
+      - name: Build
+        run: cmake --build build --target ci_reuse_compliance
+
+  ci_test_documentation:
+    runs-on: ubuntu-26.04
+    strategy:
+      matrix:
+        target: [ci_test_examples, ci_test_build_documentation, ci_test_documentation_mermaid]
+    steps:
+      - name: Harden Runner
+        uses: step-security/harden-runner@dc2769abcc0fcfbadfc1df54081c1608579ef6b2 # v2.22.2
+        with:
+          egress-policy: audit
+
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+          # the git-revision-date-localized plugin needs the history; a shallow clone makes the strict build fail
+          fetch-depth: ${{ matrix.target == 'ci_test_build_documentation' && '0' || '1' }}
+      - uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
+        if: matrix.target == 'ci_test_documentation_mermaid'
+        with:
+          node-version: 24
+      - name: Run CMake
+        run: cmake -S . -B build -DJSON_CI=On
+      - name: Build
+        run: cmake --build build --target ${{ matrix.target }}

.github/workflows/ubuntu.yml

@@ -7,6 +7,25 @@ on:
       - master
       - release/*
   pull_request:
+    # Skip pull requests that change only files no job here reads. The list is checked by
+    # tools/check_path_filters/check_path_filters.py (repository_checks.yml); change both together.
+    paths:
+      - '**'
+      - '!docs/**'
+      - '!**.md'
+      - '!.github/*'
+      - '!.github/ISSUE_TEMPLATE/**'
+      - '!.github/external_ci/**'
+      - '!.github/workflows/**'
+      - '!.reuse/**'
+      - '!LICENSES/**'
+      - '!CITATION.cff'
+      - '!REUSE.toml'
+      # read by tools/check_build_options in the ci_meson_install job (ubuntu.yml)
+      - 'docs/mkdocs/docs/integration/package_managers.md'
+      # built by the swiftpm job (macos.yml)
+      - 'docs/mkdocs/docs/integration/swift/**'
+      - '.github/workflows/ubuntu.yml'
   workflow_dispatch:
 
 permissions:
@@ -109,7 +128,7 @@ jobs:
     runs-on: ubuntu-26.04
     strategy:
       matrix:
-        target: [ci_test_single_header, ci_cppcheck, ci_cpplint, ci_reproducible_tests, ci_non_git_tests, ci_offline_testdata, ci_reuse_compliance, ci_test_valgrind]
+        target: [ci_test_single_header, ci_cppcheck, ci_cpplint, ci_reproducible_tests, ci_non_git_tests, ci_offline_testdata, ci_test_valgrind]
     steps:
       - name: Harden Runner
         uses: step-security/harden-runner@dc2769abcc0fcfbadfc1df54081c1608579ef6b2 # v2.22.2
@@ -449,31 +468,6 @@ jobs:
       - name: Build
         run: cmake --build build
 
-  ci_test_documentation:
-    runs-on: ubuntu-26.04
-    strategy:
-      matrix:
-        target: [ci_test_examples, ci_test_build_documentation, ci_test_documentation_mermaid]
-    steps:
-      - name: Harden Runner
-        uses: step-security/harden-runner@dc2769abcc0fcfbadfc1df54081c1608579ef6b2 # v2.22.2
-        with:
-          egress-policy: audit
-
-      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
-        with:
-          persist-credentials: false
-          # the git-revision-date-localized plugin needs the history; a shallow clone makes the strict build fail
-          fetch-depth: ${{ matrix.target == 'ci_test_build_documentation' && '0' || '1' }}
-      - uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
-        if: matrix.target == 'ci_test_documentation_mermaid'
-        with:
-          node-version: 24
-      - name: Run CMake
-        run: cmake -S . -B build -DJSON_CI=On
-      - name: Build
-        run: cmake --build build --target ${{ matrix.target }}
-
   # Native Linux ARM64 runner with the latest GCC. The ubuntu-24.04-arm label is
   # only available for public repositories.
   ci_test_arm64:

.github/workflows/windows.yml

@@ -7,6 +7,25 @@ on:
       - master
       - release/*
   pull_request:
+    # Skip pull requests that change only files no job here reads. The list is checked by
+    # tools/check_path_filters/check_path_filters.py (repository_checks.yml); change both together.
+    paths:
+      - '**'
+      - '!docs/**'
+      - '!**.md'
+      - '!.github/*'
+      - '!.github/ISSUE_TEMPLATE/**'
+      - '!.github/external_ci/**'
+      - '!.github/workflows/**'
+      - '!.reuse/**'
+      - '!LICENSES/**'
+      - '!CITATION.cff'
+      - '!REUSE.toml'
+      # read by tools/check_build_options in the ci_meson_install job (ubuntu.yml)
+      - 'docs/mkdocs/docs/integration/package_managers.md'
+      # built by the swiftpm job (macos.yml)
+      - 'docs/mkdocs/docs/integration/swift/**'
+      - '.github/workflows/windows.yml'
   workflow_dispatch:
 
 permissions:

include/nlohmann/detail/input/binary_reader.hpp

@@ -4293,19 +4293,6 @@ class binary_reader
         return get_bytes(len, "string", result);
     }
 
-    /// whether @a s is valid UTF-8: ASCII eight bytes at a time, the rest
-    /// sequence by sequence (as the binary writers check strings)
-    static bool is_valid_utf8_string(const string_t& s, std::true_type /*is_byte*/) noexcept
-    {
-        return valid_utf8_string(reinterpret_cast<const unsigned char*>(s.data()), s.size());
-    }
-
-    /// whether @a s, of a character type wider than a byte, is valid UTF-8
-    static bool is_valid_utf8_string(const string_t& s, std::false_type /*is_byte*/) noexcept
-    {
-        return is_valid_utf8(s);
-    }
-
     /*!
     @brief validate a decoded text string (value or object key) against @ref error_handler
 
@@ -4325,16 +4312,7 @@ class binary_reader
     */
     bool check_string_utf8(string_t& result, const char* context)
     {
-        return error_handler == error_handler_t::keep || check_string_utf8_handler(result, context);
-    }
-
-    /// @ref check_string_utf8 for an error handler other than @ref
-    /// error_handler_t::keep; out of line, so that reading strings without a
-    /// check does not pay for the code of the check
-    JSON_HEDLEY_NEVER_INLINE
-    bool check_string_utf8_handler(string_t& result, const char* context)
-    {
-        if (is_valid_utf8_string(result, std::integral_constant<bool, sizeof(typename string_t::value_type) == 1>()))
+        if (error_handler == error_handler_t::keep || is_valid_utf8(result))
         {
             return true;
         }

include/nlohmann/detail/input/simd_scan.hpp

@@ -322,78 +322,6 @@ JSON_SCAN_SSSE3_TARGET JSON_HEDLEY_NEVER_INLINE inline bool vector_utf8_run(cons
     block_out = block;
     return false;
 }
-
-/*!
-@brief skip 16-byte blocks of well-formed UTF-8 at p (a character boundary)
-
-Like vector_utf8_run, but quotes, backslashes, and control characters are
-ordinary characters. Returns the start of the first block in which the check
-found an error (which may belong to a sequence begun in the block before) or
-where fewer than 16 bytes are left; a sequence may be cut at that point, so the
-caller resumes at its start, one sequence at a time.
-*/
-JSON_SCAN_SSSE3_TARGET JSON_HEDLEY_NEVER_INLINE inline const unsigned char* vector_utf8_valid_blocks(const unsigned char* block, const unsigned char* e) noexcept
-{
-    using lookup = utf8_lookup4<>;
-#if JSON_SCAN_NEON
-    const uint8x16_t t1h = vld1q_u8(lookup::byte_1_high.data());
-    const uint8x16_t t1l = vld1q_u8(lookup::byte_1_low.data());
-    const uint8x16_t t2h = vld1q_u8(lookup::byte_2_high.data());
-    uint8x16_t prev = vdupq_n_u8(0);
-    while (e - block >= 16)
-    {
-        const uint8x16_t in = vld1q_u8(block);
-        if (vmaxvq_u8(vorrq_u8(in, prev)) < 0x80)
-        {
-            // ASCII here, and no sequence from the block before to finish
-            prev = in;
-            block += 16;
-            continue;
-        }
-        const uint8x16_t prev1 = vextq_u8(prev, in, 15);
-        const uint8x16_t sc = vandq_u8(vandq_u8(vqtbl1q_u8(t1h, vshrq_n_u8(prev1, 4)), vqtbl1q_u8(t1l, vandq_u8(prev1, vdupq_n_u8(0x0F)))), vqtbl1q_u8(t2h, vshrq_n_u8(in, 4)));
-        const uint8x16_t must23 = vorrq_u8(vqsubq_u8(vextq_u8(prev, in, 14), vdupq_n_u8(0xE0 - 0x80)), vqsubq_u8(vextq_u8(prev, in, 13), vdupq_n_u8(0xF0 - 0x80)));
-        const uint8x16_t err = veorq_u8(vandq_u8(must23, vdupq_n_u8(0x80)), sc);
-        if (vmaxvq_u8(err) != 0)
-        {
-            break;
-        }
-        prev = in;
-        block += 16;
-    }
-#else
-    const __m128i t1h = _mm_loadu_si128(static_cast<const __m128i*>(static_cast<const void*>(lookup::byte_1_high.data()))); // NOLINT(bugprone-casting-through-void)
-    const __m128i t1l = _mm_loadu_si128(static_cast<const __m128i*>(static_cast<const void*>(lookup::byte_1_low.data()))); // NOLINT(bugprone-casting-through-void)
-    const __m128i t2h = _mm_loadu_si128(static_cast<const __m128i*>(static_cast<const void*>(lookup::byte_2_high.data()))); // NOLINT(bugprone-casting-through-void)
-    const __m128i nibble = _mm_set1_epi8(0x0F);
-    const __m128i zero = _mm_setzero_si128();
-    __m128i prev = zero;
-    while (e - block >= 16)
-    {
-        const __m128i in = _mm_loadu_si128(static_cast<const __m128i*>(static_cast<const void*>(block))); // NOLINT(bugprone-casting-through-void)
-        if (_mm_movemask_epi8(_mm_or_si128(in, prev)) == 0)
-        {
-            prev = in;
-            block += 16;
-            continue;
-        }
-        const __m128i prev1 = _mm_alignr_epi8(in, prev, 15);
-        const __m128i sc = _mm_and_si128(_mm_and_si128(_mm_shuffle_epi8(t1h, _mm_and_si128(_mm_srli_epi16(prev1, 4), nibble)),
-                                         _mm_shuffle_epi8(t1l, _mm_and_si128(prev1, nibble))),
-                                         _mm_shuffle_epi8(t2h, _mm_and_si128(_mm_srli_epi16(in, 4), nibble)));
-        const __m128i must23 = _mm_or_si128(_mm_subs_epu8(_mm_alignr_epi8(in, prev, 14), _mm_set1_epi8(0xE0 - 0x80)),
-                                            _mm_subs_epu8(_mm_alignr_epi8(in, prev, 13), _mm_set1_epi8(0xF0 - 0x80)));
-        const __m128i err = _mm_xor_si128(_mm_and_si128(must23, _mm_set1_epi8(static_cast<char>(-128))), sc);
-        if (_mm_movemask_epi8(_mm_cmpeq_epi8(err, zero)) != 0xFFFF)
-        {
-            break;
-        }
-        prev = in;
-        block += 16;
-    }
-#endif
-    return block;
-}
 #endif
 
 }  // namespace detail

include/nlohmann/detail/input/string_scan.hpp

@@ -236,64 +236,6 @@ inline std::size_t valid_utf8_prefix(const unsigned char* data, std::size_t n) n
     return pos;
 }
 
-/*!
-@brief whether [data, data+n) is valid UTF-8, for checking whole strings
-
-The same answer as valid_utf8_prefix(data, n) == n. Short ASCII strings, the
-most common keys and values, are decided in one test, and long strings are
-checked 16 bytes at a time where the vector check is available.
-*/
-inline bool valid_utf8_string(const unsigned char* data, std::size_t n) noexcept
-{
-    constexpr std::uint64_t high = 0x8080808080808080ull;
-    if (n <= 16)
-    {
-        // two overlapping words cover 8 to 16 bytes, one partial word fewer
-        std::uint64_t first = 0;
-        std::uint64_t last = 0;
-        if (n >= 8)
-        {
-            std::memcpy(&first, data, sizeof(first));
-            std::memcpy(&last, data + n - 8, sizeof(last));
-        }
-        else if (n != 0)
-        {
-            std::memcpy(&first, data, n);
-        }
-        if (((first | last) & high) == 0)
-        {
-            return true;
-        }
-    }
-#if JSON_SCAN_VECTOR_UTF8
-    else if (n >= 32
-#if JSON_SCAN_SSSE3_DISPATCH
-             && cpu_has_ssse3()
-#endif
-            )
-    {
-        const unsigned char* block = vector_utf8_valid_blocks(data, data + n);
-        // the rest from the start of a sequence that may be cut at block
-        for (int i = 1; i <= 3 && block - i >= data; ++i)
-        {
-            const unsigned char c = block[-i];
-            if (c < 0x80)
-            {
-                break;
-            }
-            if (c >= 0xC0)
-            {
-                block -= i;
-                break;
-            }
-        }
-        const auto checked = static_cast<std::size_t>(block - data);
-        return checked + valid_utf8_prefix(block, n - checked) == n;
-    }
-#endif
-    return valid_utf8_prefix(data, n) == n;
-}
-
 #if JSON_SCAN_VECTOR_UTF8
 /// the end of scan_string_vector from block, where the vector loop stopped
 /// (ill-formed UTF-8, or fewer than 16 bytes left): one byte or sequence at a

include/nlohmann/detail/output/binary_writer.hpp

@@ -3080,25 +3080,6 @@ class binary_writer
         }
     }
 
-    /// write the head and the characters of @a value, at most
-    /// max_text_in_reservation of them, in one reservation
-    JSON_HEDLEY_ALWAYS_INLINE void write_cbor_string_reserved(const string_t& value)
-    {
-        CharType* const out = oa.reserve(value.size() + 2);
-        CharType* p = out;
-        if (value.size() <= 0x17)
-        {
-            *p++ = to_char_type(static_cast<std::uint8_t>(0x60 + value.size()));
-        }
-        else
-        {
-            *p++ = to_char_type(0x78);
-            *p++ = to_char_type(static_cast<std::uint8_t>(value.size()));
-        }
-        copy_characters(p, reinterpret_cast<const CharType*>(value.data()), value.size());
-        oa.commit(static_cast<std::size_t>(p - out) + value.size());
-    }
-
     /*!
     @brief write a CBOR text string
 
@@ -3120,7 +3101,19 @@ class binary_writer
             // the string is written as it is: head and characters in one reservation
             if (JSON_HEDLEY_LIKELY(value.size() <= max_text_in_reservation))
             {
-                write_cbor_string_reserved(value);
+                CharType* const out = oa.reserve(value.size() + 2);
+                CharType* p = out;
+                if (value.size() <= 0x17)
+                {
+                    *p++ = to_char_type(static_cast<std::uint8_t>(0x60 + value.size()));
+                }
+                else
+                {
+                    *p++ = to_char_type(0x78);
+                    *p++ = to_char_type(static_cast<std::uint8_t>(value.size()));
+                }
+                copy_characters(p, reinterpret_cast<const CharType*>(value.data()), value.size());
+                oa.commit(static_cast<std::size_t>(p - out) + value.size());
                 return;
             }
         }
@@ -3134,13 +3127,6 @@ class binary_writer
     JSON_HEDLEY_NEVER_INLINE
     void write_cbor_checked_string(const string_t& value, const BasicJsonType& context)
     {
-        if (error_handler == error_handler_t::strict && value.size() <= max_text_in_reservation)
-        {
-            check_utf8(value, context);
-            write_cbor_string_reserved(value);
-            return;
-        }
-
         string_t storage;
         const string_t& sanitized = sanitize_utf8_for_write(value, context, storage);
 
@@ -3155,27 +3141,6 @@ class binary_writer
     // MsgPack //
     /////////////
 
-    /// write the head and the characters of @a value, at most
-    /// max_text_in_reservation of them, in one reservation
-    JSON_HEDLEY_ALWAYS_INLINE void write_msgpack_string_reserved(const string_t& value)
-    {
-        CharType* const out = oa.reserve(value.size() + 2);
-        CharType* p = out;
-        if (value.size() <= 31)
-        {
-            // fixstr
-            *p++ = to_char_type(static_cast<std::uint8_t>(0xA0 | value.size()));
-        }
-        else
-        {
-            // str 8
-            *p++ = to_char_type(0xD9);
-            *p++ = to_char_type(static_cast<std::uint8_t>(value.size()));
-        }
-        copy_characters(p, reinterpret_cast<const CharType*>(value.data()), value.size());
-        oa.commit(static_cast<std::size_t>(p - out) + value.size());
-    }
-
     /*!
     @brief write a MessagePack str
 
@@ -3193,7 +3158,21 @@ class binary_writer
             // the string is written as it is: head and characters in one reservation
             if (JSON_HEDLEY_LIKELY(value.size() <= max_text_in_reservation))
             {
-                write_msgpack_string_reserved(value);
+                CharType* const out = oa.reserve(value.size() + 2);
+                CharType* p = out;
+                if (value.size() <= 31)
+                {
+                    // fixstr
+                    *p++ = to_char_type(static_cast<std::uint8_t>(0xA0 | value.size()));
+                }
+                else
+                {
+                    // str 8
+                    *p++ = to_char_type(0xD9);
+                    *p++ = to_char_type(static_cast<std::uint8_t>(value.size()));
+                }
+                copy_characters(p, reinterpret_cast<const CharType*>(value.data()), value.size());
+                oa.commit(static_cast<std::size_t>(p - out) + value.size());
                 return;
             }
         }
@@ -3206,13 +3185,6 @@ class binary_writer
     JSON_HEDLEY_NEVER_INLINE
     void write_msgpack_checked_string(const string_t& value, const BasicJsonType& context)
     {
-        if (error_handler == error_handler_t::strict && value.size() <= max_text_in_reservation)
-        {
-            check_utf8(value, context);
-            write_msgpack_string_reserved(value);
-            return;
-        }
-
         string_t storage;
         const string_t& sanitized = sanitize_utf8_for_write(value, context, storage);
 
@@ -4822,9 +4794,10 @@ class binary_writer
     static void check_utf8(const string_t& s, const BasicJsonType& context)
     {
         const auto* data = reinterpret_cast<const unsigned char*>(s.data());
-        if (JSON_HEDLEY_UNLIKELY(!valid_utf8_string(data, s.size())))
+        const std::size_t valid = valid_utf8_prefix(data, s.size());
+        if (JSON_HEDLEY_UNLIKELY(valid != s.size()))
         {
-            throw_invalid_utf8(data, valid_utf8_prefix(data, s.size()), context);
+            throw_invalid_utf8(data, valid, context);
         }
     }
 

include/nlohmann/json_view.hpp

@@ -766,6 +766,9 @@ class basic_json_view
     template<typename, typename> friend class detail::view::view_side;
     friend iterator;
 
+    /// whether the view is one of an editable document
+    static constexpr bool is_editable = Editable;
+
     basic_json_view(const document_data* d, const node* n) noexcept
         : m_doc(d), m_node(n)
     {}

single_include/nlohmann/json.hpp

@@ -12377,78 +12377,6 @@ JSON_SCAN_SSSE3_TARGET JSON_HEDLEY_NEVER_INLINE inline bool vector_utf8_run(cons
     block_out = block;
     return false;
 }
-
-/*!
-@brief skip 16-byte blocks of well-formed UTF-8 at p (a character boundary)
-
-Like vector_utf8_run, but quotes, backslashes, and control characters are
-ordinary characters. Returns the start of the first block in which the check
-found an error (which may belong to a sequence begun in the block before) or
-where fewer than 16 bytes are left; a sequence may be cut at that point, so the
-caller resumes at its start, one sequence at a time.
-*/
-JSON_SCAN_SSSE3_TARGET JSON_HEDLEY_NEVER_INLINE inline const unsigned char* vector_utf8_valid_blocks(const unsigned char* block, const unsigned char* e) noexcept
-{
-    using lookup = utf8_lookup4<>;
-#if JSON_SCAN_NEON
-    const uint8x16_t t1h = vld1q_u8(lookup::byte_1_high.data());
-    const uint8x16_t t1l = vld1q_u8(lookup::byte_1_low.data());
-    const uint8x16_t t2h = vld1q_u8(lookup::byte_2_high.data());
-    uint8x16_t prev = vdupq_n_u8(0);
-    while (e - block >= 16)
-    {
-        const uint8x16_t in = vld1q_u8(block);
-        if (vmaxvq_u8(vorrq_u8(in, prev)) < 0x80)
-        {
-            // ASCII here, and no sequence from the block before to finish
-            prev = in;
-            block += 16;
-            continue;
-        }
-        const uint8x16_t prev1 = vextq_u8(prev, in, 15);
-        const uint8x16_t sc = vandq_u8(vandq_u8(vqtbl1q_u8(t1h, vshrq_n_u8(prev1, 4)), vqtbl1q_u8(t1l, vandq_u8(prev1, vdupq_n_u8(0x0F)))), vqtbl1q_u8(t2h, vshrq_n_u8(in, 4)));
-        const uint8x16_t must23 = vorrq_u8(vqsubq_u8(vextq_u8(prev, in, 14), vdupq_n_u8(0xE0 - 0x80)), vqsubq_u8(vextq_u8(prev, in, 13), vdupq_n_u8(0xF0 - 0x80)));
-        const uint8x16_t err = veorq_u8(vandq_u8(must23, vdupq_n_u8(0x80)), sc);
-        if (vmaxvq_u8(err) != 0)
-        {
-            break;
-        }
-        prev = in;
-        block += 16;
-    }
-#else
-    const __m128i t1h = _mm_loadu_si128(static_cast<const __m128i*>(static_cast<const void*>(lookup::byte_1_high.data()))); // NOLINT(bugprone-casting-through-void)
-    const __m128i t1l = _mm_loadu_si128(static_cast<const __m128i*>(static_cast<const void*>(lookup::byte_1_low.data()))); // NOLINT(bugprone-casting-through-void)
-    const __m128i t2h = _mm_loadu_si128(static_cast<const __m128i*>(static_cast<const void*>(lookup::byte_2_high.data()))); // NOLINT(bugprone-casting-through-void)
-    const __m128i nibble = _mm_set1_epi8(0x0F);
-    const __m128i zero = _mm_setzero_si128();
-    __m128i prev = zero;
-    while (e - block >= 16)
-    {
-        const __m128i in = _mm_loadu_si128(static_cast<const __m128i*>(static_cast<const void*>(block))); // NOLINT(bugprone-casting-through-void)
-        if (_mm_movemask_epi8(_mm_or_si128(in, prev)) == 0)
-        {
-            prev = in;
-            block += 16;
-            continue;
-        }
-        const __m128i prev1 = _mm_alignr_epi8(in, prev, 15);
-        const __m128i sc = _mm_and_si128(_mm_and_si128(_mm_shuffle_epi8(t1h, _mm_and_si128(_mm_srli_epi16(prev1, 4), nibble)),
-                                         _mm_shuffle_epi8(t1l, _mm_and_si128(prev1, nibble))),
-                                         _mm_shuffle_epi8(t2h, _mm_and_si128(_mm_srli_epi16(in, 4), nibble)));
-        const __m128i must23 = _mm_or_si128(_mm_subs_epu8(_mm_alignr_epi8(in, prev, 14), _mm_set1_epi8(0xE0 - 0x80)),
-                                            _mm_subs_epu8(_mm_alignr_epi8(in, prev, 13), _mm_set1_epi8(0xF0 - 0x80)));
-        const __m128i err = _mm_xor_si128(_mm_and_si128(must23, _mm_set1_epi8(static_cast<char>(-128))), sc);
-        if (_mm_movemask_epi8(_mm_cmpeq_epi8(err, zero)) != 0xFFFF)
-        {
-            break;
-        }
-        prev = in;
-        block += 16;
-    }
-#endif
-    return block;
-}
 #endif
 
 }  // namespace detail
@@ -12676,64 +12604,6 @@ inline std::size_t valid_utf8_prefix(const unsigned char* data, std::size_t n) n
     return pos;
 }
 
-/*!
-@brief whether [data, data+n) is valid UTF-8, for checking whole strings
-
-The same answer as valid_utf8_prefix(data, n) == n. Short ASCII strings, the
-most common keys and values, are decided in one test, and long strings are
-checked 16 bytes at a time where the vector check is available.
-*/
-inline bool valid_utf8_string(const unsigned char* data, std::size_t n) noexcept
-{
-    constexpr std::uint64_t high = 0x8080808080808080ull;
-    if (n <= 16)
-    {
-        // two overlapping words cover 8 to 16 bytes, one partial word fewer
-        std::uint64_t first = 0;
-        std::uint64_t last = 0;
-        if (n >= 8)
-        {
-            std::memcpy(&first, data, sizeof(first));
-            std::memcpy(&last, data + n - 8, sizeof(last));
-        }
-        else if (n != 0)
-        {
-            std::memcpy(&first, data, n);
-        }
-        if (((first | last) & high) == 0)
-        {
-            return true;
-        }
-    }
-#if JSON_SCAN_VECTOR_UTF8
-    else if (n >= 32
-#if JSON_SCAN_SSSE3_DISPATCH
-             && cpu_has_ssse3()
-#endif
-            )
-    {
-        const unsigned char* block = vector_utf8_valid_blocks(data, data + n);
-        // the rest from the start of a sequence that may be cut at block
-        for (int i = 1; i <= 3 && block - i >= data; ++i)
-        {
-            const unsigned char c = block[-i];
-            if (c < 0x80)
-            {
-                break;
-            }
-            if (c >= 0xC0)
-            {
-                block -= i;
-                break;
-            }
-        }
-        const auto checked = static_cast<std::size_t>(block - data);
-        return checked + valid_utf8_prefix(block, n - checked) == n;
-    }
-#endif
-    return valid_utf8_prefix(data, n) == n;
-}
-
 #if JSON_SCAN_VECTOR_UTF8
 /// the end of scan_string_vector from block, where the vector loop stopped
 /// (ill-formed UTF-8, or fewer than 16 bytes left): one byte or sequence at a
@@ -22199,19 +22069,6 @@ class binary_reader
         return get_bytes(len, "string", result);
     }
 
-    /// whether @a s is valid UTF-8: ASCII eight bytes at a time, the rest
-    /// sequence by sequence (as the binary writers check strings)
-    static bool is_valid_utf8_string(const string_t& s, std::true_type /*is_byte*/) noexcept
-    {
-        return valid_utf8_string(reinterpret_cast<const unsigned char*>(s.data()), s.size());
-    }
-
-    /// whether @a s, of a character type wider than a byte, is valid UTF-8
-    static bool is_valid_utf8_string(const string_t& s, std::false_type /*is_byte*/) noexcept
-    {
-        return is_valid_utf8(s);
-    }
-
     /*!
     @brief validate a decoded text string (value or object key) against @ref error_handler
 
@@ -22231,16 +22088,7 @@ class binary_reader
     */
     bool check_string_utf8(string_t& result, const char* context)
     {
-        return error_handler == error_handler_t::keep || check_string_utf8_handler(result, context);
-    }
-
-    /// @ref check_string_utf8 for an error handler other than @ref
-    /// error_handler_t::keep; out of line, so that reading strings without a
-    /// check does not pay for the code of the check
-    JSON_HEDLEY_NEVER_INLINE
-    bool check_string_utf8_handler(string_t& result, const char* context)
-    {
-        if (is_valid_utf8_string(result, std::integral_constant<bool, sizeof(typename string_t::value_type) == 1>()))
+        if (error_handler == error_handler_t::keep || is_valid_utf8(result))
         {
             return true;
         }
@@ -30458,25 +30306,6 @@ class binary_writer
         }
     }
 
-    /// write the head and the characters of @a value, at most
-    /// max_text_in_reservation of them, in one reservation
-    JSON_HEDLEY_ALWAYS_INLINE void write_cbor_string_reserved(const string_t& value)
-    {
-        CharType* const out = oa.reserve(value.size() + 2);
-        CharType* p = out;
-        if (value.size() <= 0x17)
-        {
-            *p++ = to_char_type(static_cast<std::uint8_t>(0x60 + value.size()));
-        }
-        else
-        {
-            *p++ = to_char_type(0x78);
-            *p++ = to_char_type(static_cast<std::uint8_t>(value.size()));
-        }
-        copy_characters(p, reinterpret_cast<const CharType*>(value.data()), value.size());
-        oa.commit(static_cast<std::size_t>(p - out) + value.size());
-    }
-
     /*!
     @brief write a CBOR text string
 
@@ -30498,7 +30327,19 @@ class binary_writer
             // the string is written as it is: head and characters in one reservation
             if (JSON_HEDLEY_LIKELY(value.size() <= max_text_in_reservation))
             {
-                write_cbor_string_reserved(value);
+                CharType* const out = oa.reserve(value.size() + 2);
+                CharType* p = out;
+                if (value.size() <= 0x17)
+                {
+                    *p++ = to_char_type(static_cast<std::uint8_t>(0x60 + value.size()));
+                }
+                else
+                {
+                    *p++ = to_char_type(0x78);
+                    *p++ = to_char_type(static_cast<std::uint8_t>(value.size()));
+                }
+                copy_characters(p, reinterpret_cast<const CharType*>(value.data()), value.size());
+                oa.commit(static_cast<std::size_t>(p - out) + value.size());
                 return;
             }
         }
@@ -30512,13 +30353,6 @@ class binary_writer
     JSON_HEDLEY_NEVER_INLINE
     void write_cbor_checked_string(const string_t& value, const BasicJsonType& context)
     {
-        if (error_handler == error_handler_t::strict && value.size() <= max_text_in_reservation)
-        {
-            check_utf8(value, context);
-            write_cbor_string_reserved(value);
-            return;
-        }
-
         string_t storage;
         const string_t& sanitized = sanitize_utf8_for_write(value, context, storage);
 
@@ -30533,27 +30367,6 @@ class binary_writer
     // MsgPack //
     /////////////
 
-    /// write the head and the characters of @a value, at most
-    /// max_text_in_reservation of them, in one reservation
-    JSON_HEDLEY_ALWAYS_INLINE void write_msgpack_string_reserved(const string_t& value)
-    {
-        CharType* const out = oa.reserve(value.size() + 2);
-        CharType* p = out;
-        if (value.size() <= 31)
-        {
-            // fixstr
-            *p++ = to_char_type(static_cast<std::uint8_t>(0xA0 | value.size()));
-        }
-        else
-        {
-            // str 8
-            *p++ = to_char_type(0xD9);
-            *p++ = to_char_type(static_cast<std::uint8_t>(value.size()));
-        }
-        copy_characters(p, reinterpret_cast<const CharType*>(value.data()), value.size());
-        oa.commit(static_cast<std::size_t>(p - out) + value.size());
-    }
-
     /*!
     @brief write a MessagePack str
 
@@ -30571,7 +30384,21 @@ class binary_writer
             // the string is written as it is: head and characters in one reservation
             if (JSON_HEDLEY_LIKELY(value.size() <= max_text_in_reservation))
             {
-                write_msgpack_string_reserved(value);
+                CharType* const out = oa.reserve(value.size() + 2);
+                CharType* p = out;
+                if (value.size() <= 31)
+                {
+                    // fixstr
+                    *p++ = to_char_type(static_cast<std::uint8_t>(0xA0 | value.size()));
+                }
+                else
+                {
+                    // str 8
+                    *p++ = to_char_type(0xD9);
+                    *p++ = to_char_type(static_cast<std::uint8_t>(value.size()));
+                }
+                copy_characters(p, reinterpret_cast<const CharType*>(value.data()), value.size());
+                oa.commit(static_cast<std::size_t>(p - out) + value.size());
                 return;
             }
         }
@@ -30584,13 +30411,6 @@ class binary_writer
     JSON_HEDLEY_NEVER_INLINE
     void write_msgpack_checked_string(const string_t& value, const BasicJsonType& context)
     {
-        if (error_handler == error_handler_t::strict && value.size() <= max_text_in_reservation)
-        {
-            check_utf8(value, context);
-            write_msgpack_string_reserved(value);
-            return;
-        }
-
         string_t storage;
         const string_t& sanitized = sanitize_utf8_for_write(value, context, storage);
 
@@ -32200,9 +32020,10 @@ class binary_writer
     static void check_utf8(const string_t& s, const BasicJsonType& context)
     {
         const auto* data = reinterpret_cast<const unsigned char*>(s.data());
-        if (JSON_HEDLEY_UNLIKELY(!valid_utf8_string(data, s.size())))
+        const std::size_t valid = valid_utf8_prefix(data, s.size());
+        if (JSON_HEDLEY_UNLIKELY(valid != s.size()))
         {
-            throw_invalid_utf8(data, valid_utf8_prefix(data, s.size()), context);
+            throw_invalid_utf8(data, valid, context);
         }
     }
 

single_include/nlohmann/json_view.hpp

@@ -9807,6 +9807,9 @@ class basic_json_view
     template<typename, typename> friend class detail::view::view_side;
     friend iterator;
 
+    /// whether the view is one of an editable document
+    static constexpr bool is_editable = Editable;
+
     basic_json_view(const document_data* d, const node* n) noexcept
         : m_doc(d), m_node(n)
     {}

tests/src/unit-guard-page.cpp

@@ -403,7 +403,6 @@ TEST_CASE("guard page")
                     CHECK(nlohmann::detail::find_string_special(p, n) <= n);
                     CHECK(nlohmann::detail::find_ascii_copyable_run(p, n) <= n);
                     CHECK(nlohmann::detail::valid_utf8_prefix(p, n) <= n);
-                    CHECK(nlohmann::detail::valid_utf8_string(p, n) == (nlohmann::detail::valid_utf8_prefix(p, n) == n));
 #if defined(JSON_USE_SIMDUTF) && defined(JSON_HAS_CPP_17)
                     CHECK(nlohmann::detail::find_string_delimiter(p, n) <= n);
 #endif

tests/src/unit-unicode.cpp

@@ -13,7 +13,6 @@ using nlohmann::json;
 
 #include <algorithm>
 #include <fstream>
-#include <random>
 #include <string>
 #include "make_test_data_available.hpp"
 #include "test_utils.hpp"
@@ -1632,40 +1631,3 @@ TEST_CASE("Unicode RFC 3629")
 }
 
 DOCTEST_CLANG_SUPPRESS_WARNING_POP
-
-TEST_CASE("UTF-8 check of whole strings")
-{
-    // valid_utf8_string() decides short strings with a word test and long ones
-    // 16 bytes at a time where a vector check is available; it must agree with
-    // the byte-wise check for every mix of ASCII, sequences of each length,
-    // ill-formed and truncated sequences, at every length and offset
-    const char* const pieces[] =
-    {
-        "a", "\x7F", "\xC3\xA9", "\xE2\x82\xAC", "\xE0\xA0\x80", "\xEF\xBF\xBF", "\xF0\x9F\x98\x80", "\xF4\x8F\xBF\xBF",
-        "\x80", "\xC0\xAF", "\xC3", "\xE2\x82", "\xED\xA0\x80", "\xF0\x9F", "\xF4\x90\x80\x80", "\xFF"
-    };
-    // std::mt19937's sequence is fixed by the standard; no distribution is used
-    std::mt19937 rng(5);
-    std::size_t valid = 0;
-    for (int i = 0; i < 100000; ++i)
-    {
-        std::string s;
-        const std::size_t length = rng() % 100;
-        const std::uint32_t ascii = rng() % 101;
-        while (s.size() < length)
-        {
-            // mostly well-formed pieces (the first eight), so that long valid
-            // strings are common
-            s += (rng() % 100 < ascii) ? std::string("x") : std::string(pieces[rng() % (rng() % 8 == 0 ? 16 : 8)]);
-        }
-        const auto* data = reinterpret_cast<const unsigned char*>(s.data());
-        const bool expected = nlohmann::detail::is_valid_utf8(s);
-        valid += expected ? 1 : 0;
-        CAPTURE(s)
-        CHECK(nlohmann::detail::valid_utf8_string(data, s.size()) == expected);
-        CHECK((nlohmann::detail::valid_utf8_prefix(data, s.size()) == s.size()) == expected);
-    }
-    // both outcomes are common enough to be tested
-    CHECK(valid > 20000);
-    CHECK(valid < 80000);
-}

tools/check_path_filters/README.md

@@ -0,0 +1,34 @@
+# check_path_filters
+
+The compiler workflows [`ubuntu.yml`](../../.github/workflows/ubuntu.yml),
+[`macos.yml`](../../.github/workflows/macos.yml), and [`windows.yml`](../../.github/workflows/windows.yml) skip pull
+requests that change only files no compiler job reads: the documentation, Markdown files, GitHub metadata, other
+workflows, and the license files. Pushes to `develop`, `master`, and `release/*` always run them. The documentation,
+license, and path-filter checks run in [`repository_checks.yml`](../../.github/workflows/repository_checks.yml), which
+has no path filter.
+
+The filter starts with `'**'` and excludes these files explicitly, so a new file runs the compiler workflows unless it
+is excluded on purpose. [`check_path_filters.py`](check_path_filters.py) holds the filter (`PATHS`) and checks that
+
+- each of the three workflows has exactly this filter, with its own workflow file included,
+- the CI targets that read excluded files (`UNFILTERED_TARGETS`) do not run in these workflows, and
+- no file the filter keeps (sources, tests, build files, tools, workflows) mentions an excluded file or directory
+  outside a comment line, unless the mention is listed in `KNOWN_REFERENCES` with a reason.
+
+When the check reports a mention, decide whether a compiler job reads that file:
+
+- If it does, include the file in `PATHS` after the exclusions (as `package_managers.md` and the Swift example are) and
+  copy the new filter into the three workflows.
+- If it does not, add the mention to `KNOWN_REFERENCES` with the reason.
+
+Run the check with
+
+```shell
+python3 tools/check_path_filters/check_path_filters.py
+```
+
+To see which workflows a pull request would run, pass the changed files:
+
+```shell
+python3 tools/check_path_filters/check_path_filters.py --changed $(git diff --name-only origin/develop)
+```

tools/check_path_filters/check_path_filters.py

@@ -0,0 +1,269 @@
+#!/usr/bin/env python3
+"""Check the path filters of the compiler workflows.
+
+ubuntu.yml, macos.yml and windows.yml skip pull requests that change only files
+no compiler job reads (documentation, Markdown files, GitHub metadata, license
+files). The filter starts with '**' and excludes these files explicitly, so a
+new file runs the workflows unless it is excluded on purpose.
+
+The script checks that
+
+- each of the three workflows has exactly the filter defined in PATHS below,
+  with its own workflow file included, and
+- no tracked file that the filter keeps (sources, tests, build files, tools,
+  workflows) mentions a file the filter excludes, unless the mention is listed
+  in KNOWN_REFERENCES with the reason why it does not matter.
+
+A mention found this way must either be added to PATHS as an included path
+(the file is read by a compiler job) or to KNOWN_REFERENCES (it is not).
+
+With --changed FILE..., the script prints instead which workflows a pull
+request changing these files would run.
+"""
+
+import argparse
+import os
+import re
+import subprocess  # nosec B404
+import sys
+
+REPO_ROOT = os.path.normpath(os.path.join(sys.path[0], '..', '..'))
+SELF = 'tools/check_path_filters/check_path_filters.py'
+
+WORKFLOWS = ['.github/workflows/ubuntu.yml', '.github/workflows/macos.yml', '.github/workflows/windows.yml']
+
+# The pull_request paths filter of the workflows above; '{workflow}' is replaced
+# with the workflow's own file. GitHub applies the patterns in order: a file
+# matching a later pattern is included ('pattern') or excluded ('!pattern').
+PATHS = [
+    '**',
+    '!docs/**',
+    '!**.md',
+    '!.github/*',
+    '!.github/ISSUE_TEMPLATE/**',
+    '!.github/external_ci/**',
+    '!.github/workflows/**',
+    '!.reuse/**',
+    '!LICENSES/**',
+    '!CITATION.cff',
+    '!REUSE.toml',
+    # read by tools/check_build_options in the ci_meson_install job (ubuntu.yml)
+    'docs/mkdocs/docs/integration/package_managers.md',
+    # built by the swiftpm job (macos.yml)
+    'docs/mkdocs/docs/integration/swift/**',
+    '{workflow}',
+]
+
+# Mentions of excluded files that no job of the three workflows depends on:
+# (file that mentions it, the mention, reason)
+KNOWN_REFERENCES = [
+    ('cmake/ci.cmake', 'docs/', 'ci_test_examples; runs in repository_checks.yml, which has no path filter'),
+    ('cmake/ci.cmake', 'docs/mkdocs/', 'ci_test_build_documentation and ci_test_documentation_mermaid; they run in '
+                                       'repository_checks.yml, which has no path filter'),
+    ('cmake/ci.cmake', 'docs/mkdocs/docs/examples/', 'indentation check of ci_test_amalgamation; the same check runs in '
+                                                     'check_amalgamation.yml, which has no path filter'),
+    ('Makefile', 'docs/mkdocs/docs/examples/', 'make pretty; runs in check_amalgamation.yml, which has no path filter'),
+    ('Makefile', 'ChangeLog.md', 'make ChangeLog.md writes the file; no CI job runs it'),
+    ('Makefile', 'tests/fuzzing.md', 'help text'),
+    ('Makefile', 'tools/generate_natvis/README.md', 'help text'),
+    ('tests/src/make_test_data_available.hpp', 'README.md', 'a file of the external test data repository'),
+    ('tools/check_build_options/check_build_options.py', 'docs/', 'builds the path of package_managers.md, which '
+                                                                  'PATHS includes'),
+]
+
+
+# CI targets that read excluded files; they must run in a workflow without a path filter
+UNFILTERED_TARGETS = ['ci_test_examples', 'ci_test_build_documentation', 'ci_test_documentation_mermaid',
+                      'ci_test_amalgamation', 'ci_reuse_compliance']
+
+
+def git_files(root):
+    # fixed command, no user input; includes new files not yet added, so a local run
+    # sees what CI sees after the commit
+    out = subprocess.check_output(['git', 'ls-files', '-z', '--cached', '--others', '--exclude-standard'], cwd=root)  # nosec B603, B607
+    return [f for f in out.decode('utf-8').split('\0') if f]
+
+
+def glob_to_regex(pattern):
+    """Translate a GitHub Actions path pattern to a regular expression."""
+    regex = ''
+    i = 0
+    while i < len(pattern):
+        if pattern.startswith('**', i):
+            regex += '.*'
+            i += 2
+        elif pattern[i] == '*':
+            regex += '[^/]*'
+            i += 1
+        elif pattern[i] == '?':
+            regex += '[^/]'
+            i += 1
+        else:
+            regex += re.escape(pattern[i])
+            i += 1
+    return re.compile(regex + r'\Z')
+
+
+def compile_filter(paths, workflow):
+    return [(p.startswith('!'), glob_to_regex(p.lstrip('!').replace('{workflow}', workflow))) for p in paths]
+
+
+def included(compiled, path):
+    result = False
+    for negated, regex in compiled:
+        if regex.match(path):
+            result = not negated
+    return result
+
+
+def read_filter(root, workflow):
+    """Return the pull_request paths list of a workflow file."""
+    with open(os.path.join(root, workflow), encoding='utf-8') as f:
+        lines = f.read().splitlines()
+    paths = None
+    in_pull_request = False
+    for line in lines:
+        if re.match(r'^  pull_request:', line):
+            in_pull_request = True
+            continue
+        if in_pull_request:
+            if re.match(r'^  \S', line) or re.match(r'^\S', line):
+                break
+            if re.match(r'^    paths:\s*$', line):
+                paths = []
+                continue
+            m = re.match(r"^      - '(.*)'\s*(#.*)?$", line)
+            if paths is not None and m:
+                paths.append(m.group(1))
+            elif paths is not None and line.strip() and not line.strip().startswith('#'):
+                break
+    return paths
+
+
+TOKEN = re.compile(r'(["\'/]?)([\w.-]+(?:/[\w.-]+)*)')
+
+
+COMMENT_LINE = re.compile(r'^[ \t]*(//|#|/?\*|--).*$', re.MULTILINE)
+
+
+class Mentions:
+    """Finds the words and paths in a text that name an excluded file or directory."""
+
+    def __init__(self, files, excluded, is_excluded):
+        self.files = set(files)
+        self.excluded = excluded
+        self.dirs = {'/'.join(f.split('/')[:n]) for f in files for n in range(1, f.count('/') + 1)}
+        # an excluded directory: a new file in it would be excluded
+        self.excluded_dirs = {d for d in self.dirs if is_excluded(d + '/new_file')}
+        # base names that only excluded files have, e.g. 'ChangeLog.md' but not 'CMakeLists.txt'
+        self.names = {os.path.basename(f) for f in excluded} - {os.path.basename(f) for f in files if f not in excluded}
+
+    def find(self, text):
+        """Yield (offset, mention) for every word or path in text that names an excluded file or directory."""
+        for m in TOKEN.finditer(text):
+            parts = m.group(2).rstrip('/').split('/')
+            # a single word names a directory only in a path context, e.g. 'docs' in os.path.join('docs', ...)
+            path_context = len(parts) > 1 or m.group(1)
+            for i in range(len(parts)):
+                path = '/'.join(parts[i:])
+                if path in self.files:
+                    if path in self.excluded:
+                        yield m.start(2), path
+                    break
+                if path in self.dirs and path_context:
+                    if path in self.excluded_dirs:
+                        yield m.start(2), path + '/'
+                    break
+            else:
+                if parts[-1] in self.names and '.' in parts[-1]:
+                    yield m.start(2), parts[-1]
+
+
+def known(path, mention):
+    return any(path == file and mention == known_mention for file, known_mention, _ in KNOWN_REFERENCES)
+
+
+def check_workflows(root):
+    """Return the errors in the filters of the workflows and in the targets they run."""
+    errors = []
+    for workflow in WORKFLOWS:
+        expected = [p.replace('{workflow}', workflow) for p in PATHS]
+        actual = read_filter(root, workflow)
+        if actual != expected:
+            errors.append('{}: the pull_request paths filter differs from tools/check_path_filters/check_path_filters.py\n'
+                          '  expected: {}\n  actual:   {}'.format(workflow, expected, actual))
+        with open(os.path.join(root, workflow), encoding='utf-8') as f:
+            text = f.read()
+        errors += ['{}: runs {}, which reads excluded files; run it in repository_checks.yml'.format(workflow, target)
+                   for target in UNFILTERED_TARGETS if re.search(r'\b' + target + r'\b', text)]
+    return errors
+
+
+def scanned_text(root, path):
+    """Return the text of a kept file without comment lines and without the filter itself, or None to skip it."""
+    # third-party code and Markdown files read nothing; this script lists the excluded files
+    if path.startswith('tests/thirdparty/') or path.endswith('.md') or path == SELF:
+        return None
+    try:
+        with open(os.path.join(root, path), encoding='utf-8') as f:
+            # a mention in a comment line reads nothing; keep the line numbers
+            text = COMMENT_LINE.sub('', f.read())
+    except (UnicodeDecodeError, OSError):
+        return None
+    if path in WORKFLOWS:
+        # the filter itself lists the excluded files
+        for p in PATHS:
+            text = text.replace("      - '{}'".format(p.replace('{workflow}', path)), '')
+    return text
+
+
+def check_mentions(root, files, excluded, finder):
+    """Return an error for every mention of an excluded file in a kept file that KNOWN_REFERENCES does not list."""
+    errors = []
+    for path in sorted(set(files) - excluded):
+        text = scanned_text(root, path)
+        reported = set()
+        for offset, mention in finder.find(text or ''):
+            if mention not in reported and not known(path, mention):
+                reported.add(mention)
+                line = text.count('\n', 0, offset) + 1
+                errors.append('{}:{}: mentions excluded {}; include it in PATHS if a compiler job reads it, '
+                              'or add it to KNOWN_REFERENCES'.format(path, line, mention))
+    return errors
+
+
+def check(root):
+    files = git_files(root)
+    union = [compile_filter(PATHS, w) for w in WORKFLOWS]
+
+    def is_excluded(path):
+        return not any(included(c, path) for c in union)
+
+    excluded = {f for f in files if is_excluded(f)}
+    errors = check_workflows(root) + check_mentions(root, files, excluded, Mentions(files, excluded, is_excluded))
+    for e in errors:
+        print(e)
+    if not errors:
+        print('path filters OK: {} of {} tracked files skip the compiler workflows'.format(len(excluded), len(files)))
+    return 1 if errors else 0
+
+
+def explain(changed):
+    for workflow in WORKFLOWS:
+        compiled = compile_filter(PATHS, workflow)
+        hits = [f for f in changed if included(compiled, f)]
+        print('{}: {}'.format(workflow, 'runs ({})'.format(', '.join(hits[:3]) + (' ...' if len(hits) > 3 else ''))
+                                       if hits else 'skipped'))
+    return 0
+
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__.splitlines()[0])
+    parser.add_argument('--root', default=REPO_ROOT, help='repository root')
+    parser.add_argument('--changed', nargs='+', metavar='FILE', help='show which workflows these changed files run')
+    args = parser.parse_args()
+    return explain(args.changed) if args.changed else check(args.root)
+
+
+if __name__ == '__main__':
+    sys.exit(main())