cat-verify

#!/usr/bin/env python3
#
# This Source Code Form is subject to the terms of the Mozilla Public
# License, v. 2.0. If a copy of the MPL was not distributed with this
# file, You can obtain one at http://mozilla.org/MPL/2.0/.
#
# cat-verify - Generate a Markdown verification manual
#
# USAGE
#
#     $ cat-verify -c config.txt -a variable.txt

import re
import sys
import glob
import getopt
import logging
import textwrap
import csv
import os
import collections

BASEDIR = os.path.dirname(os.path.realpath(__file__))
sys.path.append(BASEDIR)

import adlib

try:
    import jinja2
except ImportError:
    print("ERROR: Please install jinja2 to run this script\n")
    print("  $ sudo apt install python3-jinja2\n")
    sys.exit(1)

#
# GLOBALS

DEFAULT_VAR = {
    "firefox_version":                "115.0 ESR",
    "windows_version":                "Windows 10",
    "configuration_sheet_name":       "configs.xlsx",
    "use_meta_installer":             "true",
    "meta_installer_name":            "Fx Meta Installer",
    "meta_installer_file_name":       "FxMetaInstaller",
    "meta_installer_version":         "115.0",
    "install_path_base":              "C:\\Program Files (x86)",
    "install_path_base_32bit":        "C:\\Program Files",
    "install_path":                   "C:\\Program Files (x86)\\Mozilla Firefox",
    "install_path_32bit":             "C:\\Program Files\\Mozilla Firefox",
    "exe_name":                       "firefox",
    "desktop_shortcut":               "true",
    "desktop_shortcut_path":          "C:\\Users\\Public\\Desktop\\Mozilla Firefox.lnk",
    "start_menu_shortcut":            "true",
    "start_menu_shortcut_path":       "C:\\ProgramData\\Microsoft\\Windows\\Start Menu\\Programs\\Mozilla Firefox.lnk",
    "finish_title":                   "Mozilla Firefox",
    "finish_message":                 "インストールが完了しました",
    "restart_title":                  "Mozilla Firefox",
    "restart_message":                "今すぐコンピュータを再起動しますか？",
    "mcd_local_file":                 "autoconfig.cfg",
    "special_profile_path":           "%AppData%\\Mozilla\\Firefox",
    "special_profile_name":           "Special",
    "home_page":                      "http://example.com/",
    "history_expiration_max_pages":   "30",
    "download_dir":                   "C:\\",
    "proxy_host":                     "example.local",
    "proxy_auth_user":                "clearcode",
    "pac_url":                        "http://example.local/proxy.pac",
    "pac_url_setup":                  "data:application/javascript,",
    "ntlm_single_signon_hosts":       "sso.example.local",
    "weak_tls_allowed_hosts":         "weak.example.local",
    "security_45_exception_hosts":    "example.com",
    "location_3_hostname_like_term":  "example",
    "max_connections":                       "6",
    "max_persistent_connections_per_server": "2",
    "max_persistent_connections_per_proxy":  "2",
    "max_pipelining_requests":               "32",
    "user_agent_name":                "Mozilla/5.0 (X11; Linux x86_64; rv:51.0) Gecko/20100101 Firefox/115.0",
    "navigator_appVersion":           "5.0 (Windows)",
    "imported_certs":                 "検証用証明書（example.com）, (発行者名1)/(証明署名1), (発行者名1)/(証明署名2), ...",
    "flash_download_url":             "https://get.adobe.com/jp/flashplayer/",
    "ModifySystemTime":               "",
    "DownloadExeFile":                "",
    "UpdateFromFirefox60":            "",
}

TEMPLATE = """
## {option_id}

『{title}：{option_title}』
{dependency_description}

**検証手順**

{config}
"""

TEMPLATE_PRETEXT = """
## {option_title}

{config}
"""

