"""

@relation(SDOC-SRS-28, SDOC-SRS-2, scope=file)

"""

import datetime

import glob

import os

import posixpath

import sys

from typing import Any, Dict, Iterator, List, Optional, Set, Union

from textx import TextXSyntaxError

from strictdoc.backend.markdown.reader import SDMarkdownReader

from strictdoc.backend.sdoc.constants import SDocMarkup

from strictdoc.backend.sdoc.error_handling import StrictDocSemanticError

from strictdoc.backend.sdoc.models.anchor import Anchor

from strictdoc.backend.sdoc.models.document import SDocDocument

from strictdoc.backend.sdoc.models.document_from_file import DocumentFromFile

from strictdoc.backend.sdoc.models.document_grammar import DocumentGrammar

from strictdoc.backend.sdoc.models.grammar_element import (

    GrammarElement,

    ReferenceType,

)

from strictdoc.backend.sdoc.models.inline_link import InlineLink

from strictdoc.backend.sdoc.models.model import (

    SDocDocumentFromFileIF,

    SDocElementIF,

    SDocNodeIF,

)

from strictdoc.backend.sdoc.models.node import SDocNode

from strictdoc.backend.sdoc.models.reference import (

    ChildReqReference,

    ParentReqReference,

)

from strictdoc.backend.sdoc.node_filter import NodeFilter

from strictdoc.backend.sdoc.validations.sdoc_validator import SDocValidator

from strictdoc.backend.sdoc_source_code.caching_reader import (

    SourceFileTraceabilityCachingReader,

)

from strictdoc.core.constants import GraphLinkType

from strictdoc.core.document_iterator import SDocDocumentIterator

from strictdoc.core.document_tree import DocumentTree

from strictdoc.core.file_dependency_manager import FileDependencyManager

from strictdoc.core.file_system.document_finder import DocumentFinder

from strictdoc.core.file_system.source_files_finder import (

    SourceFilesFinder,

)

from strictdoc.core.file_system.source_tree import SourceFile, SourceTree

from strictdoc.core.file_traceability_index import FileTraceabilityIndex

from strictdoc.core.graph.many_to_many_set import ManyToManySet

from strictdoc.core.graph.one_to_one_dictionary import OneToOneDictionary

from strictdoc.core.graph_database import GraphDatabase

from strictdoc.core.project_config import (

    ProjectConfig,

    ProjectFeature,

    SourceNodesEntry,

)

from strictdoc.core.query_engine.query_object import (

    QueryNullObject,

    QueryObject,

)

from strictdoc.core.query_engine.query_reader import QueryReader

from strictdoc.core.traceability_index import (

    TraceabilityIndex,

)

from strictdoc.core.tree_cycle_detector import TreeCycleDetector

from strictdoc.helpers.cast import assert_cast

from strictdoc.helpers.deprecation_engine import DEPRECATION_ENGINE

from strictdoc.helpers.exception import StrictDocException

from strictdoc.helpers.file_modification_time import (

    get_file_modification_time,

)

from strictdoc.helpers.mid import MID

from strictdoc.helpers.parallelizer import Parallelizer

from strictdoc.helpers.timing import measure_performance, timing_decorator

