filter char8_t from public symbols (#11881)

GitOrigin-RevId: 33f604843aa97f4f8f5b83eb069c42c3a5bb957e

Author: evil159

scripts/doc-generation/strip-compiler-artifacts.py

@@ -0,0 +1,56 @@
+#!/usr/bin/env python3
+"""Remove compiler-artifact symbols from DocC symbol graph JSON files.
+
+Newer Swift compilers (Xcode 16.3+) import `char8_t` from auto-generated
+-Swift.h bridging headers as a public typealias. When the dependency module
+is re-exported (via @_exported import), these symbols leak into the
+MapboxMaps documentation. This script strips them from the symbol graphs
+before DocC processes them.
+"""
+
+import json
+import os
+import sys
+
+# Symbols that are compiler artifacts and should not appear in public docs.
+ARTIFACTS = {"char8_t"}
+
+
+def strip(path):
+    with open(path) as f:
+        sg = json.load(f)
+
+    artifact_ids = set()
+    filtered_symbols = []
+    for sym in sg.get("symbols", []):
+        if sym["names"]["title"] in ARTIFACTS:
+            artifact_ids.add(sym["identifier"]["precise"])
+        else:
+            filtered_symbols.append(sym)
+
+    if not artifact_ids:
+        return
+
+    sg["symbols"] = filtered_symbols
+    sg["relationships"] = [
+        r for r in sg.get("relationships", []) if r["source"] not in artifact_ids and r["target"] not in artifact_ids
+    ]
+
+    with open(path, "w") as f:
+        json.dump(sg, f)
+
+    basepath = os.path.relpath(path, sys.argv[1])
+    print(f"  Stripped {artifact_ids} from {basepath}")
+
+
+def main():
+    symbol_graph_dir = sys.argv[1]
+    print(f"Stripping compiler artifacts from symbol graphs in {symbol_graph_dir}")
+    for root, _, files in os.walk(symbol_graph_dir):
+        for name in files:
+            if name.endswith(".symbols.json"):
+                strip(os.path.join(root, name))
+
+
+if __name__ == "__main__":
+    main()

scripts/doc-generation/xcode-rebuild-docc.sh

@@ -85,6 +85,10 @@ generateSymbolGraphs() {
     # Rename MapboxCoreMaps to MapboxMaps in the extension symbol graph so docc
     # correctly associates extensions with the renamed module.
     mv "$SWIFTEXTRACT_OUTPUT_DIR/MapboxMaps@MapboxCoreMaps.symbols.json" "$SWIFTEXTRACT_OUTPUT_DIR/MapboxMaps@MapboxMaps.symbols.json"
+
+    # Remove compiler-artifact symbols (e.g. char8_t leaked via -Swift.h bridging
+    # headers) from all symbol graphs so they don't appear in published docs.
+    "$MAPBOXMAPS_PATH/scripts/doc-generation/strip-compiler-artifacts.py" "$SYMBOL_GRAPH_DIR"
 }
 
 # Generate a dependency file to support incremental builds