refactor(cpp/libclang): extract reusable parser action

Author: melodyoncode

cpp/libclang/BUILD

@@ -32,9 +32,6 @@ rust_binary(
     data = [
         "@llvm_toolchain_llvm//:libclang",
     ],
-    env = {
-        "LIBCLANG_PATH": "$(rootpath @llvm_toolchain_llvm//:libclang)",
-    },
     visibility = ["//visibility:public"],
     deps = [
         "//cpp/libclang/src/utils",

cpp/libclang/README.md

@@ -26,7 +26,6 @@ cpp_parser(
   extra_args = [
   ],
   target = "//cpp/libclang/integration_test/cases/include_3rdparty",
-  tool = ":clang_rs_parser",
 )
 ```
 
@@ -38,9 +37,9 @@ Where:
 Expected result:
 
 - Bazel creates parser output artifact:
-  - `bazel-bin/cpp/libclang/cpp_parser_include_3rdparty_result.fbs.bin`
+  - `bazel-bin/cpp/libclang/cpp_parser_include_3rdparty_class_diagram.fbs.bin`
 - When `emit_debug_json = True`, the parser also writes:
-  - `bazel-bin/cpp/libclang/cpp_parser_include_3rdparty_result/debug.json`
+  - `bazel-bin/cpp/libclang/cpp_parser_include_3rdparty_debug.json`
 
 ## Configure debug logging
 
@@ -55,6 +54,6 @@ Accepted values are: `error`, `warn`, `info`, `debug`, `trace`.
 ## Quick check (optional)
 
 ```bash
-ls -l bazel-bin/cpp/libclang/cpp_parser_include_3rdparty_result.fbs.bin
-ls -l bazel-bin/cpp/libclang/cpp_parser_include_3rdparty_result/debug.json
+ls -l bazel-bin/cpp/libclang/integration_test/cases/include_3rdparty/parser_class_diagram.fbs.bin
+ls -l bazel-bin/cpp/libclang/integration_test/cases/include_3rdparty/parser_debug.json
 ```

cpp/libclang/cpp_parser.bzl

@@ -13,6 +13,9 @@
 load("@bazel_skylib//rules:common_settings.bzl", "BuildSettingInfo")
 load("@rules_cc//cc:find_cc_toolchain.bzl", "find_cc_toolchain", "use_cc_toolchain")
 load("@rules_cc//cc/common:cc_common.bzl", "cc_common")
+load("@rules_cc//cc/common:cc_info.bzl", "CcInfo")
+
+# Providers and aspects used to adapt C/C++ targets for the parser action.
 
 def _extract_files_from_attr(attr, attr_name):
     files = []
@@ -21,7 +24,13 @@ def _extract_files_from_attr(attr, attr_name):
             files.extend(src.files.to_list())
     return files
 
-SourceFilesInfo = provider(fields = ["files", "inputs"])
+SourceFilesInfo = provider(
+    doc = "Source files and transitive inputs collected for parser actions.",
+    fields = {
+        "files": "depset of source files to parse for this target.",
+        "inputs": "depset of source and header inputs needed by the parser action.",
+    },
+)
 
 def _cc_sources_aspect_impl(target, ctx):
     direct_srcs = _extract_files_from_attr(ctx.rule.attr, "srcs")
@@ -64,7 +73,15 @@ CompilationFlagsInfo = provider(
     },
 )
 
-def _collect_from_cc_info(target):
+CppParserInfo = provider(
+    doc = "Outputs generated by the C/C++ parser.",
+    fields = {
+        "class_fbs": "Class diagram FlatBuffer output file.",
+        "debug_json": "Debug JSON sidecar output file. (Optional)",
+    },
+)
+
+def _collect_from_cc_info(target, ctx):
     flags = []
 
     if CcInfo in target:
@@ -90,7 +107,7 @@ def _compilation_flags_aspect_impl(target, ctx):
         if CompilationFlagsInfo in dep:
             transitive.append(dep[CompilationFlagsInfo].flags)
 
-    direct_flags = _collect_from_cc_info(target)
+    direct_flags = _collect_from_cc_info(target, ctx)
 
     return [
         CompilationFlagsInfo(
@@ -103,6 +120,53 @@ compilation_flags_aspect = aspect(
     attr_aspects = ["deps"],
 )
 
+# Public integration helpers for rules that want to reuse the parser action.
+
+def cpp_parser_target_aspects():
+    """Return aspects required on attrs whose targets will be parsed."""
+
+    return [cc_sources_aspect, compilation_flags_aspect]
+
+def has_cpp_parser_inputs(target):
+    """Check whether a target has the providers needed by run_cpp_parser_action."""
+
+    return (CcInfo in target and
+            SourceFilesInfo in target and
+            CompilationFlagsInfo in target and
+            bool(target[SourceFilesInfo].files.to_list()))
+
+def cpp_parser_action_internal_attrs():
+    """Return private attrs required by run_cpp_parser_action callers."""
+
+    return {
+        "_tool": attr.label(
+            default = Label("//cpp/libclang:clang_rs_parser"),
+            executable = True,
+            cfg = "exec",
+            doc = "Internal libclang-based parser backend.",
+        ),
+        "_libclang": attr.label(
+            allow_single_file = True,
+            default = "@llvm_toolchain_llvm//:lib/libclang.so",
+        ),
+        "_llvm_cxx_builtin_include": attr.label(
+            default = "@llvm_toolchain_llvm//:cxx_builtin_include",
+            doc = "LLVM toolchain filegroup containing the libc++ header directory (include/c++) " +
+                  "and the clang resource include directory (lib/clang/<version>/include).",
+        ),
+        "_llvm_extra_config_site": attr.label(
+            default = "@llvm_toolchain_llvm//:extra_config_site",
+            doc = "LLVM toolchain filegroup containing the arch-specific __config_site file " +
+                  "(include/<triple>/c++/v1/__config_site) used to locate the ABI include path.",
+        ),
+        "_log_level": attr.label(
+            default = Label("//cpp/libclang:log_level"),
+            doc = "Build setting that controls clang_rs_parser log level.",
+        ),
+    }
+
+# Parser action implementation.
+
 def _detect_standard_from_flags(ctx):
     """
     Fall back: compile the action's compile flags and look for -std=.
@@ -190,58 +254,87 @@ def _collect_required_llvm_include_args(cxx_builtin_include_files, extra_config_
 
     return result
 
-def _cpp_parser_impl(ctx):
-    output_dir = ctx.actions.declare_directory(
-        ctx.label.name + "_result",
+def run_cpp_parser_action(
+        ctx,
+        *,
+        target,
+        output_prefix,
+        tool,
+        libclang,
+        llvm_cxx_builtin_include,
+        llvm_extra_config_site,
+        log_level,
+        extra_args = [],
+        emit_debug_json = False):
+    """Register the libclang parser action and return its declared outputs.
+
+    The target must be analyzed with cpp_parser_target_aspects() before this
+    helper is called. Use has_cpp_parser_inputs() when the caller accepts mixed
+    implementation target types.
+    """
+
+    class_fbs_output = ctx.actions.declare_file(
+        "{}_{}".format(output_prefix, "class_diagram.fbs.bin"),
     )
-    libclang = ctx.file._libclang
 
-    args = []
+    debug_json_output = None
+    if emit_debug_json:
+        debug_json_output = ctx.actions.declare_file(
+            "{}_{}".format(output_prefix, "debug.json"),
+        )
+
+    tool_files_to_run = tool[DefaultInfo].files_to_run
 
+    args = []
     args += [
-        "--output-dir",
-        output_dir.path,
+        "--class-fbs-output",
+        class_fbs_output.path,
     ]
 
-    if ctx.attr.emit_debug_json:
-        args.append("--json")
+    if debug_json_output:
+        args += [
+            "--debug-json-output",
+            debug_json_output.path,
+        ]
 
-    target_compilation_flags_list = ctx.attr.target[CompilationFlagsInfo].flags.to_list()
+    target_compilation_flags_list = target[CompilationFlagsInfo].flags.to_list()
 
-    cxx_builtin_include_files = ctx.attr._llvm_cxx_builtin_include.files.to_list()
-    extra_config_site_files = ctx.attr._llvm_extra_config_site.files.to_list()
+    cxx_builtin_include_files = llvm_cxx_builtin_include.files.to_list()
+    extra_config_site_files = llvm_extra_config_site.files.to_list()
     llvm_include_args = _collect_required_llvm_include_args(cxx_builtin_include_files, extra_config_site_files)
 
-    extra_args = [
+    parser_extra_args = [
         _detect_standard_from_flags(ctx),
         "-nostdinc++",
     ]
-    extra_args += llvm_include_args
-    extra_args += target_compilation_flags_list + ctx.attr.extra_args
-    for ea in extra_args:
+    parser_extra_args += llvm_include_args
+    parser_extra_args += target_compilation_flags_list + extra_args
+    for ea in parser_extra_args:
         args += ["--extra-arg", ea]
 
-    target_source_files_info = ctx.attr.target[SourceFilesInfo]
+    target_source_files_info = target[SourceFilesInfo]
     target_source_files_list = target_source_files_info.files.to_list()
     target_source_inputs_list = target_source_files_info.inputs.to_list()
 
-    # extend args with input sources
-    if SourceFilesInfo in ctx.attr.target:
-        args += [file.path for file in target_source_files_list]
+    args += ["--input"] + [file.path for file in target_source_files_list]
 
     inputs = [
         libclang,
     ] + target_source_inputs_list + cxx_builtin_include_files + extra_config_site_files
 
+    outputs = [class_fbs_output]
+    if debug_json_output:
+        outputs.append(debug_json_output)
+
     ctx.actions.run(
         inputs = inputs,
-        outputs = [output_dir],
-        executable = ctx.executable.tool,
-        tools = [ctx.attr.tool[DefaultInfo].files_to_run],
+        outputs = outputs,
+        executable = tool_files_to_run.executable,
+        tools = [tool_files_to_run],
         arguments = args,
         env = {
             "LIBCLANG_PATH": libclang.dirname,
-            "LIBCLANG_LOG": ctx.attr._log_level[BuildSettingInfo].value,
+            "LIBCLANG_LOG": log_level,
         },
         mnemonic = "CppAnalyze",
         # this is required to parse some system headers
@@ -251,49 +344,62 @@ def _cpp_parser_impl(ctx):
         progress_message = "Running C++ AST analysis: %s" % ctx.label,
     )
 
-    return DefaultInfo(
-        files = depset([output_dir]),
-        runfiles = ctx.runfiles(files = [output_dir]),
+    return struct(
+        class_fbs = class_fbs_output,
+        debug_json = debug_json_output,
     )
 
-cpp_parser = rule(
-    implementation = _cpp_parser_impl,
-    attrs = {
-        "target": attr.label(
-            aspects = [cc_sources_aspect, compilation_flags_aspect],
-            mandatory = True,
-        ),
-        "tool": attr.label(
-            executable = True,
-            cfg = "exec",
-            mandatory = True,
-        ),
-        "extra_args": attr.string_list(
-            default = [],
-        ),
-        "emit_debug_json": attr.bool(
-            default = False,
-            doc = "Emit debug.json alongside the FlatBuffer output. Intended for tests/debugging.",
-        ),
-        "_libclang": attr.label(
-            allow_single_file = True,
-            default = "@llvm_toolchain_llvm//:lib/libclang.so",
-        ),
-        "_llvm_cxx_builtin_include": attr.label(
-            default = "@llvm_toolchain_llvm//:cxx_builtin_include",
-            doc = "LLVM toolchain filegroup containing the libc++ header directory (include/c++) " +
-                  "and the clang resource include directory (lib/clang/<version>/include).",
-        ),
-        "_llvm_extra_config_site": attr.label(
-            default = "@llvm_toolchain_llvm//:extra_config_site",
-            doc = "LLVM toolchain filegroup containing the arch-specific __config_site file " +
-                  "(include/<triple>/c++/v1/__config_site) used to locate the ABI include path.",
+# cpp_parser rule
+
+def _cpp_parser_impl(ctx):
+    outputs = run_cpp_parser_action(
+        ctx,
+        target = ctx.attr.target,
+        output_prefix = ctx.label.name,
+        tool = ctx.attr._tool,
+        libclang = ctx.file._libclang,
+        llvm_cxx_builtin_include = ctx.attr._llvm_cxx_builtin_include,
+        llvm_extra_config_site = ctx.attr._llvm_extra_config_site,
+        log_level = ctx.attr._log_level[BuildSettingInfo].value,
+        extra_args = ctx.attr.extra_args,
+        emit_debug_json = ctx.attr.emit_debug_json,
+    )
+
+    runfiles_files = [outputs.class_fbs]
+    if outputs.debug_json:
+        runfiles_files.append(outputs.debug_json)
+
+    return [
+        DefaultInfo(
+            files = depset([outputs.class_fbs]),
+            runfiles = ctx.runfiles(files = runfiles_files),
         ),
-        "_log_level": attr.label(
-            default = Label("//cpp/libclang:log_level"),
-            doc = "Build setting that controls clang_rs_parser log level.",
+        CppParserInfo(
+            class_fbs = outputs.class_fbs,
+            debug_json = outputs.debug_json,
         ),
-    },
+    ]
+
+_cpp_parser_attrs = {
+    "target": attr.label(
+        aspects = cpp_parser_target_aspects(),
+        mandatory = True,
+    ),
+    "extra_args": attr.string_list(
+        default = [],
+    ),
+    "emit_debug_json": attr.bool(
+        default = False,
+        doc = "Emit debug.json alongside the FlatBuffer output. Intended for tests/debugging.",
+    ),
+}
+
+_cpp_parser_attrs.update(cpp_parser_action_internal_attrs())
+
+# BUILD-facing parser rule: wraps run_cpp_parser_action and exposes CppParserInfo.
+cpp_parser = rule(
+    implementation = _cpp_parser_impl,
+    attrs = _cpp_parser_attrs,
     toolchains = use_cc_toolchain(),
     fragments = ["cpp"],
 )