# Copyright 2025 The Fuchsia Authors. All rights reserved.
# Use of this source code is governed by a BSD-style license that can be
# found in the LICENSE file.

"""Utilities related to managing Bazel runfiles manifests and directories."""

import typing as T
from pathlib import Path

# Starting with Bazel 8, the runfiles sub-directory that matches
# the current workspace is *always* named "_main", independent of
# the workspace name provided in WORKSPACE, or the module name
# provided in MODULE.bazel.
#
# On the other hand, the _repo_mapping file will contain a line
# like this one (where the first character is a comma):
#
# ,workspace_name,_main
#
# To indicate that files from the main workspace are mapped to
# that directory.
#
_BAZEL_MAIN_WORKSPACE_NAME = "_main"

RepoMappingTree: T.TypeAlias = dict[str, dict[str, str]]


class RepoMapping(object):
    """Models the content of a repository mapping file."""

    def __init__(self, tree: RepoMappingTree) -> None:
        self._tree = tree

    @staticmethod
    def CreateFrom(content: str) -> "RepoMapping":
        tree = RepoMapping.parse_repo_mapping(content)
        return RepoMapping(tree)

    def map_apparent_name(
        self, apparent_name: str, source_name: str = ""
    ) -> str:
        """Convert a repository/module apparent name to its path in the runfiles directory.

        Args:
            apparent_name: Apparent name (workspace or repository name without a @ prefix).
            source_name: Optional canonical repository name where the apparent_name appears,
               without a @@ prefix. Default value is the empty string, corresponding to the
               main workspace.
        Returns:
            A directory name under the root runfiles directory, or an empty string
            if this apparent name is unknown.
        """
        top_map = self._tree.get(source_name, {})
        return top_map.get(apparent_name, "")

    def map_input_path(self, path: str, source_name: str = "") -> str:
        """Convert an rlocation input path to the corresponding manifest source path.

        This must replace the first path segment, and apparent workspace or repository
        name, by a canonical one. For example, assuming Bazel 8.0 + BzlMod enabled:

        my_project/src/foo -> _main/src/foo
        my_repo/data/file  ->  +custom_repo_ext+some_repo/data/file

        Args:
            path: An input runfiles path, such as <apparent_name>/something/else
            source_name: Optional canonical name of the source repository or workspace,
                without a @@ or @ prefix, where this input path is used.
                Default is empty string, which corresponds to the main workspace.
        Returns:
            The actual location relative to the runfiles directory root, e.g.
            <canonical_name>/something/else for a repository artifact, or _main/something/else
            for a workspace one.
        """
        apparent_name, sep, remainder = path.partition("/")
        if sep != "/":
            # single-segment paths can be symlinks and must not be mapped.
            # This is true for the .runfiles/_repo_mapping for example.
            return path

        mapped_dir = self.map_apparent_name(apparent_name, source_name)
        if not mapped_dir:
            # This apparent name is not in the mapping file, return path as-is.
            return path

        return f"{mapped_dir}/{remainder}"

    @staticmethod
    def parse_repo_mapping(content: str) -> RepoMappingTree:
        result: RepoMappingTree = {}
        for line in content.splitlines():
            # Each line contains three comma-separated names:
            # <source_name>,<apparent_name>,<runfile_name>
            #
            # Where <source_name> is either a canonical repository name, without a @@ prefix,
            # or the empty string for the main workspace.
            #
            # Where <apparent_name> is an apparent module/repository name, without a @ prefix,
            # that appears inside of <source_name>
            #
            # Where <runfile_name> is where the corresponding files are located in the
            # runfiles directory. It is usually a canonical name, or the special value "_main"
            # for the workspace (starting with Bazel8), or the module/workspace name (before Bazel 8)
            #
            # See runfiles_utils_test.py for concrete examples.
            #
            items = line.split(",")
            if len(items) != 3:
                raise ValueError(f"Invalid line in repo_mapping file: [{line}]")

            source_name, apparent_name, canonical_name = items

            # Save the value into a nested map {source_name -> { apparent_name -> canonical_name} }
            # and check for duplicate definitions.
            top_map = result.setdefault(source_name, {})
            cur_canonical = top_map.setdefault(apparent_name, canonical_name)
            if cur_canonical is not canonical_name:
                raise ValueError(
                    f"Duplicate canonical values for @{apparent_name} used in '{source_name}': {canonical_name} vs {cur_canonical}"
                )

        return result


