Add bazel rules for handling directories

.gitignore

@@ -1 +1,2 @@
 /bazel-*
+MODULE.bazel.lock

MODULE.bazel

@@ -18,6 +18,7 @@ bazel_dep(name = "platforms", version = "0.0.4")
 bazel_dep(name = "stardoc", version = "0.5.6", dev_dependency = True, repo_name = "io_bazel_stardoc")
 bazel_dep(name = "rules_pkg", version = "0.9.1", dev_dependency = True)
 bazel_dep(name = "rules_cc", version = "0.0.2", dev_dependency = True)
+bazel_dep(name = "rules_testing", version = "0.6.0", dev_dependency = True)
 
 # Needed for bazelci and for building distribution tarballs.
 # If using an unreleased version of bazel_skylib via git_override, apply

rules/directories/BUILD

@@ -0,0 +1 @@
+licenses(["notice"])

rules/directories/directory.bzl

@@ -0,0 +1,106 @@
+# Copyright 2024 The Bazel Authors. All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#    http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Skylib module containing rules to create metadata about directories."""
+
+load(":providers.bzl", "DirectoryInfo")
+
+visibility("public")
+
+def _directory_impl(ctx):
+    if ctx.label.workspace_root:
+        pkg_path = ctx.label.workspace_root + "/" + ctx.label.package
+    else:
+        pkg_path = ctx.label.package
+    source_dir = pkg_path.rstrip("/")
+    source_prefix = source_dir + "/"
+
+    # Declare a generated file so that we can get the path to generated files.
+    f = ctx.actions.declare_file(ctx.label.name)
+    ctx.actions.write(f, "")
+    generated_dir = f.path.rsplit("/", 1)[0]
+    generated_prefix = generated_dir + "/"
+
+    root_metadata = struct(
+        directories = {},
+        files = [],
+        source_path = source_dir,
+        generated_path = generated_dir,
+        human_readable = "@@%s//%s" % (ctx.label.repo_name, ctx.label.package),
+    )
+
+    # Topologically order directories so we can use them for DFS.
+    topo = [root_metadata]
+    for src in ctx.files.srcs:
+        prefix = source_prefix if src.is_source else generated_prefix
+        if not src.path.startswith(prefix):
+            fail("{path} is not contained within {prefix}".format(
+                path = src.path,
+                prefix = root_metadata.human_readable,
+            ))
+        relative = src.path[len(prefix):].split("/")
+        current_path = root_metadata
+        for dirname in relative[:-1]:
+            if dirname not in current_path.directories:
+                dir_metadata = struct(
+                    directories = {},
+                    files = [],
+                    source_path = "%s/%s" % (current_path.source_path, dirname),
+                    generated_path = "%s/%s" % (current_path.generated_path, dirname),
+                    human_readable = "%s/%s" % (current_path.human_readable, dirname),
+                )
+                current_path.directories[dirname] = dir_metadata
+                topo.append(dir_metadata)
+
+            current_path = current_path.directories[dirname]
+        current_path.files.append(src)
+
+    # The output DirectoryInfos. Key them by something arbitrary but unique.
+    # In this case, we choose source_path.
+    out = {}
+    for dir_metadata in reversed(topo):
+        child_dirs = {
+            dirname: out[subdir_metadata.source_path]
+            for dirname, subdir_metadata in dir_metadata.directories.items()
+        }
+        files = sorted(dir_metadata.files, key = lambda file: file.basename)
+        direct_files = depset(files)
+        transitive_files = depset(transitive = [direct_files] + [
+            d.transitive_files
+            for d in child_dirs.values()
+        ], order = "preorder")
+        out[dir_metadata.source_path] = DirectoryInfo(
+            directories = child_dirs,
+            files = {f.basename: f for f in files},
+            direct_files = direct_files,
+            transitive_files = transitive_files,
+            source_path = dir_metadata.source_path,
+            generated_path = dir_metadata.generated_path,
+            human_readable = dir_metadata.human_readable,
+        )
+
+    root_directory = out[root_metadata.source_path]
+
+    return [
+        root_directory,
+        DefaultInfo(files = root_directory.transitive_files),
+    ]
+
+directory = rule(
+    implementation = _directory_impl,
+    attrs = {
+        "srcs": attr.label_list(allow_files = True),
+    },
+    provides = [DirectoryInfo],
+)

rules/directories/providers.bzl

