build

#!/usr/bin/env python3
'''
Controls the build process for this site. Use this script for all builds.

It also manages git pushes to both repositories.

Most common usage:

For development, run `./build &` and to build and deploy to production, run `./build -D`
'''

import argparse
import atexit
import os
import re
import shlex
import shutil
import sys
import tempfile
import textwrap
from subprocess import call, check_call, CalledProcessError, DEVNULL
from typing import Any, Literal

path = os.path

try:
    import jsonc as json
except ModuleNotFoundError:
    # Windows can't find the jsonc module when this script is called from a
    # symlink.
    if path.islink(__file__):
        sys.path.insert(0, path.dirname(path.realpath(os.readlink(__file__))))
        import jsonc as json
    else:
        raise

# Make the print command automatically flush in Windows. Otherwise, nothing
# will appear until exit.
if os.name == 'nt':
    import functools
    print = functools.partial(print, flush=True)

# Initialize some global variables.
verbosity: int = 0

class AlreadyRunningError(Exception):
    pass

def create_pidfile() -> None:
    pid = str(os.getpid())
    pidfile = path.join(tempfile.gettempdir(), 'jekyll_build.pid')
    if verbosity > 0:
        print(f'\npid:\t\t{pid}\npidfile:\t{pidfile}')
    if path.isfile(pidfile):
        with open(pidfile) as f:
            oldpid = f.read()
        message = f'jekyll_build is already running (pid {oldpid}). You cannot have more than one script executing simultaneously. If this error is incorrect, delete the file "{pidfile}".'
        raise AlreadyRunningError(message)
    with open(pidfile, 'w') as f:
        f.write(pid)
    atexit.register(remove_pidfile, pidfile)
    if verbosity > 0:
        print('Created pidfile and registered exit handler.')

def remove_pidfile(pidfile: str) -> None:
    os.unlink(pidfile)

def is_build_dir(dirname: str) -> bool:
    try:
        d = os.listdir(dirname)
        return all(i in d for i in ['build_config_sample.jsonc',
            'minify_html_js.py', 'build_dev.sh', 'clean.sh', 'deploy.sh'])
    except (FileNotFoundError, NotADirectoryError):
        return False

def find_build_dir() -> str:
    bdir = path.dirname(path.realpath(__file__))

    # Sanity check needed to convince Windows about the true location of this
    # file. In Windows, path.realpath doesn't resolve symlinks, leaving us
    # unable to find our support files. So, we do the work for Windows, if
    # necessary.
    if not is_build_dir(bdir):
        error_message = '\n' + str_wrap(
                '''ERROR: The calculated build dir is "{}", but this isn't a
                real build dir. This is a bug in the build script.''')
        if path.islink(__file__):
            bdir = path.dirname(path.realpath(os.readlink(__file__)))
            if not is_build_dir(bdir):
                exit(error_message.format(bdir))
            else:
                if verbosity == 1:
                    print('NOTICE: Corrected build dir.')
        else:
            exit(error_message.format(bdir))
    return bdir

def str_wrap(string: str, kind: str = 'normal', indent: int = 0, initial_offset: int = 0) -> str:
    cols, lines = shutil.get_terminal_size()
    cols = min(cols, 100)
    if kind == 'help':
        # The width of argparse's left margin for help text, minus 1 for
        # scrollbar padding on Windows' cmd.exe.
        cols = max(cols-23-1, 10)
    out = []
    for paragraph in re.split(r'\r?\n\r?\n', textwrap.dedent(string)):
        paragraph = re.sub(r'[\s]+', ' ', paragraph.strip())
        lines = textwrap.wrap(paragraph, width=cols,
                     replace_whitespace=True, break_long_words=False,
                     initial_indent=' '*indent, subsequent_indent=' '*indent)
        out.append('\n'.join(lines))
    out = '\n\n'.join(out).rstrip()
    if kind == 'help':
        return out + '\n\n'
    else:
        return out + '\n'

def run_external_command(command: str, dry_run: bool = False) -> None:
    cmd = shlex.split(command)
    if dry_run:
        print(f'Would run this command:\n\t{cmd}')
    else:
        try:
            check_call(cmd)
        except CalledProcessError as e:
            print(f'Command failure! Error {e}.')
            raise