TEMPLATE_OPTIONS = """
# 設定画面を使用した検証

## 事前準備

- 前項に引き続き検証するか、または以下の状態を整えておく。
    - 作成済みの `{{meta_installer_file_name}}*.exe` を検証用ユーザーとして実行し、カスタマイズ済みFirefoxのインストールを完了している。
      管理者権限を要求された場合は、`管理者`ユーザーで認証する。

## 検証

- ユーザープロファイルの位置が `%AppData%\Mozilla` 配下にある場合、 `%AppData%\Mozilla` を削除する。そうでない場合、ユーザープロファイルフォルダ自体を削除する。
- Firefoxを起動する。
- パネルメニューから「設定」を開く。
- **確認**
"""

TEMPLATE_ABOUT_CONFIG = """
# about:configを使用した検証

## 事前準備

- 前項に引き続き検証するか、または以下の状態を整えておく。
    - 作成済みの `{{meta_installer_file_name}}*.exe` を検証用ユーザーとして実行し、カスタマイズ済みFirefoxのインストールを完了している。
      管理者権限を要求された場合は、`管理者`ユーザーで認証する。

## 検証

{%if Security_9_3 %}
- ポリシー設定から `BlockAboutConfig` を削除し、`about:config` を一時的に有効化しておく。
  {% endif %}
- ユーザープロファイルの位置が `%AppData%\Mozilla` 配下にある場合、 `%AppData%\Mozilla` を削除する。そうでない場合、ユーザープロファイルフォルダ自体を削除する。
- Firefoxを起動する。
- `about:config`を開く。
- **確認**
"""

TEMPLATE_ABOUT_CONFIG_END = """
  {%if Security_9_3 %}
- ポリシー設定から一時的に削除した `BlockAboutConfig` を元に戻す。
  {% endif %}
"""

TEMPLATE_ABOUT_POLICIES = """
# about:policiesを使用した検証

## 事前準備

- 前項に引き続き検証するか、または以下の状態を整えておく。
    - 作成済みの `{{meta_installer_file_name}}*.exe` を検証用ユーザーとして実行し、カスタマイズ済みFirefoxのインストールを完了している。
      管理者権限を要求された場合は、`管理者`ユーザーで認証する。

## 検証

- Firefoxを起動する。
- `about:policies`を開く。
- 「有効」を選択する。
- **確認**
"""

TEMPLATE_SHORTCUT = """
# その他のキーボードショートカットの検証

## 事前準備

- 前項に引き続き検証するか、または以下の状態を整えておく。
    - 作成済みの `{{meta_installer_file_name}}*.exe` を検証用ユーザーとして実行し、カスタマイズ済みFirefoxのインストールを完了している。
      管理者権限を要求された場合は、`管理者`ユーザーで認証する。

## 検証

- Firefoxを起動する。
- **確認**
"""

TEMPLATE_DEVTOOL_MENU = """
# 開発ツールのメニュー項目の検証

## 事前準備

- 前項に引き続き検証するか、または以下の状態を整えておく。
    - 作成済みの `{{meta_installer_file_name}}*.exe` を検証用ユーザーとして実行し、カスタマイズ済みFirefoxのインストールを完了している。
      管理者権限を要求された場合は、`管理者`ユーザーで認証する。

## 検証

- Firefoxを起動する。
- 「ツール」メニューの「ウェブ開発」サブメニューを開く。
- **確認**
"""

TEMPLATE_DEVTOOL_PANEL = """
- パネルメニューの「ウェブ開発」サブメニューを開く。
- **確認**
"""

TEMPLATE_DEVTOOL_SKIPPED = """
# 開発ツールの個別の検証

開発ツール非表示のため、「ツール」メニューの「ウェブ開発」およびサブメニューパネルメニューの「ウェブ開発」サブメニュー配下の以下の項目の非表示化は、検証を省略する。

"""

FILES = [
    'PRETEXT',
    'Install',
    'Application',
    'Admin',
    'Security',
    'Privacy',
    'Startup',
    'Websearch',
    'Location',
    'Download',
    'Tab',
    'Network',
    'Update',
    'Ui',
    'Script',
    'Plugin',
    'External',
    'Stability',
    'Appearance',
    'Performance',
    'Addon-IEView',
    'Addon-FireIE',
    'Addon-Acrobat',
    'Addon-Skysea',
    'MenuShortcut',
]