class RunfilesManifest(object):
    """A class grouping method to manage Bazel runfiles manifests."""

    def __init__(self, file_map: dict[str, str]) -> None:
        self._map = file_map

    @staticmethod
    def CreateFrom(content: str) -> "RunfilesManifest":
        """Create new instance from manifest file content."""
        file_map = RunfilesManifest.parse_manifest(content)
        return RunfilesManifest(file_map)

    @staticmethod
    def CreateFromDirectory(runfiles_dir: Path) -> "RunfilesManifest":
        """Create new instance from a given directory."""
        assert (
            runfiles_dir.exists()
        ), f"Runfiles directory does not exist: {runfiles_dir}"
        # If the directory contains a manifest, use it.
        probe_manifest = runfiles_dir / "MANIFEST"
        if probe_manifest.exists():
            return RunfilesManifest.CreateFrom(probe_manifest.read_text())

        # Otherwise simple walk the directory for files and symlinks.
        file_map: dict[str, str] = {}
        for root, dirnames, filenames in os.walk(runfiles_dir):
            for filename in filenames:
                path = Path(os.path.join(root, filename))
                source_path = os.path.relpath(path, runfiles_dir)
                if path.is_symlink():
                    target = path.readlink()
                    file_map[source_path] = target
                else:
                    # Empty files do not need a target path after the space separator.
                    # For non-empty files though, convert the source path to an
                    # absolute one.
                    if path.stat().st_size == 0:
                        file_map[source_path] = ""
                    else:
                        file_map[source_path] = path.resolve()

        return RunfilesManifest(file_map)

    def lookup(self, runfile_path: str) -> str:
        """Lookup a runfile's target location, or return an empty string on error.

        Args:
            runfile_path: A runfiles-root-relative source path.
               Note that this is *not* the path passed to an Rlocation()
               function at runtime, but can be the result of a previous
               RepoMapping.map_input_path() call.

        Returns:
            The target path recorded in the manifest. An empty string if not found.
        """
        return self._map.get(runfile_path, "")

    def find_source_path_for(self, target_path: str) -> T.Optional[str]:
        """Find the source path that matches a given target path in the manifest.

        This can be used to locate a real executable from a Bazel output_base layout.
        For example, with:

        bazel-bin/src/foo
        bazel-bin/src/foo.runfiles/
            main_/
                src/
                    foo -----> absolute path of bazel-bin/src/foo

        find_source_path("<absolute_bazel-bin>/src/foo") will return
        "main_/src/foo".
        """
        for source, target in self._map.items():
            if target == target_path:
                return source

        return None

    @staticmethod
    def unescape(path: str) -> str:
        """Unescape a path that appears in a runfile manifest."""
        # Reference code from:
        # https://github.com/bazelbuild/rules_cc/blob/main/cc/runfiles/runfiles.cc#L182
        result = ""
        prev_ch = "\0"
        ch = "\0"
        for ch in path:
            result += ch
            if prev_ch == "\\":
                if ch == "s":
                    # Replace \s with a space in result.
                    result = result[:-2] + " "
                elif ch == "n":
                    # Replace \n with a newline in result.
                    result = result[:-2] + "\n"
                elif ch == "b":
                    # Replace \\ with a single backslash
                    result = result[:-1]

            prev_ch = ch
        return result

    @staticmethod
    def escape(path: str) -> str:
        """Escape a path for the runfile manifest."""
        result = ""
        for ch in path:
            if ch == "\\":
                result += "\\b"
            elif ch == " ":
                result += "\\s"
            elif ch == "\n":
                result += "\\n"
            else:
                result += ch
        return result

    @staticmethod
    def path_needs_escaping(path: str) -> bool:
        """Return True if a path needs escaping."""
        return any(ch in " \n\\" for ch in path)

    @staticmethod
    def parse_manifest(content: str) -> dict[str, str]:
        """Parse the content of a manifest file.

        Args:
            content: The file's content as a string.
        Returns:
            A dictionary mapping runfiles relative source paths
            to their target location as recorded in the manifest.
        """
        result: dict[str, str] = {}
        for line in content.splitlines():
            if not line:
                # Stop parsing on empty line. This mimics the behavior
                # of the C runfiles library parser.
                break
            if line[0] == " ":
                # A line that begins with a space contains escaped paths
                # separated by a space, e.g.:
                # <SPACE> <ESCAPED_RUNFILE_PATH> <SPACE> <ESCAPED_FILE_PATH>
                escaped_source, sep, escaped_target = line[1:].partition(" ")
                if sep != " ":
                    raise ValueError(
                        f"No space separator in manifest line: [{line}]"
                    )
                source = RunfilesManifest.unescape(escaped_source)
                target = RunfilesManifest.unescape(escaped_target)
            else:
                # Otherwise, the line contains two paths separated by spaces.
                # Note that it is possible for the target path to be empty, but the
                # space separator will always be present.
                source, sep, target = line.partition(" ")
                if sep != " ":
                    raise ValueError(
                        f"No space separator in manifest line: [{line}]"
                    )

            result[source] = target
        return result

    def remove_legacy_external_runfiles(self, workspace_name: str) -> None:
        """Remove legacy <project_name>/external/<repo_name>/..." entries.

        Starting with Bazel 8.0, --legacy_external_runfiles is off and these entries
        are no longer created, but before that it was enabled by default. These were
        already omitted when running `bazel test` since Bazel 7.1, but still kept for
        `bazel build` for legacy reasons.

        Args:
            workspace_name: Name of the workspace directory name at the root of the
                runfiles directory / collection. When BzlMod is enabled, this
                must always be `_main`. Otherwise this should match the name
                given in the workspace() directive of the project's WORKSPACE file,
                or "__main__" if none is provided.
        """
        external_prefix = f"{workspace_name}/external/"
        paths_to_remove = [
            p for p in self._map.keys() if p.startswith(external_prefix)
        ]
        for p in paths_to_remove:
            self._map.pop(p, None)

    def as_dict(self) -> dict[str, str]:
        """Return the content of this manifest as a {source_path -> target_path} dictionary."""
        return self._map.copy()

    def generate_content(self) -> str:
        """Generate a manifest file content from the current instance."""
        result = ""
        for source, target in sorted(self._map.items()):
            if self.path_needs_escaping(source) or self.path_needs_escaping(
                target
            ):
                result += f" {self.escape(source)} {self.escape(target)}\n"
            else:
                result += f"{source} {target}\n"
        return result