def clean(dry_run: bool = False, clean_directories: list[str] = [], clean_files: list[str] = []) -> bool:
    if verbosity >= 0:
        print('Cleaning...')
    if dry_run:
        for dir_ in clean_directories:
            print(f'Cleaner: Would delete {dir_} and its contents.')
    else:
        for file_ in clean_files:
            if verbosity >= 0:
                print(f'Removing file {file_}...')
            try:
                os.remove(file_)
            except FileNotFoundError:
                if verbosity >= 0:
                    print(f'File {file_} doesn\'t exist, so there\'s nothing to delete.')
            except PermissionError:
                if verbosity >= 0:
                    print(f'Permission denied when trying to delete {file_}.')
                    return False
            except OSError as e:
                if verbosity >= 0:
                    print(f'An error occurred when trying to delete {file_}: {e}')
                    return False
        for dir_ in clean_directories:
            if verbosity >= 0:
                print(f'Removing directory {dir_}...')
            try:
                shutil.rmtree(dir_)
            except FileNotFoundError:
                if verbosity >= 0:
                    print(f'Directory {dir_} doesn\'t exist, so there\'s nothing to delete.')
            except PermissionError:
                if verbosity >= 0:
                    print(f'Permission denied when trying to delete {dir_}.')
                    return False
            except OSError as e:
                if verbosity >= 0:
                    print(f'An error occurred when trying to delete {dir_}: {e}')
                    return False
    cmd = [path.join(build_dir, 'clean.sh'), build_dir]
    if os.name == 'nt':
        cmd.insert(0, 'bash')
    if dry_run:
        print(f'Would call {cmd}')
        return True
    result = call(cmd)
    return True if result == 0 else False

def launch_apache(config: dict[str, Any], dry_run: bool = False) -> bool:
    if os.name != 'nt':
        print("Unable to launch Apache on this system.")
        return False
    elif 'xampp_path' not in config.keys():
        with open(path.join(build_dir, 'build_config_sample.jsonc')) as f:
            config['xampp_path'] = json.loads(f.read())['xampp_path']
        print('\n' + str_wrap(f'''
            WARNING: Not configured. Please set the "xampp_path" option in the
            config file ("_build_config.jsonc"). Using the default path
            ({config['xampp_path']}), which may or may not work.
            '''))
    elif ' ' in config['xampp_path']:
        if verbosity >= 0:
            print('\n' + str_wrap(f'''
                WARNING: The configured server path ({config['xampp_path']})
                contains one or more spaces. Though it is untested, it's likely
                that this can't be made to work as the Windows command used to
                launch the server doesn't like the server path to be
                quoted.'''))
    if verbosity >= 0:
        print('Launching server...')
    cmd = ['cmd', '/C', f'start {config["xampp_path"]} /run']
    if dry_run:
        print(f'Would call {cmd}')
        return True
    result = call(cmd)
    return True if result == 0 else False

def update_ctags(dry_run: bool = False) -> bool:
    cmd = ['ctags', '.']
    if dry_run:
        print(f'Would call {cmd}')
        return True
    if verbosity > 0:
        cmd.insert(1, '--verbose')
    if verbosity < 0:
        result = call(cmd, stdout=DEVNULL, stderr=DEVNULL)
    else:
        result = call(cmd)
    return True if result == 0 else False

def build(config: dict[str, Any], dev: bool, minify_html: bool, minify_js: bool, incremental: bool = True, watch: bool = False,
          serve: bool = False, trace: bool = False, dry_run: bool = False, clean_directories: list[str] = []) -> bool:
    mode: Literal['serve', 'build'] = 'serve' if serve else 'build'
    which: Literal['build_production.sh', 'build_dev.sh'] = 'build_production.sh'
    if dev:
        which = 'build_dev.sh'
    else:
        success = clean(dry_run, clean_directories=clean_directories)
        if not success:
            return False
    update_ctags(dry_run)
    args = [path.join(build_dir, which), mode]
    if os.name == 'nt':
        args.insert(0, 'bash')
    args.append(build_dir)
    if incremental:
        args.append('--incremental')
    if watch and mode == 'build':
        args.append('--watch')
    if trace:
        args.append('--trace')
    if verbosity == 1:
        print('Calling `{}`...'.format(' '.join(args)))
    try:
        if dry_run:
            print(f'Would call {args}')
        else:
            check_call(args)
        if not dev or (not watch and not serve and not incremental):
            return minify(config, js=minify_js, html=minify_html, dry_run=dry_run)
    except CalledProcessError:
        return False
    except KeyboardInterrupt:
        if verbosity >= 0:
            print('\nExiting `{}`.'.format(' '.join(args)))
        return True if (watch or serve) else False
    else:
        return True
    finally:
        if verbosity > 0:
            print('Build process ended.')

