#!/usr/bin/env python3 # SPDX-FileCopyrightText: Copyright Eric S. Raymond # SPDX-License-Identifier: BSD-2-Clause """ This is the open-adventure dungeon text coverage report generator. It consumes a YAML description of the dungeon and determines whether the various strings contained are present within the test check files. The default HTML output is appropriate for use with Gitlab CI. You can override it with a command-line argument. The DANGLING lists are for actions and messages that should be considered always found even if the checkfile search doesn't find them. Typically this will because an action emit a templated message that can't be regression-tested by equality. """ # pylint: disable=consider-using-f-string,line-too-long,invalid-name,missing-function-docstring,redefined-outer-name import os import sys import re import yaml TEST_DIR = "." YAML_PATH = "../adventure.yaml" HTML_TEMPLATE_PATH = "../templates/coverage_dungeon.html.tpl" DEFAULT_HTML_OUTPUT_PATH = "../coverage/adventure.yaml.html" DANGLING_ACTIONS = ["ACT_VERSION"] DANGLING_MESSAGES = ["SAVERESUME_DISABLED"] STDOUT_REPORT_CATEGORY = ( " {name:.<19}: {percent:5.1f}% covered ({covered} of {total})\n" ) HTML_SUMMARY_ROW = """ {name}: {total} {covered} {percent:.1f}% """ HTML_CATEGORY_SECTION = """ {rows}   """ HTML_CATEGORY_HEADER = """ {label} {cells} """ HTML_CATEGORY_HEADER_CELL = '{}\n' HTML_CATEGORY_COVERAGE_CELL = ' \n' HTML_CATEGORY_ROW = """ {id} {cells} """ def search(needle, haystack): # Search for needle in haystack, first escaping needle for regex, then # replacing %s, %d, etc. with regex wildcards, so the variable messages # within the dungeon definition will actually match if needle is None or needle == "" or needle == "NO_MESSAGE": # if needle is empty, assume we're going to find an empty string return True needle_san = ( re.escape(needle) .replace("\\n", "\n") .replace("\\t", "\t") .replace("%S", ".*") .replace("%s", ".*") .replace("%d", ".*") .replace("%V", ".*") ) return re.search(needle_san, haystack) def obj_coverage(objects, text, report): # objects have multiple descriptions based on state for _, objouter in enumerate(objects): (obj_name, obj) = objouter if obj["descriptions"]: for j, desc in enumerate(obj["descriptions"]): name = "{}[{}]".format(obj_name, j) if name not in report["messages"]: report["messages"][name] = {"covered": False} report["total"] += 1 if not report["messages"][name]["covered"] and search(desc, text): report["messages"][name]["covered"] = True report["covered"] += 1 def loc_coverage(locations, text, report): # locations have a long and a short description, that each have to # be checked separately for name, loc in locations: desc = loc["description"] if name not in report["messages"]: report["messages"][name] = {"long": False, "short": False} report["total"] += 2 if not report["messages"][name]["long"] and search(desc["long"], text): report["messages"][name]["long"] = True report["covered"] += 1 if not report["messages"][name]["short"] and search(desc["short"], text): report["messages"][name]["short"] = True report["covered"] += 1 def hint_coverage(obituaries, text, report): # hints have a "question" where the hint is offered, followed # by the actual hint if the player requests it for _, hintouter in enumerate(obituaries): hint = hintouter["hint"] name = hint["name"] if name not in report["messages"]: report["messages"][name] = {"question": False, "hint": False} report["total"] += 2 if not report["messages"][name]["question"] and search(hint["question"], text): report["messages"][name]["question"] = True report["covered"] += 1 if not report["messages"][name]["hint"] and search(hint["hint"], text): report["messages"][name]["hint"] = True report["covered"] += 1 def obit_coverage(obituaries, text, report): # obituaries have a "query" where it asks the player for a resurrection, # followed by a snarky comment if the player says yes for name, obit in enumerate(obituaries): if name not in report["messages"]: report["messages"][name] = {"query": False, "yes_response": False} report["total"] += 2 if not report["messages"][name]["query"] and search(obit["query"], text): report["messages"][name]["query"] = True report["covered"] += 1 if not report["messages"][name]["yes_response"] and search( obit["yes_response"], text ): report["messages"][name]["yes_response"] = True report["covered"] += 1 def threshold_coverage(classes, text, report): # works for class thresholds and turn threshold, which have a "message" # property for name, item in enumerate(classes): if name not in report["messages"]: report["messages"][name] = {"covered": False} report["total"] += 1 if not report["messages"][name]["covered"] and search(item["message"], text): report["messages"][name]["covered"] = True report["covered"] += 1 def arb_coverage(arb_msgs, text, report): for name, message in arb_msgs: if name not in report["messages"]: report["messages"][name] = {"covered": False} report["total"] += 1 if not report["messages"][name]["covered"] and ( search(message, text) or name in DANGLING_MESSAGES ): report["messages"][name]["covered"] = True report["covered"] += 1 def actions_coverage(items, text, report): # works for actions for name, item in items: if name not in report["messages"]: report["messages"][name] = {"covered": False} report["total"] += 1 if not report["messages"][name]["covered"] and ( search(item["message"], text) or name in DANGLING_ACTIONS ): report["messages"][name]["covered"] = True report["covered"] += 1 def coverage_report(db, check_file_contents): # Create report for each category, including total items, number of items # covered, and a list of the covered messages report = {} for name in db.keys(): # initialize each catagory report[name] = { "name": name, # convenience for string formatting "total": 0, "covered": 0, "messages": {}, } # search for each message in every test check file for chk in check_file_contents: arb_coverage(db["arbitrary_messages"], chk, report["arbitrary_messages"]) hint_coverage(db["hints"], chk, report["hints"]) loc_coverage(db["locations"], chk, report["locations"]) obit_coverage(db["obituaries"], chk, report["obituaries"]) obj_coverage(db["objects"], chk, report["objects"]) actions_coverage(db["actions"], chk, report["actions"]) threshold_coverage(db["classes"], chk, report["classes"]) threshold_coverage(db["turn_thresholds"], chk, report["turn_thresholds"]) return report if __name__ == "__main__": # load DB try: with open(YAML_PATH, "r", encoding="ascii", errors="surrogateescape") as f: db = yaml.safe_load(f) except IOError as e: print("ERROR: could not load %s (%s)" % (YAML_PATH, e.strerror)) sys.exit(-1) # get contents of all the check files check_file_contents = [] for filename in os.listdir(TEST_DIR): if filename.endswith(".chk"): with open(filename, "r", encoding="ascii", errors="surrogateescape") as f: check_file_contents.append(f.read()) # run coverage analysis report on dungeon database report = coverage_report(db, check_file_contents) # render report output categories_html = "" summary_html = "" summary_stdout = "adventure.yaml coverage rate:\n" for name, category in sorted(report.items()): # ignore categories with zero entries if category["total"] > 0: # Calculate percent coverage category["percent"] = (category["covered"] / float(category["total"])) * 100 # render section header cat_messages = list(category["messages"].items()) cat_keys = cat_messages[0][1].keys() headers_html = "" colspan = 10 - len(cat_keys) for key in cat_keys: headers_html += HTML_CATEGORY_HEADER_CELL.format(key) category_html = HTML_CATEGORY_HEADER.format( colspan=colspan, label=category["name"], cells=headers_html ) # render message coverage row for message_id, covered in cat_messages: category_html_row = "" for key, value in covered.items(): category_html_row += HTML_CATEGORY_COVERAGE_CELL.format( "uncovered" if not value else "covered" ) category_html += HTML_CATEGORY_ROW.format( id=message_id, colspan=colspan, cells=category_html_row ) categories_html += HTML_CATEGORY_SECTION.format(id=name, rows=category_html) # render category summaries summary_stdout += STDOUT_REPORT_CATEGORY.format(**category) summary_html += HTML_SUMMARY_ROW.format(**category) # output some quick report stats print(summary_stdout) if len(sys.argv) > 1: html_output_path = sys.argv[1] else: html_output_path = DEFAULT_HTML_OUTPUT_PATH # render HTML report try: with open( HTML_TEMPLATE_PATH, "r", encoding="ascii", errors="surrogateescape" ) as f: # read in HTML template html_template = f.read() except IOError as e: print("ERROR: reading HTML report template failed ({})".format(e.strerror)) sys.exit(-1) # parse template with report and write it out try: with open( html_output_path, "w", encoding="ascii", errors="surrogateescape" ) as f: f.write( html_template.format(categories=categories_html, summary=summary_html) ) except IOError as e: print("ERROR: writing HTML report failed ({})".format(e.strerror))