class TraceabilityIndexBuilder:

    @classmethod

    def create(

        cls,

        *,

        project_config: ProjectConfig,

        parallelizer: Parallelizer,

        skip_source_files: bool = False,

    ) -> TraceabilityIndex:

        # TODO: It would be great to hide this code behind --development flag.

        # There is no need for this to be activated in the Pip-released builds.

        strict_own_files_unfiltered: Iterator[str] = glob.iglob(

            f"{project_config.get_strictdoc_root_path()}/strictdoc/**/*",

            recursive=True,

        )

        strict_own_files: List[str] = [

            f

            for f in strict_own_files_unfiltered

            if f.endswith(".html")

            or f.endswith(".py")

            or f.endswith(".jinja")

            or f.endswith(".svg")

        ]

        latest_strictdoc_own_file = (

            max(strict_own_files, key=os.path.getctime)

            if len(strict_own_files) > 0

            else None

        )

        strictdoc_last_update: datetime.datetime = (

            get_file_modification_time(latest_strictdoc_own_file)

            if (latest_strictdoc_own_file is not None)

            else datetime.datetime.fromtimestamp(0)

        )

        if (

            project_config.config_last_update is not None

            and project_config.config_last_update > strictdoc_last_update

        ):

            strictdoc_last_update = project_config.config_last_update

        document_tree, asset_manager = DocumentFinder.find_sdoc_content(

            project_config=project_config, parallelizer=parallelizer

        )

        # TODO: This is rather messy, but it is better than it used to be.

        # Currently, the traceability index holds everything that is later used

        # by HTML generators:

        # - traceability index itself

        # - document tree

        # - assets

        # - runtime configuration.

        traceability_index: TraceabilityIndex = (

            TraceabilityIndexBuilder.create_from_document_tree(

                document_tree,

                project_config,

            )

        )

        traceability_index.asset_manager = asset_manager

        traceability_index.strictdoc_last_update = strictdoc_last_update

        if node_filter_query := project_config.filter_nodes:

            traceability_index.node_filter = cls._create_filter(

                traceability_index=traceability_index,

                filter_query=node_filter_query,

            )

        #

        # File traceability-related calculations.

        #

        if not skip_source_files and project_config.is_feature_activated(

            ProjectFeature.REQUIREMENT_TO_SOURCE_TRACEABILITY

        ):

            file_tracability_index = (

                traceability_index.get_file_traceability_index()

            )

            with measure_performance("Find source files"):

                source_tree: SourceTree = SourceFilesFinder.find_source_files(

                    project_config=project_config

                )

            source_files = source_tree.source_files

            source_file: SourceFile

            for source_file in source_files:

                with measure_performance(

                    f"Reading source: {source_file.in_doctree_source_file_rel_path}"

                ):

                    source_nodes_cfg_entry = (

                        project_config.get_relevant_source_nodes_entry(

                            source_file.full_path

                        )

                    )

                    if source_nodes_cfg_entry is not None:

                        source_node_grammar_element = (

                            traceability_index.get_grammar_element(

                                source_nodes_cfg_entry.uid,

                                source_nodes_cfg_entry.node_type,

                            )

                        )

                        assert source_node_grammar_element is not None, (

                            "Missing grammar element for node: "

                            f"{source_nodes_cfg_entry.uid} {source_nodes_cfg_entry.node_type}"

                        )

                        source_node_tags = (

                            TraceabilityIndexBuilder.source_node_parser_tags(

                                source_nodes_cfg_entry,

                                source_node_grammar_element,

                            )

                        )

                    else:

                        source_node_tags = None

                    traceability_info = (

                        SourceFileTraceabilityCachingReader.read_from_file(

                            source_file.full_path,

                            project_config,

                            source_node_tags,

                        )

                    )

                if traceability_info:

                    traceability_index.create_traceability_info(

                        source_file,

                        traceability_info,

                    )

                    # Is file referenced by backwards links?

                    if len(traceability_info.markers) > 0:

                        source_file.is_referenced = True

            file_tracability_index.validate_and_resolve(

                traceability_index, project_config

            )

            # Iterate again to resolve if the file is referenced.

            # FIXME: Not great to iterate two times.

            for source_file in file_tracability_index.indexed_source_files():

                # Is file referenced by forward links?

                is_source_file_referenced = (

                    traceability_index.has_source_file_reqs(

                        source_file.in_doctree_source_file_rel_path_posix

                    )

                )

                if is_source_file_referenced:

                    source_file.is_referenced = True

                    source_file_reqs: Optional[List[SDocNode]] = (

                        traceability_index.get_source_file_reqs(

                            source_file.in_doctree_source_file_rel_path_posix

                        )

                    )

                    if source_file_reqs is None:

                        continue

                    for node_ in source_file_reqs:

                        node_document = assert_cast(

                            node_.get_document(), SDocDocument

                        )

                        assert node_document.meta is not None

                        traceability_index.file_dependency_manager.add_dependency(

                            source_file.full_path,

                            source_file.output_file_full_path,

                        )

                        traceability_index.file_dependency_manager.add_dependency(

                            source_file.full_path,

                            node_document.meta.output_document_full_path,

                        )

                        traceability_index.file_dependency_manager.add_dependency(

                            node_document.meta.input_doc_full_path,

                            source_file.output_file_full_path,

                        )

            traceability_index.document_tree.attach_source_tree(source_tree)

        #

        # Resolve pending InlineLinks. This depends on UIDs and anchors from

        # static documents, generated documents and source nodes.

        #

        for inline_link in traceability_index.pending_inline_links:

            if not traceability_index.graph_database.has_any_link(

                link_type=GraphLinkType.UID_TO_NODE,

                lhs_node=inline_link.link,

            ):

                raise StrictDocException(

                    "DocumentIndex: "

                    "the inline link references an object with an UID "

                    "that does not exist: "

                    f"{inline_link.link}."

                )

            traceability_index.create_inline_link(inline_link)

        traceability_index.pending_inline_links.clear()

        #

        # Resolve all modification dates to support the incremental generation of

        # all artifacts.

        #

        file_dependency_manager = traceability_index.file_dependency_manager

        file_dependency_manager.resolve_modification_dates(

            traceability_index.strictdoc_last_update

        )

        if project_config.user_plugin is not None:

            project_config.user_plugin.traceability_index_build_finished(

                traceability_index

            )

        return traceability_index

    @staticmethod

    @timing_decorator("Build traceability graph")

    def create_from_document_tree(

        document_tree: DocumentTree,

        project_config: ProjectConfig,

    ) -> TraceabilityIndex:

        """

        @relation(SDOC-SRS-32, SDOC-SRS-102, scope=function)

        """

        # FIXME: Too many things going on below. Would be great to simplify this

        # workflow.

        d_01_document_iterators: Dict[SDocDocument, SDocDocumentIterator] = {}

        d_07_file_traceability_index = FileTraceabilityIndex()

        graph_database = GraphDatabase(

            [

                (

                    GraphLinkType.MID_TO_NODE,

                    OneToOneDictionary(

                        MID,

                        (

                            SDocNode,

                            SDocDocument,

                            InlineLink,

                            Anchor,

                        ),

                    ),

                ),

                (

                    GraphLinkType.UID_TO_NODE,

                    OneToOneDictionary(str, (SDocDocument, SDocNode, Anchor)),

                ),

                (

                    GraphLinkType.NODE_TO_PARENT_NODES,

                    ManyToManySet(SDocNode, SDocNode),

                ),

                (

                    GraphLinkType.NODE_TO_CHILD_NODES,

                    ManyToManySet(SDocNode, SDocNode),

                ),

                (

                    GraphLinkType.NODE_TO_INCOMING_LINKS,

                    ManyToManySet(MID, InlineLink),

                ),

                (

                    GraphLinkType.DOCUMENT_TO_TAGS,

                    OneToOneDictionary(MID, dict),

                ),

            ]

        )

        file_dependency_manager: FileDependencyManager = (

            FileDependencyManager.create_from_cache(

                project_config=project_config

            )

        )

        traceability_index = TraceabilityIndex(

            document_tree,

            d_01_document_iterators,

            file_traceability_index=d_07_file_traceability_index,

            graph_database=graph_database,

            file_dependency_manager=file_dependency_manager,

        )

        # It seems to be impossible to accomplish everything in just one for

        # loop. One particular problem that requires two passes: it is not

        # possible to know after one iteration which of the requirements

        # parents do not exist for each given requirement.

        #

        # Step #1:

        # - Collect a dictionary of all requirements in the document tree:

        # {req_id: req}  # noqa: ERA001

        # - Each requirement's 'parents_uids' is populated with the forward

        # declarations of its parents uids.

        # - A separate map is created: {req_id: [req_children]}

        # At this point some information is in place, but it was not known if

        # some UIDs could not be resolved which is the task of the second

        # step.

        #

        # Step #2:

        # - Check if each requirement's has valid parent relations.

        # - Resolve parent forward declarations

        # - Re-assign children declarations

        # - Detect cycles

        # - Calculate depth of both parent and child relations.

        for (

            path_to_grammar_,

            grammar_from_file_,

        ) in document_tree.map_grammars_by_filenames.items():

            try:

                SDocValidator.validate_grammar_from_file(

                    path_to_grammar_, grammar_from_file_

                )

            except StrictDocSemanticError as exc:

                print(exc.to_print_message())  # noqa: T201

                sys.exit(1)

        document: SDocDocument

        for document in document_tree.document_list:

            assert document.grammar is not None

            assert document.meta is not None

            traceability_index.file_dependency_manager.add_dependency(

                document.meta.input_doc_full_path,

                document.meta.output_document_full_path,

            )

            if document.config.view_style_tag == "REQUIREMENT_STYLE":

                DEPRECATION_ENGINE.add_message(

                    "DEPRECATED_REQUIREMENT_STYLE",

                    "WARNING: REQUIREMENT_STYLE is deprecated. Replace it to VIEW_STYLE.",

                )

            if document.config.node_in_toc_tag == "REQUIREMENT_IN_TOC":

                DEPRECATION_ENGINE.add_message(

                    "DEPRECATED_REQUIREMENT_IN_TOC",

                    "WARNING: REQUIREMENT_IN_TOC is deprecated. Replace it to NODE_IN_TOC.",

                )

            #

            # First, resolve all grammars that are imported from grammar files.

            #

            if document.grammar.import_from_file is not None:

                grammar_path = document.grammar.import_from_file

                if grammar_path.startswith("@"):

                    grammar_path = project_config.grammars[grammar_path]

                else:

                    grammar_path = posixpath.join(

                        document.meta.input_doc_dir_rel_path.relative_path_posix,

                        grammar_path,

                    )

                document_grammar: Optional[DocumentGrammar] = (

                    document_tree.get_grammar_by_filename(grammar_path)

                )

                if document_grammar is None:

                    raise StrictDocException(

                        "TraceabilityIndex: "

                        f'the document "{document.reserved_title}" '

                        "imports a grammar from a file that does not exist: "

                        f'"{document.grammar.import_from_file}". One known '

                        f"source of this error is when only a single document "

                        f"file is provided as input to the export or server "

                        f"command, rather than the containing folder. To locate "

                        f"the grammar file, StrictDoc needs to be able to "

                        f"resolve it relative to the input path."

                    )

                document.grammar.update_with_elements(document_grammar.elements)

                # This is for the backward compatibility with the existing users.

                # If the included project grammar has no TEXT element defined,

                # we add it here automatically.

                if not document.grammar.has_text_element():

                    document.grammar.add_element_first(

                        DocumentGrammar.create_default_text_element(

                            document.grammar,

                            enable_mid=document.config.enable_mid is True,

                        )

                    )

            # This is important because due to the difference between the

            # normal grammar vs imported grammar, the parent may not be set at

            # this point.

            document.grammar.parent = document

            if document.config.markup == SDocMarkup.MARKDOWN:

                SDMarkdownReader.fixup_composite_nodes(document)

            try:

                SDocValidator.validate_document(document)

            except StrictDocSemanticError as exc:

                print(exc.to_print_message())  # noqa: T201

                sys.exit(1)

            if graph_database.has_any_link(

                link_type=GraphLinkType.MID_TO_NODE,

                lhs_node=document.reserved_mid,

            ):

                other_document: SDocDocument = graph_database.get_link_value(

                    link_type=GraphLinkType.MID_TO_NODE,

                    lhs_node=document.reserved_mid,

                )

                raise StrictDocException(

                    "TraceabilityIndex: "

                    "the document MID is not unique: "

                    f"{document.reserved_mid}. "

                    "All machine identifiers (MID) must be unique values. "

                    f"Affected documents:\n"

                    f"{other_document.get_debug_info()}\n"

                    f"and\n"

                    f"{document.get_debug_info()}."

                )

            graph_database.create_link(

                link_type=GraphLinkType.MID_TO_NODE,

                lhs_node=document.reserved_mid,

                rhs_node=document,

            )

            if document.uid:

                graph_database.create_link(

                    link_type=GraphLinkType.UID_TO_NODE,

                    lhs_node=document.uid,

                    rhs_node=document,

                )

            document_tags: Dict[str, int] = {}

            graph_database.create_link(

                link_type=GraphLinkType.DOCUMENT_TO_TAGS,

                lhs_node=document.reserved_mid,

                rhs_node=document_tags,

            )

            document_iterator = SDocDocumentIterator(document)

            d_01_document_iterators[document] = document_iterator

            for node, _ in document_iterator.all_content(

                print_fragments=False,

            ):

                if isinstance(node, SDocNode):

                    try:

                        assert document.grammar is not None

                        SDocValidator.validate_node(

                            node,

                            document_grammar=document.grammar,

                            path_to_sdoc_file=document.meta.input_doc_full_path,

                            auto_uid_mode=project_config.auto_uid_mode,

                        )

                    except StrictDocSemanticError as exc:

                        print(exc.to_print_message())  # noqa: T201

                        sys.exit(1)

                if graph_database.has_any_link(

                    link_type=GraphLinkType.MID_TO_NODE,

                    lhs_node=node.reserved_mid,

                ):

                    other_node: SDocDocument = graph_database.get_link_value(

                        link_type=GraphLinkType.MID_TO_NODE,

                        lhs_node=node.reserved_mid,

                    )

                    raise StrictDocException(

                        "TraceabilityIndex: "

                        "the node MID is not unique: "

                        f"{node.reserved_mid}. "

                        "All machine identifiers (MID) must be unique values. "

                        f"Affected nodes:\n"

                        f"{other_node.get_debug_info()}\n"

                        f"and\n"

                        f"{node.get_debug_info()}."

                    )

                graph_database.create_link(

                    link_type=GraphLinkType.MID_TO_NODE,

                    lhs_node=node.reserved_mid,

                    rhs_node=node,

                )

                if node.reserved_uid is not None:

                    # @relation(SDOC-SRS-29, scope=range_start)

                    if traceability_index.graph_database.has_any_link(

                        link_type=GraphLinkType.UID_TO_NODE,

                        lhs_node=node.reserved_uid,

                    ):

                        already_existing_node: SDocNode = (

                            traceability_index.graph_database.get_link_value(

                                link_type=GraphLinkType.UID_TO_NODE,

                                lhs_node=node.reserved_uid,

                            )

                        )

                        other_req_doc = assert_cast(

                            already_existing_node.get_document(), SDocDocument

                        )

                        if other_req_doc == document:

                            print(  # noqa: T201

                                "error: DocumentIndex: "

                                "two nodes with the same UID "

                                "exist in the same document: "

                                f'{node.reserved_uid} in "{document.title}".'

                            )

                        else:

                            print(  # noqa: T201

                                "error: DocumentIndex: "

                                "two nodes with the same UID "

                                "exist in two different documents: "

                                f'{node.reserved_uid} in "{other_req_doc.title}" '

                                f'and "{document.title}".'

                            )

                        sys.exit(1)

                    # @relation(SDOC-SRS-29, scope=range_end)

                    traceability_index.graph_database.create_link(

                        link_type=GraphLinkType.UID_TO_NODE,

                        lhs_node=node.reserved_uid,

                        rhs_node=node,

                    )

                if isinstance(node, SDocNode):

                    requirement_node: SDocNode = assert_cast(node, SDocNode)

                    if requirement_node.reserved_tags is not None:

                        for tag in requirement_node.reserved_tags:

                            document_tags.setdefault(tag, 0)

                            document_tags[tag] += 1

                    for node_field_ in node.enumerate_fields():

                        for part in node_field_.parts:

                            # The inline links are handled at the next big

                            # For loop pass because the information about

                            # all Nodes and Anchors have not been

                            # collected yet at this point.

                            # see create_inline_link below.

                            if isinstance(part, Anchor):

                                graph_database.create_link(

                                    link_type=GraphLinkType.MID_TO_NODE,

                                    lhs_node=part.mid,

                                    rhs_node=part,

                                )

                                graph_database.create_link(

                                    link_type=GraphLinkType.UID_TO_NODE,

                                    lhs_node=part.value,

                                    rhs_node=part,

                                )

        # Now iterate over the requirements again to build an in-depth map of

        # parents and children.

        requirement: SDocNode

        for document in document_tree.document_list:

            assert document.meta is not None

            document_iterator = d_01_document_iterators[document]

            if document.config.custom_metadata is not None:

                for metadata_entry_ in document.config.custom_metadata.entries:

                    for part in metadata_entry_.parts:

                        if isinstance(part, InlineLink):

                            traceability_index.pending_inline_links.append(part)

            for node, _ in document_iterator.all_content(

                print_fragments=False,

            ):

                if not isinstance(node, SDocNode):

                    continue

                requirement = assert_cast(node, SDocNode)

                for node_field_ in requirement.enumerate_fields():

                    for part in node_field_.parts:

                        if isinstance(part, InlineLink):

                            traceability_index.pending_inline_links.append(part)

                if requirement.reserved_uid is None:

                    continue

                # Now it is possible to resolve parents first checking if they

                # indeed exist.

                for reference in requirement.relations:

                    if reference.ref_type == ReferenceType.FILE:

                        d_07_file_traceability_index.create_requirement_with_forward_source_links(

                            requirement

                        )

                    elif reference.ref_type == ReferenceType.PARENT:

                        parent_reference: ParentReqReference = assert_cast(

                            reference, ParentReqReference

                        )

                        parent_requirement = traceability_index.graph_database.get_link_value_weak(

                            link_type=GraphLinkType.UID_TO_NODE,

                            lhs_node=parent_reference.ref_uid,

                        )

                        if parent_requirement is None:

                            raise StrictDocException(

                                f"[DocumentIndex.create] "

                                f"Requirement {requirement.reserved_uid} "

                                f"references "

                                f"parent requirement which doesn't exist: "

                                f"{parent_reference.ref_uid}."

                            )

                        traceability_index.graph_database.create_link(

                            link_type=GraphLinkType.NODE_TO_PARENT_NODES,

                            lhs_node=requirement,

                            rhs_node=parent_requirement,

                            edge=parent_reference.role,

                        )

                        traceability_index.graph_database.create_link(

                            link_type=GraphLinkType.NODE_TO_CHILD_NODES,

                            lhs_node=parent_requirement,

                            rhs_node=requirement,

                            edge=parent_reference.role,

                        )

                        # Set document dependencies.

                        parent_document: SDocDocument = assert_cast(

                            parent_requirement.get_document(), SDocDocument

                        )

                        if document != parent_document:

                            assert parent_document.meta is not None

                            # This is where we help the incremental generation to

                            # understand that the related documents must be

                            # re-generated together.

                            file_dependency_manager.add_dependency(

                                document.meta.input_doc_full_path,

                                parent_document.meta.output_document_full_path,

                            )

                            file_dependency_manager.add_dependency(

                                parent_document.meta.input_doc_full_path,

                                document.meta.output_document_full_path,

                            )

                    elif reference.ref_type == ReferenceType.CHILD:

                        child_reference: ChildReqReference = assert_cast(

                            reference, ChildReqReference

                        )

                        child_requirement = traceability_index.graph_database.get_link_value_weak(

                            link_type=GraphLinkType.UID_TO_NODE,

                            lhs_node=child_reference.ref_uid,

                        )

                        if child_requirement is None:

                            raise StrictDocException(

                                f"[DocumentIndex.create] "

                                f"Requirement {requirement.reserved_uid} "

                                f"references a "

                                f"child requirement that doesn't exist: "

                                f"{child_reference.ref_uid}."

                            )

                        traceability_index.graph_database.create_link(

                            link_type=GraphLinkType.NODE_TO_PARENT_NODES,

                            lhs_node=child_requirement,

                            rhs_node=requirement,

                            edge=child_reference.role,

                        )

                        traceability_index.graph_database.create_link(

                            link_type=GraphLinkType.NODE_TO_CHILD_NODES,

                            lhs_node=requirement,

                            rhs_node=child_requirement,

                            edge=child_reference.role,

                        )

                        # Set document dependencies.

                        child_requirement_document = assert_cast(

                            child_requirement.get_document(), SDocDocument

                        )

                        if document != child_requirement_document:

                            assert child_requirement_document.meta is not None

                            # This is where we help the incremental generation to

                            # understand that the related documents must be

                            # re-generated together.

                            file_dependency_manager.add_dependency(

                                document.meta.input_doc_full_path,

                                child_requirement_document.meta.output_document_full_path,

                            )

                            file_dependency_manager.add_dependency(

                                child_requirement_document.meta.input_doc_full_path,

                                document.meta.output_document_full_path,

                            )

                    else:

                        raise AssertionError(reference.ref_type)

        # Iterate for the third time to validate the graph against

        # requirement cycles.

        parents_cycle_detector = TreeCycleDetector()

        children_cycle_detector = TreeCycleDetector()

        for document in document_tree.document_list:

            document_iterator = d_01_document_iterators[document]

            for node, _ in document_iterator.all_content(

                print_fragments=False,

            ):

                if not isinstance(node, SDocNode):

                    continue

                requirement = assert_cast(node, SDocNode)

                if requirement.reserved_uid is None:

                    continue

                # @relation(SDOC-SRS-30, scope=range_start)

                # Detect cycles

                def parent_cycle_traverse_(node_id: str) -> Any:

                    current_node = (

                        traceability_index.graph_database.get_link_value(

                            link_type=GraphLinkType.UID_TO_NODE,

                            lhs_node=node_id,

                        )

                    )

                    return list(

                        map(

                            lambda node_: node_.reserved_uid,

                            traceability_index.graph_database.get_link_values(

                                link_type=GraphLinkType.NODE_TO_PARENT_NODES,

                                lhs_node=current_node,

                            ),

                        )

                    )

                parents_cycle_detector.check_node(

                    requirement.reserved_uid,

                    parent_cycle_traverse_,

                )

                def child_cycle_traverse_(node_id: str) -> Any:

                    current_node = (

                        traceability_index.graph_database.get_link_value(

                            link_type=GraphLinkType.UID_TO_NODE,

                            lhs_node=node_id,

                        )

                    )

                    return list(

                        map(

                            lambda node_: node_.reserved_uid,

                            traceability_index.graph_database.get_link_values(

                                link_type=GraphLinkType.NODE_TO_CHILD_NODES,

                                lhs_node=current_node,

                            ),

                        )

                    )

                children_cycle_detector.check_node(

                    requirement.reserved_uid,

                    child_cycle_traverse_,

                )

                # @relation(SDOC-SRS-30, scope=range_end)

        map_documents_by_input_rel_path: Dict[str, SDocDocument] = {}

        for document_ in document_tree.document_list:

            assert document_.meta is not None

            map_documents_by_input_rel_path[

                document_.meta.input_doc_full_path

            ] = document_

        # @relation(SDOC-SRS-109, scope=range_start)

        unique_document_from_file_occurences: Set[str] = set()

        for document_ in document_tree.document_list:

            document_from_file_: SDocDocumentFromFileIF

            for document_from_file_ in document_.fragments_from_files:

                traceability_index.contains_included_documents = True

                assert isinstance(document_from_file_, DocumentFromFile), (

                    document_from_file_

                )

                assert (

                    document_from_file_.resolved_full_path_to_document_file

                    is not None

                )

                if (

                    document_from_file_.resolved_full_path_to_document_file

                    not in map_documents_by_input_rel_path

                ):

                    raise StrictDocException(

                        "A document includes contains a link to another document "

                        "which is not resolved in the current documentation tree: "

                        f"'{document_from_file_.file}'. This can happen if a single "

                        f"document path is provided as input to a StrictDoc command. "

                        f"Try providing a path to a folder where all documents "

                        f"are stored."

                    )

                resolved_document: SDocDocument = (

                    map_documents_by_input_rel_path[

                        document_from_file_.resolved_full_path_to_document_file

                    ]

                )

                if (

                    document_from_file_.resolved_full_path_to_document_file

                    in unique_document_from_file_occurences