def minify(config: dict[str, Any], js: bool = True, html: bool = True, dry_run: bool = False) -> bool:
    if js is False and html is False:
        if verbosity > 0:
            print('Minification is disabled.')
        return True
    if verbosity >= 0:
        print('Minifying...')
    cmd = [path.join(build_dir, 'minify.sh'), build_dir, config.get('minify_options', '')]
    if js:
        cmd.append('--js')
    if html:
        cmd.append('--html')
    if dry_run:
        cmd.append('--dry-run')
    if os.name == 'nt':
        cmd.insert(0, 'bash')
    try:
        check_call(cmd)
    except CalledProcessError:
        return False
    else:
        return True

def deploy(args, dry_run=False):
    if verbosity >= 0:
        print('Running deploy script...')
    cmd = [path.join(build_dir, 'deploy.sh'), build_dir, '_site']
    cmd += ['--config', args.deploy_config]
    if dry_run:
        cmd.append('--dry-run')
    if os.name == 'nt':
        cmd.insert(0, 'bash')
    try:
        check_call(cmd)
    except CalledProcessError:
        return False
    else:
        return True

def git_push(*upstreams, dry_run=False):
    if verbosity >= 0:
        print('Pushing to: {}'.format(' '.join(upstreams)))
    switch = '--quiet' if verbosity == -1 else ''
    if verbosity == 1:
        switch = '--verbose'
    for upstream in upstreams:
        call_lst = ['git', 'push']
        if len(switch) > 0:
            call_lst.append(switch)
        if dry_run:
            call_lst.append('--dry-run')
        call_lst.append(upstream)
        try:
            check_call(call_lst)
        except CalledProcessError:
            return False
    return True