SPECIALS = [
    'OPTIONS',
    'ABOUT_CONFIG',
    'ABOUT_POLICIES',
]

#
# Utils

def is_deprecated(string):
    return '廃止' in string

def anyof(vars, *args):
    return any(vars[k] for k in args)

def should_skip(vars, dependency):
    """Return True if the verification step should be skipped.

    >>> vars = {'ModifyTime': 1}
    >>> should_skip(vars, 'ModifyTime')
    False
    >>> should_skip(vars, 'ModifySystem')
    False
    >>> should_skip(vars, 'not ModifyTime')
    True
    """
    key  = dependency
    func = lambda x: x

    if key.startswith('not '):
        key = key[4:]
        func = lambda x: not x

    if key not in vars:
        return False

    return not func(vars[key])

def parse_special(text):
    ht = text.split('\n', maxsplit=1)

    if ht[0] in SPECIALS:
        return (ht[0], ht[1])

    return ('', text)

DISABLED_ITEM_KEY_MATCHER = re.compile('(DISABLED_[A-Z_]+):\s+(.+)\Z')

def shift_disabled_item(text):
    ht = text.split('\n', maxsplit=1)

    match = re.match(DISABLED_ITEM_KEY_MATCHER, ht[0])
    if match:
        rest = ''
        if len(ht) > 1:
            rest = ht[1]
        return (match.group(1), match.group(2), rest)

    return ('', '', text)

PRETEXT_OPTION_MATCHER = re.compile('^[^-]+-0-[0-9]+\Z')
LIST_ITEM_MATCHER = re.compile('^(\s*)(- )?(.*[^\\\\])$', re.MULTILINE)
LIST_LINE_MATCHER = re.compile('^(\s*)(- )?(.+)$', re.MULTILINE)

