blob: 3f101db589f3009f4447ceee476def0ef7b7bf6a [file]
#!/usr/bin/env python3
# ***************************************************************************************************************************
# * Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file *
# * distributed with this work for additional information regarding copyright ownership. The ASF licenses this file *
# * to you 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. *
# ***************************************************************************************************************************
"""
Optional juneau-terminal live view for build-docs.py, release-docs-stage.py and release-docs.py.
The scripts load juneau-terminal's toolkit from the Juneau checkout they resolve
(<juneau-root>/juneau-terminal/src/main/python). With it, each stage is a row of the console view
(--console full|board|none, default board, or JUNEAU_TERMINAL_CONSOLE), with the full and
board logs under ~/.cache/juneau-terminal/. When it can't be found or imported, View is plain:
banners and the tools' own output on the terminal, as the scripts printed before. juneau-docs
never depends on juneau-terminal.
"""
import contextlib
import importlib
import importlib.util
import os
import subprocess
import sys
from pathlib import Path
import mvn_lock
BOOTSTRAP_FILE = 'bootstrap.py'
CONSOLE_MODES = ('full', 'board', 'none')
#: Every row build-docs.py draws, in order, as (id, label). Skipped stages still draw, as skipped rows.
BUILD_ROWS = (
('clean', 'Clean'),
('npm', 'npm'),
('install', 'Install'),
('site', 'Site'),
('copy', 'Copy'),
('docs', 'Docs build'),
('verify', 'Verify'),
('links', 'Links'),
)
# The toolkit functions the scripts call; an older juneau-terminal without one of them counts as unavailable.
_REQUIRED = ('session', 'step', 'cmd', 'say', 'handoff', 'checks', 'export_console', 'paused')
def toolkit_dir(juneau_root):
"""Where juneau-terminal's Python sources sit in a Juneau checkout."""
return Path(juneau_root) / 'juneau-terminal' / 'src' / 'main' / 'python'
def load_toolkit(juneau_root):
"""
juneau_terminal_scripts.run from the Juneau checkout, or None.
Returns None silently when juneau_root is None or doesn't exist (e.g. a CI runner with only
the docs checkout), and with one warning on stderr when the checkout has no usable juneau-terminal.
"""
if juneau_root is None or not Path(juneau_root).is_dir():
return None
src = toolkit_dir(juneau_root)
try:
if not (src / BOOTSTRAP_FILE).is_file():
raise ImportError(f"{src / BOOTSTRAP_FILE} not found")
sys.dont_write_bytecode = True # nothing may write __pycache__ into the Juneau source tree
bootstrap = sys.modules.get('bootstrap')
if bootstrap is None or Path(getattr(bootstrap, '__file__', '')).resolve() != (src / BOOTSTRAP_FILE).resolve():
spec = importlib.util.spec_from_file_location('bootstrap', src / BOOTSTRAP_FILE)
bootstrap = importlib.util.module_from_spec(spec)
spec.loader.exec_module(bootstrap)
sys.modules['bootstrap'] = bootstrap
bootstrap.load(pom=str(Path(juneau_root) / 'pom.xml'), terminal=True)
run = importlib.import_module('juneau_terminal_scripts.run')
missing = [name for name in _REQUIRED if not hasattr(run, name)]
if missing:
raise ImportError(f"juneau_terminal_scripts.run has no {', '.join(missing)}")
return run
except Exception as e: # any failure means plain output, never a failed build
print(f"warning: juneau-terminal unavailable ({e}); running with plain output", file=sys.stderr)
return None
def open_view(juneau_root, console=None, *, verbose=False, plain=False):
"""
The View for a script run. console is the --console value (None: JUNEAU_TERMINAL_CONSOLE, else
board). plain=True (e.g. --dry-run) skips juneau-terminal altogether.
"""
run = None if plain else load_toolkit(juneau_root)
if run is not None:
try:
run.export_console(console)
except Exception as e: # e.g. a bad JUNEAU_TERMINAL_CONSOLE value: plain output, never a failed build
print(f"warning: juneau-terminal console setting rejected ({e}); running with plain output", file=sys.stderr)
run = None
return View(run, verbose=verbose)
def add_console_argument(parser):
"""--console, for the docs scripts. Validated here, since the toolkit may not be loaded."""
parser.add_argument('--console', choices=CONSOLE_MODES, default=None,
help='Console output when juneau-terminal is available: full, board (default) or none '
'(also JUNEAU_TERMINAL_CONSOLE; the flag wins)')
def branch_warning(repo):
"""
None when repo is on a branch that isn't behind its upstream; otherwise one line saying what
is off (detached HEAD, behind upstream, or the check couldn't run). Fetches the upstream first,
without prompting for credentials, so it never hangs or stops a release.
"""
env = {**os.environ, 'GIT_TERMINAL_PROMPT': '0', 'GIT_SSH_COMMAND': 'ssh -oBatchMode=yes'}
def git(*args):
return subprocess.run(['git', *args], cwd=repo, capture_output=True, text=True, check=False,
env=env, timeout=60)
try:
branch = git('symbolic-ref', '--short', '-q', 'HEAD')
if branch.returncode != 0:
return 'detached HEAD, not on a branch'
if git('rev-parse', '--abbrev-ref', '--symbolic-full-name', '@{upstream}').returncode != 0:
return None
if git('fetch', '-q').returncode != 0:
return f"{branch.stdout.strip()}: could not fetch its upstream"
counts = git('rev-list', '--left-right', '--count', 'HEAD...@{upstream}')
if counts.returncode != 0:
return f"{branch.stdout.strip()}: could not compare with its upstream"
behind = int(counts.stdout.split()[1])
except (OSError, subprocess.SubprocessError, ValueError, IndexError) as e:
return f"could not check the branch ({e})"
if behind:
return f"{branch.stdout.strip()} is {behind} commit{'' if behind == 1 else 's'} behind its upstream"
return None
class _PlainStep:
"""What View.stage yields in a plain run: the row's outcome, printed when it matters."""
def __init__(self):
self.status = 'ok'
self.summary = None
def fail(self, exit=None): # NOSONAR python:S5806 - mirrors juneau_terminal.Step.fail
self.status = 'fail'
def skip(self, reason=None):
self.status = 'skip'
self.summary = reason
def warn(self, text):
print(f"⚠ {text}", flush=True)
class View:
"""The live view through juneau-terminal (run set), or plain output (run None)."""
def __init__(self, run=None, *, verbose=False):
self.run = run
self.verbose = verbose
@property
def live(self):
"""True when juneau-terminal is loaded (the rows are drawn unless --console full)."""
return self.run is not None
def say(self, text='', level='info'):
"""Status text: printed in a plain run; under the view a note filtered by its detail level."""
if self.run is None:
print(text, flush=True)
else:
self.run.say(text, level)
def banner(self, title):
"""A stage header in a plain run (the row says it under the view)."""
if self.run is None:
print(f"\n=== {title} ===" if self.verbose else f"-> {title}", flush=True)
@contextlib.contextmanager
def stage(self, id, label, title, *, parent=None): # NOSONAR python:S5806 - mirrors juneau_terminal.step
"""A row around the block. Set .summary on what it yields, or call .skip(reason) or .fail()."""
if self.run is None:
self.banner(title)
step = _PlainStep()
yield step
if step.status == 'skip':
print(f" skipped{f' ({step.summary})' if step.summary else ''}", flush=True)
return
with self.run.step(id, title, label=label, parent=parent) as step:
yield step
def skip(self, id, label, title, reason, *, parent=None): # NOSONAR python:S5806 - mirrors juneau_terminal.step
"""A row shown skipped, with reason as its text."""
if self.run is None:
print(f"\n=== Skipping {title} ({reason}) ===" if self.verbose else f"-> Skipping {title} ({reason})",
flush=True)
return
with self.run.step(id, title, label=label, parent=parent) as step:
step.skip(reason)
def lock_wait(self, say):
"""The on_wait callback for the Maven lock: the log lines, plus (under the view) a "Maven lock" row that
appears only if the lock is busy. Call .close() on it once the lock is taken."""
# juneau_terminal itself: the scripts' run module wraps steps but has no bare row or tick
jr = None if self.run is None else sys.modules.get('juneau_terminal')
open_row = None if jr is None else lambda: jr.row("mvn-lock", "Maven lock", label="Maven lock")
return mvn_lock.WaitRow(open_row or (lambda: None), say, None if jr is None else jr.tick)
def paused(self):
"""The console view cleared for the block, so a prompt or an interactive child isn't drawn over; a no-op when plain."""
if self.run is None:
return contextlib.nullcontext()
return self.run.paused()
def cmd(self, cmd, *, id, title, label=None, tool=None, cwd=None, env=None, parent=None, tty=False): # NOSONAR python:S5806
"""
Run cmd as its own row (a child row with parent). tool is juneau-terminal's parser (None picks it
from the command: mvn is maven, npm is npm). Raises CalledProcessError when it fails.
"""
if self.run is None:
print(f"Running: {' '.join(map(str, cmd))}", flush=True)
if cwd:
print(f" (in directory: {cwd})", flush=True)
subprocess.run(cmd, cwd=cwd, env=env, check=True)
return
result = self.run.cmd(cmd, title=title, id=id, label=label, tool=tool, cwd=cwd, env=env, parent=parent,
tty=tty)
if not result.ok:
raise subprocess.CalledProcessError(result.code, cmd)
def remote_cmd(self, cmd, **kwargs):
"""
cmd (a git clone or fetch) as its own row, as cmd(). When it fails, adds a line naming the likely
cause, since a remote that wants credentials fails without a prompt here, then re-raises.
"""
try:
self.cmd(cmd, **kwargs)
except subprocess.CalledProcessError:
self.say(" The remote may need credentials; load your ssh key into the agent "
"(ssh-add) or sign in to your git credential helper, then run again.", 'error')
raise
def prechecks(self, checks):
"""
Run checks as the Prechecks row and return False when one failed. checks is a list of
(name, fn); fn() returns None for a pass, or (status, reason, hint lines) with status
"warn" or "fail". Every check runs, even after a failure.
"""
if self.run is None:
ok = True
for name, fn in checks:
out = fn()
if out is None:
print(f"✅ {name}", flush=True)
continue
status, reason, hint = out
print(f"{'❌' if status == 'fail' else '⚠️ '} {name}: {reason}", flush=True)
for line in hint:
print(f" {line}", flush=True)
ok = ok and status != 'fail'
return ok
jc = importlib.import_module('juneau_terminal_scripts.checks')
def verdict(fn):
def check():
out = fn()
return None if out is None else jc.Verdict(out[0], out[1], tuple(out[2]))
return check
items = [jc.Check(name, verdict(fn)) for name, fn in checks]
return self.run.checks('prechecks', 'Prechecks', items, label='Prechecks').ok
@contextlib.contextmanager
def handoff(self):
"""The terminal for a child script that joins this view; yields the env additions it needs."""
if self.run is None:
yield {}
return
with self.run.handoff() as extra:
yield extra
def session(self, title, body, *, header=(), lines=(), plan=None, repo='.', mode=None):
"""
Run body() -- which returns an exit code -- inside a juneau-terminal session and return the
session's code: 0, 1 on a failure (a failed command's row already says why), 130 on Ctrl-C.
header is the items after the title; lines are header lines under it (one each, cut to one
line on the live screen). Only for a live View.
"""
def guarded():
try:
return body()
except subprocess.CalledProcessError:
raise SystemExit(1)
with self.run.session(title, header=tuple(header), lines=tuple(lines), repo=str(repo), mode=mode,
project=Path(repo).name, exit=False,
plan=list(plan) if plan is not None else None) as s:
code = guarded()
if code:
raise SystemExit(code)
return s.code