javascript/private/jsdoc.bzl

"""Rule for running jsdoc using Bazel-managed Node.js.

This rule creates a wrapper script that:
1. Runs jsdoc from the bazel-managed npm package
2. Outputs to the workspace build directory
3. Ignores jsdoc exit code (it exits 1 on type warnings) but verifies output was generated
"""

def _jsdoc_impl(ctx):
    jsdoc_bin = ctx.attr.jsdoc_binary[DefaultInfo].files_to_run.executable
    is_windows = ctx.target_platform_has_constraint(ctx.attr._windows_constraint[platform_common.ConstraintValueInfo])

    if is_windows:
        script = ctx.actions.declare_file(ctx.label.name + ".bat")
        ctx.actions.write(script, _WINDOWS_TEMPLATE.format(
            config = ctx.file.config.basename,
            jsdoc_bin = jsdoc_bin.short_path.replace("/", "\\\\"),
        ), is_executable = True)
    else:
        script = ctx.actions.declare_file(ctx.label.name + ".sh")
        ctx.actions.write(script, _UNIX_TEMPLATE.format(
            config = ctx.file.config.basename,
            jsdoc_bin = jsdoc_bin.short_path,
        ), is_executable = True)

    runfiles = ctx.runfiles(files = ctx.files.data + [ctx.file.config])
    runfiles = runfiles.merge(ctx.attr.jsdoc_binary[DefaultInfo].default_runfiles)
    return [DefaultInfo(executable = script, runfiles = runfiles)]

_UNIX_TEMPLATE = """#!/usr/bin/env bash
set -euo pipefail
cd "$BUILD_WORKSPACE_DIRECTORY/javascript/selenium-webdriver"
DEST="$BUILD_WORKSPACE_DIRECTORY/build/docs/api/javascript"
TEMPLATE="$0.runfiles/_main/javascript/selenium-webdriver/node_modules/clean-jsdoc-theme"

# Set BAZEL_BINDIR to suppress rules_js error for non-build actions
export BAZEL_BINDIR="."

# Clean destination to prevent stale files
rm -rf "$DEST"
mkdir -p "$DEST"

# Run jsdoc - ignore exit code since it fails on type warnings
"$0.runfiles/_main/{jsdoc_bin}" --configure {config} --destination "$DEST" --template "$TEMPLATE" "$@" || true

# Verify docs were generated
if [[ -f "$DEST/index.html" ]]; then
    echo "Documentation generated successfully at $DEST"
else
    echo "ERROR: Documentation was not generated"
    exit 1
fi
"""

_WINDOWS_TEMPLATE = """@echo off
cd /d "%BUILD_WORKSPACE_DIRECTORY%\\javascript\\selenium-webdriver"
set DEST=%BUILD_WORKSPACE_DIRECTORY%\\build\\docs\\api\\javascript
set TEMPLATE=%~dp0.runfiles\\_main\\javascript\\selenium-webdriver\\node_modules\\clean-jsdoc-theme
set BAZEL_BINDIR=.

if exist "%DEST%" rmdir /s /q "%DEST%"
mkdir "%DEST%"

"%~dp0.runfiles\\_main\\{jsdoc_bin}" --configure {config} --destination "%DEST%" --template "%TEMPLATE%" %*
if %ERRORLEVEL% neq 0 (
    echo jsdoc exited with warnings, checking output...
)

if exist "%DEST%\\index.html" (
    echo Documentation generated successfully at %DEST%
) else (
    echo ERROR: Documentation was not generated
    exit /b 1
)
"""

jsdoc = rule(
    implementation = _jsdoc_impl,
    executable = True,
    attrs = {
        "config": attr.label(
            mandatory = True,
            allow_single_file = [".json"],
        ),
        "data": attr.label_list(
            allow_files = True,
        ),
        "jsdoc_binary": attr.label(
            mandatory = True,
            executable = True,
            cfg = "target",
            doc = "The jsdoc binary target from npm",
        ),
        "_windows_constraint": attr.label(
            default = "@platforms//os:windows",
        ),
    },
)