def create_template(manual, config, vars, options):
    items_options               = []
    items_about_config          = []
    items_about_policies        = []
    items_disabled_shortcuts    = []
    items_disabled_devtool_menu = []

    template = vars.get('COVER', '') + '\n'
    template += "# 事前準備"

    for item in manual['PRETEXT']:
        for option in item['options']:
            template += TEMPLATE_PRETEXT.format(**option) + '\n'


    # prepare internal variables

    vars['use_meta_installer'] = vars['use_meta_installer'] == 'true'
    vars['desktop_shortcut'] = vars['desktop_shortcut'] == 'true'
    vars['start_menu_shortcut'] = vars['start_menu_shortcut'] == 'true'
    vars['show_bookmarks_toolbar_on_startup'] = False

    for items in manual.values():
        for item in items[1:]:
            for option in item['options']:
                vars[option['option_id'].replace('-', '_')] = option['option_id'] in config
                vars['not ' + option['option_id'].replace('-', '_')] = option['option_id'] not in config

    vars['DisableDeveloperTools'] = anyof(vars,
        'MenuShortcut_10_1', 'MenuShortcut_11_1', 'MenuShortcut_12_1',
        'MenuShortcut_13_1', 'MenuShortcut_14_1', 'MenuShortcut_15_1',
        'MenuShortcut_16_1', 'MenuShortcut_17_1', 'MenuShortcut_18_1',
        'MenuShortcut_21_1', 'MenuShortcut_22_1', 'MenuShortcut_23_1',
        'MenuShortcut_24_1', 'MenuShortcut_25_1', 'MenuShortcut_26_1',
        'MenuShortcut_28_1', 'MenuShortcut_29_1', 'MenuShortcut_57_1',
        'MenuShortcut_64_1', 'MenuShortcut_65_1')

    vars['not DisableDeveloperTools'] = not vars['DisableDeveloperTools']

    vars['DisableSync'] = anyof(vars, 'Privacy_22_2', 'Privacy_22_3', 'Privacy_24_2', 'Privacy_24_3')
    vars['not DisableSync'] = not vars['DisableSync']
    vars['DisableFirefoxAccount'] = vars['DisableSync']
    vars['not DisableFirefoxAccount'] = not vars['DisableFirefoxAccount']

    vars['OfferToSaveLogins'] = not (vars['Privacy_5_3'] or vars['Privacy_5_4'])
    vars['not OfferToSaveLogins'] = not vars['OfferToSaveLogins']

    vars['UsePACFile'] = vars['Network_2_8']

    missing_any_of_privacy_33 = not any([vars['Privacy_33_1'],
                                         vars['Privacy_33_2'],
                                         vars['Privacy_33_4'],
                                         vars['Privacy_33_5']])
    vars['UseBlockList'] = (not (vars['Security_5_2'] or vars['Security_6_2'] or vars['Privacy_33_5'])) or \
                           missing_any_of_privacy_33

    vars['InstallAddonsPermission'] = vars['Security_3_3'] or vars['Security_3_6'] or vars['Security_3_7']

    vars['DisableSync'] = vars['Privacy_22_2'] or vars['Privacy_22_3']
    vars['not DisableSync'] = not vars['DisableSync']

    vars['NotificationGloballyDisabled'] = vars['Script_2_3'] or vars['Script_2_6']
    vars['not NotificationGloballyDisabled'] = not vars['NotificationGloballyDisabled']

    vars['DisabledSponsoredTopSites'] = vars['Tab_5_5'] or vars['Tab_11_6'] or vars['Tab_21_2']
    vars['not DisabledSponsoredTopSites'] = not vars['DisabledSponsoredTopSites']

    vars['DisabledStatistics'] = vars['Privacy_18_3']
    vars['not DisabledStatistics'] = not vars['DisabledStatistics']

    vars['PromptForDownloadLocation'] = vars['Download_3_4']

    missing_any_of_startup_2 = not any([vars['Startup_2_1'],
                                        vars['Startup_2_4'],
                                        vars['Startup_2_5'],
                                        vars['Startup_2_6']])
    vars['show_bookmarks_toolbar_on_startup'] = (vars['Startup_2_1'] or missing_any_of_startup_2) and vars['Appearance_5_2']

    vars['show_home_button'] = (vars['Startup_2_4'] or vars['Startup_2_5']) or vars['Appearance_12_1']
    if vars['Appearance_12_2']:
        vars['show_home_button'] = False

    chapters                  = {}
    chapter_options           = []
    chapter_about_config      = []
    chapter_about_policies    = []
    chapter_disabled_shortcut = []
    chapter_disabled_devtool  = []

    first_level_chapter = 2
    for items in manual.values():
        tmp = ''

        if len(items) > 0 and re.match(PRETEXT_OPTION_MATCHER, items[0]['options'][0]['option_id']):
            second_level_chapter = 2
        else:
            second_level_chapter = 1

        for item in items[1:]:
            for option in item['options']:
                if option['option_id'] not in config:
                    continue

                if should_skip(vars, option['dependency']):
                    continue

                config_values = config.get(option['option_id'], '')

                option['option_title'] = config_values['option_title']
                option['dependency_description'] = ''

                if is_deprecated(option['option_title']):
                    continue

                if option['dependency'] in vars:
                    if not vars[option['dependency']]:
                        continue
                    option['dependency'] = ''

                sp, text = parse_special(option['config'])
                if sp == 'OPTIONS':
                    items_options.append((option['option_id'], option['dependency'], text))
                    chapter_options.append(option['option_id'])
                    continue
                elif sp == 'ABOUT_CONFIG':
                    items_about_config.append((option['option_id'], option['dependency'], text))
                    chapter_about_config.append(option['option_id'])
                    continue
                elif sp == 'ABOUT_POLICIES':
                    items_about_policies.append((option['option_id'], option['dependency'], text))
                    chapter_about_policies.append(option['option_id'])
                    continue

                while True:
                    key, desc, text = shift_disabled_item(text)
                    if key == '':
                        break
                    elif key == 'DISABLED_SHORTCUT':
                        items_disabled_shortcuts.append((option['option_id'], desc))
                        chapter_disabled_shortcut.append(option['option_id'])
                    elif key == 'DISABLED_DEVTOOL_MENU':
                        items_disabled_devtool_menu.append((option['option_id'], desc))
                        chapter_disabled_devtool.append(option['option_id'])

                if text == '':
                    continue

                option['config'] = text

                if option['dependency'] != '':
                    option['dependency_description'] = '（' + option['dependency'] + '）'

                tmp += TEMPLATE.format(**option, **item) + '\n'
                if not re.match(PRETEXT_OPTION_MATCHER, option['option_id']):
                    capter_id = '%s.%s' % (first_level_chapter, second_level_chapter)
                    if capter_id in chapters:
                        option_ids = chapters[capter_id]
                    else:
                        option_ids = []
                    option_ids.append(option['option_id'])
                    chapters[capter_id] = option_ids

                second_level_chapter += 1

        if not tmp:
            continue  # Nothing to verify

        template += '\n# %s' % items[0]['title']
        for option in items[0]['options']:
            template += TEMPLATE_PRETEXT.format(**option) + '\n'
        template += tmp

        first_level_chapter += 1

    if items_options:
        template += TEMPLATE_OPTIONS
        for option_id, dependency, text in items_options:
            if dependency:
                suffix = ' (%s %s)' % (option_id, dependency)
            else:
                suffix = ' (%s)' % (option_id)
            template += re.sub(LIST_LINE_MATCHER, '\\1    \\2\\3', re.sub(LIST_ITEM_MATCHER, '\\1\\2\\3 %s' % (suffix), text))
            template += '\n'

        chapters['%s' % (first_level_chapter)] = chapter_options
        first_level_chapter += 1

    if items_about_config:
        template += TEMPLATE_ABOUT_CONFIG
        config_list = []
        for option_id, dependency, text in items_about_config:
            if dependency:
                suffix = ' (%s %s)' % (option_id, dependency)
            else:
                suffix = ' (%s)' % (option_id)
            config_list.append(re.sub(LIST_LINE_MATCHER, '\\1    \\2\\3', re.sub(LIST_ITEM_MATCHER, '\\1\\2\\3 %s' % (suffix), text)))
        if options['sort-about-config'] == 'pref':
            config_list.sort()
            template += '\n'.join(config_list)
        elif options['sort-about-config'] == 'option':
            # Align by Install, Application, Admin...
            for key in chapter_about_config:
                for line in config_list:
                    if re.search('\(%s\s?' % key, line):
                        template += '\n'.join(config_list)
        template += TEMPLATE_ABOUT_CONFIG_END
        template += '\n'
        chapters['%s' % (first_level_chapter)] = chapter_about_config
        first_level_chapter += 1

    if items_about_policies:
        template += TEMPLATE_ABOUT_POLICIES
        for option_id, dependency, text in items_about_policies:
            if dependency:
                suffix = ' (%s %s)' % (option_id, dependency)
            else:
                suffix = ' (%s)' % (option_id)
            template += re.sub(LIST_LINE_MATCHER, '\\1    \\2\\3', re.sub(LIST_ITEM_MATCHER, '\\1\\2\\3 %s' % (suffix), text))
            template += '\n'
        chapters['%s' % (first_level_chapter)] = chapter_about_policies
        first_level_chapter += 1

    if items_disabled_shortcuts:
        template += TEMPLATE_SHORTCUT
        for option_id, text in items_disabled_shortcuts:
            template += '    - %s (%s)\n' % (text, option_id)
        chapters['%s' % (first_level_chapter)] = chapter_disabled_shortcut
        first_level_chapter += 1

    if items_disabled_devtool_menu:
        if vars['DisableDeveloperTools']:
            template += TEMPLATE_DEVTOOL_SKIPPED
            for option_id, text in items_disabled_devtool_menu:
                template += '- %s (%s)\n' % (text, option_id)
        else:
            template += TEMPLATE_DEVTOOL_MENU
            for option_id, text in items_disabled_devtool_menu:
                template += '    - %s (%s)\n' % (text, option_id)
            template += TEMPLATE_DEVTOOL_PANEL
            for option_id, text in items_disabled_devtool_menu:
                template += '    - %s (%s)\n' % (text, option_id)

        chapters['%s' % (first_level_chapter)] = chapter_disabled_devtool
        first_level_chapter += 1

    template += "\n" + vars.get('POSTSCRIPT', '')

    urls = extract_urls(template)
    vars['urls'] = "\n".join(list(map(lambda url: ('      - `'  + url + '`'), urls)))
    vars['has_urls'] = len(urls) > 0

    return (template, chapters)