def parse_args():
    def jekyll_directory(s):
        if verbosity == 1:
            print(path.basename(sys.argv[0]))
        if not path.isdir(s):
            raise argparse.ArgumentTypeError('\n' + str_wrap('''
                The directory "{}" doesn't exist.'''.format(s),
                indent=8))
        files = os.listdir(s)
        if '_includes' not in files or '_config.yml' not in files:
            raise argparse.ArgumentTypeError('\n' + str_wrap('''
                The directory "{}" doesn't appear to be a Jekyll site source
                directory. If you didn't pass the -j/--jekyll_dir argument, this
                error is caused by your current working directory not being a
                Jekyll site source directory. Either change directory or pass
                -j.
                '''.format(s),
                indent=8))
        return path.abspath(s)

    def json_file(s):
        if s is not None:
            try:
                with open(s) as f:
                    json.loads(f.read())
            except (FileNotFoundError, IsADirectoryError, json.JSONDecodeError):
                raise argparse.ArgumentTypeError(
                    f"The file {s} isn't a valid JSON config file!")
        return s

    dev = '''Do a development build. This is the default unless --deploy is
            given.'''
    prod = 'Do a production build.'
    deploy = '''Do a build, then deploy. Implies --production unless --dev is
            specified.'''
    deploy_only = '''Don't build; only deploy. Useful when manual changes have
            to be made prior to deployment. This is meant as a stopgap only.'''
    clean = 'Clean the build dir.'
    incr = 'Disable incremental builds. Only applies to development builds.'
    watch = """Don't watch for changes. Only applies to development builds.
            Ignored when deploying or serving."""
    serve = '''After building, run Jekyll's built-in server. Ignored when
            deploying.'''
    push = '''Does a `git push` to each remote configured herein. All other
            options are ignored when this is in effect.'''
    remotes = '''List all configured git remotes which will be pushed to with -g/--git-push'''
    xampp = '''Windows only: Launch Apache, which must have been previously
            configured on the machine and live at the configured path.'''
    ctags = 'Update the tags file.'
    jdir = '''Use this directory as the Jekyll source directory. Default: the
            current working directory.'''
    epilog = '''When run with no arguments, this script runs a development
            build, passing Jekyll the --watch and --incremental arguments.'''
    verbose = 'Print all available debugging information'
    deploy_cfg = 'Path to the deploy configuration file. Default: _deploy.jsonc'
    no_minify = """Don't minify HTML or JavaScript. CSS minification is handled
            by Jekyll, not the build scripts. Equivalent to -HJ."""
    no_minify_html = "Don't minify HTML."
    no_minify_js = "Don't minify JavaScript."
    dry_run = "Do a dry run; don't actually change anything."
    silent = 'Print minimal information'
    trace = 'Pass the --trace argument to jekyll build'
    precmd = "Don't execute the pre-command found in the configuration."
    postcmd = "Don't execute the post-build command found in the configuration."

    parser = argparse.ArgumentParser(description=__doc__, epilog=epilog,
            usage='%(prog)s [options]', add_help=False)
    #add = parser.add_argument
    g = parser.add_argument_group(title='Mode',
                    description='At most one of these arguments may be given:')
    group = g.add_mutually_exclusive_group()
    gadd = group.add_argument
    o = parser.add_argument_group(title='Other arguments')
    oadd = o.add_argument
    v = parser.add_argument_group(title="Verbosity",
                    description='At most one of these arguments may be given:')
    vgroup = v.add_mutually_exclusive_group()
    vadd = vgroup.add_argument

    gadd('-d', '--dev', dest='no_dev', action='store_false', help=dev)
    gadd('-p', '--production', action='store_true', help=prod)
    gadd('-c', '--clean', action='store_true', help=clean)
    gadd('-g', '--git-push', dest='push', action='store_true', help=push)
    gadd('--list-remotes', dest='list_remotes', action='store_true', help=remotes)
    gadd('-S', '--apache', action='store_true', help=xampp)
    gadd('-t', '--ctags', action='store_true', help=ctags)

    oadd('-D', '--deploy', action='store_true', help=deploy)
    oadd('--deploy-only', action='store_true', help=deploy_only)
    oadd('-i', '--no-incremental', dest='incremental', action='store_false',
         help=incr)
    oadd('-s', '--serve', action='store_true', help=serve)
    oadd('-w', '--no-watch', dest='watch', action='store_false', help=watch)
    oadd('-H', '--no-minify-html', dest='minify_html', action='store_false',
         help=no_minify_html)
    oadd('-J', '--no-minify-js', dest='minify_js', action='store_false',
         help=no_minify_js)
    oadd('-M', '--no-minify', dest='minify', action='store_false',
         help=no_minify)
    oadd('-j', '--jekyll-dir', type=jekyll_directory, default=os.getcwd(),
         help=jdir)
    oadd('-z', '--deploy-config', type=json_file, default=None, help=deploy_cfg)
    oadd('--trace', action='store_true', help=trace)
    oadd('-P', '--skip-precmd', action='store_false', dest='use_precmd', help=precmd)
    oadd('-C', '--skip-postcmd', action='store_false', dest='use_postcmd', help=postcmd)
    oadd('-n', '--dry-run', action='store_true', help=dry_run)
    oadd('-h', '--help', action='help', help="Show this help message and exit.")

    vadd('-q', '--quiet', action='store_true', help=silent)
    vadd('-v', '--verbose', action='store_true', help=verbose)

    return parser.parse_args()

