# -*- coding: utf8 -*-
########################################################################################
# This file is part of exhale.  Copyright (c) 2017-2024, Stephen McDowell.             #
# Full BSD 3-Clause license available here:                                            #
#                                                                                      #
#                https://github.com/svenevs/exhale/blob/master/LICENSE                 #
########################################################################################
"""
Defines the core sphinx project based test case utilities.

All project based test cases should inherit from :class:`testing.base.ExhaleTestCase`.
"""

from __future__ import unicode_literals
import os
import platform
import re
import shutil
import textwrap
import unittest
from importlib import import_module

import exhale
import pytest
import six
from six import add_metaclass
import sphinx
if sphinx.version_info < (7, 0):
    from sphinx.testing.path import path
else:
    from pathlib import Path as path

from . import TEST_PROJECTS_ROOT, get_exhale_root
from .decorators import default_confoverrides


def make_default_config(project):
    """
    Return a default configuration for exhale.

    **Parameters**
        ``project`` (str)
            The name of the project that will be searched for in
            ``testing/projects/{project}``.

    **Return**
        ``dict``
            The global default testing configuration to supply to ``confoverrides``
            with ``@pytest.mark.sphinx``, these are values that would ordinarily be
            written in a ``conf.py``.
    """
    return {
        "breathe_projects": {
            project: "./_doxygen/xml"
        },
        "breathe_default_project": project,
        "exhale_args": {
            # required arguments
            "containmentFolder": "./api",
            "rootFileName": "{0}_root.rst".format(project),
            "rootFileTitle": "``{0}`` Test Project".format(project),
            "doxygenStripFromPath": "..",
            # additional arguments
            "exhaleExecutesDoxygen": True,
            "exhaleDoxygenStdin": "INPUT = ../include"
        }
    }