@@ -0,0 +1,33 @@
+# Copyright 2024 The Bazel Authors. All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#    http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Skylib module containing providers for directories."""
+
+visibility("public")
+
+DirectoryInfo = provider(
+    doc = "Information about a directory",
+    # @unsorted-dict-items
+    fields = {
+        "directories": "(Dict[str, DirectoryInfo]) The subdirectories contained directly within",
+        "files": "(Dict[str, File]) The files contained directly within the directory, keyed by their path relative to this directory.",
+        "direct_files": "(Depset[File])",
+        # A transitive_directories would be useful here, but is blocked on
+        # https://github.com/bazelbuild/starlark/issues/272
+        "transitive_files": "(Depset[File])",
+        "source_path": "(string) Path to all source files contained within this directory",
+        "generated_path": "(string) Path to all generated files contained within this directory",
+        "human_readable": "(string) A human readable identifier for a directory. Useful for providing error messages to a user.",
+    },
+)

rules/directories/subdirectory.bzl

@@ -0,0 +1,36 @@
+# Copyright 2024 The Bazel Authors. All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#    http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Skylib module containing rules to create metadata about subdirectories."""
+
+load(":providers.bzl", "DirectoryInfo")
+load(":utils.bzl", "get_subdirectory")
+
+visibility("public")
+
+def _subdirectory_impl(ctx):
+    dir = get_subdirectory(ctx.attr.parent[DirectoryInfo], ctx.attr.path)
+    return [
+        dir,
+        DefaultInfo(files = dir.transitive_files),
+    ]
+
+subdirectory = rule(
+    implementation = _subdirectory_impl,
+    attrs = {
+        "parent": attr.label(providers = [DirectoryInfo], mandatory = True),
+        "path": attr.string(mandatory = True),
+    },
+    provides = [DirectoryInfo],
+)

rules/directories/utils.bzl

@@ -0,0 +1,55 @@
+# Copyright 2024 The Bazel Authors. All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#    http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Skylib module containing utility functions related to directories."""
+
+visibility("public")
+
+_DIR_NOT_FOUND = """{directory} does not contain a directory named {dirname}.
+Instead, it contains the directories {children}."""
+
+def _check_path_relative(path):
+    if path.startswith("/"):
+        fail("Path must be relative. Got {path}".format(path = path))
+
+def get_direct_subdirectory(directory, dirname):
+    """Gets the direct subdirectory of a directory.
+
+    Args:
+        directory: (DirectoryInfo) The directory to look within.
+        dirname: (string) The name of the directory to look for.
+    Returns:
+        (DirectoryInfo) The directory contained within."""
+    if dirname not in directory.directories:
+        fail(_DIR_NOT_FOUND.format(
+            directory = directory.human_readable,
+            dirname = repr(dirname),
+            children = repr(sorted(directory.directories)),
+        ))
+    return directory.directories[dirname]
+
+def get_subdirectory(directory, path):
+    """Gets a subdirectory contained within a tree of another directory.
+
+    Args:
+        directory: (DirectoryInfo) The directory to look within.
+        path: (string) The path of the directory to look for within it.
+    Returns:
+        (DirectoryInfo) The directory contained within.
+    """
+    _check_path_relative(path)
+
+    for dirname in path.split("/"):
+        directory = get_direct_subdirectory(directory, dirname)
+    return directory

tests/directories/BUILD

@@ -0,0 +1,50 @@
+load("@rules_testing//lib:analysis_test.bzl", "analysis_test")
+load(
+    ":directory_test.bzl",
+    "directory_test",
+    "nonexistent_subdirectory_test",
+    "outside_testdata_test",
+    "subdirectory_test",
+)
+
+analysis_test(
+    name = "directory_test",
+    impl = directory_test,
+    targets = {
+        "root": "//tests/directories/testdata:root",
+        "f1": "//tests/directories/testdata:f1_filegroup",
+        "f2": "//tests/directories/testdata:f2_filegroup",
+        "f3": "//tests/directories/testdata:f3",
+    },
+)
+
+filegroup(
+    name = "outside_testdata",
+    srcs = ["BUILD"],
+    visibility = ["//tests/directories/testdata:__pkg__"],
+)
+
+analysis_test(
+    name = "outside_testdata_test",
+    expect_failure = True,
+    impl = outside_testdata_test,
+    target = "//tests/directories/testdata:outside_testdata",
+)
+
+analysis_test(
+    name = "subdirectory_test",
+    impl = subdirectory_test,
+    targets = {
+        "root": "//tests/directories/testdata:root",
+        "dir": "//tests/directories/testdata:dir",
+        "subdir": "//tests/directories/testdata:subdir",
+        "f2": "//tests/directories/testdata:f2_filegroup",
+    },
+)
+
+analysis_test(
+    name = "nonexistent_subdirectory_test",
+    expect_failure = True,
+    impl = nonexistent_subdirectory_test,
+    target = "//tests/directories/testdata:nonexistent_subdirectory",
+)