def extract_urls(input):
    all_extracted_urls = re.findall('(?P<url>https?://[^/(\s」`]+(?:[^(^\s`」][^\s`」]*)?)', input)
    wildcard_replaced_urls = list(map(lambda url: re.sub('[~～]$', '*', url), all_extracted_urls))
    sorted_urls = sorted(list(set(wildcard_replaced_urls)))
    shortened_urls = re.sub("(https?://[^\n]+)(\n\\1[^\n]+)+", "\\1*", "\n".join(sorted_urls)).split("\n")
    return shortened_urls

def chapters_to_csv(chapters):
    chapters_by_option_id = {}
    for chapter_id, option_ids in chapters.items():
        for option_id in option_ids:
            if option_id in chapters_by_option_id:
                chapter_ids = chapters_by_option_id[option_id]
            else:
                chapter_ids = []
            if not chapter_id in chapter_ids:
                chapter_ids.append(chapter_id)
                chapters_by_option_id[option_id] = chapter_ids

    csv_source = []
    for option_id, chapter_ids in chapters_by_option_id.items():
        csv_source.append((option_id, "\n".join(chapter_ids)))

    return csv_source

def chapters_to_checklist(chapters):
    rows = []
    rows.append(("見出し番号", "検証対象項目", "検証結果（ok/ng）"))
    for chapter_id, option_ids in chapters.items():
        for option_id in option_ids:
            rows.append(("%s" % chapter_id, option_id, ""))

    return rows