def main():
    args = parse_args()
    building = True
    if args.push or args.list_remotes:
        building = False
    dry_run = args.dry_run
    global verbosity
    verbosity = 1 if args.verbose else 0
    if args.quiet:
        verbosity = -1
    os.environ['JEKYLL_BUILD_VERBOSITY'] = str(verbosity)

    if building:
        create_pidfile()
        if verbosity > 0:
            print("os.environ: " + str(os.environ))
            print("Python sees this OS as: {}".format(os.name))
        if dry_run and verbosity >= 0:
            print("Dry run enabled")
    global build_dir
    config_file = '_build_config.jsonc'
    if not args.deploy_config:
        args.deploy_config = '_deploy.jsonc'
    build_dir = find_build_dir()
    if verbosity >= 0 and building:
        print(f'Jekyll source directory: {args.jekyll_dir}')
        print(f'Build scripts located in: {build_dir}')
    if not args.minify:
        args.minify_js = args.minify_html = False
    if verbosity == 1:
        print(f'Build arguments: {args}')
    os.chdir(args.jekyll_dir)
    if not path.isfile(config_file):
        exit(str_wrap(f'''
            Couldn't find the configuration file "{config_file}". Please create
            it before continuing. You can find an example at
            "{path.join(build_dir, 'build_config_sample.jsonc')}".
            '''))
    with open(config_file) as f:
        config: dict[str, Any] = json.loads(f.read())

    if args.push:
        targets = config.get('git_remotes', ['origin'])
        success = git_push(*targets, dry_run=dry_run)
        code = 0 if success else 4
        return code
    
    if args.list_remotes:
        remotes = config.get('git_remotes', ['origin'])
        print('Configured git remotes:\n- ', end='')
        print('\n- '.join(remotes))
        return 0
    
    elif args.clean:
        clean_directories = config.get('clean_directories', [])
        clean_files = config.get('clean_files', [])
        success = clean(dry_run, clean_directories, clean_files)
        code = 0 if success else 3
        return code
    
    elif args.apache:
        success = launch_apache(config, dry_run)
        code = 0 if success else 5
        return code
    
    elif args.ctags:
        success = update_ctags(dry_run)
        code = 0 if success else 9
        return code
    
    elif args.deploy or args.deploy_only:
        if args.deploy and args.deploy_only:
            exit(str_wrap('''ERROR: You can't specify both --deploy and
                            --deploy_only.'''))
        if args.deploy:
            d = {'dev': False, 'trace': args.trace}
            args.serve = False
            args.watch = False
            if args.no_dev: # we want to deploy a production build
                args.incremental = not args.incremental
            else:
                d['dev'] = True
            d['incremental'] = args.incremental
            pre_cmd = config.get('deploy_pre_command', None)
            if args.use_precmd and pre_cmd:
                run_external_command(pre_cmd, dry_run)
            success = build(config, **d, minify_html=args.minify_html,
                    minify_js=args.minify_js, dry_run=dry_run,
                    clean_directories=config.get('clean_directories', []))
            if success:
                if args.use_postcmd and 'build_post_command' in config:
                    if isinstance(config['build_post_command'], str):
                        run_external_command(config['build_post_command'], dry_run)
                    else:
                        for command in config['build_post_command']:
                            run_external_command(command, dry_run)
                success = deploy(args, dry_run)
                code = 0 if success else 2
                return code
            else:
                return 1
        else:
            success = deploy(args, dry_run)
            code = 0 if success else 2
            return code
        
    else:
        d = {
            'dev': False if args.production else True,
            'incremental': args.incremental,
            'watch': args.watch,
            'serve': args.serve
        }
        pre_cmd = config.get('build_pre_command', None)
        if args.use_precmd and pre_cmd:
            run_external_command(pre_cmd, dry_run)
        if args.use_postcmd and 'build_post_command' in config and (args.watch or args.serve) and not args.verbose:
            print(str_wrap(f'''
                Unable to run the post command
                "{config["build_post_command"]}" because we aren't exiting
                immediately after the build. If you run the build script in a
                way that it will exit of its own accord when finished, then the
                post command will run.'''))
        success = build(config, **d, minify_html=args.minify_html,
                minify_js=args.minify_js, dry_run=dry_run)
        code = 0 if success else 1
        if args.use_postcmd and 'build_post_command' in config and not (args.watch or args.serve):
            if isinstance(config['build_post_command'], str):
                run_external_command(config['build_post_command'], dry_run)
            else:
                for command in config['build_post_command']:
                    run_external_command(command, dry_run)
        return code

if __name__ == '__main__':
    exit(main())