class ExhaleTestCaseMetaclass(type):
    """
    Metaclass to enforce mandatory attributes on :class:`testing.base.ExhaleTestCase`.
    """

    def __new__(mcs, name, bases, attrs):  # noqa: N804
        """
        Return a new instance with the specified attributes.

        **Parameters**
            ``mcs`` (:class:`python:type`)
                This metaclass (:class:`testing.base.ExhaleTestCaseMetaclass`).

            ``name`` (:class:`python:str`)
                The name of the class being instantiated.

            ``bases`` (:class:`python:list`)
                The list of base classes of ``name``.

            ``attrs`` (:class:`python:dict`)
                The class-level attributes.  These will be inspected / modified as
                needed to produce a final class definition that can use sphinx test
                applications where desired.
        """
        if attrs["__module__"] == __name__:
            # we skip everything if we're creating ExhaleTestCase below
            return super(ExhaleTestCaseMetaclass, mcs).__new__(mcs, name, bases, attrs)

        # Make sure `test_project` is defined in all derived classes.
        test_project = attrs.get("test_project", None)
        if test_project is None:
            # otherwise we need a ``test_project`` attribute
            raise RuntimeError(
                "ExhaleTestCase subclasses must define a 'test_project' attribute"
            )
        if not isinstance(test_project, six.string_types):
            raise RuntimeError(
                "'test_project' in class {0} must be a string!".format(name)
            )

        # looking for test methods ("test_*")
        has_tests = False
        for n, attr in attrs.items():
            if callable(attr) and n.startswith("test_"):
                has_tests = True
                break

        # if there are tests, we set the app attribute using the
        # ``sphinx.testing.fixtures.app`` fixture
        if has_tests:
            ############################################################################
            # Make the sphinx test application available as `self.app`.                #
            ############################################################################
            def _set_app(self, app):
                # before the test
                self.app = app
                yield  # the test runs
                # @no_cleanup sets self.testroot to [self.testroot] as a flag that
                # cleanup should not transpire
                if isinstance(self.testroot, six.string_types):
                    # This cleanup happens between each test case, do not delete docs/
                    # until all tests for this class are done!
                    containmentFolder = self.getAbsContainmentFolder()
                    if os.path.isdir(containmentFolder):
                        shutil.rmtree(containmentFolder)
                    # Delete the doctrees as well as e.g. _build/html, app.outdir is going
                    # to be docs/_build/{builder_name}
                    _build = os.path.abspath(os.path.dirname(app.outdir))
                    if os.path.isdir(_build):
                        shutil.rmtree(_build)
                    # Make sure doxygen output is deleted between runs
                    doxy_xml_dir = app.config.breathe_projects[test_project]
                    if not os.path.isabs(doxy_xml_dir):
                        doxy_xml_dir = os.path.abspath(os.path.join(
                            self.app.srcdir, doxy_xml_dir
                        ))
                    doxy_dir = os.path.dirname(doxy_xml_dir)
                    if os.path.isdir(doxy_dir):
                        shutil.rmtree(doxy_dir)
                self.app = None

            ############################################################################
            # Automatically create docs_Class_test/{conf.py,index.rst} for this test.  #
            ############################################################################
            def _rootdir(self, app_params):
                # Create the test project's 'docs' dir with a conf.py and index.rst.

                # the root directory name is generated from the test name
                testroot = os.path.join(
                    TEST_PROJECTS_ROOT,
                    self.test_project,
                    "docs_{0}_{1}".format(self.__class__.__name__, self._testMethodName)
                )
                if os.path.isdir(testroot):
                    shutil.rmtree(testroot)
                os.makedirs(testroot)

                # Make the testing root available for this test case for when separate
                # source / build directories are used (in this case, self.app.srcdir
                # is a subdirectory of testroot).
                self.testroot = testroot

                # set the 'testroot' kwarg so that sphinx knows about it
                app_params.kwargs["srcdir"] = path(testroot)

                # Sphinx demands a `conf.py` is present
                with open(os.path.join(testroot, "conf.py"), "w") as conf_py:
                    conf_py.write(textwrap.dedent('''\
                        # -*- coding: utf-8 -*-
                        project = "{test_project}"
                        extensions = ["breathe", "exhale"]
                        master_doc = "index"
                        source_suffix = [".rst"]
                    ''').format(
                        test_project=test_project
                    ))
                    # Absurd test cases may need an increased recursion limit for Sphinx
                    if self.test_project in ["cpp_long_names"]:
                        conf_py.write(textwrap.dedent('''
                            import sys
                            sys.setrecursionlimit(2000)
                        '''))

                # If a given test case needs to run app.build(), make sure index.rst
                # is available as well
                with open(os.path.join(testroot, "index.rst"), "w") as index_rst:
                    index_rst.write(textwrap.dedent('''
                        Exhale Test Case
                        ================
                        .. toctree::
                           :maxdepth: 2

                           {containmentFolder}/{rootFileName}
                    ''').format(
                        # containmentFolder and rootFileName are always in exhale_args
                        **app_params.kwargs["confoverrides"]["exhale_args"])
                    )

                # run the test in testroot
                yield testroot

                # perform cleanup by deleting the docs dir
                # @no_cleanup sets self.testroot to [self.testroot] as a flag that
                # cleanup should not transpire
                if isinstance(self.testroot, six.string_types) and os.path.isdir(self.testroot):
                    shutil.rmtree(self.testroot)

                self.testroot = None

            # Create the class-level fixture for creating / deleting the docs/ dir
            attrs["_rootdir"] = pytest.fixture(autouse=True)(_rootdir)
            attrs["_set_app"] = pytest.fixture(autouse=True)(_set_app)

            # Create a default test that will validate some common tests
            def test_common(self):
                marks  = getattr(self, "pytestmark", False)
                no_run = marks and any('no_run' in m.args for m in marks)
                if not no_run:
                    self.checkRequiredConfigs()
                    self.checkAllFilesGenerated()
                    self.checkAllFilesIncluded()

            attrs["test_common"] = test_common

            # Import the default hierarchy dictionaries from the testing/projects folder
            # and make it available to the class directly.
            proj_mod = import_module(
                "testing.projects.{test_project}".format(test_project=test_project))

            default_class_hierarchy_dict = proj_mod.default_class_hierarchy_dict

            def class_hierarchy_wrapper(self):
                return default_class_hierarchy_dict()
            attrs["class_hierarchy_dict"] = class_hierarchy_wrapper

            default_file_hierarchy_dict = proj_mod.default_file_hierarchy_dict

            def file_hierarchy_wrapper(self):
                return default_file_hierarchy_dict()
            attrs["file_hierarchy_dict"] = file_hierarchy_wrapper

            attrs["test_project_module"] = proj_mod  # In case it's ever needed...

        # applying the default configuration override, which is overridden using the
        # @confoverride decorator at class or method level
        return default_confoverrides(
            super(ExhaleTestCaseMetaclass, mcs).__new__(mcs, name, bases, attrs),
            make_default_config(attrs["test_project"])
        )