#
# Main

def usage(err):
    print('error: %s' % err, file=sys.stderr)
    print('usage: %s INFILE' % sys.argv[0], file=sys.stderr)
    sys.exit(1)

def main(args):
    config = {}
    vars   = {}
    options = {}
    options['sort-about-config'] = 'pref'

    only_index_output = False
    only_checklist_output = False

    opts, args = getopt.getopt(args, 'c:a:il', ["sort-about-config="])
    for key, value in opts:
        if key == '-c':
            config = adlib.load_as_dict(value)
        elif key == '-a':
            vars = adlib.load_variables(value)
        elif key == '-i':
            only_index_output = True
        elif key == '-l':
            only_checklist_output = True
        elif key == '--sort-about-config' and value in ['pref', 'option']:
            # type of sort: pref or option
            options['sort-about-config'] = value

    vars = {**DEFAULT_VAR, **vars}
    manual = collections.OrderedDict()
    for fn in FILES:
        manual[fn] = adlib.load('verify/%s' % fn)

    # Check whether option id is belonged to pre-defined category
    invalid_option_id_count = 0
    for option_id in config.keys():
        found = False
        for category in FILES:
            if category in option_id:
                found = True
        if not found:
            invalid_option_id_count += 1
            print("%s must be invalid option id, check category of %s: %s" %
                  (option_id, option_id, config[option_id]['option_title']), file=sys.stderr)
    if invalid_option_id_count > 0:
        exit(1)

    template, chapters = create_template(manual, config, vars, options)

    if only_index_output:
        # Generate a mapping file of (option_id -> chapter) for
        # configuration sheets (see build-xlsx).
        csv_writer = csv.writer(sys.stdout)
        csv_writer.writerows(chapters_to_csv(chapters))
    elif only_checklist_output:
        # Generate a checklist for humans.
        csv_writer = csv.writer(sys.stdout,  quotechar='"', quoting=csv.QUOTE_ALL)
        csv_writer.writerows(chapters_to_checklist(chapters))
    else:
        # Generate a verification manual (default)
        logging.basicConfig(format="\033[31m%(message)s\033[0m")
        log = logging.getLogger(__name__)
        env = jinja2.Environment(undefined=jinja2.make_logging_undefined(log))
        print(env.from_string(template).render(vars))

if __name__ == '__main__':
    sys.exit(main(sys.argv[1:]))