blob: cec6b0938bf4733119849084d05c3e19a9511651 [file]
# Copyright 2026 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.
"""Common SHAC execution helpers for fx lint and fx format-code."""
import json
import os
import pathlib
import platform
import shutil
import subprocess
import sys
from collections.abc import Collection, Mapping, Sequence
import scm
_STATIC_CHECKS_TARGET = "//bundles/buildbot/static_checks"
# Tool names in tool_paths.json corresponding to the dependencies of
# //bundles/buildbot/static_checks/BUILD.gn invoked via compiled_tool_path() in
# //scripts/shac/common.star.
_STATIC_CHECK_TOOLS = frozenset(
(
"bazel2gn",
"check-licenses",
"clippy-reporter",
"cmc",
"doc-checker",
"fidl-format",
"fidl-lint",
"formatjson5",
"gidl-format",
"mdlint",
"readme_fuchsia",
"rfcmeta",
)
)
def _resolve_shac_binary() -> pathlib.Path:
"""Locates the prebuilt shac binary from PREBUILT_SHAC or PATH.
Returns:
Path to the shac executable.
Raises:
FileNotFoundError: If PREBUILT_SHAC points to a non-existent file or
shac cannot be found on PATH.
"""
if prebuilt_shac := os.environ.get("PREBUILT_SHAC"):
candidate = pathlib.Path(prebuilt_shac)
if candidate.is_file():
return candidate
raise FileNotFoundError(
f"shac binary not found at PREBUILT_SHAC={prebuilt_shac}"
)
if (which_shac := shutil.which("shac")) is not None:
return pathlib.Path(which_shac)
raise FileNotFoundError("shac binary not found.")
def _validate_explicit_files(
explicit_files: Collection[str],
fuchsia_dir: pathlib.Path,
cwd: pathlib.Path,
) -> Sequence[str]:
"""Validates explicit file paths and prints an error for missing files."""
valid_files = []
for raw_path in explicit_files:
stripped_path = raw_path.strip()
if not stripped_path:
continue
absolute_path = scm.canonicalize_path(stripped_path, cwd, fuchsia_dir)
if not absolute_path.is_file():
print(f"ERROR: no such file: {absolute_path}", file=sys.stderr)
continue
valid_files.append(stripped_path)
return tuple(valid_files)
def split_comma_separated(
entries: Collection[str],
) -> Sequence[str]:
"""Splits repeatable comma-separated CLI flag entries into stripped items.
Args:
entries: Collection of raw CLI flag values (each possibly
comma-separated).
Returns:
A sequence of non-empty stripped strings in order of appearance.
"""
return tuple(
stripped
for entry in entries
for item in entry.split(",")
if (stripped := item.strip())
)
def resolve_workspace_paths(
default_fuchsia_dir: pathlib.Path,
) -> tuple[pathlib.Path, pathlib.Path, pathlib.Path]:
"""Resolves FUCHSIA_DIR, FUCHSIA_BUILD_DIR, and current working directory.
Args:
default_fuchsia_dir: Fallback Fuchsia root directory when FUCHSIA_DIR
is not set in the environment.
Returns:
A tuple of (fuchsia_dir, build_dir, cwd) as resolved absolute paths.
"""
if (fuchsia_dir_env := os.environ.get("FUCHSIA_DIR")) is not None:
fuchsia_dir = pathlib.Path(fuchsia_dir_env).resolve()
else:
fuchsia_dir = default_fuchsia_dir.resolve()
if (
fuchsia_build_dir_env := os.environ.get("FUCHSIA_BUILD_DIR")
) is not None:
build_dir = pathlib.Path(fuchsia_build_dir_env).resolve()
else:
build_dir = fuchsia_dir / "out" / "default"
cwd = pathlib.Path.cwd().resolve()
return (fuchsia_dir, build_dir, cwd)
def _build_shac_command(
shac_binary: pathlib.Path,
subcommand: str,
group: scm.RepoGroup,
fuchsia_dir: pathlib.Path,
build_dir: pathlib.Path,
*,
all_files: bool,
only_checks: Collection[str],
skip_checks: Collection[str],
extra_args: Collection[str],
verbose: bool,
) -> Sequence[str]:
"""Builds the shac command-line invocation for a single repository group."""
relative_fuchsia_dir = os.path.relpath(fuchsia_dir, group.repo_root)
relative_build_dir = os.path.relpath(build_dir, fuchsia_dir)
command = [
str(shac_binary),
subcommand,
"-C",
str(group.repo_root),
f"--var=fuchsia_dir={relative_fuchsia_dir}",
f"--var=fuchsia_build_dir={relative_build_dir}",
]
if all_files:
command.append("--all")
if verbose:
command.append("--verbose")
else:
command.append("--quiet")
if only_checks:
command.append(f"--only={','.join(only_checks)}")
if skip_checks:
command.append(f"--skip={','.join(skip_checks)}")
if extra_args:
command.extend(extra_args)
if group.files:
command.extend(group.files)
return tuple(command)
def _host_platform_and_cpu() -> tuple[str, str]:
"""Returns the current host (os, cpu) matching tool_paths.json."""
host_os = "mac" if sys.platform == "darwin" else sys.platform
machine = platform.machine()
if machine == "x86_64":
host_cpu = "x64"
elif machine in ("aarch64", "arm64"):
host_cpu = "arm64"
else:
host_cpu = machine
return (host_os, host_cpu)
def _are_static_check_tools_built(build_dir: pathlib.Path) -> bool:
"""Returns True if tool_paths.json and all static_checks binaries exist."""
tool_paths_file = build_dir / "tool_paths.json"
if not tool_paths_file.is_file():
return False
try:
entries = json.loads(tool_paths_file.read_text())
except (OSError, json.JSONDecodeError):
return False
if not isinstance(entries, list):
return False
host_os, host_cpu = _host_platform_and_cpu()
tool_paths = {
entry["name"]: entry["path"]
for entry in entries
if isinstance(entry, dict)
and entry.get("os") == host_os
and entry.get("cpu") == host_cpu
and isinstance(entry.get("name"), str)
and isinstance(entry.get("path"), str)
}
for tool_name in _STATIC_CHECK_TOOLS:
if (relative_path := tool_paths.get(tool_name)) is None:
return False
tool_binary = build_dir / relative_path
if not tool_binary.is_file() or not os.access(tool_binary, os.X_OK):
return False
return True
# SHAC executes checks inside a read-only sandbox and cannot invoke `fx build`
# on demand when resolving compiled host tools via `compiled_tool_path()` in
# //scripts/shac/common.star. In clean checkouts or `fx worktree` environments
# where a full build has not been run, missing host binaries in
# $FUCHSIA_BUILD_DIR would otherwise cause SHAC to fail.
#
# When tool_paths.json or any binary in //bundles/buildbot/static_checks is
# missing on disk, building the static_checks umbrella group as a pre-flight
# step ensures all required host tools are compiled while skipping the `fx build`
# overhead and avoiding clobbering last_ninja_build_targets.txt when already
# present.
def _ensure_static_check_tools_built(
fuchsia_dir: pathlib.Path,
build_dir: pathlib.Path,
env: Mapping[str, str],
*,
verbose: bool,
dry_run: bool,
) -> None:
"""Builds the static_checks host tool bundle if any binary is missing."""
if _are_static_check_tools_built(build_dir):
return
command = (
str(fuchsia_dir / "scripts" / "fx"),
"build",
"--host",
_STATIC_CHECKS_TARGET,
)
if verbose:
print(f"Running: {' '.join(command)}")
if dry_run:
print(f"[dry-run] Would execute: {' '.join(command)}")
return
subprocess.run(command, cwd=fuchsia_dir, env=env, check=True)
def run_shac(
subcommand: str,
fuchsia_dir: pathlib.Path,
build_dir: pathlib.Path,
cwd: pathlib.Path,
*,
all_files: bool = False,
only_checks: Collection[str] = (),
skip_checks: Collection[str] = (),
explicit_files: Collection[str] | None = None,
extra_args: Collection[str] = (),
verbose: bool = False,
dry_run: bool = False,
) -> None:
"""Runs a shac subcommand ('check', 'fix', or 'fmt') across repository groups.
Args:
subcommand: The SHAC subcommand to execute ('check', 'fix', or 'fmt').
fuchsia_dir: Absolute path to the Fuchsia checkout root.
build_dir: Path to the active Fuchsia build directory.
cwd: Current working directory for resolving relative paths.
all_files: If True, passes '--all' to SHAC to check all tracked files.
only_checks: Collection of check names to pass via '--only'.
skip_checks: Collection of check names to pass via '--skip'.
explicit_files: Optional collection of explicit file paths to check, or
None to run across all active repositories without file filtering.
If an empty collection (or if all specified files are missing),
returns without invoking SHAC.
extra_args: Collection of extra CLI arguments forwarded to SHAC.
verbose: If True, passes '--verbose' to SHAC and logs command lines;
otherwise passes '--quiet' to SHAC.
dry_run: If True, prints the SHAC command lines without executing them.
Raises:
subprocess.CalledProcessError: If `fx build`, `shac`, or `git` exits
with a non-zero status code.
FileNotFoundError: If the `shac` binary cannot be found or if a target
path requires invoking `git` and the `git` executable cannot be
found.
"""
valid_files = None
if explicit_files is not None:
valid_files = _validate_explicit_files(explicit_files, fuchsia_dir, cwd)
if not valid_files:
return
shac_binary = _resolve_shac_binary()
shac_env = os.environ | {
"FUCHSIA_DIR": str(fuchsia_dir),
"FUCHSIA_BUILD_DIR": str(build_dir),
}
repo_groups = scm.get_repo_groups(
fuchsia_dir,
cwd,
explicit_files=valid_files,
)
shac_groups = tuple(group for group in repo_groups if group.has_shac)
if not shac_groups:
return
_ensure_static_check_tools_built(
fuchsia_dir,
build_dir,
shac_env,
verbose=verbose,
dry_run=dry_run,
)
for group in shac_groups:
command = _build_shac_command(
shac_binary,
subcommand,
group,
fuchsia_dir,
build_dir,
all_files=all_files,
only_checks=only_checks,
skip_checks=skip_checks,
extra_args=extra_args,
verbose=verbose,
)
if verbose:
print(f"Running: {' '.join(command)}")
if dry_run:
print(f"[dry-run] Would execute: {' '.join(command)}")
continue
subprocess.run(command, cwd=group.repo_root, env=shac_env, check=True)