@add_metaclass(ExhaleTestCaseMetaclass)
class ExhaleTestCase(unittest.TestCase):
    """
    The primary project based test class to inherit from.

    The ``__metaclass__`` is set to :class:`testing.base.ExhaleTestCaseMetaclass`.
    Inherits from :class:`python:unittest.TestCase`.

    **Attributes Populated by the Metaclass Fixtures for Each Test**
        These attributes are populated during the setup of a test function, and then
        later set to ``None`` during the test function teardown.  These are **only**
        available inside the method body of a testing function (a function with a name
        starting with ``test_``).

        ``self.app`` (``sphinx.testing.util.SphinxTestApp``)
            The sphinx testing application.  Acquire the ``conf.py`` values (and
            corresponding ``@confoverrides``) via ``self.app.config`` like any
            traditional sphinx application.

        ``self.testroot`` (:class:`python:str`)
            The ``testroot`` supplied to ``pytest.mark.sphinx``, the "docs" directory.
            Its value will be
            ``testing/projects/{test_project}/docs_{ClassName}_{test_function_name}``.

            .. todo::

               This value is saved in order to be able to distinguish when a "separate
               source and build" directory is being tested.  At this time this is not
               fully implemented, ``self.app.srcdir`` should be a subdirectory of
               ``self.testroot`` and ``conf.py`` / ``index.rst`` should be generated
               there.

               Currently, these are always generated in ``testroot``, implying that
               there is no "separate source and build" directory structure.  Solution
               requires further investigation of the sphinx testing suite.

        .. danger::

           As a consequence, running tests in parallel is not and never will be
           supported (e.g., when running ``tox -e py``).
    """

    test_project = None
    """
    The string representing the project to run Doxygen / exhale on.

    This variable is used to index into ``testing/projects/{test_project}``.  For
    example, with ``test_project = "c_maths"``, the directory used is
    ``testing/projects/c_maths``.  That is, this variable is joined with the path
    defined by :data:`testing.TEST_PROJECTS_ROOT`.

    **This class-level string variable must be set in subclasses**.
    """

    def cross_validate(self, contents, required=None, forbidden=None):
        """
        Validate *all* ``required`` and *no* ``forbidden`` items found in ``contents``.

        For each item in ``required`` an assertion of ``item in contents`` is made, and
        for each item in ``forbidden`` an assertion of ``item not in contents`` is made.

        If neither ``required`` nor ``forbidden`` are supplied, no checks are performed.

        **Parameters**

        ``contents`` (:class:`python:str` or Iterable)
            The contents to cross validate that all required items and no forbidden
            items are found in.

        ``required`` (:data:`python:None` or Iterable)
            The listing of all required entries that are required to be in ``contents``.

        ``forbidden`` (:data:`python:None` or Iterable)
            The listing of all forbidden entries that are not allowed in ``contents``.
        """
        if required:
            for item in required:
                self.assertTrue(
                    item in contents,
                    "Required entry [{item}] not found in:\n{contents}".format(
                        item=item, contents=contents
                    )
                )
        if forbidden:
            for item in forbidden:
                self.assertTrue(
                    item not in contents,
                    "Forbidden entry [{item}] found in:\n{contents}".format(
                        item=item, contents=contents
                    )
                )

    def contents_for_node(self, node):
        """
        Return the generated file contents for the specified ``node``.

        **Parameters**

        ``node`` (:class:`exhale.graph.ExhaleNode`)
            The node whose generated file contents are desired.  Note that this must be
            a proper :class:`~exhale.graph.ExhaleNode` instance, since
            ``node.file_name`` is what is used.  That is, a mocked testing node should
            not be used!

        **Return** (:class:`python:str`)
            The contents of ``node.file_name``.

        **Raises**
            If ``os.path.join(self.getAbsContainmentFolder(), node.file_name)`` does
            not exist.
        """
        node_path = os.path.join(self.getAbsContainmentFolder(), node.file_name)
        with open(node_path) as f:
            return f.read()

    def getAbsContainmentFolder(self):
        r"""
        Return the absolute path to ``"containmentFolder"``.

        If ``exhale_args["containmentFolder"]`` is an absolute path, it will be returned
        unchanged.  Otherwise, it will be resolved against ``app.srcdir``.

        **Return**
            ``str``
                An absolute path to the ``"containmentFolder"`` where Exhale will be
                generating its reStructuredText documents.

                .. note::

                    When ``platform.system() == "Windows"``, this string will **always**
                    be prefixed with ``\\?\`` to deal with maximum path length issues.
                    This is to accommodate the somewhat long containment folders
                    generated by using the testing class name as well as the test name.
                    See :data:`~exhale.configs.MAXIMUM_WINDOWS_PATH_LENGTH` for more
                    information.

                    If this is not done, then even if ``self.app.build()`` is skipped
                    for the test cases that cause this (in
                    :class:`~testing.tests.cpp_long_names.CPPLongNames`),
                    :func:`python:shutil.rmtree` will crash during test teardown.
                    Better to just always include it.
        """
        containmentFolder = self.app.config.exhale_args["containmentFolder"]
        if not os.path.isabs(containmentFolder):
            containmentFolder = os.path.abspath(os.path.join(
                self.app.srcdir, containmentFolder
            ))

        # Guarantee Windows can cope with this path.
        if platform.system() == "Windows":
            # NOTE: containmentFolder is *ALREADY* an absolute path, this prefix
            #       requires absolute paths!  See documentation for
            #       configs.MAXIMUM_WINDOWS_PATH_LENGTH.
            containmentFolder = "{magic}{containmentFolder}".format(
                magic="{slash}{slash}?{slash}".format(slash="\\"),  # \\?\ I HATE YOU WINDOWS
                containmentFolder=containmentFolder
            )

        return containmentFolder

    def checkRequiredConfigs(self):
        """
        Validate the four required configuration arguments in ``exhale_args``.

        1. Checks that ``{containmentFolder}`` was created.
        2. Checks that ``{containmentFolder}/{rootFileName}`` was created.
        3. Checks that ``{rootFileTitle}`` is found in
           ``{containmentFolder}/{rootFileName}``.

        .. todo::

           4. identify via a ``file_*`` method that ``{doxygenStripFromPath}``
              was correctly removed / wielded.

        .. autotested::
        """
        containmentFolder    = self.getAbsContainmentFolder()
        rootFileName         = self.app.config.exhale_args["rootFileName"]
        rootFileTitle        = self.app.config.exhale_args["rootFileTitle"]
        doxygenStripFromPath = self.app.config.exhale_args["doxygenStripFromPath"]

        # validate that the containmentFolder was created
        assert os.path.isdir(containmentFolder)
        # validate that {containmentFolder}/{rootFileName} was created
        assert os.path.isfile(os.path.join(containmentFolder, rootFileName))
        # validate that the title was included
        with open(os.path.join(containmentFolder, rootFileName), "r") as root:
            root_contents = root.read()
        root_heading = "{0}\n{1}".format(
            rootFileTitle,
            exhale.utils.heading_mark(rootFileTitle, exhale.configs.SECTION_HEADING_CHAR)
        )
        assert root_heading in root_contents

        # TODO: validate doxygenStripFromPath
        if doxygenStripFromPath:  # this is only here to avoid a flake8 fail on a todo
            pass

    def checkAllFilesGenerated(self):
        """
        Validate that all files are actually generated.

        .. autotested::
        """
        root = get_exhale_root(self)
        containmentFolder = self.getAbsContainmentFolder()
        for node in root.all_nodes:
            if node.kind in ["enumvalue", "group"]:
                continue
            gen_file_path = os.path.join(containmentFolder, node.file_name)
            self.assertTrue(
                os.path.isfile(gen_file_path),
                "File for {kind} node with refid=[{refid}] not generated to [{gen_file_path}]!".format(
                    kind=node.kind, refid=node.refid, gen_file_path=gen_file_path
                )
            )

    def checkAllFilesIncluded(self):
        """
        Validate that all files are actually included in the library root.

        .. autotested::
        """
        # TODO: config objects: this import can go away
        from exhale.configs import unabridgedOrphanKinds

        # build path to unabridged api document that adds all toctree directives
        root = get_exhale_root(self)
        containmentFolder = self.getAbsContainmentFolder()
        unabridged_api_path = os.path.join(containmentFolder, "unabridged_api.rst.include")
        unabridged_orphan_path = os.path.join(containmentFolder, "unabridged_orphan.rst")

        # gather lines that match the indented part of the toctree
        #
        # .. toctree::
        #    :maxdepth: {toctreeMaxDepth}
        #
        #    some_node.file_name.rst
        #
        # so just lazily look for the leading three spaces and ending with .rst
        full_api_toctrees = []
        under_toctree_re = re.compile(r"^   .+\.rst$")
        with open(unabridged_api_path) as unabridged_api:
            for line in unabridged_api:
                if under_toctree_re.match(line):
                    full_api_toctrees.append(line.strip())

        orphan_toctrees = []
        if os.path.isfile(unabridged_orphan_path):
            with open(unabridged_orphan_path) as unabridged_orphan:
                for line in unabridged_orphan:
                    if under_toctree_re.match(line):
                        orphan_toctrees.append(line.strip())

        # Scan all nodes and make sure they were found in the toctrees above.
        doxygen_mainpage_was_used = False
        for node in root.all_nodes:
            if node.kind in {"enumvalue", "group"}:
                continue

            # When doxygen \mainpage command is used, the .. doxygenpage:: index
            # is .. include::'ed in the root file document.  Those checks come
            # after this loop.
            if node.kind == "page" and node.refid == "indexpage":
                doxygen_mainpage_was_used = True
                continue

            if node.kind in unabridgedOrphanKinds or \
                    (node.kind == "class" and "struct" in unabridgedOrphanKinds) or \
                    (node.kind == "struct" and "class" in unabridgedOrphanKinds):
                toctrees = orphan_toctrees
                doc = unabridged_orphan_path
            else:
                toctrees = full_api_toctrees
                doc = unabridged_api_path

            self.assertTrue(
                node.file_name in toctrees,
                "Node refid=[{refid}] and basename=[{file_name}] not found in [{doc}]!".format(
                    refid=node.refid, file_name=node.file_name, doc=doc
                )
            )

        # Make sure every document expected to be .. include::'ed in the library root
        # has actually been included.
        full_root_file_path = root.full_root_file_path
        root_file_includes = []
        with open(full_root_file_path, "r") as full_root_f:
            for line in full_root_f:
                include_mark = ".. include::"
                if line.startswith(include_mark):
                    root_file_includes.append(line.split(include_mark)[-1].strip())

        index_include = False  # page_index.rst comes from doxygen \mainpage
        page_hierarchy_include = False  # page_view_hierarchy.rst
        class_hierarchy_include = False  # class_view_hierarchy.rst
        file_hierarchy_include = False  # file_view_hierarchy.rst
        unabridged_api_include = True  # unabridged_api.rst.  Always included.
        orphan_api_include = False  # unabridged_orphan.rst.  Never included.
        for node in root.all_nodes:
            if node.kind == "page":
                if node.refid == "indexpage":
                    index_include = True
                else:
                    page_hierarchy_include = True
            elif node.kind in exhale.utils.CLASS_LIKE_KINDS:
                class_hierarchy_include = True
            elif node.kind in {"dir", "file"}:
                file_hierarchy_include = True

        self.assertTrue(
            doxygen_mainpage_was_used == index_include,
            "Mismatch: doxygen_mainpage_was_used != index_include!")

        include_map = {
            "page_index.rst.include": index_include,
            os.path.basename(root.page_hierarchy_file): page_hierarchy_include,
            os.path.basename(root.class_hierarchy_file): class_hierarchy_include,
            os.path.basename(root.file_hierarchy_file): file_hierarchy_include,
            os.path.basename(root.unabridged_api_file): unabridged_api_include,
            os.path.basename(root.unabridged_orphan_file): orphan_api_include
        }
        root_file_base = os.path.basename(full_root_file_path)
        for key, val in include_map.items():
            if val:
                check = getattr(self, "assertTrue")
                msg = "*WAS* expected in {root_file_base}, but was *NOT* found!".format(
                    root_file_base=root_file_base
                )
            else:
                check = getattr(self, "assertFalse")
                msg = "was *NOT* expected in {root_file_base}, but *WAS* found!".format(
                    root_file_base=root_file_base
                )
            check(
                key in root_file_includes,
                "Page '{key}' {msg}".format(key=key, msg=msg))

        # Some tests may want the toctree names afterward.
        return full_api_toctrees, orphan_toctrees